2.7. VERTEX SPECIFICATION

Pointer, VertexPointer, VertexAttribPointer, ClientActiveTexture, InterleavedArrays, and PixelStore is not allowed within any Begin/End pair, but an error may or may not be generated if such execution occurs. If an error is not generated, GL operation is undefined. (These commands are described in sections 2.8, 3.6.1, and chapter 6.)

2.7Vertex Specification

Vertices are specified by giving their coordinates in two, three, or four dimensions. This is done using one of several versions of the Vertex command:

void Vertex{234}{sifd}( T coords ); void Vertex{234}{sifd}v( T coords );

A call to any Vertex command specifies four coordinates: x, y, z, and w. The x coordinate is the first coordinate, y is second, z is third, and w is fourth. A call to Vertex2 sets the x and y coordinates; the z coordinate is implicitly set to zero and the w coordinate to one. Vertex3 sets x, y, and z to the provided values and w to one. Vertex4 sets all four coordinates, allowing the specification of an arbitrary point in projective three-space. Invoking a Vertex command outside of a Begin/End pair results in undefined behavior.

Current values are used in associating auxiliary data with a vertex as described in section 2.6. A current value may be changed at any time by issuing an appropriate command. The commands

void TexCoord{1234}{sifd}( T coords ); void TexCoord{1234}{sifd}v( T coords );

specify the current homogeneous texture coordinates, named s, t, r, and q. The TexCoord1 family of commands set the s coordinate to the provided single argument while setting t and r to 0 and q to 1. Similarly, TexCoord2 sets s and t to the specified values, r to 0 and q to 1; TexCoord3 sets s, t, and r, with q set to 1, and TexCoord4 sets all four texture coordinates.

Implementations must support at least two sets of texture coordinates. The commands

void MultiTexCoord{1234}{sifd}(enum texture,T coords) void MultiTexCoord{1234}{sifd}v(enum texture,T

coords)

Version 2.0 - October 22, 2004

constant of the form TEXTUREi, indicating that texture coordinate set i is to be modified. The constants obey TEXTUREi = TEXTURE0 + i (i is in the range 0 to k −1, where k is the implementation-dependent number of texture coordinate sets defined by MAX TEXTURE COORDS).

The TexCoord commands are exactly equivalent to the corresponding MultiTexCoord commands with texture set to TEXTURE0.

Gets of CURRENT TEXTURE COORDS return the texture coordinate set defined by the value of ACTIVE TEXTURE.

Specifying an invalid texture coordinate set for the texture argument of MultiTexCoord results in undefined behavior.

The current normal is set using

void Normal3{bsifd}( T coords ); void Normal3{bsifd}v( T coords );

Byte, short, or integer values passed to Normal are converted to floating-point values as indicated for the corresponding (signed) type in table 2.9.

The current fog coordinate is set using

void FogCoord{fd}( T coord ); void FogCoord{fd}v( T coord );

There are several ways to set the current color and secondary color. The GL stores a current single-valued color index, as well as a current four-valued RGBA color and secondary color. Either the index or the color and secondary color are significant depending as the GL is in color index mode or RGBA mode. The mode selection is made when the GL is initialized.

The commands to set RGBA colors are

void Color{34}{bsifd ubusui}( T components ); void Color{34}{bsifd ubusui}v( T components );

void SecondaryColor3{bsifd ubusui}( T components ); void SecondaryColor3{bsifd ubusui}v( T components );

The Color command has two major variants: Color3 and Color4. The four value versions set all four values. The three value versions set R, G, and B to the provided values; A is set to 1.0. (The conversion of integer color components (R, G, B, and A) to floating-point values is discussed in section 2.14.)

The secondary color has only the three value versions. Secondary A is always set to 1.0.

Version 2.0 - October 22, 2004

Versions of the Color and SecondaryColor commands that take floating-point values accept values nominally between 0.0 and 1.0. 0.0 corresponds to the minimum while 1.0 corresponds to the maximum (machine dependent) value that a component may take on in the framebuffer (see section 2.14 on colors and coloring). Values outside [0, 1] are not clamped.

The command

void Index{sifd ub}( T index ); void Index{sifd ub}v( T index );

updates the current (single-valued) color index. It takes one argument, the value to which the current color index should be set. Values outside the (machinedependent) representable range of color indices are not clamped.

Vertex shaders (see section 2.15) can be written to access an array of 4- component generic vertex attributes in addition to the conventional attributes specified previously. The first slot of this array is numbered 0, and the size of the array is specified by the implementation-dependent constant MAX VERTEX ATTRIBS.

The commands

void VertexAttrib{1234}{sfd}( uint index, T values ); void VertexAttrib{123}{sfd}v( uint index, T values ); void VertexAttrib4{bsifd ubusui}v( uint index, T values );

can be used to load the given value(s) into the generic attribute at slot index, whose components are named x, y, z, and w. The VertexAttrib1* family of commands sets the x coordinate to the provided single argument while setting y and z to 0 and w to 1. Similarly, VertexAttrib2* commands set x and y to the specified values, z to 0 and w to 1; VertexAttrib3* commands set x, y, and z, with w set to 1, and VertexAttrib4* commands set all four coordinates. The error INVALID VALUE is generated if index is greater than or equal to MAX VERTEX ATTRIBS.

The commands

void VertexAttrib4Nub( uint index, T values );

void VertexAttrib4N{bsi ubusui}v( uint index, T values );

also specify vertex attributes with fixed-point coordinates that are scaled to a normalized range, according to table 2.9.

The VertexAttrib* entry points defined earlier can also be used to load attributes declared as a 2 × 2, 3 × 3 or 4 × 4 matrix in a vertex shader. Each column of a matrix takes up one generic 4-component attribute slot out of the

Version 2.0 - October 22, 2004

MAX VERTEX ATTRIBS available slots. Matrices are loaded into these slots in column major order. Matrix columns need to be loaded in increasing slot numbers.

Setting generic vertex attribute zero specifies a vertex; the four vertex coordinates are taken from the values of attribute zero. A Vertex2, Vertex3, or Vertex4 command is completely equivalent to the corresponding VertexAttrib* command with an index of zero. Setting any other generic vertex attribute updates the current values of the attribute. There are no current values for vertex attribute zero.

There is no aliasing among generic attributes and conventional attributes. In other words, an application can set all MAX VERTEX ATTRIBS generic attributes and all conventional attributes without fear of one particular attribute overwriting the value of another attribute.

The state required to support vertex specification consists of four floatingpoint numbers per texture coordinate set to store the current texture coordinates s, t, r, and q, three floating-point numbers to store the three coordinates of the current normal, one floating-point number to store the current fog coordinate, four floatingpoint values to store the current RGBA color, four floating-point values to store the current RGBA secondary color, one floating-point value to store the current color index, and MAX VERTEX ATTRIBS − 1 four-component floating-point vectors to store generic vertex attributes.

There is no notion of a current vertex, so no state is devoted to vertex coordinates or generic attribute zero. The initial texture coordinates are (s, t, r, q) = (0, 0, 0, 1) for each texture coordinate set. The initial current normal has coordinates (0, 0, 1). The initial fog coordinate is zero. The initial RGBA color is (R, G, B, A) = (1, 1, 1, 1) and the initial RGBA secondary color is (0, 0, 0, 1). The initial color index is 1. The initial values for all generic vertex attributes are

(0, 0, 0, 1).

2.8Vertex Arrays

The vertex specification commands described in section 2.7 accept data in almost any format, but their use requires many command executions to specify even simple geometry. Vertex data may also be placed into arrays that are stored in the client’s address space. Blocks of data in these arrays may then be used to specify multiple geometric primitives through the execution of a single GL command. The client may specify up to seven plus the values of MAX TEXTURE COORDS and MAX VERTEX ATTRIBS arrays: one each to store vertex coordinates, normals, colors, secondary colors, color indices, edge flags, fog coordinates, two or more texture coordinate sets, and one or more generic vertex attributes. The commands

Version 2.0 - October 22, 2004

void VertexPointer( int size, enum type, sizei stride, void *pointer );

void NormalPointer( enum type, sizei stride, void *pointer );

void ColorPointer( int size, enum type, sizei stride, void *pointer );

void SecondaryColorPointer( int size, enum type, sizei stride, void *pointer );

void IndexPointer( enum type, sizei stride, void *pointer );

void EdgeFlagPointer( sizei stride, void *pointer );

void FogCoordPointer( enum type, sizei stride, void *pointer );

void TexCoordPointer( int size, enum type, sizei stride, void *pointer );

void VertexAttribPointer( uint index, int size, enum type, boolean normalized, sizei stride, const

void *pointer );

describe the locations and organizations of these arrays. For each command, type specifies the data type of the values stored in the array. Because edge flags are always type boolean, EdgeFlagPointer has no type argument. size, when present, indicates the number of values per vertex that are stored in the array. Because normals are always specified with three values, NormalPointer has no size argument. Likewise, because color indices and edge flags are always specified with a single value, IndexPointer and EdgeFlagPointer also have no size argument. Table 2.4 indicates the allowable values for size and type (when present). For type the values BYTE, SHORT, INT, FLOAT, and DOUBLE indicate types byte, short, int, float, and double, respectively; and the values

UNSIGNED BYTE, UNSIGNED SHORT, and UNSIGNED INT indicate types ubyte, ushort, and uint, respectively. The error INVALID VALUE is generated if size is specified with a value other than that indicated in the table.

The index parameter in the VertexAttribPointer command identifies the generic vertex attribute array being described. The error INVALID VALUE is generated if index is greater than or equal to MAX VERTEX ATTRIBS. The normalized parameter in the VertexAttribPointer command identifies whether fixed-point types

Version 2.0 - October 22, 2004

Table 2.4: Vertex array sizes (values per vertex) and data types. The ”normalized” column indicates whether fixed-point types are accepted directly or normalized to [0, 1] (for unsigned types) or [−1, 1] (for signed types). For generic vertex attributes, fixed-point data are normalized if and only if the VertexAttribPointer normalized flag is set.

Version 2.0 - October 22, 2004

should be normalized when converted to floating-point. If normalized is TRUE, fixed-point data are converted as specified in table 2.9; otherwise, the fixed-point values are converted directly.

The one, two, three, or four values in an array that correspond to a single vertex comprise an array element. The values within each array element are stored sequentially in memory. If stride is specified as zero, then array elements are stored sequentially as well. The error INVALID VALUE is generated if stride is negative. Otherwise pointers to the ith and (i + 1)st elements of an array differ by stride basic machine units (typically unsigned bytes), the pointer to the (i + 1)st element being greater. For each command, pointer specifies the location in memory of the first value of the first element of the array being specified.

An individual array is enabled or disabled by calling one of

void EnableClientState( enum array ); void DisableClientState( enum array );

with array set to VERTEX ARRAY, NORMAL ARRAY, COLOR ARRAY,

SECONDARY COLOR ARRAY, INDEX ARRAY, EDGE FLAG ARRAY, FOG COORD ARRAY, or TEXTURE COORD ARRAY, for the vertex, normal, color, secondary color, color index, edge flag, fog coordinate, or texture coordinate array, respectively.

An individual generic vertex attribute array is enabled or disabled by calling one of

void EnableVertexAttribArray( uint index ); void DisableVertexAttribArray( uint index );

where index identifies the generic vertex attribute array to enable or disable. The error INVALID VALUE is generated if index is greater than or equal to

MAX VERTEX ATTRIBS. The command

void ClientActiveTexture( enum texture );

is used to select the vertex array client state parameters to be modified by the TexCoordPointer command and the array affected by EnableClientState and DisableClientState with parameter TEXTURE COORD ARRAY. This command sets the client state variable CLIENT ACTIVE TEXTURE. Each texture coordinate set has a client state vector which is selected when this command is invoked. This state vector includes the vertex array state. This call also selects the texture coordinate set state used for queries of client state.

Version 2.0 - October 22, 2004

Specifying an invalid texture generates the error INVALID ENUM. Valid values of texture are the same as for the MultiTexCoord commands described in section 2.7.

The command

void ArrayElement( int i );

transfers the ith element of every enabled array to the GL. The effect of ArrayElement(i) is the same as the effect of the command sequence

if (normal array enabled) Normal3[type]v(normal array element i);

if (color array enabled) Color[size][type]v(color array element i);

if (secondary color array enabled) SecondaryColor3[type]v(secondary color array element i);

if (fog coordinate array enabled) FogCoord[type]v(fog coordinate array element i);

for (j = 0; j < textureUnits; j++) { if (texture coordinate set j array enabled)

MultiTexCoord[size][type]v(TEXTURE0 + j, texture coordinate set j array element i); if (color index array enabled)

Index[type]v(color index array element i); if (edge flag array enabled )

EdgeFlagv(edge flag array element i);

for (j = 1; j < genericAttributes; j++) { if (generic vertex attribute j array enabled) {

if (generic vertex attribute j array normalization flag is set, and type is not FLOAT or DOUBLE)

VertexAttrib[size]N[type]v(j, generic vertex attribute j array element i); else

VertexAttrib[size][type]v(j, generic vertex attribute j array element i);

}

}

if (generic attribute array 0 enabled) {

if (generic vertex attribute 0 array normalization flag is set, and type is not FLOAT or DOUBLE)

VertexAttrib[size]N[type]v(0, generic vertex attribute 0 array element i); else

VertexAttrib[size][type]v(0, generic vertex attribute 0 array element i);

Version 2.0 - October 22, 2004

} else if (vertex array enabled) { Vertex[size][type]v(vertex array element i);

}

where textureUnits and genericAttributes give the number of texture coordinate sets and generic vertex attributes supported by the implementation, respectively. ”[size]” and ”[type]” correspond to the size and type of the corresponding array.

For generic vertex attributes, it is assumed that a complete set of vertex attribute commands exists, even though not all such functions are provided by the GL.

Changes made to array data between the execution of Begin and the corresponding execution of End may affect calls to ArrayElement that are made within the same Begin/End period in non-sequential ways. That is, a call to ArrayElement that precedes a change to array data may access the changed data, and a call that follows a change to array data may access original data.

Specifying i < 0 results in undefined behavior. Generating the error INVALID VALUE is recommended in this case.

The command

void DrawArrays( enum mode, int first , sizei count );

constructs a sequence of geometric primitives using elements first through first + count − 1 of each enabled array. mode specifies what kind of primitives are constructed; it accepts the same token values as the mode parameter of the Begin command. The effect of

DrawArrays (mode, first, count);

is the same as the effect of the command sequence

if (mode or count is invalid ) generate appropriate error

else {

Begin(mode);

for (int i = 0; i < count ; i++)

ArrayElement(first+ i); End();

}

with one exception: the current normal coordinates, color, secondary color, color index, edge flag, fog coordinate, texture coordinates, and generic attributes are each indeterminate after execution of DrawArrays, if the corresponding array is

Version 2.0 - October 22, 2004

enabled. Current values corresponding to disabled arrays are not modified by the execution of DrawArrays.

Specifying first < 0 results in undefined behavior. Generating the error INVALID VALUE is recommended in this case.

The command

void MultiDrawArrays( enum mode, int *first , sizei *count, sizei primcount );

behaves identically to DrawArrays except that primcount separate ranges of elements are specified instead. It has the same effect as:

for (i = 0; i < primcount; i++) { if (count[i] > 0)

DrawArrays(mode, first[i], count[i]);

}

The command

void DrawElements( enum mode, sizei count, enum type, void *indices );

constructs a sequence of geometric primitives using the count elements whose indices are stored in indices. type must be one of UNSIGNED BYTE, UNSIGNED SHORT, or UNSIGNED INT, indicating that the values in indices are indices of GL type ubyte, ushort, or uint respectively. mode specifies what kind of primitives are constructed; it accepts the same token values as the mode parameter of the Begin command. The effect of

DrawElements (mode, count, type, indices);

is the same as the effect of the command sequence

if (mode, count, or type is invalid ) generate appropriate error

else {

Begin(mode);

for (int i = 0; i < count ; i++)

ArrayElement(indices[i]); End();

}

Version 2.0 - October 22, 2004

with one exception: the current normal coordinates, color, secondary color, color index, edge flag, fog coordinate, texture coordinates, and generic attributes are each indeterminate after the execution of DrawElements, if the corresponding array is enabled. Current values corresponding to disabled arrays are not modified by the execution of DrawElements.

The command

void MultiDrawElements( enum mode, sizei *count, enum type, void **indices, sizei primcount );

behaves identically to DrawElements except that primcount separate lists of elements are specified instead. It has the same effect as:

for (i = 0; i < primcount; i++) { if (count[i]) > 0)

DrawElements(mode, count[i], type, indices[i]);

}

The command

void DrawRangeElements( enum mode, uint start, uint end, sizei count, enum type, void *indices );

is a restricted form of DrawElements. mode, count, type, and indices match the corresponding arguments to DrawElements, with the additional constraint that all values in the array indices must lie between start and end inclusive.

Implementations denote recommended maximum amounts of vertex and index data, which may be queried by calling GetIntegerv with the symbolic constants

MAX ELEMENTS VERTICES and MAX ELEMENTS INDICES. If end − start + 1 is greater than the value of MAX ELEMENTS VERTICES, or if count is greater than the value of MAX ELEMENTS INDICES, then the call may operate at reduced performance. There is no requirement that all vertices in the range [start, end] be referenced. However, the implementation may partially process unused vertices, reducing performance from what could be achieved with an optimal index set.

The error INVALID VALUE is generated if end < start. Invalid mode, count, or type parameters generate the same errors as would the corresponding call to DrawElements. It is an error for indices to lie outside the range [start, end], but implementations may not check for this. Such indices will cause implementationdependent behavior.

The command

Version 2.0 - October 22, 2004

void InterleavedArrays( enum format, sizei stride, void *pointer );

efficiently initializes the six arrays and their enables to one of 14 con-

T4F V4F, T2F C4UB V3F, T2F C3F V3F, T2F N3F V3F, T2F C4F N3F V3F, or

T4F C4F N3F V4F. The effect of

InterleavedArrays(format, stride, pointer);

is the same as the effect of the command sequence

if (format or stride is invalid) generate appropriate error

else {

int str;

set et, ec, en, st, sc, sv, tc, pc, pn, pv, and s as a function of table 2.5 and the value of format.

str = stride;

if (str is zero) str = s;

DisableClientState(EDGE FLAG ARRAY); DisableClientState(INDEX ARRAY);

DisableClientState(SECONDARY COLOR ARRAY);

DisableClientState(FOG COORD ARRAY);

if (et) {

EnableClientState(TEXTURE COORD ARRAY); TexCoordPointer(st, FLOAT, str, pointer);

}else

DisableClientState(TEXTURE COORD ARRAY);

if (ec) {

EnableClientState(COLOR ARRAY); ColorPointer(sc, tc, str, pointer + pc);

}else

DisableClientState(COLOR ARRAY);

if (en) {

EnableClientState(NORMAL ARRAY); NormalPointer(FLOAT, str, pointer + pn);

} else

Version 2.0 - October 22, 2004

Table 2.5: Variables that direct the execution of InterleavedArrays. f is sizeof(FLOAT). c is 4 times sizeof(UNSIGNED BYTE), rounded up to the nearest multiple of f. All pointer arithmetic is performed in units of sizeof(UNSIGNED BYTE).

Version 2.0 - October 22, 2004