src/third_party/webgl/src/extensions/EXT_disjoint_timer_query/extension.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <draft href="EXT_disjoint_timer_query/">
   3   <name>EXT_disjoint_timer_query</name>
   4
   5   <contact> <a href="https://www.khronos.org/webgl/public-mailing-list/">WebGL
   6   working group</a> (public_webgl 'at' khronos.org) </contact>
   7
   8   <contributors>
   9     <contributor>Contributors to ARB_occlusion_query</contributor>
  10     <contributor>Contributors to EXT_timer_query</contributor>
  11     <contributor>Contributors to ARB_timer_query</contributor>
  12     <contributor>Ben Vanik, Google Inc.</contributor>
  13     <contributor>Daniel Koch, TransGaming Inc.</contributor>
  14     <contributor>Florian Boesch (pyalot 'at' gmail.com)</contributor>
  15     <contributor>Members of the WebGL working group</contributor>
  16   </contributors>
  17
  18   <number>26</number>
  19
  20   <depends>
  21     <api version="1.0"/>
  22   </depends>
  23
  24   <overview>
  25     <mirrors href="http://www.khronos.org/registry/gles/extensions/EXT/EXT_disjoint_timer_query.txt"
  26              name="EXT_disjoint_timer_query">
  27       <addendum>
  28         Specifies that queries' results only become available at certain well-defined times.
  29       </addendum>
  30     </mirrors>
  31
  32     <features>
  33       <feature>
  34         This extension provides a query mechanism that can be used to determine
  35         the amount of time it takes to fully complete a set of GL commands, and
  36         without stalling the rendering pipeline.  It uses the query object
  37         mechanisms first introduced in the occlusion query extension, which allow
  38         time intervals to be polled asynchronously by the application.
  39       </feature>
  40     </features>
  41   </overview>
  42
  43   <idl xml:space="preserve">
  44     typedef unsigned long long GLuint64EXT;
  45
  46     [NoInterfaceObject]
  47     interface WebGLTimerQueryEXT : WebGLObject {
  48     };
  49
  50     [NoInterfaceObject]
  51     interface EXT_disjoint_timer_query {
  52       const GLenum QUERY_COUNTER_BITS_EXT      = 0x8864;
  53       const GLenum CURRENT_QUERY_EXT           = 0x8865;
  54       const GLenum QUERY_RESULT_EXT            = 0x8866;
  55       const GLenum QUERY_RESULT_AVAILABLE_EXT  = 0x8867;
  56       const GLenum TIME_ELAPSED_EXT            = 0x88BF;
  57       const GLenum TIMESTAMP_EXT               = 0x8E28;
  58       const GLenum GPU_DISJOINT_EXT            = 0x8FBB;
  59
  60       WebGLTimerQueryEXT? createQueryEXT();
  61       void deleteQueryEXT(WebGLTimerQueryEXT? query);
  62       [WebGLHandlesContextLoss] boolean isQueryEXT(WebGLTimerQueryEXT? query);
  63       void beginQueryEXT(enum target, WebGLTimerQueryEXT? query);
  64       void endQueryEXT(enum target);
  65       void queryCounterEXT(WebGLTimerQueryEXT? query, enum target);
  66       any getQueryEXT(enum target, enum pname);
  67       any getQueryObjectEXT(WebGLTimerQueryEXT? query, enum pname);
  68     };
  69   </idl>
  70
  71   <newfun>
  72     <function name="createQueryEXT" type="WebGLTimerQueryEXT?">
  73     </function>
  74   </newfun>
  75
  76   <newfun>
  77     <function name="deleteQueryEXT" type="void">
  78       <param name="query" type="WebGLTimerQueryEXT?"/>
  79     </function>
  80   </newfun>
  81
  82   <newfun>
  83     <function name="isQueryEXT" type="boolean">
  84       <param name="query" type="WebGLTimerQueryEXT?"/>
  85       Returns true if the passed WebGLTimerQueryEXT is valid and false otherwise. Returns false if
  86       the query's <a
  87       href="http://www.khronos.org/registry/webgl/specs/1.0.1/#webgl-object-invalidated-flag">invalidated
  88       flag</a> is set.
  89     </function>
  90   </newfun>
  91
  92   <newfun>
  93     <function name="beginQueryEXT" type="void">
  94       <param name="target" type="GLenum"/>
  95       <param name="query" type="WebGLTimerQueryEXT?"/>
  96       <code>target</code> accepts <code>TIME_ELAPSED_EXT</code>.
  97     </function>
  98   </newfun>
  99
 100   <newfun>
 101     <function name="endQueryEXT" type="void">
 102       <param name="target" type="GLenum"/>
 103       <code>target</code> accepts <code>TIME_ELAPSED_EXT</code>.
 104     </function>
 105   </newfun>
 106
 107   <newfun>
 108     <function name="queryCounterEXT" type="void">
 109       <param name="query" type="WebGLTimerQueryEXT?"/>
 110       <param name="target" type="GLenum"/>
 111       <code>target</code> accepts <code>TIMESTAMP_EXT</code>.
 112     </function>
 113   </newfun>
 114
 115   <newfun>
 116     <function name="getQueryEXT" type="any">
 117       <param name="target" type="GLenum"/>
 118       <param name="pname" type="GLenum"/>
 119       <code>target</code> accepts <code>TIME_ELAPSED_EXT</code> or <code>TIMESTAMP_EXT</code>.
 120       <code>pname</code> accepts <code>CURRENT_QUERY_EXT</code> or <code>QUERY_COUNTER_BITS_EXT</code>.
 121       <br/>
 122       The return type of this method depends on the parameter queried:
 123       <table width="30%">
 124       <tr><th>pname</th><th>returned type</th></tr>
 125       <tr><td>CURRENT_QUERY_EXT</td><td>WebGLTimerQueryEXT?</td></tr>
 126       <tr><td>QUERY_COUNTER_BITS_EXT</td><td>GLint</td></tr>
 127       </table>
 128     </function>
 129   </newfun>
 130
 131   <newfun>
 132     <function name="getQueryObjectEXT" type="any">
 133       <param name="query" type="WebGLTimerQueryEXT?"/>
 134       <param name="pname" type="GLenum"/>
 135       <code>pname</code> accepts <code>QUERY_RESULT_EXT</code> or <code>QUERY_RESULT_AVAILABLE_EXT</code>.
 136       <br/>
 137       The return type of this method depends on the parameter queried:
 138       <table width="30%">
 139       <tr><th>pname</th><th>returned type</th></tr>
 140       <tr><td>QUERY_RESULT_EXT</td><td>GLuint64EXT</td></tr>
 141       <tr><td>QUERY_RESULT_AVAILABLE_EXT</td><td>boolean</td></tr>
 142       </table>
 143       <br/>
 144       In order to ensure consistent behavior across platforms, queries' results must only be made
 145       available when the user agent's <a
 146       href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-loops">event
 147       loop</a> is not executing a task. In other words:
 148       <ul>
 149         <li> A query's result must not be made available until the current frame has completed
 150              rendering. </li>
 151         <li> Repeatedly fetching a query's QUERY_RESULT_AVAILABLE_EXT parameter in a loop, without
 152              returning control to the user agent, must always return the same value. </li>
 153       </ul>
 154     </function>
 155   </newfun>
 156
 157   <newtok>
 158     <function name="getParameter" type="any">
 159       <param name="pname" type="GLenum"/>
 160       <code>pname</code> accepts <code>TIMESTAMP_EXT</code> or <code>GPU_DISJOINT_EXT</code>.
 161       <br/>
 162
 163       The return type depends on the parameter queried:
 164       <table width="30%">
 165       <tr><th>pname</th><th>returned type</th></tr>
 166       <tr><td>TIMESTAMP_EXT</td><td>GLuint64EXT</td></tr>
 167       <tr><td>GPU_DISJOINT_EXT</td><td>boolean</td></tr>
 168       </table>
 169     </function>
 170   </newtok>
 171
 172   <issues>
 173     <ol>
 174       <li>
 175         <p>
 176           Can getQueryObjectEXT be exposed in its current form according to ECMAScript
 177           semantics?  ECMAScript's <a
 178           href="http://wiki.ecmascript.org/doku.php?id=strawman:concurrency">de-facto concurrency
 179           model</a> is "shared nothing" communicating event loops. Is it acceptable for sequential
 180           calls to getQueryObjectEXT to return different answers? Note that Date.now() advances
 181           during script execution, so this may be fine; but if concerns are raised, then the API may
 182           need to be redesigned to use callbacks.
 183         </p>
 184       </li>
 185     </ol>
 186   </issues>
 187
 188   <samplecode xml:space="preserve">
 189     <pre>
 190         // Example (1) -- uses beginQueryEXT/endQueryEXT.
 191         var ext = gl.getExtension('EXT_disjoint_timer_query');
 192         var query = ext.createQueryEXT();
 193         ext.beginQueryEXT(ext.TIME_ELAPSED_EXT, query);
 194
 195         // Draw object
 196         gl.drawElements(...);
 197
 198         ext.endQueryEXT(ext.TIME_ELAPSED_EXT);
 199
 200         // At some point in the future, after returning control to the browser and being called again:
 201         var available = ext.getQueryObjectEXT(query, ext.QUERY_RESULT_AVAILABLE_EXT);
 202         var disjoint = gl.getParamater(ext.GPU_DISJOINT_EXT);
 203
 204         if (available &amp;&amp; !disjoint) {
 205           // See how much time the rendering of the object took in nanoseconds.
 206           var timeElapsed = ext.getQueryObjectEXT(query, ext.QUERY_RESULT_EXT);
 207
 208           // Do something useful with the time.  Note that care should be
 209           // taken to use all significant bits of the result, not just the
 210           // least significant 32 bits.
 211           adjustObjectLODBasedOnDrawTime(timeElapsed);
 212         }
 213
 214
 215         //----------------------------------------------------------------------
 216
 217         // Example (2) -- same as the example above, but uses queryCounterEXT instead.
 218         var ext = gl.getExtension('EXT_disjoint_timer_query');
 219         var startQuery = ext.createQueryEXT();
 220         var endQuery = ext.createQueryEXT();
 221         ext.queryCounterEXT(startQuery, ext.TIMESTAMP_EXT);
 222
 223         // Draw object
 224         gl.drawElements(...);
 225
 226         ext.queryCounterEXT(endQuery, ext.TIMESTAMP_EXT);
 227
 228         // At some point in the future, after returning control to the browser and being called again:
 229         var available = ext.getQueryObjectEXT(endQuery, ext.QUERY_RESULT_AVAILABLE_EXT);
 230         var disjoint = gl.getParameter(ext.GPU_DISJOINT_EXT);
 231
 232         if (available &amp;&amp; !disjoint) {
 233           // See how much time the rendering of the object took in nanoseconds.
 234           var timeStart = ext.getQueryObjectEXT(startQuery, ext.QUERY_RESULT_EXT);
 235           var timeEnd = ext.getQueryObjectEXT(endQuery, ext.QUERY_RESULT_EXT);
 236
 237           // Do something useful with the time.  Note that care should be
 238           // taken to use all significant bits of the result, not just the
 239           // least significant 32 bits.
 240           adjustObjectLODBasedOnDrawTime(timeEnd - timeStart);
 241         }
 242     </pre>
 243   </samplecode>
 244
 245   <history>
 246     <revision date="2013/04/02">
 247       <change>Initial revision.</change>
 248     </revision>
 249     <revision date="2013/04/03">
 250       <change>Based on public_webgl discussion, specified that queries' results only become available at well-defined times.</change>
 251     </revision>
 252     <revision date="2014/02/12">
 253       <change>Recast as EXT_disjoint_timer_query and harmonized with mirrored extension.</change>
 254     </revision>
 255     <revision date="2014/07/15">
 256       <change>Added NoInterfaceObject extended attribute.</change>
 257     </revision>
 258   </history>
 259 </draft>