NAME¶
glBeginQueryIndexed,_glEndQueryIndexed - delimit the boundaries of a query
object on an indexed target
C SPECIFICATION¶
void
glBeginQueryIndexed(GLenum target,
GLuint index, GLuint id);
PARAMETERS¶
target
Specifies the target type of query object
established between glBeginQueryIndexed and the subsequent
glEndQueryIndexed(). 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.
index
Specifies the index of the query target upon
which to begin the query.
id
Specifies the name of a query object.
C SPECIFICATION¶
void
glEndQueryIndexed(GLenum target,
GLuint index);
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.
index
Specifies the index of the query target upon
which to end the query.
DESCRIPTION¶
glBeginQueryIndexed and
glEndQueryIndexed() 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.
index specifies the index of the query target and must be between a
target-specific maximum.
If
target is
GL_SAMPLES_PASSED,
id must be an unused name,
or the name of an existing occlusion query object. When
glBeginQueryIndexed 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
glEndQueryIndexed 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. When
target is
GL_SAMPLES_PASSED,
index must be zero.
If
target is
GL_ANY_SAMPLES_PASSED,
id must be an unused
name, or the name of an existing boolean occlusion query object. When
glBeginQueryIndexed 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
glEndQueryIndexed 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. When
target is
GL_ANY_SAMPLES_PASSED,
index must be zero.
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
glBeginQueryIndexed 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 to the stream given by
index, or from the vertex shader if
index is zero and no geometry shader is present. When
glEndQueryIndexed is executed, the primitives-generated counter for
stream
index is assigned to the query object's result value. This value
can be queried by calling
glGetQueryObject() with
pname
GL_QUERY_RESULT. When
target is
GL_PRIMITIVES_GENERATED,
index must be less than the value of
GL_MAX_VERTEX_STREAMS.
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
glBeginQueryIndexed is executed, the query object's
primitives-written counter for the stream specified by
index is reset
to 0. Subsequent rendering will increment the counter once for every vertex
that is written into the bound transform feedback buffer(s) for stream
index. If transform feedback mode is not activated between the call to
glBeginQueryIndexed and
glEndQueryIndexed, the counter will not
be incremented. When
glEndQueryIndexed is executed, the
primitives-written counter for stream
index is assigned to the query
object's result value. This value can be queried by calling
glGetQueryObject() with
pname GL_QUERY_RESULT. When
target is
GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN,
index
must be less than the value of
GL_MAX_VERTEX_STREAMS.
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
glBeginQueryIndexed is
executed, the query object's time counter is reset to 0. When
glEndQueryIndexed is executed, the elapsed server time that has passed
since the call to
glBeginQueryIndexed is written into the query
object's time counter. This value can be queried by calling
glGetQueryObject() with
pname GL_QUERY_RESULT. When
target is
GL_TIME_ELAPSED,
index must be zero.
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.
Calling
glBeginQuery() or
glEndQuery() is equivalent to calling
glBeginQueryIndexed() or
glEndQueryIndexed() with
index
set to zero, respectively.
ERRORS¶
GL_INVALID_ENUM is generated if
target is not one of the accepted
tokens.
GL_INVALID_VALUE is generated if
index is greater than the query
target-specific maximum.
GL_INVALID_OPERATION is generated if
glBeginQueryIndexed is
executed while a query object of the same
target is already active.
GL_INVALID_OPERATION is generated if
glEndQueryIndexed() 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(),
glBeginQuery(),
glEndQuery(),
glGenQueries(),
glGetQueryiv(),
glGetQueryObject(),
glIsQuery()
COPYRIGHT¶
Copyright © 2010 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/.