GLBEGINQUERY(3G)

NAME
glBeginQuery - delimit the boundaries of a query object

C SPECIFICATION

void glBeginQuery(GLenum target, GLuint id);

PARAMETERS

target
    Specifies the target type of query object established between glBeginQuery and the subsequent glEndQuery(). The symbolic constant must be GL_SAMPLES_PASSED.

id
    Specifies the name of a query object.

C SPECIFICATION

void glEndQuery(GLenum target);

PARAMETERS

target
    Specifies the target type of query object to be concluded. The symbolic constant must be GL_SAMPLES_PASSED.

DESCRIPTION

glBeginQuery and glEndQuery() delimit the boundaries of a query object. If a query object with name id does not yet exist it is created.

When glBeginQuery is executed, the query object's samples-passed counter is reset to 0. Subsequent rendering will increment the counter once for every sample that passes the depth test. When glEndQuery is executed, the samples-passed counter is assigned to the query object's result value. This value can be queried by calling glGetQueryObject() with pname GL_QUERY_RESULT.

Querying the GL_QUERY_RESULT implicitly flushes the GL pipeline until the rendering delimited by the query object has completed and the result is available. GL_QUERY_RESULT_AVAILABLE can be queried to determine if the result is immediately available or if the rendering is not yet complete.

NOTES

If the samples-passed count exceeds the maximum value representable in the number of available bits, as reported by glGetQueryiv() with pname GL_QUERY_COUNTER_BITS, the count becomes undefined.

An implementation may support 0 bits in its samples-passed counter, in which case query results are always undefined and essentially useless.

When GL_SAMPLE_BUFFERS is 0, the samples-passed counter will increment once for each fragment that passes the depth test. When GL_SAMPLE_BUFFERS is 1, an implementation may either increment the samples-passed counter individually for each sample of a fragment that passes the depth test, or it may choose to increment the counter for all samples of a fragment if any one of them passes the depth test.

glBeginQuery and glEndQuery() are available only if the GL version is 1.5 or greater.

ERRORS

GL_INVALID_ENUM is generated if target is not GL_SAMPLES_PASSED.

GL_INVALID_OPERATION is generated if glBeginQuery is executed while a query object of the same target is already active.

GL_INVALID_OPERATION is generated if glEndQuery() is executed when a query object of the same target is not active.

GL_INVALID_OPERATION is generated if id is 0.

GL_INVALID_OPERATION is generated if id is the name of an already active query object.

GL_INVALID_OPERATION is generated if glBeginQuery or glEndQuery() is executed between the execution of glBegin() and the corresponding execution of glEnd().

SEE ALSO

glDeleteQueries(), glGenQueries(), glGetQueryiv(), glGetQueryObject(), glIsQuery()

COPYRIGHT

Copyright © 2005 Addison-Wesley. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.