1Name 2 3 ARB_pipeline_statistics_query 4 5Name Strings 6 7 GL_ARB_pipeline_statistics_query 8 9Contact 10 11 Brian Paul, VMware Inc. (brianp 'at' vmware.com) 12 13Contributors 14 15 Brian Paul, VMware 16 Daniel Rakos, AMD 17 Graham Sellers, AMD 18 Pat Brown, NVIDIA 19 Piers Daniell, NVIDIA 20 21Notice 22 23 Copyright (c) 2014 The Khronos Group Inc. Copyright terms at 24 http://www.khronos.org/registry/speccopyright.html 25 26Specification Update Policy 27 28 Khronos-approved extension specifications are updated in response to 29 issues and bugs prioritized by the Khronos OpenGL Working Group. For 30 extensions which have been promoted to a core Specification, fixes will 31 first appear in the latest version of that core Specification, and will 32 eventually be backported to the extension document. This policy is 33 described in more detail at 34 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 35 36Status 37 38 Complete. 39 Approved by the ARB on June 26, 2014. 40 Ratified by the Khronos Board of Promoters on August 7, 2014. 41 42Version 43 44 Date: 2017-07-23 45 Revision: 11 46 47Number 48 49 ARB Extension #171 50 51Dependencies 52 53 OpenGL 3.0 is required. 54 55 The extension is written against the OpenGL 4.4 Specification, Core 56 Profile, March 19, 2014. 57 58 OpenGL 3.2 and ARB_geometry_shader4 affect the definition of this 59 extension. 60 61 OpenGL 4.0 and ARB_gpu_shader5 affect the definition of this extension. 62 63 OpenGL 4.0 and ARB_tessellation_shader affect the definition of this 64 extension. 65 66 OpenGL 4.3 and ARB_compute_shader affect the definition of this extension. 67 68 This extension interacts with AMD_transform_feedback4. 69 70Overview 71 72 This extension introduces new query types that allow applications to get 73 statistics information about different parts of the pipeline: 74 75 * Number of vertices and primitives issued to the GL; 76 77 * Number of times a vertex shader, tessellation evaluation shader, 78 geometry shader, fragment shader, and compute shader was invoked; 79 80 * Number of patches processed by the tessellation control shader stage; 81 82 * Number of primitives emitted by a geometry shader; 83 84 * Number of primitives that entered the primitive clipping stage; 85 86 * Number of primitives that are output by the primitive clipping stage; 87 88IP Status 89 90 No known IP claims. 91 92New Procedures and Functions 93 94 None. 95 96New Tokens 97 98 Accepted by the <target> parameter of BeginQuery, EndQuery, GetQueryiv, 99 BeginQueryIndexed, EndQueryIndexed and GetQueryIndexediv: 100 101 VERTICES_SUBMITTED_ARB 0x82EE 102 PRIMITIVES_SUBMITTED_ARB 0x82EF 103 VERTEX_SHADER_INVOCATIONS_ARB 0x82F0 104 TESS_CONTROL_SHADER_PATCHES_ARB 0x82F1 105 TESS_EVALUATION_SHADER_INVOCATIONS_ARB 0x82F2 106 GEOMETRY_SHADER_INVOCATIONS 0x887F 107 GEOMETRY_SHADER_PRIMITIVES_EMITTED_ARB 0x82F3 108 FRAGMENT_SHADER_INVOCATIONS_ARB 0x82F4 109 COMPUTE_SHADER_INVOCATIONS_ARB 0x82F5 110 CLIPPING_INPUT_PRIMITIVES_ARB 0x82F6 111 CLIPPING_OUTPUT_PRIMITIVES_ARB 0x82F7 112 113Additions to Chapter 4 of the OpenGL 4.4 (Core Profile) Specification (Event Model) 114 115 Modify Section 4.2, Query Objects and Asynchronous Queries 116 117 (add to the end of the bullet list on the first paragraph on p. 39) 118 119 * Submission queries with a target of VERTICES_SUBMITTED_ARB and 120 PRIMITIVES_SUBMITTED_ARB return information on the number of vertices 121 and primitives transferred to the GL, respectively (see section 10.11). 122 123 * Vertex shader queries with a target of VERTEX_SHADER_INVOCATIONS_ARB 124 return information on the number of times the vertex shader has been 125 invoked (see section 11.1.4). 126 127 * Tessellation shader queries with a target of TESS_CONTROL_SHADER_- 128 PATCHES_ARB and TESS_EVALUATION_SHADER_INVOCATIONS_ARB return 129 information on the number of patches processed by the tessellation 130 control shader stage and the number of times the tessellation 131 evaluation shader has been invoked, respectively (see section 11.2.4). 132 133 * Geometry shader queries with a target of GEOMETRY_SHADER_INVOCATIONS 134 and GEOMETRY_SHADER_PRIMITIVES_EMITTED_ARB return information on the 135 number of times the geometry shader has been invoked and the number of 136 primitives it emitted (see section 11.3.5). 137 138 * Primitive clipping queries with a target of CLIPPING_INPUT_- 139 PRIMITIVES_ARB and CLIPPING_OUTPUT_PRIMITIVES_ARB return information 140 on the number of primitives that were processed in the primitive 141 clipping stage and the number of primitives that were output by the 142 primitive clipping stage and are further processed by the 143 rasterization stage, respectively (see section 13.5.2). 144 145 * Fragment shader queries with a target of FRAGMENT_SHADER_INVOCATIONS_- 146 ARB return information on the number of times the fragment shader has 147 been invoked (see section 15.3). 148 149 * Compute shader queries with a target of COMPUTE_SHADER_INVOCATIONS_ARB 150 return information on the number of times the compute shader has been 151 invoked (see section 19.2). 152 153 (replace the INVALID_ENUM error for the <target> parameter of 154 BeginQueryIndexed on p. 40): 155 156 An INVALID_ENUM error is generated if <target> is TIMESTAMP, or is not 157 one of the query object targets described in section 4.2. 158 159 (replace the INVALID_ENUM error for the <target> parameter of 160 EndQueryIndexed on p. 41): 161 162 An INVALID_ENUM error is generated if <target> is TIMESTAMP, or is not 163 one of the query object targets described in section 4.2. 164 165 (modify the INVALID_VALUE error for <index> on non-indexed <target>s on 166 p. 42): 167 168 An INVALID_OPERATION error is generated if <target> is a valid target 169 other than PRIMITIVES_GENERATED or 170 TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN, and <index> is not zero. 171 172 173 Modify Section 4.2.1, Query Object Queries 174 175 (add before the errors section for GetQueryIndexediv on p. 43) 176 177 For pipeline statistics queries (VERTICES_SUBMITTED_ARB, PRIMITIVES_- 178 SUBMITTED_ARB, VERTEX_SHADER_INVOCATIONS_ARB, TESS_CONTROL_SHADER_- 179 PATCHES_ARB, TESS_EVALUATION_SHADER_INVOCATIONS_ARB, GEOMETRY_SHADER_- 180 INVOCATIONS, FRAGMENT_SHADER_INVOCATIONS_ARB, COMPUTE_SHADER_- 181 INVOCATIONS_ARB, GEOMETRY_SHADER_PRIMITIVES_EMITTED_ARB, CLIPPING_- 182 INPUT_PRIMITIVES_ARB, CLIPPING_OUTPUT_PRIMITIVES_ARB), if the number 183 of bits is non-zero, the minimum number of bits allowed is 32. 184 185 (replace the INVALID_ENUM error for the <target> parameter of 186 GetQueryIndexediv on p. 43): 187 188 An INVALID_ENUM error is generated if <target> is not one of the query 189 object targets described in section 4.2. 190 191 (modify the INVALID_VALUE error for <index> on non-indexed <target>s on 192 p. 43): 193 194 An INVALID_OPERATION error is generated if <target> is a valid target 195 other than PRIMITIVES_GENERATED or 196 TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN, and <index> is not zero. 197 198Additions to Chapter 10 of the OpenGL 4.4 (Core Profile) Specification (Vertex Specification and Drawing Commands) 199 200 Add new Section after 10.10, Conditional Rendering 201 202 10.11 Submission Queries 203 204 Submission queries use query objects to track the number of vertices and 205 primitives that are issued to the GL using draw commands. 206 207 When BeginQuery is called with a target of VERTICES_SUBMITTED_ARB, the 208 submitted vertices count maintained by the GL is set to zero. When a 209 vertices submitted query is active, the submitted vertices count is 210 incremented every time a vertex is transferred to the GL (see sections 211 10.3.4, and 10.5). In case of primitive types with adjacency information 212 (see sections 10.1.11 through 10.1.14) implementations may or may not 213 count vertices not belonging to the main primitive. In case of line loop 214 primitives implementations are allowed to count the first vertex twice 215 for the purposes of VERTICES_SUBMITTED_ARB queries. Additionally, 216 vertices corresponding to incomplete primitives may or may not be counted. 217 218 When BeginQuery is called with a target of PRIMITIVES_SUBMITTED_ARB, the 219 submitted primitives count maintained by the GL is set to zero. When a 220 primitives submitted query is active, the submitted primitives count is 221 incremented every time a point, line, triangle, or patch primitive is 222 transferred to the GL (see sections 10.1, 10.3.5, and 10.5). Restarting 223 a primitive topology using the primitive restart index has no effect on 224 the issued primitives count. Incomplete primitives may or may not be 225 counted. 226 227Additions to Chapter 11 of the OpenGL 4.4 (Core Profile) Specification (Programmable Vertex Processing) 228 229 Modify Section 11.1.3, Shader Execution 230 231 (add after bullet list on p. 352) 232 233 Implementations are allowed to skip the execution of certain shader 234 invocations, and to execute additional shader invocations for any shader 235 type during programmable vertex processing due to implementation dependent 236 reasons, including the execution of shader invocations that don't have an 237 active program object present for the particular shader stage, as long as 238 the results of rendering otherwise remain unchanged. 239 240 Add new Section after 11.1.3, Shader Execution 241 242 11.1.4 Vertex Shader Queries 243 244 Vertex shader queries use query objects to track the number of vertex 245 shader invocations. 246 247 When BeginQuery is called with a target of VERTEX_SHADER_INVOCATIONS_ARB, 248 the vertex shader invocations count maintained by the GL is set to zero. 249 When a vertex shader invocations query is active, the counter is 250 incremented every time the vertex shader is invoked (see section 11.1). 251 252 The result of vertex shader queries may be implementation dependent due 253 to reasons described in section 11.1.3. 254 255 Add new Section after 11.2.3, Tessellation Evaluation Shaders 256 257 11.2.4 Tessellation Shader Queries 258 259 Tessellation shader queries use query objects to track the number of 260 tessellation control shader and tessellation evaluation shader invocations. 261 262 When BeginQuery is called with a target of TESS_CONTROL_SHADER_PATCHES_ARB, 263 the tessellation control shader patches count maintained by the GL is set 264 to zero. When a tessellation control shader patches query is active, the 265 counter is incremented every time a patch is processed by the tessellation 266 control shader stage (see section 11.2.1). 267 268 When BeginQuery is called with a target of TESS_EVALUATION_SHADER_- 269 INVOCATIONS_ARB, the tessellation evaluation shader invocations count 270 maintained by the GL is set to zero. When a tessellation evaluation shader 271 invocations query is active, the counter is incremented every time the 272 tessellation evaluation shader is invoked (see section 11.2.3). 273 274 The result of tessellation shader queries may be implementation dependent 275 due to reasons described in section 11.1.3. 276 277 Add new Section after 11.3.4, Geometry Shader Execution Environment 278 279 11.3.5 Geometry Shader Queries 280 281 Geometry shader queries use query objects to track the number of geometry 282 shader invocations and the number of primitives those emitted. 283 284 When BeginQuery is called with a target of GEOMETRY_SHADER_INVOCATIONS, 285 the geometry shader invocations count maintained by the GL is set to zero. 286 When a geometry shader invocations query is active, the counter is 287 incremented every time the geometry shader is invoked (see section 11.3). 288 In case of instanced geometry shaders (see section 11.3.4.2) the geometry 289 shader invocations count is incremented for each separate instanced 290 invocation. 291 292 When BeginQuery is called with a target of GEOMETRY_SHADER_PRIMITIVES_- 293 EMITTED_ARB, the geometry shader output primitives count maintained by the 294 GL is set to zero. When a geometry shader primitives emitted query is 295 active, the counter is incremented every time the geometry shader emits 296 a primitive to a vertex stream. Implementations may or may not count 297 primitives emitted to a vertex stream that isn't further processed by the 298 GL (see section 11.3.2). Restarting primitive topology using the shading 299 language built-in functions EndPrimitive or EndStreamPrimitive does not 300 increment the geometry shader output primitives count. 301 302 The result of geometry shader queries may be implementation dependent due 303 to reasons described in section 11.1.3. 304 305Additions to Chapter 13 of the OpenGL 4.4 (Core Profile) Specification (Fixed-Function Vertex Post-Processing) 306 307 Modify Section 13.5, Primitive Clipping 308 309 (add new paragraph before the last paragraph of the section on p. 405) 310 311 Implementations are allowed to pass incoming primitives unchanged and to 312 output multiple primitives for an incoming primitive due to implementation 313 dependent reasons as long as the results of rendering otherwise remain 314 unchanged. 315 316 Add new Section after 13.5.1, Clipping Shader Outputs 317 318 13.5.2 Primitive Clipping Queries 319 320 Primitive clipping queries use query objects to track the number of 321 primitives that are processed by the primitive clipping stage and the 322 number of primitives that are output by the primitive clipping stage and 323 are further processed by the rasterization stage. 324 325 When BeginQuery is called with a target of CLIPPING_INPUT_PRIMITIVES_ARB, 326 the clipping input primitives count maintained by the GL is set to zero. 327 When a clipping input primitives query is active, the counter is 328 incremented every time a primitive reaches the primitive clipping stage 329 (see section 13.5). 330 331 When BeginQuery is called with a target of CLIPPING_OUTPUT_PRIMITIVES_ARB, 332 the clipping output primitives count maintained by the GL is set to zero. 333 When a clipping output primitives query is active, the counter is 334 incremented every time a primitive passes the primitive clipping stage. 335 The actual number of primitives output by the primitive clipping stage for 336 a particular input primitive is implementation dependent (see section 13.5) 337 but must satisfy the following conditions: 338 339 * If at least one vertex of the input primitive lies inside the clipping 340 volume, the counter is incremented by one or more. 341 342 * Otherwise, the counter is incremented by zero or more. 343 344 If RASTERIZER_DISCARD is enabled, implementations are allowed to discard 345 primitives right after the optional transform feedback state (see Section 346 14.1). As a result, if RASTERIZER_DISCARD is enabled, the clipping input 347 and output primitives count may not be incremented. 348 349Additions to Chapter 15 of the OpenGL 4.4 (Core Profile) Specification (Programmable Fragment Processing) 350 351 Modify Section 15.2, Shader Execution 352 353 (add after first paragraph on p. 434) 354 355 Implementations are allowed to skip the execution of certain fragment 356 shader invocations, and to execute additional fragment shader invocations 357 during programmable fragment processing due to implementation dependent 358 reasons, including the execution of fragment shader invocations when there 359 isn't an active program object present for the fragment shader stage, as 360 long as the results of rendering otherwise remain unchanged. 361 362 Add new Section after 15.2, Shader Execution 363 364 15.3 Fragment Shader Queries 365 366 Fragment shader queries use query objects to track the number of fragment 367 shader invocations. 368 369 When BeginQuery is called with a target of FRAGMENT_SHADER_INVOCATIONS_ARB, 370 the fragment shader invocations count maintained by the GL is set to zero. 371 When a fragment shader invocations query is active, the counter is 372 incremented every time the fragment shader is invoked (see section 15.2). 373 374 The result of fragment shader queries may be implementation dependent due 375 to reasons described in section 15.2. 376 377Additions to Chapter 19 of the OpenGL 4.4 (Core Profile) Specification (Compute Shaders) 378 379 Add new Section after 19.1, Compute Shader Variables 380 381 19.2 Compute Shader Queries 382 383 Compute shader queries use query objects to track the number of compute 384 shader invocations. 385 386 When BeginQuery is called with a target of COMPUTE_SHADER_INVOCATIONS_ARB, 387 the compute shader invocations count maintained by the GL is set to zero. 388 When a compute shader invocations query is active, the counter is 389 incremented every time the compute shader is invoked (see chapter 19). 390 391 Implementations are allowed to skip the execution of certain compute 392 shader invocations, and to execute additional compute shader invocations 393 due to implementation dependent reasons as long as the results of 394 rendering otherwise remain unchanged. 395 396Additions to the AGL/EGL/GLX/WGL Specifications 397 398 None. 399 400Dependencies on OpenGL 3.2 and ARB_geometry_shader4 401 402 If OpenGL 3.2 and ARB_geometry_shader4 are not supported then remove all 403 references to GEOMETRY_SHADER_INVOCATIONS and 404 GEOMETRY_SHADER_PRIMITIVES_EMITTED_ARB. 405 406Dependencies on OpenGL 4.0 and ARB_gpu_shader5 407 408 If OpenGL 4.0 and ARB_gpu_shader5 are not supported then rename 409 GEOMETRY_SHADER_INVOCATIONS to GEOMETRY_SHADER_INVOCATIONS_ARB. 410 411Dependencies on OpenGL 4.0 and ARB_tessellation_shader 412 413 If OpenGL 4.0 and ARB_tessellation_shader are not supported then remove 414 all references to TESS_CONTROL_SHADER_PATCHES_ARB and 415 TESS_EVALUATION_SHADER_INVOCATIONS_ARB. 416 417Dependencies on OpenGL 4.3 and ARB_compute_shader 418 419 If OpenGL 4.3 and ARB_compute_shader are not supported then remove all 420 references to COMPUTE_SHADER_INVOCATIONS_ARB. 421 422Dependencies on AMD_transform_feedback4 423 424 If AMD_transform_feedback4 is supported then GEOMETRY_SHADER_PRIMITIVES_- 425 EMITTED_ARB counts primitives emitted to any of the vertex streams for 426 which STREAM_RASTERIZATION_AMD is enabled. 427 428New State 429 430 Modify Table 23.74, Miscellaneous 431 432 (update the state table to cover the new query types on p. 599) 433 434 Get Value Type Get Command Initial Value Description Sec. 435 ------------- ----- ----------- ------------- ------------------------- ----- 436 CURRENT_QUERY 18xZ+ GetQueryiv 0 Active query object names 4.2.1 437 438New Implementation Dependent State 439 440 Modify Table 23.69, Implementation Dependent Values 441 442 (update the state table to cover the new query types on p. 594) 443 444 Get Value Type Get Command Minimum Value Description Sec. 445 ------------------ ----- ----------- -------------- ------------------ ----- 446 QUERY_COUNTER_BITS 18xZ+ GetQueryiv see sec. 4.2.1 Asynchronous query 4.1.1 447 counter bits 448 449Issues 450 451 (1) Why is this extension necessary? 452 453 RESOLVED: A competing graphics API supports this feature. This extension 454 will allow one to easier implement that API's features on top of OpenGL. 455 Also, this feature could be useful for profiling tools and debuggers. 456 457 (2) Should a single query (such as GL_PIPELINE_STATISTICS) return all the 458 statistics in an 11-field record or should there be separate queries? 459 460 DISCUSSION: 461 462 Single query: Returning 11 values in one query may be trouble if we want 463 to extend the set of statistics in the future. It would probably require 464 defining a whole new query. Also, if someone is only interested in one 465 or two queries there may be overhead in querying all the statistics at 466 once. Also, the interaction with GL_ARB_query_buffer_object is not 467 clear. Would all 11 values be written to the buffer or would we define a 468 set of 11 enumerants to specify which value is queried? 469 470 Multiple queries: Defining 11 separate queries is straight-forward. 471 But if the underlying hardware is designed to collect the whole set of 472 statistics, it may be inefficient to support separate queries. 473 474 RESOLVED: Define 11 separate queries to avoid problems with future 475 statistic queries. 476 477 (3) Can the result of pipeline statistic queries be used for conditional 478 rendering? 479 480 DISCUSSION: It doesn't make sense if one query of 11 values is used. 481 It could make sense if there are 11 separate queries. But is there 482 a legitimate use case for this? D3D10 doesn't allow this. 483 484 RESOLVED: No. 485 486 (4) Should pipeline statistics use the glBegin/EndQuery() interface or 487 the glQueryCounter() interface? 488 489 DISCUSSION: The glBegin/EndQuery interface matches what D3D10 uses. 490 To count the statistics between points A and B with glQueryCounter() 491 one would query the statistic counter at point A and again at point B 492 and compute the difference. A problem with this approach is that the 493 statistic counters would always have to be running because we wouldn't 494 know when they might be queried. That could be inefficient/inconvenient. 495 496 RESOLVED: Use the glBegin/EndQuery interface. 497 498 (5) How accurate should the statistics be? 499 500 RESOLVED: None of the statistics have to be exact, thus implementations 501 might return slightly different results for any of them. 502 503 (6) What should this extension be called? 504 505 DISCUSSION: This extension provides similar functionality to that of 506 D3D's pipeline statistics queries thus it makes sense to call this 507 extension similarly (even though there is a separate classification of 508 the individual queries in this specification). 509 510 RESOLVED: ARB_pipeline_statistics_query. 511 512 (7) Can multiple pipeline statistics queries be active at the same time? 513 514 RESOLVED: Yes, as long as they have different targets. Otherwise it is 515 an error. 516 517 (8) What stage the VERTICES_SUBMITTED_ARB and PRIMITIVES_SUBMITTED_ARB 518 belong to? What do they count? 519 520 DISCUSSION: There is no separate pipeline stage introduced in the 521 specification that matches D3D's "input assembler" stage. While the 522 latest version of the GL specification mentions a "vertex puller" stage 523 in the pipeline diagram, this stage does not have a corresponding 524 chapter in the specification that introduces it. 525 526 RESOLVED: Introduce VERTICES_SUBMITTED_ARB and PRIMITIVES_SUBMITTED_ARB 527 in chapter 10, Vertex Specification and Drawing Command. They count the 528 total number of vertices and primitives processed by the GL. Including 529 multiple instances. 530 531 (9) What does 'number of primitives' mean in case of PRIMITIVES_SUBMITTED_- 532 ARB, GEOMETRY_SHADER_PRIMITIVES_EMITTED_ARB, CLIPPING_INPUT_- 533 PRIMITIVES_ARB, and CLIPPING_OUTPUT_PRIMITIVES_ARB queries? 534 535 DISCUSSION: The specification heavily overloaded the term primitive. 536 E.g. a triangle strip is considered a primitive type and primitive index 537 is meant to restart the 'primitive', however, on the other hand, 538 gl_PrimitiveID is incremented for each individual triangle of a triangle 539 strip and despite a geometry shader operates on primitives, it works 540 also on the indivudal triangles of a triangle strip. 541 542 RESOLVED: The number of individual points, lines, triangles, or patches 543 are counted (or polygons, in case of CLIPPING_OUTPUT_PRIMTIIVES_ARB). 544 545 (10) Why doesn't GEOMETRY_SHADER_INVOCATIONS have an ARB suffix? 546 547 RESOLVED: We reuse the existing token introduced by ARB_gpu_shader5 that 548 was previously only accepted by GetProgramiv and meant to return the 549 invocation count of instanced geometry shaders. 550 551 (11) What does GEOMETRY_SHADER_PRIMITIVES_EMITTED_ARB count? How is it 552 different than PRIMITIVES_GENERATED? 553 554 RESOLVED: GEOMETRY_SHADER_PRIMITIVES_EMITTED_ARB counts primitives that 555 were output by the geometry shader. All vertex streams are considered, 556 but implementations are allowed to not count primitives that aren't 557 further processed by the GL. If no goemetry shader is present then the 558 counter may or may not be incremented. 559 560 (12) What does CLIPPING_INPUT_PRIMITIVES_ARB count? 561 562 RESOLVED: The number of primitives that reach the primitive clipping 563 stage. However, see issue (13) for more details. 564 565 (13) What is the result of a CLIPPING_INPUT_PRIMITIVES_ARB query in case 566 RASTERIZER_DISCARD is enabled? 567 568 DISCUSSION: Currently RASTERIZER_DISCARD is specified to be happening 569 after primitive clipping, however, some implementations might discard 570 primitives right after the transform feedback stage if RASTERIZER_DISCARD 571 is enabled. This is perfectly legal from a spec point of view, as none 572 of the vertex post-processing operations after transform feedback have 573 any effect if RASTERIZER_DISCARD is enabled. 574 575 RESOLVED: Allow implementations to not count clipping input and output 576 primitives if RASTERIZER_DISCARD is enabled. 577 578 (14) What does CLIPPING_OUTPUT_PRIMITIVES_ARB count? 579 580 DISCUSSION: The specification defines primitive clipping as an operation 581 on points, lines, or polygons. Points and lines are of no interest as 582 they always generate at most one output primitive even if clipped. 583 On the other hand, according to the specification, triangles are handled 584 as polygons and in case clipping happens new vertices are added to the 585 polygon but it still remains a single polygon. 586 587 Actual hardware, on the other hand, is likely to support only triangle 588 rasterization so in these cases each vertex added due to clipping 589 implies the generation of another triangle. 590 591 Also, the specification defines primitive clipping to be water-tight, 592 i.e. in theory hardware should always clip primitives that have one of 593 their vertices fall out of any of the clip planes. In practice, however, 594 this can be fairly sub-optimal as primitive clipping can be way more 595 expensive than if the non-visible parts of the primitives would be 596 discarded at e.g. the pixel ownership test, so hardware often uses 597 guardbands that allow some primitives to pass through the clipper 598 unchanged even though they partially fall outside of the clip volume. 599 600 All of these hardware optimizations are legal from the specification's 601 point of view, but make it difficult to define the meaning of this new 602 counter without introducing severe restrictions to how a GL 603 implementation should handle certain cases. 604 605 RESOLVED: Define CLIPPING_OUTPUT_PRIMITIVES_ARB so that they count 606 the actual number of primitives output by the primitive clipping stage 607 by the implemenation, which might include primitives output for 608 implementation dependent reasons. The only guarantees on the number 609 of output primitives are the following: 610 611 * If at least one vertex of the primitive lies inside the clipping 612 volume, the counter is incremented by one or more. 613 * Otherwise, the counter is incremented by zero or more. 614 615 (15) Do we need to add any language to discuss why certain shader 616 invocation counts might not match the "expected" values in practice? 617 618 DISCUSSION: Implementations might be able to do optimizations that 619 allow avoiding the execution of certain invocations in some 620 circumstances while also might need "helper" invocations in other cases. 621 622 RESOLVED: Add language to describe that such behavior is allowed as long 623 as the results of the rendering otherwise remain unchanged. 624 625 (16) What should be the result of VERTEX_SHADER_INVOCATIONS_ARB, 626 TESS_CONTROL_SHADER_PATCHES_ARB, TESS_EVALUATION_SHADER_- 627 INVOCATIONS_ARB, GEOMETRY_SHADER_INVOCATIONS, FRAGMENT_SHADER_- 628 INVOCATIONS_ARB and COMPUTE_SHADER_INVOCATIONS_ARB if the current 629 program does not contain a shader of the appropriate type? 630 631 DISCUSSION: D3D is vague about the exact specification of this scenario, 632 except that it explicitly allows geometry shader invocations count to 633 increment also if there is no geometry shader. 634 635 In case of OpenGL, however, the programmable fragment processing stage 636 is undefined if there is no fragment shader in the current program. This 637 is because some implementations might require to run a fragment shader 638 even if the application developer does not need one. 639 640 RESOLVED: Add language to describe that implementations are allowed to 641 increment these counters even if there isn't a current program for the 642 particular shader stage. 643 644 (17) Due to the introduction of a lot of new query types the error section 645 of query object related commands like BeginQueryIndexed, 646 EndQueryIndexed and GetQueryIndexediv became pretty bloated. 647 Shouldn't we introduce some new tables for indexed and non-indexed 648 query types and reference those in the error sections instead? 649 650 RESOLVED: Probably, but not as part of this extension. 651 652 (18) What are VERTEX_SHADER_INVOCATIONS_ARB queries useful for? 653 654 DISCUSSION: In most cases VERTEX_SHADER_INVOCATIONS_ARB queries are 655 likely to return the same results as VERTICES_SUBMITTED_ARB queries. 656 However, implementations are allowed to perform optimizations that 657 enable avoiding the re-processing of the same vertex in case of an 658 indexed draw command. This is often referred to as vertex reuse or 659 post-transform vertex cache optimization. In case such optimizations 660 are applied, the number of vertex shader invocations can be smaller 661 than the number of vertices issued. 662 663 RESOLVED: They can be used together with VERTICES_SUBMITTED_ARB queries 664 to analyze how efficiently the index ordering takes advantage of the 665 post-transform vertex cache. 666 667 (19) Does GEOMETRY_SHADER_INVOCATIONS queries account for instanced 668 geometry shaders? 669 670 RESOLVED: Yes, GEOMETRY_SHADER_INVOCATIONS queries count the total 671 number of geometry shader executions, including individual invocations 672 of an instanced geometry shader. 673 674 (20) What are CLIPPING_INPUT_PRIMITIVES_ARB and CLIPPING_OUTPUT_- 675 PRIMITIVES_ARB queries useful for? 676 677 RESOLVED: These two types of queries can be used together to determine a 678 conservative estimate on how efficiently the primitive clipping stage is 679 used. If the rasterizer primitives count is substantially lower than the 680 clipper primitives count, it may indicate that too many primitives were 681 tried to be rendered that ended up outside of the viewport. On the other 682 hand, if the rasterizer primitives count is substantially higher than 683 the clipper primitives count, it may indicate that too many primitives 684 were clipped and primitive clipping might have become the bottleneck of 685 the rendering pipeline. 686 687 (21) What are FRAGMENT_SHADER_INVOCATIONS_ARB queries useful for? 688 689 DISCUSSION: In many cases the hardware can perform early per-fragment 690 tests which might result in the fragment shader not being executed. 691 These and similar optimizations might result in a lower fragment shader 692 invocation count than expected. 693 694 RESOLVED: They can be used to analyze how efficiently the application 695 takes advantage of early per-fragment tests and other fragment shader 696 optimizations. 697 698 (22) What is the behavior of pipeline statistics queries returning 699 information about primitive counts in case of legacy primitive types 700 like quads or polygons? 701 702 DISCUSSION: This extension is intentionally written against the core 703 profile of the specification as defining the behavior of these queries 704 for legacy primitive types would be either non-portable or too relaxed 705 to be useful for any reasonably accurate measurement. 706 707 RESOLVED: Undefined, as this is a core profile extension. 708 709 (23) How do operations like Clear, TexSubImage, etc. affect the results of 710 the newly introduced queries? 711 712 DISCUSSION: Implementations might require "helper" rendering commands be 713 issued to implement certain operations like Clear, TexSubImage, etc. 714 715 RESOLVED: They don't. Only application submitted rendering commands 716 should have an effect on the results of the queries. 717 718 (24) Should partial primitives be counted by submission queries? 719 720 DISCUSSION: Consider the example of calling DrawArrays with <mode> 721 TRIANGLES and <count> of 8. 722 Should VERTICES_SUBMITTED_ARB return 6 or 8? 723 Should PRIMITIVES_SUBMITTED_ARB return 2 or 3? 724 725 RESOLVED: Undefined, incomplete primitives and vertices of incomplete 726 primitives may or may not be counted by PRIMITIVES_SUBMITTED_ARB and 727 VERTICES_SUBMITTED_ARB queries, respectively. 728 729 (25) What should we count in case of tessellation control shaders? 730 731 DISCUSSION: While OpenGL tessellation control shaders are defined to 732 be invoked once per vertex, D3D defines the same shader stage to be 733 executed once per patch. 734 735 RESOLVED: The number of patches processed by the tessellation control 736 shader stage is counted. 737 738 (26) Should VERTICES_SUBMITTED_ARB count adjacent vertices in case of 739 primitives with adjacency? 740 741 DISCUSSION: Implementations have different answers for this. 742 743 RESOLVED: Allow both. It is up to the implementation whether adjacent 744 vertices are counted. 745 746 (27) Should VERTICES_SUBMITTED_ARB count vertices multiple times in case 747 of primitive types that reuse vertices (e.g. LINE_LOOP, LINE_STRIP, 748 TRIANGLE_STRIP)? 749 750 RESOLVED: No for strip primitives, but allow (but not require) counting 751 the first vertex twice for line loop primitives. 752 753Revision History 754 755 Revision 11, 2017/07/23 (Jon Leech) 756 - Replace the long list of valid <target> parameters for 757 BeginQueryIndexed, EndQueryIndexed, and GetQueryIndexediv with a 758 reference to the list of query targets in section 4.2 (gitlab #18). 759 - Add the new query targets to those for which the <index> parameter 760 of BeginQueryIndexed and GetQueryIndexediv must be zero (gitlab 761 #26). 762 763 Revision 10, 2014/10/30 (Daniel Rakos) 764 - Relaxed the behavior of VERTICES_SUBMITTED_ARB queries for primitives 765 with adjacency to allow counting of adjacent vertices. 766 - Relaxed the behavior of GEOMETRY_SHADER_PRIMITIVES_EMITTED_ARB queries 767 to also allow counting primitives emitted to all vertex streams. 768 769 Revision 9, 2014/10/08 (Daniel Rakos) 770 - Specified that the vertices submitted count is only incremented for 771 vertices belonging to the main primitive in case of primitives with 772 adjacency. 773 - Relaxed the definition of VERTICES_SUBMITTED_ARB queries to allow 774 implementations to count the first vertex twice for line loop 775 primitives. 776 - Changed the definition of GEOMETRY_SHADER_PRIMITIVES_EMITTED_ARB 777 queries to only count primitives emitted to vertex streams that are 778 further processed by the GL. 779 - Added interaction with AMD_transform_feedback4. 780 781 Revision 8, 2014/06/27 (Daniel Rakos) 782 - Renamed tessellation control shader query to TESS_CONTROL_SHADER_- 783 PATCHES_ARB and updated language respectively. 784 785 Revision 7, 2014/05/09 (Daniel Rakos) 786 - Resolved issue (24), updated resolution of issue (5). 787 788 Revision 6, 2014/05/06 (Daniel Rakos) 789 - Added issue (24). 790 791 Revision 5, 2014/04/25 (Daniel Rakos) 792 - Renamed to ARB_pipeline_statistics_query. 793 - Replaced EXT suffixes with ARB ones. 794 - Resolved outstanding issues and added language to the spec to explain 795 these resolutions. 796 797 Revision 4, 2014/04/23 (Daniel Rakos) 798 - Fixed some typos. 799 - Renamed primitive clipping queries to CLIPPING_INPUT_PRIMITIVES_EXT 800 and CLIPPING_OUTPUT_PRIMITIVES_EXT. 801 - Resolved issues (2), (9), (12), (18), and (20). 802 - Updated suggestions for issues (11), (13), (14), (15), and (16). 803 - Added issue (23). 804 805 Revision 3, 2014/04/16 (Daniel Rakos) 806 - Major rewrite of the spec language that clarifies in what pipeline 807 stage the various queries take place and what exactly is counted. 808 - Added issues (6) through (22). 809 - Removed conformance testing section (a separate conformance test spec 810 will be created). 811 - Added state table changes. 812 - Clarified dependencies on other extensions. 813 814 Revision 2, 2014/04/09 (Brian Paul) 815 - Break the original single 11-valued query into 11 individual queries. 816 - Added issues (2), (3), (4), and (5). 817 - Added conformance testing section. 818 819 Revision 1, 2014/02/03 (Brian Paul) 820 - Initial revision. 821