2005
Sams Publishing
glBeginQuery
3G

# 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/.