GLBEGINCONDITIONALRE(3G)

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

💅 GLBEGINCONDITIONALRE(3G) — glBeginConditionalRender

okay bestie, so this is a page from the 3G manual section, and it's literally about conditional rendering — like, rendering that only happens if a query says it should. main character energy for your draw calls, no cap. ✨

🎀 NAME

glBeginConditionalRender — start conditional rendering. that's it, that's the name, periodt. 💖

🦋 C SPECIFICATION

both functions, together, exactly like this:

void glBeginConditionalRender(GLuint id, GLenum mode);

void glEndConditionalRender(void);

🌸 PARAMETERS FOR GLBEGINCONDITIONALRENDER

  • id — the name of an occlusion query object. the results of that query are what decide whether your rendering commands get discarded or not. so like, the query is the vibe check 👑
  • mode — tells glBeginConditionalRender how to interpret the results of that occlusion query. iykyk.

✨ DESCRIPTION

so conditional rendering gets started with glBeginConditionalRender and ended with glEndConditionalRender. simple. during conditional rendering, all vertex array commands, plus glClear() and glClearBuffer(), have literally no effect if the GL_SAMPLES_PASSED result of the query object id is zero, or if the GL_ANY_SAMPLES_PASSED result is GL_FALSE. poof, gone. 🫶

heads up: the results of commands that set the current vertex state — things like glVertexAttrib() — are undefined during this. not "zero", not "whatever", undefined. so don't come for me. 😭

if the GL_SAMPLES_PASSED result is non-zero, or if the GL_ANY_SAMPLES_PASSED result is GL_TRUE, then those commands are not discarded. slay. ✨

the id parameter you pass to glBeginConditionalRender must be the name of a query object that was previously returned from a call to glGenQueries(). no making up names, bestie.

mode is the whole how-do-we-read-this-query thing:

  • GL_QUERY_WAIT — the GL waits for the query results to be available, then uses those results to determine if the subsequent rendering commands get discarded. patient icon.
  • GL_QUERY_NO_WAIT — the GL may choose to unconditionally execute the subsequent rendering commands without waiting for the query to complete. impatient icon, honestly valid.
  • GL_QUERY_BY_REGION_WAIT — the GL also waits for the occlusion query results and discards rendering commands if the result of the occlusion query is zero. if the query result is non-zero, the subsequent rendering commands are executed, but the GL may discard the results of the commands for any region of the framebuffer that did not contribute to the sample count in the specified occlusion query. any such discarding is done in an implementation-dependent manner, but the rendering command results may not be discarded for any samples that contributed to the occlusion query sample count. so it's per-region selective about it. 💅
  • GL_QUERY_BY_REGION_NO_WAIT — the GL operates as in GL_QUERY_BY_REGION_WAIT, but it may choose to unconditionally execute the subsequent rendering commands without waiting for the query to complete.

🧚 NOTES

  • glBeginConditionalRender and glEndConditionalRender are available only if the GL version is 3.0 or greater. so if you're on 2.x, sad. 🙈
  • the GL_ANY_SAMPLES_PASSED query result is available only if the GL version is 3.3 or greater.

💀 ERRORS

like, so many ways to fumble this. let's go:

  • GL_INVALID_VALUE is generated if id is not the name of an existing query object.
  • GL_INVALID_ENUM is generated if mode is not one of the accepted tokens.
  • GL_INVALID_OPERATION is generated if glBeginConditionalRender is called while conditional rendering is already active, or if glEndConditionalRender is called while conditional rendering is inactive. (yes, both directions are a problem. balance. 🌈)
  • GL_INVALID_OPERATION is generated if id is the name of a query object with a target other than GL_SAMPLES_PASSED or GL_ANY_SAMPLES_PASSED.
  • GL_INVALID_OPERATION is generated if id is the name of a query that's currently in progress. not finished? not allowed. 🍓

👑 VERSION SUPPORT

the original ships this as a big grid, so here's the same tea, un-gridded, because tables are not the vibe in a terminal:

  • glBeginConditionalRender — 2.0: -, 2.1: -, 3.0: ✔, 3.1: ✔, 3.2: ✔, 3.3: ✔, 4.0: ✔, 4.1: ✔, 4.2: ✔, 4.3: ✔, 4.4: ✔, 4.5: ✔
  • glEndConditionalRender — 2.0: -, 2.1: -, 3.0: ✔, 3.1: ✔, 3.2: ✔, 3.3: ✔, 4.0: ✔, 4.1: ✔, 4.2: ✔, 4.3: ✔, 4.4: ✔, 4.5: ✔

so basically: everything from 3.0 on, and absolutely nothing before. ⭐

🔥 SEE ALSO

go read these next, they're the friend group:

  • glGenQueries()
  • glDeleteQueries()
  • glBeginQuery()

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 © 2010-2014 Khronos Group

okay that's the whole page, you ate that 🫶 this was <rainbow>[FIXME: source]</rainbow> on 08/09/2021, and yes the header still says GLBEGINCONDITIONALRE(3G) and the manual tag was still [FIXME: manual] — we keep the FIXMEs, they're iconic at this point. bye bestie, go render conditionally 💅🎀

📦 where this page comes from