GLBEGINQUERY(3G)

📦
version 1.1 · 7 versions
, in centos-stream 9

💅 glBeginQuery(3G) — the query-boundaries glow-up

ok so this is the 3G manual page for glBeginQuery / glEndQuery, and bestie, it's literally the "start the stopwatch / stop the stopwatch" of OpenGL queries. Stay with me, it's gonna slay. 🎀

✨ 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 — tells everyone what kind of query object we're setting up between glBeginQuery and the glEndQuery that comes right after it. This symbolic constant has to 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 — the name of a query object. like, its whole identity 💅

✨ PARAMETERS FOR GLENDQUERY ✨

  • target — tells everyone what kind of query object we're wrapping up now. This symbolic constant has to 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. the query has to be a name that came back from an earlier call to glGenQueries(), no cap. and if a query object with name id doesn't exist yet? it literally gets created on the spot with the type that target decides. 👑

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 it goes a little something like this:

🦋 when target is GL_SAMPLES_PASSED

id must be an unused name, or the name of an existing occlusion query object. when glBeginQuery runs, the query object's samples-passed counter gets reset to 0. after that, rendering bumps the counter for every sample that passes the depth test. here's the vibe check:

  • if GL_SAMPLE_BUFFERS is 0, then the samples-passed count goes up by 1 for each fragment.
  • if GL_SAMPLE_BUFFERS is 1, then the samples-passed count goes up by the number of samples whose coverage bit is set. but — and this is the messy part — 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 runs, the samples-passed counter gets assigned to the query object's result value. you can query that value by calling glGetQueryObject() with pname GL_QUERY_RESULT.

🦋 when 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 runs, the query object's samples-passed flag gets reset to GL_FALSE. then rendering causes the flag to be set to GL_TRUE:

  • if any sample passes the depth test — that's the GL_ANY_SAMPLES_PASSED case.
  • if the implementation determines that any sample might pass the depth test — that's the GL_ANY_SAMPLES_PASSED_CONSERVATIVE case.

the implementation may be able to provide a more efficient test in the GL_ANY_SAMPLES_PASSED_CONSERVATIVE case if some false positives are acceptable to the application. trade-offs, we love them. ✨

when glEndQuery runs, the samples-passed flag gets assigned to the query object's result value, and you can query that value with glGetQueryObject() and pname GL_QUERY_RESULT.

🦋 when target is GL_PRIMITIVES_GENERATED

id must be an unused name, or the name of an existing primitive query object that was previously bound to the GL_PRIMITIVES_GENERATED query binding. when glBeginQuery runs, the query object's primitives-generated counter gets reset to 0. after that, rendering increments the counter once for every vertex that's emitted from the geometry shader — or from the vertex shader if there's no geometry shader in the picture. when glEndQuery runs, the primitives-generated counter gets assigned to the query object's result value, and yeah, glGetQueryObject() with pname GL_QUERY_RESULT is how you grab it. 💖

🦋 when target is GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN

id must be an unused name, or the name of an existing primitive query object that was previously bound to the GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN query binding. when glBeginQuery runs, the query object's primitives-written counter gets reset to 0. after that, rendering increments the counter once for every vertex that's written into the bound transform feedback buffer(s). 🫧 important: if transform feedback mode is not activated between the call to glBeginQuery and glEndQuery, the counter will not be incremented. like, at all. when glEndQuery runs, the primitives-written counter gets assigned to the query object's result value, queryable via glGetQueryObject() with pname GL_QUERY_RESULT.

🦋 when target is GL_TIME_ELAPSED

id must be an unused name, or the name of an existing timer query object that was previously bound to the GL_TIME_ELAPSED query binding. when glBeginQuery runs, the query object's time counter gets reset to 0. when glEndQuery runs, the elapsed server time that has passed since the call to glBeginQuery gets written into the query object's time counter. that value can be queried by calling glGetQueryObject() with pname GL_QUERY_RESULT. ⏱️

🧚 the flush tea

querying 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. iykyk. 💅

💀 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. literally giving nothing. 🫠
  • when GL_SAMPLE_BUFFERS is 0, the samples-passed counter of an occlusion query increments 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. (one at a time, bestie!!)
  • 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 👑

(the original is a whole table, so here it is laid out as the vibe-check list it truly is ✨ — the columns were the OpenGL versions and every single cell is a checkmark, okay?)

glBeginQuery is supported in: 2.0 ✔, 2.1 ✔, 3.0 ✔, 3.1 ✔, 3.2 ✔, 3.3 ✔, 4.0 ✔, 4.1 ✔, 4.2 ✔, 4.3 ✔, 4.4 ✔, 4.5 ✔

glEndQuery is supported in: 2.0 ✔, 2.1 ✔, 3.0 ✔, 3.1 ✔, 3.2 ✔, 3.3 ✔, 4.0 ✔, 4.1 ✔, 4.2 ✔, 4.3 ✔, 4.4 ✔, 4.5 ✔

like... every OpenGL version in the Function / Feature Name vs OpenGL Version grid said yes. periodt. 💅🌈

🍓 SEE ALSO 🍓

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

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 © 2005 Sams Publishing Copyright © 2010-2014 Khronos Group

ok that's the whole page, you ate that 🫶 source slot was stuck at [FIXME: source] and the date said 08/09/2021 — iconic of the docs team honestly, go off besties 💖✨🎀

📦 where this page comes from