6 State and State Requests

The values of most GL state variables can be obtained using a set of Get  commands. There are four commands for obtaining simple state variables:

void GetBooleanv ( enum value, boolean *data ) ;
void GetIntegerv ( enum value, int *data ) ;
void GetFloatv ( enum value, float *data ) ;
void GetDoublev ( enum value, double *data ) ;

The commands obtain boolean, integer, floating-point, or double-precision state variables. value is a symbolic constant indicating the state variable to return, *data is a pointer to an array of the indicated type in which to place the returned data. In addition

boolean IsEnabled ( enum value ) ;

can be used to determine if value is currently enabled (as with Enable ) or disabled.

If a Get  command is issued that returns value types different from the type of the value being obtained, a type conversion is performed. If GetBooleanv  is called, a floating-point or integer value converts to FALSE if and only if it is zero (otherwise it converts to TRUE). If GetIntegerv  (or any of the Get  commands below) is called, a boolean value is interpreted as either 1 or 0, and a floating-point value is rounded to the nearest integer, unless the value is a an RGBA color component, a DepthRange  value, a depth buffer clear value, or a normal coordinate. In these cases, the Get  command converts the floating-point value to an integer according the INT entry of Table 4.7; a value not in converts to an undefined value. If GetFloatv  is called, a boolean value is interpreted as either or , an integer is coerced to floating-point, and a double-precision floating-point value is converted to single-precision. Analogous conversions are carried out in the case of GetDoublev . If a value is so large in magnitude that it cannot be represented with the requested type, then the nearest value representable using the requested type is returned.

Other commands exist to obtain state variables that are indexed by a target. These are

void GetClipPlane ( enum plane, double eqn[4] ) ;
void GetLight[if]v ( enum light, enum value, T data ) ;
void GetMaterial[if]v ( enum face, enum value, T data ) ;
void GetTexEnv[if]v ( enum env, enum value, T data ) ;
void GetTexGen[if]v ( enum coord, enum value, T data ) ;
void GetTexParameter[if]v ( enum target, enum value, T data ) ;
void GetTexLevelParameter[if]v ( enum target, int lod, enum value, T data ) ;
void GetPixelMap[ui ( enum map, T data ) ;
void GetMap[ifd]v ( enum map, enum value, T data ) ;

GetClipPlane  always returns four double-precision values in eqn; these are the coefficients of the plane equation of plane in eye coordinates (these coordinates are those that were computed when the plane was specified).

GetLight  places information about value (a symbolic constant) for light (also a symbolic constant) in data. POSITION or SPOT_DIRECTION returns values in eye coordinates (again, these are the coordinates that were computed when the position or direction was specified).

GetMaterial , GetTexGen , GetTexEnv , and GetTexParameter  are similar to GetLight , placing information about value for the target indicated by their first argument into data. The face argument to GetMaterial  must be either FRONT or BACK, indicating the front or back material, respectively. The env argument to GetTexEnv  must currently be TEXTURE_ENV. The coord argument to GetTexGen  must be one of S, T, R, or Q. For GetTexGen , EYE_LINEAR coefficients are returned in the eye coordinates that were computed when the plane was specified; OBJECT_LINEAR coefficients are returned in object coordinates.

For GetTexParameter  and GetTexLevelParameter , target must currently be TEXTURE_1D or TEXTURE_2D, indicating the currently bound one-dimensional or two-dimensional texture object, or PROXY_TEXTURE_1D or PROXY_TEXTURE_2D, indicating the one-dimensional or two-dimensional proxy state vector. value is a symbolic value indicating which texture parameter is to be obtained. The lod argument to GetTexLevelParameter  determines which level-of-detail's state is returned. If the lod argument is less than zero or if it is larger than the maximum allowable level-of-detail then the error INVALID_VALUE occurs. Queries of TEXTURE_RED_SIZE, TEXTURE_GREEN_SIZE, TEXTURE_BLUE_SIZE, TEXTURE_ALPHA_SIZE, TEXTURE_LUMINANCE_SIZE, and TEXTURE_INTENSITY_SIZE return the actual resolutions of the stored image array components, not the resolutions specified when the image array was defined. Queries of TEXTURE_WIDTH, TEXTURE_HEIGHT, and TEXTURE_BORDER return the width, height, and border as specified when the image array was created. The internal format of the image array is queried as TEXTURE_INTERNAL_FORMAT, or as TEXTURE_COMPONENTS for compatibility with GL version 1.0.

For GetPixelMap , the map must be a map name from Table 3.3. For GetMap , map must be one of the map types described in section 5.1, and value must be one of ORDER, COEFF, or DOMAIN.

GetTexImage  is used to obtain texture images.

void GetTexImage ( enum tex, int lod, enum format, enum type, void *img ) ;

It is somewhat different from the other get commands; tex is a symbolic value indicating which texture is to be obtained. TEXTURE_1D indicates a one-dimensional texture, while TEXTURE_2D indicates a two-dimensional texture. lod is a level-of-detail number, format is a pixel format from Table 3.5, type is a pixel type from Table 3.4, and *img is a pointer to a block of memory. GetTexImage  obtains component groups from a texture image with the indicated level-of-detail. The components are assigned among R, G, B, and A according to Table 6.1, starting with the first group in the first row, and continuing by obtaining groups in order from each row and proceeding from the first row to the last. These groups are then packed and placed in client memory as described in section 4.3.2 under ReadPixels . The row length and number of rows is determined by the size of the texture image (including any borders). Calling GetTexImage  with lod less than zero or larger than the maximum allowable causes the error INVALID_VALUE. Calling GetTexImage  with format of COLOR_INDEX, STENCIL_INDEX, or DEPTH_COMPONENT causes the error INVALID_ENUM.

  
Table 6.1: Texture return values. , , , , , and are texture array values that are assigned to pixel values R, G, B, and A.

The command

boolean IsTexture ( uint texture ) ;

returns TRUE if texture is the name of a texture object. If texture is zero, or is a non-zero value that is not the name of a texture object, or if an error condition occurs, IsTexture  returns FALSE. A name returned by GenTextures , but not yet bound, is not the name of a texture object.

The command

void GetPolygonStipple ( void *pattern ) ;

obtains the polygon stipple. The pattern is packed into memory according to the procedure given in section 4.3.2 for ReadPixels ; it is as if the height and width passed to that command were both equal to 32, the type were BITMAP, and the format were COLOR_INDEX.

The command

void GetPointerv ( enum pname, void **params ) ;

obtains the pointer or pointers named pname in the array params. The possible values for pname are SELECTION_BUFFER_POINTER, FEEDBACK_BUFFER_POINTER, VERTEX_ARRAY_POINTER, NORMAL_ARRAY_POINTER, COLOR_ARRAY_POINTER, INDEX_ARRAY_POINTER, TEXTURE_COORD_ARRAY_POINTER, and EDGE_FLAG_ARRAY_POINTER. Each returns a single pointer value.

Finally,

ubyte *GetString ( enum name ) ;

returns a pointer to a static string describing some aspect of the current GL connection. The possible values for name are VENDOR, RENDERER, VERSION, and EXTENSIONS. The format of the RENDERER and VERSION strings is implementation dependent. The EXTENSIONS string contains a space separated list of extension names (The extension names themselves do not contain any spaces); the VERSION string is laid out as follows:

<version number><space><vendor-specific information>

The version number is either of the form major_number.minor_number or major_number.minor_number.release_number, where the numbers all have one or more digits. The vendor specific information is optional. However, if it is present then it pertains to the server and the format and contents are implementation dependent.

GetString  returns the version number (returned in the VERSION string) and the extension names (returned in the EXTENSIONS string) that can be supported on the connection. Thus, if the client and server support different versions and/or extensions, a compatible version and list of extensions is returned.

The tables on the following pages indicate which state variables are obtained with what commands. State variables that can be obtained using any of GetBooleanv , GetIntegerv , GetFloatv , or GetDoublev  are listed with just one of these commands -- the one that is most appropriate given the type of the data to be returned. These state variables cannot be obtained using IsEnabled . However, state variables for which IsEnabled  is listed as the query command can also be obtained using GetBooleanv , GetIntegerv , GetFloatv , and GetDoublev . State variables for which any other command is listed as the query command can be obtained only by using that command.

Unless otherwise indicated, multi-valued state variables return their multiple values in the same order as they are given as arguments to the commands that set them. For instance, the two DepthRange  parameters are returned in the order n followed by f. Similarly, points for evaluator maps are returned in the order that they appeared when passed to Map1 . Map2  returns in the th block of values (see page for i, j, uorder, and ).

Besides providing a means to obtain the values of state variables, the GL also provides a means to save and restore groups of state variables. The PushAttrib , PushClientAttrib , PopAttrib  and PopClientAttrib  commands are used for this purpose. The commands

void PushAttrib ( bitfield mask ) ;
void PushClientAttrib ( bitfield mask ) ;

take a bitwise OR of symbolic constants indicating which groups of state variables to push onto an attribute stack. PushAttrib  uses a server attribute stack while PushClientAttrib  uses a client attribute stack. Each constant refers to a group of state variables. The classification of each variable into a group is indicated in the following tables of state variables. The error STACK_OVERFLOW is generated if PushAttrib  or PushClientAttrib  is executed while the corresponding stack depth is MAX_ATTRIB_STACK_DEPTH or MAX_CLIENT_ATTRIB_STACK_DEPTH respectively. The commands

void PopAttrib ( void ) ;
void PopClientAttrib ( void ) ;

reset the values of those state variables that were saved with the last corresponding PushAttrib  or PopClientAttrib . Those not saved remain unchanged. The error STACK_UNDERFLOW is generated if PopAttrib  or PopClientAttrib  is executed while the respective stack is empty.

Table 6.2 shows the attribute groups with their corresponding symbolic constant names and stacks.

  
Table 6.2: Attribute groups

When PushAttrib  is called with TEXTURE_BIT set, the priorities, border colors, filter modes, and wrap modes of the currently bound texture objects, as well as the current texture bindings and enables, are pushed onto the attribute stack. (Unbound texture objects are not pushed or restored.) When an attribute set that includes texture information is popped, the bindings and enables are first restored to their pushed values, then the bound texture objects' priorities, border colors, filter modes, and wrap modes are restored to their pushed values.

The depth of each attribute stack is implementation dependent but must be at least 16. The state required for each attribute stack is potentially 16 copies of each state variable, 16 masks indicating which groups of variables are stored in each stack entry, and an attribute stack pointer. In the initial state, both attribute stacks are empty.

In the tables that follow, a type is indicated for each variable. Table 6.3 explains these types. The type actually identifies all state associated with the indicated description; in certain cases only a portion of this state is returned. This is the case with all matrices, where only the top entry on the stack is returned; with clip planes, where only the selected clip plane is returned, with parameters describing lights, where only the value pertaining to the selected light is returned; with textures, where only the selected texture or texture parameter is returned; and with evaluator maps, where only the selected map is returned. Finally, a ``--'' in the attribute column indicates that the indicated value is not included in any attribute group (and thus can not be pushed or popped with PushAttrib , PushClientAttrib , PopAttrib , or PopClientAttrib ).

  
Table 6.3: State variable types

GL Internal begin-end state variables (inaccessible)

 [IMAGE ]
Table 6.4: GL Internal begin-end state variables (inaccessible)

Current Values and Associated Data

 [IMAGE ]
Table 6.5: Current Values and Associated Data

Vertex Array Data

 [IMAGE ]
Table 6.6: Vertex Array Data

Transformation state

 [IMAGE ]
Table 6.7: Transformation state

Coloring

 [IMAGE ]
Table 6.8: Coloring

Lighting (see also Table 2.5 for defaults)

 [IMAGE ]
Table 6.9: Lighting (see also Table 2.5 for defaults)

Rasterization

 [IMAGE ]
Table 6.10: Rasterization

Texture Objects

 [IMAGE ]
Table 6.11: Texture Objects

Texture Environment and Generation

 [IMAGE ]
Table 6.12: Texture Environment and Generation

Pixel Operations

 [IMAGE ]
Table 6.13: Pixel Operations

Framebuffer Control

 [IMAGE ]
Table 6.14: Framebuffer Control

Pixels

 [IMAGE ]
Table 6.15: Pixels

Pixels (cont.)

 [IMAGE ]
Table 6.16: Pixels (cont.)

Evaluators ( GetMap takes a map name)

 [IMAGE ]
Table 6.17: Evaluators ( GetMap takes a map name)

Hints

 [IMAGE ]
Table 6.18: Hints

Implementation Dependent Values

 [IMAGE ]
Table 6.19: Implementation Dependent Values

More Implementation Dependent Values

 [IMAGE ]
Table 6.20: More Implementation Dependent Values

Implementation Dependent Pixel Depths

 [IMAGE ]
Table 6.21: Implementation Dependent Pixel Depths

Miscellaneous

 [IMAGE ]
Table 6.22: Miscellaneous