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 one of
GL_SAMPLES_PASSED, GL_ANY_SAMPLES_PASSED,
GL_PRIMITIVES_GENERATED,
GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN, or
GL_TIME_ELAPSED.
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 one of GL_SAMPLES_PASSED,
GL_ANY_SAMPLES_PASSED, GL_PRIMITIVES_GENERATED,
GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN, or
GL_TIME_ELAPSED.
DESCRIPTION¶
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,
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. 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.
NOTES¶
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.
ERRORS¶
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.
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/.