Chapter 6

State and State Requests

The state required to describe the GL machine is enumerated in section 6.2. Most state is set through the calls described in previous chapters, and can be queried using the calls described in section 6.1.

6.1Querying GL State

6.1.1 Simple Queries

Much of the GL state is completely identified by symbolic constants. The values of these 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 a scalar or 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.

244

6.1.2 Data Conversions

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 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 [−1, 1] converts to an undefined value. If GetFloatv is called, a boolean value is interpreted as either 1.0 or 0.0, 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.

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 Rij in the [(uorder)i + j]th block of values (see page 228 for i, j, uorder, and Rij).

Matrices may be queried and returned in transposed form by calling GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev with pname set to one of TRANSPOSE MODELVIEW MATRIX, TRANSPOSE PROJECTION MATRIX,

TRANSPOSE TEXTURE MATRIX, or TRANSPOSE COLOR MATRIX. The effect of

GetFloatv(TRANSPOSE MODELVIEW MATRIX,m);

is the same as the effect of the command sequence

GetFloatv(MODELVIEW MATRIX,m); m = mT ;

Similar conversions occur when querying TRANSPOSE PROJECTION MATRIX,

TRANSPOSE TEXTURE MATRIX, and TRANSPOSE COLOR MATRIX.

Most texture state variables are qualified by the value of ACTIVE TEXTURE

Version 2.0 - October 22, 2004

units (namely, TexGen state and enables, and matrices) will generate an INVALID OPERATION error if the value of ACTIVE TEXTURE is greater than or equal to MAX TEXTURE COORDS. All other texture state queries will result in an INVALID OPERATION error if the value of ACTIVE TEXTURE is greater than or equal to MAX COMBINED TEXTURE IMAGE UNITS.

6.1.3 Enumerated Queries

Other commands exist to obtain state variables that are identified by a category (clip plane, light, material, etc.) as well as a symbolic constant. 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{ifd}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 us f}v( enum map, T data ); void GetMap{ifd}v( enum map, enum value, T data ); void GetBufferParameteriv( enum target, 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, GetTexParameter, and GetBufferParameter 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 be either TEXTURE ENV or

Version 2.0 - October 22, 2004

TEXTURE FILTER CONTROL. 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.

GetTexParameter

parameter target may be one of TEXTURE 1D, TEXTURE 2D, TEXTURE 3D, or

TEXTURE CUBE MAP, indicating the currently bound one-, two-, three-dimensional, or cube map texture object. GetTexLevelParameter parameter target may be one of TEXTURE 1D, TEXTURE 2D, TEXTURE 3D, TEXTURE CUBE MAP POSITIVE X,

PROXY TEXTURE 3D, or PROXY TEXTURE CUBE MAP, indicating the one-, two-, or three-dimensional texture object, or one of the six distinct 2D images making up the cube map texture object or one-, two-, three-dimensional, or cube map proxy state vector. Note that TEXTURE CUBE MAP is not a valid target parameter for GetTexLevelParameter, because it does not specify a particular cube map face. value is a symbolic value indicating which texture parameter is to be obtained. For GetTexParameter, value must be either TEXTURE RESIDENT, or one of the symbolic values in table 3.19. 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

and TEXTURE INTENSITY SIZE return the actual resolutions of the stored image array components, not the resolutions specified when the image array was defined. For texture images with a compressed internal format, the resolutions returned specify the component resolution of an uncompressed internal format that produces an image of roughly the same quality as the compressed image in question. Since the quality of the implementation’s compression algorithm is likely data-dependent, the returned component sizes should be treated only as rough approximations.

an uncompressed internal format or on proxy targets and will result in an INVALID OPERATION error if attempted.

Version 2.0 - October 22, 2004