Provided by: opengl-4-man-doc_1.0~svn33624-1_all bug

NAME

       glBeginQuery - delimit the boundaries of a query object

C SPECIFICATION

       void glBeginQuery(GLenum target, GLuint id);

       void glEndQuery(GLenum target);

PARAMETERS FOR GLBEGINQUERY

       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.

PARAMETERS FOR GLENDQUERY

       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.

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

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.

       The query target GL_ANY_SAMPLES_PASSED_CONSERVATIVE is available only of the GL version is
       4.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.

VERSION SUPPORT

       ┌─────────────┬───────────────────────────────────────────────────────────────────────┐
       │             │                OpenGL Version                                         │
       ├─────────────┼─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┤
       │Function2.02.13.03.13.23.34.04.14.24.34.44.5 │
       │/            │     │     │     │     │     │     │     │     │     │     │     │     │
       │Feature      │     │     │     │     │     │     │     │     │     │     │     │     │
       │Name         │     │     │     │     │     │     │     │     │     │     │     │     │
       ├─────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
       │glBeginQuery │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │
       ├─────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
       │glEndQuery   │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │
       └─────────────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘

SEE ALSO

       glBeginQueryIndexed(), glDeleteQueries(),

       glEndQuery, glGenQueries(), glGetQueryObject(), glGetQueryiv(), glIsQuery()

COPYRIGHT

       Copyright © 2005 Addison-Wesley. Copyright © 2010-2014 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/.

COPYRIGHT

       Copyright © 2005 Sams Publishing
       Copyright © 2010-2014 Khronos Group

[FIXME: source]                             01/03/2018                           GLBEGINQUERY(3G)