glBeginQuery — delimit the boundaries of a query object
void glBeginQuery( | GLenum target, |
GLuint id) ; |
target
Specifies the target type of query object established between
glBeginQuery
and the subsequent glEndQuery.
The symbolic constant must be one of GL_SAMPLES_PASSED
, GL_ANY_SAMPLES_PASSED
,
GL_ANY_SAMPLES_PASSED_CONSERVATIVE
,
GL_PRIMITIVES_GENERATED
, GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN
, or
GL_TIME_ELAPSED
.
id
Specifies the name of a query object.
void glEndQuery( | GLenum target) ; |
target
Specifies the target type of query object to be concluded.
The symbolic constant must be one of GL_SAMPLES_PASSED
, GL_ANY_SAMPLES_PASSED
,
GL_ANY_SAMPLES_PASSED_CONSERVATIVE
,
GL_PRIMITIVES_GENERATED
, GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN
, or
GL_TIME_ELAPSED
.
glBeginQuery
and glEndQuery delimit the
boundaries of a query object. query
must be a name previously returned from a call to
glGenQueries. If a query object with name id
does not yet exist it is created with the type determined by target
. target
must
be one of GL_SAMPLES_PASSED
, GL_ANY_SAMPLES_PASSED
, GL_PRIMITIVES_GENERATED
,
GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN
, or GL_TIME_ELAPSED
. The behavior of the query
object depends on its type and is as follows.
If target
is GL_SAMPLES_PASSED
, id
must be an unused name,
or the name of an existing occlusion query object.
When glBeginQuery
is executed, the query object's samples-passed counter is reset to 0. Subsequent
rendering will increment the counter for every sample that passes the depth test. If the value of GL_SAMPLE_BUFFERS
is 0, then the samples-passed count is incremented by 1 for each fragment. If the value of GL_SAMPLE_BUFFERS
is 1, then the samples-passed count is incremented by the number of samples whose coverage bit is set. However, implementations, at their
discression may instead increase the samples-passed count by the value of GL_SAMPLES
if any sample in the fragment
is covered. 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
.
If target
is GL_ANY_SAMPLES_PASSED
or GL_ANY_SAMPLES_PASSED_CONSERVATIVE
,
id
must be an unused name, or the name of an existing boolean occlusion query object.
When glBeginQuery
is executed, the query object's samples-passed flag is reset to GL_FALSE
.
Subsequent rendering causes the flag to be set to GL_TRUE
if any sample passes the depth test in the case of GL_ANY_SAMPLES_PASSED
,
or if the implementation determines that any sample might pass the depth test in the case of GL_ANY_SAMPLES_PASSED_CONSERVATIVE
.
The implementation may be able to provide a more efficient test in the case of GL_ANY_SAMPLES_PASSED_CONSERVATIVE
if some false positives are acceptable to the application. When
glEndQuery
is executed, the samples-passed flag is assigned to the query object's result value. This value can
be queried by calling glGetQueryObject with pname
GL_QUERY_RESULT
.
If target
is GL_PRIMITIVES_GENERATED
, id
must be an unused
name, or the name of an existing primitive query object previously bound to the GL_PRIMITIVES_GENERATED
query binding.
When glBeginQuery
is executed, the query object's primitives-generated counter is reset to 0. Subsequent
rendering will increment the counter once for every vertex that is emitted from the geometry shader, or from the vertex shader if
no geometry shader is present. When glEndQuery
is executed, the primitives-generated counter is assigned to
the query object's result value. This value can be queried by calling glGetQueryObject with pname
GL_QUERY_RESULT
.
If target
is GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN
, id
must be
an unused name, or the name of an existing primitive query object previously bound to the GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN
query binding. When glBeginQuery
is executed, the query object's primitives-written counter is reset to 0. Subsequent
rendering will increment the counter once for every vertex that is written into the bound transform feedback buffer(s). If transform feedback
mode is not activated between the call to glBeginQuery
and glEndQuery
, the counter will not be
incremented. When glEndQuery
is executed, the primitives-written counter is assigned to
the query object's result value. This value can be queried by calling glGetQueryObject with pname
GL_QUERY_RESULT
.
If target
is GL_TIME_ELAPSED
, id
must be
an unused name, or the name of an existing timer query object previously bound to the GL_TIME_ELAPSED
query binding. When glBeginQuery
is executed, the query object's time counter is reset to 0. When glEndQuery
is executed, the elapsed server time that has passed since the call to glBeginQuery
is written into the query object's
time counter. 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.
If the query target's count exceeds the maximum value representable in the number of available bits, as reported by
glGetQueryiv with target
set to the
appropriate query target and pname
GL_QUERY_COUNTER_BITS
, the count becomes undefined.
An implementation may support 0 bits in its counter, in which case query results are always undefined and essentially useless.
When GL_SAMPLE_BUFFERS
is 0, the samples-passed counter of an occlusion query 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.
The query targets GL_ANY_SAMPLES_PASSED
, and GL_TIME_ELAPSED
are availale only if
the GL version is 3.3 or higher.
The query target GL_ANY_SAMPLES_PASSED_CONSERVATIVE
is available only of the GL version is 4.3 or higher.
GL_INVALID_ENUM
is generated if target
is not one of the accepted tokens.
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 id
refers to an existing query object whose type
does not does not match target
.
Copyright © 2005 Addison-Wesley. Copyright © 2010-2012 Khronos Group. 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/.