1Name 2 3 AMD_occlusion_query_event 4 5Name Strings 6 7 GL_AMD_occlusion_query_event 8 9Contact 10 11 Graham Sellers (graham.sellers 'at' amd.com) 12 13Contributors 14 15 Graham Sellers, AMD 16 Daniel Rakos, AMD 17 18Status 19 20 SHIPPING 21 22Version 23 24 Last Modified Date: 11/20/2013 25 Author Revision: 3 26 27Number 28 29 OpenGL Extension #442 30 31Dependencies 32 33 OpenGL 1.5 is required. 34 35 This extension is written against the OpenGL 4.4 (core) specification. 36 37 This extension depends on the definition of OpenGL 3.3 and 38 GL_ARB_occlusion_query2. 39 40 This extension depends on the definition of OpenGL 4.3 and 41 GL_ARB_ES3_compatibility. 42 43 This extension depends on the definition of GL_EXT_depth_bounds_test. 44 45Overview 46 47 Occlusion queries provide a means to count the number of fragments that 48 pass the depth and stencil tests and that may contribute to a rendered 49 image. In unextended OpenGL, an occlusion query increments its 50 samples-passed count whenever a sample passes both the stencil test and 51 the depth test (if enabled). However, there is no way to count fragments 52 that fail the stencil test, or pass the stencil test and then subsequently 53 fail the depth test. 54 55 This extension introduces the concept of occlusion query events and changes 56 the concept of an occlusion query from counting passed fragments to counting 57 fragments that generate any of a user-selectable set of events. Provided 58 events include passing the depth test, and passing or failing the stencil 59 test. For a given occlusion query object, counting of these events may be 60 enabled or disabled, allowing any combination to be counted. 61 62New Procedures and Functions 63 64 void QueryObjectParameteruiAMD(enum target, 65 uint id, 66 enum pname, 67 uint param); 68 69New Tokens 70 71 Accepted by the <pname> argument to QueryObejctParameteruiAMD, 72 GetQueryObjectiv, GetQueryObjectuiv, GetQueryObjecti64v, and 73 GetQueryObjectui64v: 74 75 OCCLUSION_QUERY_EVENT_MASK_AMD 0x874F 76 77 Accepted by the <param> argument to QueryObjectParameteruiAMD: 78 79 QUERY_DEPTH_PASS_EVENT_BIT_AMD 0x00000001 80 QUERY_DEPTH_FAIL_EVENT_BIT_AMD 0x00000002 81 QUERY_STENCIL_FAIL_EVENT_BIT_AMD 0x00000004 82 QUERY_DEPTH_BOUNDS_FAIL_EVENT_BIT_AMD 0x00000008 83 QUERY_ALL_EVENT_BITS_AMD 0xFFFFFFFF 84 85Additions to Chapter 4 of the OpenGL 4.4 (core) Specification (Event Model) 86 87 Insert Section 4.2.1, "Query Object Parameters", p.42. Renumber subsequent 88 sections. 89 90 Query object parameters control the behavior of the query object. Changing 91 the value of a query object parameter is done by calling 92 93 void QueryObjectParameteruiAMD(enum target, 94 uint id, 95 enum pname, 96 uint param); 97 98 with <target> set to a valid query target, <id> set to a value returned 99 from a previous call to GenQueries. <pname> specifies the parameter to 100 modify and <param> contains its new value. If <id> is an unused query object 101 name then the name is marked as used and associated with a new query object 102 of the type specified by <target>. Otherwise, <id> must be the name of an 103 existing query object of that type. 104 105Additions to Chapter 17 of the OpenGL 4.3 (core) Specification (Writing Fragments 106and Samples to the Framebuffer) 107 108 Modify the first paragraph of Subection 17.3.7, "Occlusion Queries" as 109 follows: 110 111 Occlusion queries use query objects to track fragments as they pass through 112 the depth bounds test, stencil test and depth test, in that order. Each 113 stage may generate an event. An event is generated if a fragment fails 114 the depth bounds test. If a fragment passes the depth bounds test, it then 115 undergoes the stencil test and generates an event should it fail that. 116 Should it pass the stencil test, it undergoes the depth test, upon which 117 it will generate an event indicating whether it passed or failed the depth 118 test. An occlusion query can be started and finished by calling BeginQuery 119 and EndQuery, respectively, with a <target> of SAMPLES_PASSED, 120 ANY_SAMPLES_PASSED, or ANY_SAMPLES_PASSED_CONSERVATIVE. 121 122 In the remainder of the Subsection, replace any occurrence of "passes the 123 depth test" with "generates an enabled event". Add the following to the end 124 of the subsection: 125 126 Counting of occlusion query events are enabled and disabled for a query 127 object by calling QueryObjectParameteruiAMD with <target> set to 128 SAMPLES_PASSED, ANY_SAMPLES_PASSED or ANY_SAMPLES_PASSED_CONSERVATIVE, with 129 <id> set to the name of an existing query object of the appropriate type, or 130 to a name returned from a call to GenQueries but not yet associated with a 131 query object, with <pname> set to OCCLUSION_QUERY_EVENT_MASK_AMD and with 132 <param> set to the bitwise or of the set of the following flags: 133 134 +---------------------------------------+---------------------------------------------------------+ 135 | QUERY_DEPTH_PASS_EVENT_BIT_AMD | Indicates that the fragment passed all tests. | 136 | QUERY_DEPTH_FAIL_EVENT_BIT_AMD | Indicates that the fragment passed the depth bounds and | 137 | | stencil tests, but failed the depth test. | 138 | QUERY_STENCIL_FAIL_EVENT_BIT_AMD | Indicates that the fragment passed the depth bounds | 139 | | test but failed the stencil test. | 140 | QUERY_DEPTH_BOUNDS_FAIL_EVENT_BIT_AMD | Indicates that the fragment failed the depth bounds | 141 | | test. | 142 | QUERY_ALL_EVENT_BITS_AMD | Indicates that any event generated by the fragment | 143 | | should be counted. | 144 +---------------------------------------+---------------------------------------------------------+ 145 146 By default, the value of OCCLUSION_QUERY_EVENT_MASK_AMD for a newly created 147 occlusion query object is QUERY_DEPTH_PASS_EVENT_BIT_AMD. 148 149Additions to the AGL/GLX/WGL Specifications 150 151 None. 152 153GLX Protocol 154 155 None. 156 157Errors 158 159 INVALID_OPERATION is generated by GetQueryObjectiv, GetQueryObjectuiv, 160 GetQueryObjecti64v, and GetQueryObjectui64v if <pname> is 161 OCCLUSION_QUERY_EVENT_MASK_AMD and the target of the query object 162 specified by <id> is not SAMPLES_PASSED, ANY_SAMPLES_PASSED, or 163 ANY_SAMPLES_PASSED_CONSERVATIVE. 164 165 INVALID_ENUM is generated by QueryObjectParameteruiAMD if <target> is not 166 an accepted query target. 167 168 INVALID_ENUM is generated by QueryObjectParameteruiAMD if <pname> is not 169 OCCLUSION_QUERY_EVENT_MASK_AMD. 170 171 INVALID_VALUE is generated by QueryObjectParameteruiAMD if <id> is not a 172 name returned from a previous call to GenQueries, or if such a name has 173 since been deleted with DeleteQueries. 174 175 INVALID_OPERATION is generated by QueryObjectParameteruiAMD if <id> is the 176 name of an existing query object whose target does not match <target>, or 177 an active query object name for <target>. 178 179 INVALID_OPERATION is generated by QueryObjectParameteruiAMD if <pname> is 180 OCCLUSION_QUERY_EVENT_MASK_AMD and <target> is not SAMPLES_PASSED, 181 ANY_SAMPLES_PASSED, or ANY_SAMPLES_PASSED_CONSERVATIVE. 182 183 INVALID_VALUE is generated by QueryObjectParameteruiAMD if <pname> is 184 OCCLUSION_QUERY_EVENT_MASK_AMD and <param> contains any unsupported bits, 185 except in the case when <param> is equal to the special value, 186 QUERY_ALL_EVENT_BITS_AMD. 187 188New State 189 190 Append to Table 23.44, "Query Object State" 191 192 +-----------------------------------+-------+--------------------+--------------------------------+------------------------------------+--------+ 193 | Get Value | Type | Get Command | Initial Value | Description | Sec. | 194 +-----------------------------------+-------+--------------------+--------------------------------+------------------------------------+--------+ 195 | OCCLUSION_QUERY_EVENT_MASK_AMD | Z+ | GetQueryObjectuiv | QUERY_DEPTH_PASS_EVENT_BIT_AMD | Bitmask of events to count in an | 17.3.7 | 196 | | | | | occlusion query | | 197 +-----------------------------------+-------+--------------------+--------------------------------+------------------------------------+--------+ 198 199New Implementation Dependent State 200 201 None. 202 203Usage Examples 204 205 TBD 206 207Dependencies on GL_EXT_depth_bounds_test 208 209 If GL_EXT_depth_bounds_test is not supported, remove any reference to 210 the depth bounds test and the QUERY_DEPTH_BOUNDS_FAIL_EVENT_BIT_AMD token. 211 The value of the QUERY_DEPTH_BOUNDS_FAIL_EVENT_BIT_AMD remains reserved, however. 212 This extension shall behave as if all fragments pass the depth bounds 213 test. 214 215Dependencies on OpenGL 3.3 and GL_ARB_occlusion_query2 216 217 If GL_ARB_occlusion_query2 is not present, and the GL version is less than 218 3.3, then remove any reference to the ANY_SAMPLES_PASSED target. 219 220Dependencies on OpenGL 4.3 and GL_ARB_ES3_compatibility 221 222 If GL_ARB_ES3_compatility is not present, and the GL version is less than 223 4.3, then remove any reference to the ANY_SAMPLES_PASSED_CONSERVATIVE 224 target. 225 226Issues 227 228 1) Why is there no QUERY_STENCIL_PASS_BIT_AMD or 229 QUERY_DEPTH_BOUNDS_PASS_BIT_AMD? 230 231 Fragments that pass the depth bounds test proceed to the stencil test 232 and subsequently to the depth test. The sum of depth pass, depth fail 233 and stencil fail is, by definition, the number of fragments that pass 234 the depth bounds test. Likewise, the sum of depth pass and depth fail 235 is the number of fragments that pass the stencil test. Thus, setting 236 the event mask to (QUERY_DEPTH_PASS_EVENT_BIT_AMD | 237 QUERY_DEPTH_FAIL_EVENT_BIT_AMD | QUERY_STENCIL_FAIL_EVENT_BIT_AMD) 238 allows counting of fragments that pass the depth bounds test. Similarly, 239 setting the event mask to (QUERY_DEPTH_PASS_EVENT_BIT_AMD | 240 QUERY_DEPTH_FAIL_EVENT_BIT_AMD) provides the count of fragments that pass 241 the stencil test. 242 243 2) Will fragments that fail the stencil test generate a depth pass or fail 244 event as if they were depth tested? Will fragments that fail the depth 245 bounds test generate stencil fail events? 246 247 RESOLVED: No. Once a fragment fails testing at a particular stage, it 248 is discarded and cannot generate any more events. 249 250 3) What happens if the implementation doesn't support EXT_depth_bounds. 251 252 RESOLVED: It is as if all fragments pass the depth bounds test. No 253 depth bounds failed events are generated. 254 255 4) What is the purpose of QUERY_ALL_EVENT_BITS_AMD? 256 257 RESOLVED: It allows the counting of all fragments that are subjected to 258 any test regardless of the outcome of those tests. 259 260 5) What should the new query state setter function be called? 261 262 DISCUSSION: Unfortunately, the query object API doesn't really follow 263 the naming conventions of object state getters already, as 264 GetQueryObject should have been rather called GetQueryParameter. 265 We considered the following options: 266 267 (a) QueryObjectuiAMD 268 (b) QueryParameteruiAMD 269 (c) QueryObjectParameteruiAMD 270 271 Option (a) follows the existing naming convention of the query object 272 API, but is too general. 273 Option (b) follows the naming convention of other object types, but 274 because the getter of existing query states is called GetQueryObject, 275 while there is also a GetQuery getter that returns context state, 276 not per-query object state. 277 Option (c) doesn't follow either the naming convention of the query 278 object API or any other object type's, but rather a mixture of the two, 279 however, it makes explicit both the fact that the setter operates 280 on a query object and that it modifies its parameter. 281 282 RESOLVED: QueryObjectParameteruiAMD, because the function modifies 283 a state/parameter of a query object. 284 285 6) Should there be also a GetQueryObjectParameteruiAMD? 286 287 RESOLVED: No. GetQueryObject is already defined to query the state of 288 a query object (see also issue #5). 289 290Revision History 291 292 Rev. Date Author Changes 293 ---- -------- -------- --------------------------------------------- 294 3 11/20/2013 gsellers Make ready for posting 295 2 08/20/2013 drakos Internal revision 296 1 10/08/2012 gsellers Initial revision 297