1Name 2 3 NV_conditional_render 4 5Name Strings 6 7 GL_NV_conditional_render 8 9Contact 10 11 Eric Werness, NVIDIA (ewerness 'at' nvidia.com) 12 Pat Brown, NVIDIA (pbrown 'at' nvidia.com) 13 14Contributors 15 16 Daniel Koch, NVIDIA 17 18Status 19 20 Shipping. 21 22Version 23 24 Last Modified Date: 05/26/2014 25 NVIDIA Revision: 6 26 27Number 28 29 OpenGL Extension #346 30 OpenGL ES Extension #198 31 32Dependencies 33 34 The extension is written against the OpenGL 2.0 Specification. 35 36 ARB_occlusion_query or OpenGL 1.5 is required in an OpenGL 37 implementation. 38 39 This extension interacts with NVX_conditional_render. 40 41 This extension interacts with ARB_occlusion_query2. 42 43 This extension interacts with ARB_ES3_compatibility. 44 45 This extension interacts trivially with the OpenGL compatibility profile. 46 47 This extension interacts with OpenGL 3.0, 3.2, 3.3, and 4.3 48 49 EXT_occlusion_query_boolean or OpenGL ES 3.0 is required in an OpenGL ES 50 implementation. 51 52 This extension interacts with EXT_occlusion_query_boolean. 53 54 This extension interacts with NV_occlusion_query_samples. 55 56 This extension interacts with OpenGL ES 3.0. 57 58Overview 59 60 This extension provides support for conditional rendering based on the 61 results of an occlusion query. This mechanism allows an application to 62 potentially reduce the latency between the completion of an occlusion 63 query and the rendering commands depending on its result. It additionally 64 allows the decision of whether to render to be made without application 65 intervention. 66 67 This extension defines two new functions, BeginConditionalRenderNV and 68 EndConditionalRenderNV, between which rendering commands may be discarded 69 based on the results of an occlusion query. If the specified occlusion 70 query returns a non-zero value, rendering commands between these calls are 71 executed. If the occlusion query returns a value of zero, all rendering 72 commands between the calls are discarded. 73 74 If the occlusion query results are not available when 75 BeginConditionalRenderNV is executed, the <mode> parameter specifies 76 whether the GL should wait for the query to complete or should simply 77 render the subsequent geometry unconditionally. 78 79 Additionally, the extension provides a set of "by region" modes, allowing 80 for implementations that divide rendering work by screen regions to 81 perform the conditional query test on a region-by-region basis without 82 checking the query results from other regions. Such a mode is useful for 83 cases like split-frame SLI, where a frame is divided between multiple 84 GPUs, each of which has its own occlusion query hardware. 85 86 87New Procedures and Functions 88 89 void BeginConditionalRenderNV(uint id, enum mode); 90 void EndConditionalRenderNV(void); 91 92 93New Tokens 94 95 Accepted by the <mode> parameter of BeginConditionalRenderNV: 96 97 QUERY_WAIT_NV 0x8E13 98 QUERY_NO_WAIT_NV 0x8E14 99 QUERY_BY_REGION_WAIT_NV 0x8E15 100 QUERY_BY_REGION_NO_WAIT_NV 0x8E16 101 102 103Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 104 105 (Incorporate the spec edits from the EXT_transform_feedback specification 106 that move the "Occlusion Queries" Section 4.1.7 -- to between Section 2.11, 107 Coordinate Transforms and Section 2.12, Clipping, and rename it to 108 "Asynchronous Queries". Insert a new section immediately after the moved 109 "Asynchronous Queries" section. If EXT_transform_feedback is incorporated, 110 this section should be inserted prior the the "Transform Feedback" 111 section.) 112 113 (also modify the BeginQuery language to disallow BeginQuery while the 114 query object is being used for conditional rendering) 115 ... 116 BeginQuery sets the active query object name for the query type given by 117 <target> to <id>. If BeginQuery is called with an <id> of zero, if the 118 active query object name for <target> is non-zero, if <id> is the active 119 query object name for any query type, or if <id> is the active query 120 object for condtional rendering (Section 2.X), the error INVALID OPERATION 121 is generated. 122 123 124 Section 2.X, Conditional Rendering 125 126 Conditional rendering can be used to discard rendering commands based on 127 the result of an occlusion query. Conditional rendering is started and 128 stopped using the commands 129 130 void BeginConditionalRenderNV(uint id, enum mode); 131 void EndConditionalRenderNV(void); 132 133 <id> specifies the name of an occlusion query object whose results are 134 used to determine if the rendering commands are discarded. If the result 135 (SAMPLES_PASSED) of the query is zero, or if the result 136 (ANY_SAMPLES_PASSED or ANY_SAMPLES_PASSED_CONSERVATIVE) is false, all 137 rendering commands between BeginConditionalRenderNV and the corresponding 138 EndConditionalRenderNV are discarded. In this case, Begin, End, all 139 vertex array commands performing an implicit Begin and End, DrawPixels 140 (section 3.6), Bitmap (section 3.7), Clear (section 4.2.3), Accum 141 (section 4.2.4), CopyPixels (section 4.3.3), EvalMesh1 and EvalMesh2 142 (section 5.1), BlitFramebuffer, ClearBuffer*, and DispatchCompute* have 143 no effect. 144 145 The effect of commands setting current vertex state (e.g., Color or 146 VertexAttrib) is undefined. If the result (SAMPLES_PASSED) of the 147 query is non-zero, or if the result (ANY_SAMPLES_PASSED or 148 ANY_SAMPLES_PASSED_CONSERVATIVE) is true, such commands are not discarded. 149 150 <mode> specifies how BeginConditionalRenderNV interprets the results of 151 the occlusion query given by <id>. If <mode> is QUERY_WAIT_NV, the GL 152 waits for the results of the query to be available and then uses the 153 results to determine if subsequent rendering commands are discarded. If 154 <mode> is QUERY_NO_WAIT_NV, the GL may choose to unconditionally execute 155 the subsequent rendering commands without waiting for the query to 156 complete. 157 158 If <mode> is QUERY_BY_REGION_WAIT_NV, the GL will also wait for occlusion 159 query results and discard rendering commands if the result of the 160 occlusion query is zero. If the query result is non-zero, subsequent 161 rendering commands are executed, but the GL may discard the results of the 162 commands for any region of the framebuffer that did not contribute to the 163 sample count in the specified occlusion query. Any such discarding is 164 done in an implementation-dependent manner, but the rendering command 165 results may not be discarded for any samples that contributed to the 166 occlusion query sample count. If <mode> is QUERY_BY_REGION_NO_WAIT_NV, 167 the GL operates as in QUERY_BY_REGION_WAIT_NV, but may choose to 168 unconditionally execute the subsequent rendering commands without waiting 169 for the query to complete. 170 171 If BeginConditionalRenderNV is called while conditional rendering is in 172 progress, or if EndConditionalRenderNV is called while conditional 173 rendering is not in progress, the error INVALID_OPERATION is generated. 174 The error INVALID_VALUE is generated if <id> is not the name of an 175 existing query object query. The error INVALID_OPERATION is generated if 176 <id> is the name of a query object with a target other than 177 SAMPLES_PASSED, ANY_SAMPLES_PASSED, or ANY_SAMPLES_PASSED_CONSERVATIVE, or 178 if <id> is the name of a query currently in progress. 179 180 181Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 182 183 None. 184 185Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 186Operations and the Frame Buffer) 187 188 None. 189 190Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 191 192 None. 193 194Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State 195Requests) 196 197 None. 198 199Additions to Appendix A of the OpenGL 2.0 Specification (Invariance) 200 201 None. 202 203Additions to the AGL/GLX/WGL Specifications 204 205 None. 206 207GLX Protocol 208 209 The following rendering commands are sent to the server as part of 210 glXRender requests: 211 212 BeginConditionalRenderNV 213 2 12 rendering command length 214 2 348 rendering command opcode 215 4 CARD32 id 216 4 ENUM mode 217 218 EndConditionalRenderNV 219 2 4 rendering command length 220 2 349 rendering command opcode 221 222Dependencies on NVX_conditional_render 223 224 NVX_conditional_render was an early version of this extension. This 225 extension provides several conditional rendering modes (QUERY_WAIT_NV, 226 QUERY_NO_WAIT_NV, QUERY_BY_REGION_WAIT_NV, QUERY_BY_REGION_NO_WAIT_NV) not 227 present in the NVX extension. The NVX extension's commands: 228 229 glBeginConditionalRenderNVX(id); 230 glEndConditionalRenderNVX(); 231 232 are equivalent to the following commands from this extension: 233 234 glBeginConditionalRenderNV(id, QUERY_WAIT_NV); 235 glEndConditionalRenderNV(); 236 237Dependencies on ARB_occlusion_query2 and OpenGL 3.3 238 239 If ARB_occlusion_query2 or OpenGL 3.3 is not supported in an OpenGL 240 implementation, ignore references to the ANY_SAMPLES_PASSED query type. 241 242Dependencies on ARB_ES3_compatibility and OpenGL 4.3 243 244 If ARB_ES3_compatibility or OpenGL 4.3 is not supported in an OpenGL 245 implementation, ignore references to the ANY_SAMPLES_PASSED_CONSERVATIVE 246 query type. 247 248Dependencies on the OpenGL compatibility profile 249 250 In contexts which support the core profile only (for GL) or OpenGL ES, 251 ignore references to the following commands: Begin, End, DrawPixels, 252 Bitmap, Accum, Color, CopyPixels, EvalMesh1 and EvalMesh2. 253 254Dependencies on OpenGL 3.0 and OpenGL ES 3.0 255 256 If OpenGL 3.0 or OpenGL ES 3.0 is not supported, ignore references to 257 the BlitFramebuffer and ClearBuffer* commands, unless provided by 258 other extensions. 259 260Dependencies on OpenGL 4.3 and OpenGL ES 3.1 261 262 If OpenGL 4.3 or OpenGL ES 3.1 is not supported, ignore references to 263 DispatchCompute* commands. 264 265Dependencies on EXT_occlusion_query_boolean and OpenGL ES 3.0 266 267 In an OpenGL ES implementation, if OpenGL ES 3.0 is not supported 268 replace references to query functionality in OpenGL ES 3.0 with 269 the query functionality provided by EXT_occlusion_query_boolean. 270 271Dependencies on NV_occlusion_query_samples 272 273 If NV_occlusion_query_samples is not supported in an OpenGL ES 274 implementation, ignore all references to SAMPLES_PASSED. 275 276 If NV_occlusion_query_samples is supported, replaces references to 277 SAMPLES_PASSED with SAMPLES_PASSED_NV. 278 279Errors 280 281 INVALID_OPERATION is generated by BeginConditionalRenderNV if a previous 282 BeginConditionalRenderNV command has been executed without a 283 corresponding EndConditionalRenderNV command. 284 285 INVALID_OPERATION is generated by EndConditionalRenderNV if no 286 corresponding BeginConditionalRenderNV command has been executed. 287 288 INVALID_VALUE is generated by BeginConditionalRenderNV if <id> is not the 289 name of an existing occlusion query object. 290 291 INVALID_OPERATION is generated by BeginConditionalRenderNV if <id> is the 292 name of a query object with a <target> other than SAMPLES_PASSED, 293 ANY_SAMPLES_PASSED, or ANY_SAMPLES_PASSED_CONSERVATIVE. 294 295 INVALID_OPERATION is generated by BeginConditionalRenderNV if the query 296 identified by <id> is still in progress. 297 298Issues 299 300 (1) How should rendering commands other than "normal" Begin/End-style 301 geometry be affected by conditional rendering? 302 303 RESOLVED: All rendering commands (DrawPixels, Bitmap, Clear, Accum, 304 etc...) are performed conditionally. 305 306 (2) What does NO_WAIT do, and why would anyone care? 307 308 RESOLVED: Hardware OpenGL implementations are heavily pipelined. After 309 vertices are transformed, they are assembled into primitives and 310 rasterized. While a GPU is rasterizing a primitive, it may be 311 simultaneously transforming the vertices of the next primitive provided 312 to the GL. At the same time, the CPU may be preparing hardware commands 313 to process primitives following that one. 314 315 Conditional rendering uses the results of rasterizing one primitive (an 316 occlusion query) to determine whether it will process subsequent ones. 317 In a pipelined implementation, the initial set of primitives may not be 318 finished drawing by the time the GL needs the occlusion query results. 319 Waiting for the query results will leave portions of the GPU temporarily 320 idle. It may be preferable to avoid the idle time by proceeding with a 321 conservative assumption that the primitives rendered during the 322 occlusion query will hit at least one sample. The NO_WAIT <mode> 323 parameter tells the driver move ahead in that case. 324 325 For best performance, applications should attempt to insert some amount 326 of non-dependent rendering between an occlusion query and the 327 conditionally-rendered primitives that depend on the query result. 328 329 (3) What does BY_REGION do, and why should anyone care? 330 331 RESOLVED: Conditional rendering may be used for a variety of effects. 332 Some of these use conditional rendering only for performance. One 333 common use would be to draw a bounding box for a primitive 334 unconditionally with an occlusion query active, and then conditionally 335 execute a DrawElements call to draw the full (complex) primitive. If 336 the bounding box is not visible, any work needed to process the full 337 primitive can be skipped in the conditional rendering pass. 338 339 In a split-screen SLI implementation, one GPU might draw the top half of 340 the scene while a second might draw the bottom half. The results of the 341 occlusion query would normally be obtained by combining individual 342 occlusion query results from each half of the screen. However, it is 343 not necessary to do this for the bounding box algorithm. We could skip 344 this synchronization point, and each region could instead use only its 345 local occlusion query results. If the bounding box hits only the bottom 346 half of the screen, the complex primitive need not be drawn on the top 347 half, because that portion is known not to be visible. The bottom half 348 would still be drawn, but the GPU used for the top half could skip it 349 and start drawing the next primitive specified. The 350 QUERY_BY_REGION_*_NV modes would be useful in that case. 351 352 However, some algorithms may require conditional rendering for 353 correctness. For example, an application may want to render a 354 post-processing effect that should be drawn if and only if a point is 355 visible in the scene. Drawing only half of such an effect due to 356 BY_REGION tests would not be desirable. 357 358 For QUERY_BY_REGION_NO_WAIT_NV, we expect that GL implementations using 359 region-based rendering will discard rendering commands in any region 360 where query results are available and the region's sample count is zero. 361 Rendering would proceed normally in all other regions. The spec 362 language doesn't require such behavior, however. 363 364 (4) Should the <mode> parameter passed to BeginConditionalRenderNV be 365 specified as a hint instead? 366 367 RESOLVED: The "wait" or "don't wait" portion of the <mode> parameter 368 could be a hint. But it doesn't fit nicely with the FASTEST or NICEST 369 values that are normally passed to Hint. Providing this functionality 370 via a <mode> parameter to BeginConditionalRenderNV seems to make the 371 most sense. Note that the <mode> parameter is specified such that 372 QUERY_NO_WAIT_NV can be implemented as though QUERY_WAIT_NV were 373 specified, which makes the "NO_WAIT" part of the mode a hint. 374 375 The "BY_REGION" part is also effectively a hint. These modes may be 376 implemented as though the equivalent non-BY_REGION mode were provided. 377 Many OpenGL implementations will do all of their processing in a single 378 region. 379 380 (5) What happens if BeginQuery is called while the specified occlusion 381 query is begin used for conditional rendering? 382 383 RESOLVED: An INVALID_OPERATION error is generated. 384 385 (6) Should conditional rendering work with any type of query other than 386 SAMPLES_PASSED (occlusion)? 387 388 RESOLVED: Not in this extension. The spec currently requires that <id> 389 be the name of an occlusion query. There might be other query types 390 where such an operation would make sense, but there aren't any in the 391 current OpenGL spec. 392 393 (7) What is the effect on current state for immediate mode attribute calls 394 (e.g., Color, VertexAttrib) made during conditional rendering if the 395 corresponding occlusion query failed? 396 397 RESOLVED: The effect of these calls is undefined. If subsequent 398 primitives depend on a vertex attribute set inside a conditional 399 rendering block, and application should re-send the values after 400 EndConditionalRenderNV. 401 402 (8) Should we provide any new query object types for conditional 403 rendering? 404 405 RESOLVED: No. It may be useful to some GL implementations to provide 406 an occlusion query type that only returns "zero" or "non-zero", or to 407 provide a query type that is used only for conditional rendering but 408 doesn't have to maintain results that can be returned to the 409 application. However, performing conditional rendering using only the 410 occlusion query mechanisms already in core OpenGL is sufficient for 411 the platforms targeted by this extension. 412 413 (9) What happens if QUERY_BY_REGION_* is used, and the application switches 414 between windows or FBOs between the occlusion query and conditional 415 rendering blocks? The "regions" used for the two operations may not be 416 identical. 417 418 RESOLVED: The spec language doesn't specifically address this issue, and 419 implementations may choose to define regions arbitrarily in this case. 420 421 We strongly recommend that applications using QUERY_BY_REGION_* should 422 not change windows or FBO configuration between the occlusion query and 423 the dependent rendering. 424 425 426Usage Example 427 428 GLuint queryID = 0x12345678; 429 430 // Use an occlusion query while rendering the bounding box of the real 431 // object. 432 glBeginQuery(GL_SAMPLES_PASSED, queryID); 433 drawBoundingBox(); 434 glEndQuery(GL_SAMPLES_PASSED); 435 436 // Do some unrelated rendering in hope that the query result will be 437 // available by the time we call glBeginConditionalRenderNV. 438 439 // Now conditionally render the real object if any portion of its 440 // bounding box is visible. 441 glBeginConditionalRenderNV(queryID, GL_QUERY_WAIT_NV); 442 drawComplicatedObject(); 443 glEndConditionalRenderNV(); 444 445 446Revision History 447 448 Rev. Date Author Changes 449 ---- -------- -------- -------------------------------------------- 450 6 05/26/14 dkoch Add interactions with later GL extensions and 451 core versions. 452 Add interactions with OpenGL ES extensions 453 and versions. 454 455 5 08/07/12 pbrown Fix minor typos; added interaction with the 456 older NVX_conditional_render extension. 457 458 4 09/22/10 srahman Added GLX protocol. 459 460 3 02/19/08 pbrown Document the INVALID_OPERATION error from 461 calling BeginQuery while the query is used 462 for conditional rendering in the spec body. 463 464 2 11/29/07 ewerness First public release 465 466 1 Internal revisions 467