xref: /third_party/openGLES/extensions/APPLE/APPLE_vertex_program_evaluators.txt

Name

    APPLE_vertex_program_evaluators

Name Strings

    GL_APPLE_vertex_program_evaluators

Contact

    Bob Beretta, Apple Inc. (beretta 'at' apple.com)

Version

    1.0

Number

    369

Dependencies

    This extension requires ARB_vertex_program.

Overview

    This extension allows the one- and two-dimensional evaluators to be used
    with vertex program attributes.  The operation of this extension is
    precisely analogous to the operation of the normal evaluators.

	Where normal evaluators are enabled with Enable(MAP1_VERTEX_3), for
    example, attribute evaluators are enabled with
    EnableVertexAttribAPPLE(index, VERTEX_ATTRIB_MAP1_APPLE).

	Where the size (1, 2, 3, or 4) of a normal evaluator is embedded in the
    token for that evaluator (for example, MAP1_VERTEX_3 has size 3),
    attribute evaluators give the size as an argument to MapVertexAttrib**APPLE.

	The 1D and 2D evaluator order, domain, and coefficients are given as
    arguments to MapVertexAttrib**APPLE, with exactly the same meaning and
    restrictions as the same arguments to Map1f, Map2f, Map1d, & Map2d.
	The evaluator order, domain, and coefficients may be queried with
    GetVertexAttrib*vARB, with the same operation as GetMap*v.

Issues

    (1) Normal evaluators provide separate storage for the coefficients of
    each size of each vertex element.  For example, GL_MAP1_VERTEX_3
    and GL_MAP1_VERTEX_4 indentify separate storage for 3-element vertex
    coefficients and 4-element vertex coefficients.  Does this extension
    provide separate storage for each possible attribute size, 1, 2, 3, & 4?

    RESOLVED:  No.  Size is given as a parameter to MapVertexAttrib**APPLE.
    Storage is only provided for one set of coefficients per vertex attrib
    index.  If MapVertexAttrib**APPLE is called with a <size> of 3, the
    coefficients associated with any other <size> are replaced.

New Procedures and Functions

    void EnableVertexAttribAPPLE(uint index, enum pname);
    void DisableVertexAttribAPPLE(uint index, enum pname);
    boolean IsVertexAttribEnabledAPPLE(uint index, enum pname);
    void MapVertexAttrib1dAPPLE(uint index, uint size, double u1, double u2,
        int stride, int order, const double *points);
    void MapVertexAttrib1fAPPLE(uint index, uint size, float u1, float u2,
        int stride, int order, const float *points);
    void MapVertexAttrib2dAPPLE(uint index, uint size, double u1, double u2,
        int ustride, int uorder, double v1, double v2, int vstride, int vorder,
        const double *points);
    void MapVertexAttrib2fAPPLE(uint index, uint size, float u1, float u2,
        int ustride, int uorder, float v1, float v2, int vstride, int vorder,
        const float *points);
 
New Tokens

    Accepted by the <pname> parameter of EnableVertexAttribAPPLE,
    DisableVertexAttribAPPLE, and IsVertexAttribEnabledAPPLE. 
    
    VERTEX_ATTRIB_MAP1_APPLE                      0x8A00
    VERTEX_ATTRIB_MAP2_APPLE                      0x8A01

    Accepted by the <pname> parameter of GetVertexAttribdvARB,
    GetVertexAttribfvARB, and GetVertexAttribivARB.

    VERTEX_ATTRIB_MAP1_SIZE_APPLE                 0x8A02
    VERTEX_ATTRIB_MAP1_COEFF_APPLE                0x8A03
    VERTEX_ATTRIB_MAP1_ORDER_APPLE                0x8A04
    VERTEX_ATTRIB_MAP1_DOMAIN_APPLE               0x8A05
    VERTEX_ATTRIB_MAP2_SIZE_APPLE                 0x8A06
    VERTEX_ATTRIB_MAP2_COEFF_APPLE                0x8A07
    VERTEX_ATTRIB_MAP2_ORDER_APPLE                0x8A08
    VERTEX_ATTRIB_MAP2_DOMAIN_APPLE               0x8A09

Errors

    The error INVALID_VALUE is generated by EnableVertexAttribAPPLE, 
    DisableVertexAttribAPPLE, IsVertexAttribEnabledAPPLE, or
    MapVertexAttrib**APPLE if <index> is greater than or equal to
    MAX_VERTEX_ATTRIBS_ARB.

    The error INVALID_ENUM is generated by EnableVertexAttribAPPLE, 
    DisableVertexAttribAPPLE, or IsVertexAttribEnabledAPPLE if <pname>
    is not VERTEX_ATTRIB_MAP1_APPLE or VERTEX_ATTRIB_MAP2_APPLE.

    The error INVALID_VALUE is generated by MapVertexAttrib**APPLE if
    <size> is less than 1 or greater than 4.

    The error INVALID_VALUE is generated by MapVertexAttrib1*APPLE if
    <order> is less than 1 or greater than MAX_EVAL_ORDER.

    The error INVALID_VALUE is generated by MapVertexAttrib2*APPLE if
    <uorder> or <vorder> are less than 1 or greater than MAX_EVAL_ORDER.

    The error INVALID_VALUE is generated by MapVertexAttrib1*APPLE if
    <u1> is equal to <u2>.

    The error INVALID_VALUE is generated by MapVertexAttrib2*APPLE if
    <u1> is equal to <u2> or <v1> is equal to <v2>.

    The error INVALID_VALUE is generated by MapVertexAttrib1*APPLE if
    <stride> is less than <size>.

    The error INVALID_VALUE is generated by MapVertexAttrib1*APPLE if
    <ustride> is less than <size> or if <vstride> is less than size.

New State

Get Value                        Type     Get Command                 Initial Value Description        Section
------------------------------   -------  --------------------------  ------------- -----------------  ------------
VERTEX_ATTRIB_MAP1_APPLE         16+xB    IsVertexAttribEnabledAPPLE  False         1D evaluator       enable, eval
                                                                                    enabled
VERTEX_ATTRIB_MAP2_APPLE         16+xB    IsVertexAttribEnabledAPPLE  False         2D evaluator       enable, eval
                                                                                    enabled
VERTEX_ATTRIB_MAP1_SIZE_APPLE    16+xZ4   GetVertexAttribivARB        4             1D evaluator       eval
                                                                                    size
VERTEX_ATTRIB_MAP2_SIZE_APPLE    16+xZ4   GetVertexAttribivARB        4             2D evaluator       eval
                                                                                    size
VERTEX_ATTRIB_MAP1_ORDER_APPLE   16+xZ+   GetVertexAttribivARB        1             1D evaluator       eval
                                                                                    order
VERTEX_ATTRIB_MAP2_ORDER_APPLE   32+xZ+   GetVertexAttribivARB        1, 1          2D evaluator       eval
                                                                                    order
VERTEX_ATTRIB_MAP1_COEFF_APPLE   N+xRn    GetVertexAttribfvARB        0, 0, 0, 1    1D evaluator       eval
                                                                                    coefficients
VERTEX_ATTRIB_MAP2_COEFF_APPLE   N+xM+xRn GetVertexAttribfvARB        0, 0, 0, 1    2D evaluator       eval
                                                                                    coefficients
VERTEX_ATTRIB_MAP1_DOMAIN_APPLE  2+xR     GetVertexAttribfvARB        0, 1          1D evaluator       eval
                                                                                    domain
VERTEX_ATTRIB_MAP2_DOMAIN_APPLE  4+xR     GetVertexAttribfvARB        0, 1, 0, 1    2D evaluator       eval
                                                                                    domain
New Implementation Dependent State

    None