| Name |
| |
| AMD_occlusion_query_event |
| |
| Name Strings |
| |
| GL_AMD_occlusion_query_event |
| |
| Contact |
| |
| Graham Sellers (graham.sellers 'at' amd.com) |
| |
| Contributors |
| |
| Graham Sellers, AMD |
| Daniel Rakos, AMD |
| |
| Status |
| |
| SHIPPING |
| |
| Version |
| |
| Last Modified Date: 11/20/2013 |
| Author Revision: 3 |
| |
| Number |
| |
| OpenGL Extension #442 |
| |
| Dependencies |
| |
| OpenGL 1.5 is required. |
| |
| This extension is written against the OpenGL 4.4 (core) specification. |
| |
| This extension depends on the definition of OpenGL 3.3 and |
| GL_ARB_occlusion_query2. |
| |
| This extension depends on the definition of OpenGL 4.3 and |
| GL_ARB_ES3_compatibility. |
| |
| This extension depends on the definition of GL_EXT_depth_bounds_test. |
| |
| Overview |
| |
| Occlusion queries provide a means to count the number of fragments that |
| pass the depth and stencil tests and that may contribute to a rendered |
| image. In unextended OpenGL, an occlusion query increments its |
| samples-passed count whenever a sample passes both the stencil test and |
| the depth test (if enabled). However, there is no way to count fragments |
| that fail the stencil test, or pass the stencil test and then subsequently |
| fail the depth test. |
| |
| This extension introduces the concept of occlusion query events and changes |
| the concept of an occlusion query from counting passed fragments to counting |
| fragments that generate any of a user-selectable set of events. Provided |
| events include passing the depth test, and passing or failing the stencil |
| test. For a given occlusion query object, counting of these events may be |
| enabled or disabled, allowing any combination to be counted. |
| |
| New Procedures and Functions |
| |
| void QueryObjectParameteruiAMD(enum target, |
| uint id, |
| enum pname, |
| uint param); |
| |
| New Tokens |
| |
| Accepted by the <pname> argument to QueryObejctParameteruiAMD, |
| GetQueryObjectiv, GetQueryObjectuiv, GetQueryObjecti64v, and |
| GetQueryObjectui64v: |
| |
| OCCLUSION_QUERY_EVENT_MASK_AMD 0x874F |
| |
| Accepted by the <param> argument to QueryObjectParameteruiAMD: |
| |
| QUERY_DEPTH_PASS_EVENT_BIT_AMD 0x00000001 |
| QUERY_DEPTH_FAIL_EVENT_BIT_AMD 0x00000002 |
| QUERY_STENCIL_FAIL_EVENT_BIT_AMD 0x00000004 |
| QUERY_DEPTH_BOUNDS_FAIL_EVENT_BIT_AMD 0x00000008 |
| QUERY_ALL_EVENT_BITS_AMD 0xFFFFFFFF |
| |
| Additions to Chapter 4 of the OpenGL 4.4 (core) Specification (Event Model) |
| |
| Insert Section 4.2.1, "Query Object Parameters", p.42. Renumber subsequent |
| sections. |
| |
| Query object parameters control the behavior of the query object. Changing |
| the value of a query object parameter is done by calling |
| |
| void QueryObjectParameteruiAMD(enum target, |
| uint id, |
| enum pname, |
| uint param); |
| |
| with <target> set to a valid query target, <id> set to a value returned |
| from a previous call to GenQueries. <pname> specifies the parameter to |
| modify and <param> contains its new value. If <id> is an unused query object |
| name then the name is marked as used and associated with a new query object |
| of the type specified by <target>. Otherwise, <id> must be the name of an |
| existing query object of that type. |
| |
| Additions to Chapter 17 of the OpenGL 4.3 (core) Specification (Writing Fragments |
| and Samples to the Framebuffer) |
| |
| Modify the first paragraph of Subection 17.3.7, "Occlusion Queries" as |
| follows: |
| |
| Occlusion queries use query objects to track fragments as they pass through |
| the depth bounds test, stencil test and depth test, in that order. Each |
| stage may generate an event. An event is generated if a fragment fails |
| the depth bounds test. If a fragment passes the depth bounds test, it then |
| undergoes the stencil test and generates an event should it fail that. |
| Should it pass the stencil test, it undergoes the depth test, upon which |
| it will generate an event indicating whether it passed or failed the depth |
| test. An occlusion query can be started and finished by calling BeginQuery |
| and EndQuery, respectively, with a <target> of SAMPLES_PASSED, |
| ANY_SAMPLES_PASSED, or ANY_SAMPLES_PASSED_CONSERVATIVE. |
| |
| In the remainder of the Subsection, replace any occurrence of "passes the |
| depth test" with "generates an enabled event". Add the following to the end |
| of the subsection: |
| |
| Counting of occlusion query events are enabled and disabled for a query |
| object by calling QueryObjectParameteruiAMD with <target> set to |
| SAMPLES_PASSED, ANY_SAMPLES_PASSED or ANY_SAMPLES_PASSED_CONSERVATIVE, with |
| <id> set to the name of an existing query object of the appropriate type, or |
| to a name returned from a call to GenQueries but not yet associated with a |
| query object, with <pname> set to OCCLUSION_QUERY_EVENT_MASK_AMD and with |
| <param> set to the bitwise or of the set of the following flags: |
| |
| +---------------------------------------+---------------------------------------------------------+ |
| | QUERY_DEPTH_PASS_EVENT_BIT_AMD | Indicates that the fragment passed all tests. | |
| | QUERY_DEPTH_FAIL_EVENT_BIT_AMD | Indicates that the fragment passed the depth bounds and | |
| | | stencil tests, but failed the depth test. | |
| | QUERY_STENCIL_FAIL_EVENT_BIT_AMD | Indicates that the fragment passed the depth bounds | |
| | | test but failed the stencil test. | |
| | QUERY_DEPTH_BOUNDS_FAIL_EVENT_BIT_AMD | Indicates that the fragment failed the depth bounds | |
| | | test. | |
| | QUERY_ALL_EVENT_BITS_AMD | Indicates that any event generated by the fragment | |
| | | should be counted. | |
| +---------------------------------------+---------------------------------------------------------+ |
| |
| By default, the value of OCCLUSION_QUERY_EVENT_MASK_AMD for a newly created |
| occlusion query object is QUERY_DEPTH_PASS_EVENT_BIT_AMD. |
| |
| Additions to the AGL/GLX/WGL Specifications |
| |
| None. |
| |
| GLX Protocol |
| |
| None. |
| |
| Errors |
| |
| INVALID_OPERATION is generated by GetQueryObjectiv, GetQueryObjectuiv, |
| GetQueryObjecti64v, and GetQueryObjectui64v if <pname> is |
| OCCLUSION_QUERY_EVENT_MASK_AMD and the target of the query object |
| specified by <id> is not SAMPLES_PASSED, ANY_SAMPLES_PASSED, or |
| ANY_SAMPLES_PASSED_CONSERVATIVE. |
| |
| INVALID_ENUM is generated by QueryObjectParameteruiAMD if <target> is not |
| an accepted query target. |
| |
| INVALID_ENUM is generated by QueryObjectParameteruiAMD if <pname> is not |
| OCCLUSION_QUERY_EVENT_MASK_AMD. |
| |
| INVALID_VALUE is generated by QueryObjectParameteruiAMD if <id> is not a |
| name returned from a previous call to GenQueries, or if such a name has |
| since been deleted with DeleteQueries. |
| |
| INVALID_OPERATION is generated by QueryObjectParameteruiAMD if <id> is the |
| name of an existing query object whose target does not match <target>, or |
| an active query object name for <target>. |
| |
| INVALID_OPERATION is generated by QueryObjectParameteruiAMD if <pname> is |
| OCCLUSION_QUERY_EVENT_MASK_AMD and <target> is not SAMPLES_PASSED, |
| ANY_SAMPLES_PASSED, or ANY_SAMPLES_PASSED_CONSERVATIVE. |
| |
| INVALID_VALUE is generated by QueryObjectParameteruiAMD if <pname> is |
| OCCLUSION_QUERY_EVENT_MASK_AMD and <param> contains any unsupported bits, |
| except in the case when <param> is equal to the special value, |
| QUERY_ALL_EVENT_BITS_AMD. |
| |
| New State |
| |
| Append to Table 23.44, "Query Object State" |
| |
| +-----------------------------------+-------+--------------------+--------------------------------+------------------------------------+--------+ |
| | Get Value | Type | Get Command | Initial Value | Description | Sec. | |
| +-----------------------------------+-------+--------------------+--------------------------------+------------------------------------+--------+ |
| | OCCLUSION_QUERY_EVENT_MASK_AMD | Z+ | GetQueryObjectuiv | QUERY_DEPTH_PASS_EVENT_BIT_AMD | Bitmask of events to count in an | 17.3.7 | |
| | | | | | occlusion query | | |
| +-----------------------------------+-------+--------------------+--------------------------------+------------------------------------+--------+ |
| |
| New Implementation Dependent State |
| |
| None. |
| |
| Usage Examples |
| |
| TBD |
| |
| Dependencies on GL_EXT_depth_bounds_test |
| |
| If GL_EXT_depth_bounds_test is not supported, remove any reference to |
| the depth bounds test and the QUERY_DEPTH_BOUNDS_FAIL_EVENT_BIT_AMD token. |
| The value of the QUERY_DEPTH_BOUNDS_FAIL_EVENT_BIT_AMD remains reserved, however. |
| This extension shall behave as if all fragments pass the depth bounds |
| test. |
| |
| Dependencies on OpenGL 3.3 and GL_ARB_occlusion_query2 |
| |
| If GL_ARB_occlusion_query2 is not present, and the GL version is less than |
| 3.3, then remove any reference to the ANY_SAMPLES_PASSED target. |
| |
| Dependencies on OpenGL 4.3 and GL_ARB_ES3_compatibility |
| |
| If GL_ARB_ES3_compatility is not present, and the GL version is less than |
| 4.3, then remove any reference to the ANY_SAMPLES_PASSED_CONSERVATIVE |
| target. |
| |
| Issues |
| |
| 1) Why is there no QUERY_STENCIL_PASS_BIT_AMD or |
| QUERY_DEPTH_BOUNDS_PASS_BIT_AMD? |
| |
| Fragments that pass the depth bounds test proceed to the stencil test |
| and subsequently to the depth test. The sum of depth pass, depth fail |
| and stencil fail is, by definition, the number of fragments that pass |
| the depth bounds test. Likewise, the sum of depth pass and depth fail |
| is the number of fragments that pass the stencil test. Thus, setting |
| the event mask to (QUERY_DEPTH_PASS_EVENT_BIT_AMD | |
| QUERY_DEPTH_FAIL_EVENT_BIT_AMD | QUERY_STENCIL_FAIL_EVENT_BIT_AMD) |
| allows counting of fragments that pass the depth bounds test. Similarly, |
| setting the event mask to (QUERY_DEPTH_PASS_EVENT_BIT_AMD | |
| QUERY_DEPTH_FAIL_EVENT_BIT_AMD) provides the count of fragments that pass |
| the stencil test. |
| |
| 2) Will fragments that fail the stencil test generate a depth pass or fail |
| event as if they were depth tested? Will fragments that fail the depth |
| bounds test generate stencil fail events? |
| |
| RESOLVED: No. Once a fragment fails testing at a particular stage, it |
| is discarded and cannot generate any more events. |
| |
| 3) What happens if the implementation doesn't support EXT_depth_bounds. |
| |
| RESOLVED: It is as if all fragments pass the depth bounds test. No |
| depth bounds failed events are generated. |
| |
| 4) What is the purpose of QUERY_ALL_EVENT_BITS_AMD? |
| |
| RESOLVED: It allows the counting of all fragments that are subjected to |
| any test regardless of the outcome of those tests. |
| |
| 5) What should the new query state setter function be called? |
| |
| DISCUSSION: Unfortunately, the query object API doesn't really follow |
| the naming conventions of object state getters already, as |
| GetQueryObject should have been rather called GetQueryParameter. |
| We considered the following options: |
| |
| (a) QueryObjectuiAMD |
| (b) QueryParameteruiAMD |
| (c) QueryObjectParameteruiAMD |
| |
| Option (a) follows the existing naming convention of the query object |
| API, but is too general. |
| Option (b) follows the naming convention of other object types, but |
| because the getter of existing query states is called GetQueryObject, |
| while there is also a GetQuery getter that returns context state, |
| not per-query object state. |
| Option (c) doesn't follow either the naming convention of the query |
| object API or any other object type's, but rather a mixture of the two, |
| however, it makes explicit both the fact that the setter operates |
| on a query object and that it modifies its parameter. |
| |
| RESOLVED: QueryObjectParameteruiAMD, because the function modifies |
| a state/parameter of a query object. |
| |
| 6) Should there be also a GetQueryObjectParameteruiAMD? |
| |
| RESOLVED: No. GetQueryObject is already defined to query the state of |
| a query object (see also issue #5). |
| |
| Revision History |
| |
| Rev. Date Author Changes |
| ---- -------- -------- --------------------------------------------- |
| 3 11/20/2013 gsellers Make ready for posting |
| 2 08/20/2013 drakos Internal revision |
| 1 10/08/2012 gsellers Initial revision |