6.1.9 Histogram Query

The current contents of the histogram table are queried using

void GetHistogram( enum target, boolean reset, enum format, enum type, void* values );

target must be HISTOGRAM. type and format accept the same values as do the corresponding parameters of GetTexImage. The one-dimensional histogram table image is returned to values. Pixel processing and component mapping are identical to those of GetTexImage, except that instead of applying the Final Conversion pixel storage mode, component values are simply clamped to the range of the target data type.

If reset is TRUE, then all counters of all elements of the histogram are reset to zero. Counters are reset whether returned or not.

No counters are modified if reset is FALSE. Calling

void ResetHistogram( enum target );

resets all counters of all elements of the histogram table to zero. target must be

HISTOGRAM.

It is not an error to reset or query the contents of a histogram table with zero entries.

The functions

void GetHistogramParameter{if}v( enum target, enum pname, T params );

are used for integer and floating point query. target must be HISTOGRAM or

PROXY HISTOGRAM. pname is one of HISTOGRAM FORMAT, HISTOGRAM WIDTH,

parameter is returned in params.

6.1.10 Minmax Query

The current contents of the minmax table are queried using

void GetMinmax( enum target, boolean reset, enum format, enum type, void* values );

Version 2.0 - October 22, 2004

target must be MINMAX. type and format accept the same values as do the corresponding parameters of GetTexImage. A one-dimensional image of width 2 is returned to values. Pixel processing and component mapping are identical to those of GetTexImage.

If reset is TRUE, then each minimum value is reset to the maximum representable value, and each maximum value is reset to the minimum representable value. All values are reset, whether returned or not.

No values are modified if reset is FALSE. Calling

void ResetMinmax( enum target );

resets all minimum and maximum values of target to to their maximum and minimum representable values, respectively, target must be MINMAX.

The functions

void GetMinmaxParameter{if}v( enum target, enum pname, T params );

are used for integer and floating point query. target must be MINMAX. pname is MINMAX FORMAT or MINMAX SINK. The value of the specified parameter is returned in params.

6.1.11 Pointer and String Queries

The command

EDGE FLAG ARRAY POINTER. Each returns a single pointer value. Finally,

ubyte *GetString( enum name );

Version 2.0 - October 22, 2004

returns a pointer to a static string describing some aspect of the current GL connection1. The possible values for name are VENDOR, RENDERER, VERSION,

SHADING LANGUAGE VERSION, and EXTENSIONS. The format of the RENDERER and VENDOR 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 and SHADING LANGUAGE VERSION strings are 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 release number and vendor specific information are optional. However, if present, then they pertain to the server and their 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.

6.1.12 Occlusion Queries

The command

boolean IsQuery( uint id );

returns TRUE if id is the name of a query object. If id is zero, or if id is a non-zero value that is not the name of a query object, IsQuery returns FALSE.

Information about a query target can be queried with the command

void GetQueryiv( enum target, enum pname, int *params );

If pname is CURRENT QUERY, the name of the currently active query for target, or zero if no query is active, will be placed in params.

If pname is QUERY COUNTER BITS, the number of bits in the counter for target will be placed in params. The number of query counter bits may be zero, in which case the counter contains no useful information. Otherwise, the minimum number

1Applications making copies of these static strings should never use a fixed-length buffer, because the strings may grow unpredictably between releases, resulting in buffer overflow when copying. This is particularly true of the EXTENSIONS string, which has become extremely long in some GL implementations.

Version 2.0 - October 22, 2004

of bits allowed is a function of the implementation’s maximum viewport dimensions (MAX VIEWPORT DIMS). In this case, the counter must be able to represent at least two overdraws for every pixel in the viewport The formula to compute the allowable minimum value (where n is the minimum number of bits) is:

n = min{32, dlog2(maxV iewportW idth maxV iewportHeight 2)e}

The state of a query object can be queried with the commands

void GetQueryObjectiv( uint id, enum pname, int *params );

void GetQueryObjectuiv( uint id, enum pname, uint *params );

If id is not the name of a query object, or if the query object named by id is currently active, then an INVALID OPERATION error is generated.

If pname is QUERY RESULT, then the query object’s result value is placed in params. If the number of query counter bits for target is zero, then the result value is always 0.

There may be an indeterminate delay before the above query returns. If pname is QUERY RESULT AVAILABLE, it immediately returns FALSE if such a delay would be required, TRUE otherwise. It must always be true that if any query object returns result available of TRUE, all queries issued prior to that query must also return TRUE.

Querying the state for any given query object forces that occlusion query to complete within a finite amount of time.

If multiple queries are issued on the same target and id prior to calling GetQueryObject[u]iv, the result returned will always be from the last query issued. The results from any queries before the last one will be lost if the results are not retrieved before starting a new query on the same target and id.

6.1.13 Buffer Object Queries

The command

boolean IsBuffer( uint buffer );

returns TRUE if buffer is the name of an buffer object. If buffer is zero, or if buffer is a non-zero value that is not the name of an buffer object, IsBuffer returns FALSE.

The command

Version 2.0 - October 22, 2004