2.3 GL Command Syntax

GL commands are functions or procedures. Various groups of commands perform the same operation but differ in how arguments are supplied to them. To conveniently accommodate this variation, we adopt a notation for describing commands and their arguments.

GL commands are formed from a name followed, depending on the particular command, by up to 4 characters. The first character indicates the number of values of the indicated type that must be presented to the command. The second character or character pair indicates the specific type of the arguments: 8-bit integer, 16-bit integer, 32-bit integer, single-precision floating-point, or double-precision floating-point. The final character, if present, is v, indicating that the command takes a pointer to an array (a vector) of values rather than a series of individual arguments. Two specific examples come from the Vertex  command:

void Vertex3f ( float x, float y, float z ) ;

and

void Vertex2sv ( short v[2] ) ;

These examples show the ANSI C declarations for these commands. In general,

a command declaration has the form

rtype Name{ 1234} { b s i f d ub us ui} { v}
( [args ,] T arg1 , , T argN [, args] );

rtype is the return type of the function. The braces ({}) enclose a series of characters (or character pairs) of which one is selected. indicates no character. The arguments enclosed in brackets ( [args ,] and [, args]) may or may not be present. The N arguments arg1 through argN have type T, which corresponds to one of the type letters or letter pairs as indicated in Table 2.1 (if there are no letters, then the arguments' type is given explicitly). If the final character is not v, then N is given by the digit 1, 2, 3, or 4 (if there is no digit, then the number of arguments is fixed). If the final character is v, then only arg1 is present and it is an array of N values of the indicated type. Finally, we indicate an unsigned type by the shorthand of prepending a u to the beginning of the type name (so that, for instance, unsigned char is abbreviated uchar).

  
Table 2.1: Correspondence of command suffix letters to GL argument types. Refer to Table 2.2 for definitions of the GL types.

For example,

void Normal3[fd] ( T arg ) ;

indicates the two declarations

void Normal3f ( float arg1, float arg2, float arg3 ) ;
void Normal3d ( double arg1, double arg2, double arg3 ) ;

while

void Normal3[fd]v ( T arg ) ;

means the two declarations

void Normal3fv ( float arg[3] ) ;
void Normal3dv ( double arg[3] ) ;

Arguments whose type is fixed (i.e. not indicated by a suffix on the command) are of one of 14 types (or pointers to one of these). These types are summarized in Table 2.2.

  
Table 2.2: GL data types. GL types are not C types. Thus, for example, GL type int is referred to as GLint outside this document, and is not necessarily equivalent to the C type int. An implementation may use more bits than the number indicated in the table to represent a GL type. Correct interpretation of integer values outside the minimum range is not required, however.