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

   1 <?xml version="1.0"?>
   2
   3 <draft href="WEBGL_shared_resources/">
   4   <name>WEBGL_shared_resources</name>
   5   <contact>
   6     <a href="https://www.khronos.org/webgl/public-mailing-list/">WebGL working group</a> (public_webgl 'at' khronos.org)
   7   </contact>
   8   <contributors>
   9     <contributor>Members of the WebGL working group</contributor>
  10   </contributors>
  11   <number>22</number>
  12   <depends>
  13     <api version="1.0"/>
  14   </depends>
  15   <overview>
  16     <p>
  17       This extension exposes the ability to share WebGL resources with multiple WebGLRenderingContexts.
  18     </p>
  19     <p>
  20       Background:
  21     </p>
  22     <p>
  23       The OpenGL ES spec defines that you can share a resource (texture, buffer, shader, program,
  24       renderbuffer) with 2 or more GL contexts but with some caveats. To guarantee you'll see a
  25       change made in one context in other context requires calling glFinish on the context that
  26       made the change and call glBind on the context that wants to see the change.
  27     </p>
  28     <p>
  29       Not calling glFinish and/or glBind does not guarantee you won't see the results which means
  30       that users may do neither and their app might just happen to work on some platforms and
  31       mysteriously have glitches, rendering corruption, gl errors or program failure on others.
  32     </p>
  33     <p>
  34       WebGL must present consistent behavior for sharing and so this extension provides
  35       an API so that implementions can enforce and optimize these requirements.
  36     </p>
  37     <features>
  38       <feature>
  39         <p>Adds a new context creation parameter:</p>
  40         <dl>
  41             <dt><span class="prop-value">shareGroup</span></dt>
  42                 <dd>
  43                     <em>Default: undefined</em>. If the value is set to the <code>group</code>
  44                     attribute from the <code>WEBGL_shared_resources</code> object from an existing context
  45                     then resources from the existing context are shared with the newly created context.
  46                 </dd>
  47         </dl>
  48         <pre class="example">
  49 var canvas1 = document.createElement("canvas");
  50 var canvas2 = document.createElement("canvas");
  51 var ctx1 = canvas1.getContext("webgl");
  52 var sharedResourcesExtension = ctx1.getExtension("WEBGL_shared_resources");
  53 var ctx2 = canvas2.getContext("webgl", {
  54     shareGroup: sharedResourcesExtension.group
  55 });
  56         </pre>
  57       </feature>
  58       <feature>
  59         <p>
  60         In order for a context to use a resouce it must first acquire it.
  61         Contexts can make a request to acquire a resource by calling acquireSharedResource
  62         in one of 2 modes, EXCLUSIVE or READ_ONLY. A resource may be acquired by multiple
  63         contexts in READ_ONLY mode. The resource may only be acquired by one context
  64         if the mode is EXCLUSIVE. acquireSharedResource returns an id you can use to cancel the acquire
  65         by calling cancelAcquireSharedResource.
  66         When the resource is available in the requested mode the callback
  67         will be invoked. Resources start their life as acquired in EXCLUSIVE mode in the context
  68         in which they are created.
  69         </p>
  70         <p>
  71         To release a resource so it may be acquired by another context call releaseSharedResource and
  72         pass it the resource to be released.
  73         </p>
  74       </feature>
  75       <feature>
  76         <p>
  77         After a resource is acquired it must be bound before it is used. Binding
  78         means for buffers calling bindBuffer, for textures either bindTexture or
  79         framebufferTexture2D, for renderbuffers either bindRenderbuffer or framebufferRenderbuffer,
  80         for shaders attachShader, for programs useProgram. Binding once is sufficient to satisfy
  81         this requirement. In other words, if you have a texture attached to more than one texture
  82         unit the texture only needs to be re-bound to 1 texture unit.  Attemping to use a resource
  83         which has not been bound since it was acquired generates INVALID_OPERATION.
  84         </p>
  85         <p>
  86         Bind Requirement Algorithm:
  87         </p>
  88         <p>
  89         Each resource has a per-context bound flag. When a resource is acquired in a context its
  90         bound flag for that context is set to false. If one of the functions listed above
  91         is called the bound flag for that context is set to true. Drawing and reading functions,
  92         clear, drawArrays, drawElements, readPixels, that would access a resource whose bound flag
  93         for that context is false generate INVALID_FRAMEBUFFER_OPERATION. All other functions that
  94         use a resource whose bound flag for that context is false generate INVALID_OPERATION.
  95         </p>
  96         <p>
  97         Note: In the specific case of programs, it is not an error to call draw with a program
  98         or call useProgram for a program which has shaders that have
  99         been acquired but not re-attached. Nor it is an error to draw with or call useProgram
 100         for a program which has shaders that have not been acquired.  It is an error to call linkProgram
 101         for a program that is using shaders that have been acquired but not re-attached.
 102         </p>
 103       </feature>
 104       <feature>
 105         <p>
 106         When an attempt is made to use a resource that is not acquired in the current context
 107         the implementation must generate the error INVALID_OPERATION or INVALID_FRAMEBUFFER_OPRATION.
 108         This includes all gl calls
 109         that would access the given resource directly or indirectly. For example, a
 110         draw call must fail if any of the resources it would access is not acquired in the
 111         correct mode for the call. In other words, if the draw call would read from a buffer
 112         or texture and that buffer or texture is not acquired for READ_ONLY or EXCLUSIVE mode the draw
 113         must fail with INVALID_FRAMEBUFFER_OPERATION. If the draw would render to a texture or renderbuffer
 114         that is not acquired for EXCLUSIVE mode the draw must fail and generate INVALID_FRAMEBUFFER_OPERATION.
 115         If a program used in the draw is not acquired for READ_ONLY or EXCLUSIVE mode the draw or clear must fail
 116         and generate INVALID_FRAMEBUFFER_OPERATION.
 117         </p>
 118         <p>
 119         For buffers not acquired this includes but is not limited to
 120         </p>
 121         <pre>
 122           bindBuffer
 123           bufferData
 124           bufferSubData
 125           deleteBuffer
 126           drawArrays
 127           drawElements
 128           getParameter with parameter (BUFFER_SIZE or BUFFER_USAGE)
 129           isBuffer
 130           vertexAttribPointer
 131         </pre>
 132         <p>
 133         For a buffer acquired in READ_ONLY mode this includes but is not limited to
 134         </p>
 135         <pre>
 136           bufferData
 137           bufferSubData
 138         </pre>
 139         <p>
 140         For programs not acquired this includes but is not limited to
 141         </p>
 142         <pre>
 143           attachShader
 144           bindAttribLocation
 145           drawArrays
 146           drawElements
 147           deleteProgram
 148           getActiveAttrib
 149           getActiveUniform
 150           getAttribLocation
 151           getUniformLocation
 152           getProgramParameter
 153           getProgramInfoLog
 154           isProgram
 155           linkProgram
 156           useProgram
 157           validateProgram
 158         </pre>
 159         <p>
 160         For programs acquired in READ_ONLY mode includes but is not limited to
 161         </p>
 162         <pre>
 163           bindAttribLocation
 164           deleteProgram
 165           linkProgram
 166         </pre>
 167         <p>
 168         For renderbuffers not acquired this includes but is not limited to
 169         </p>
 170         <pre>
 171           bindRenderbuffer
 172           clear
 173           deleteRenderbuffer
 174           drawArrays
 175           drawElements
 176           framebufferRenderbuffer
 177           isRenderbuffer
 178           renderbufferStorage
 179         </pre>
 180         <p>
 181         For renderbuffers acquired in READ_ONLY mode this includes
 182         </p>
 183         <pre>
 184           clear
 185           deleteRenderbuffer
 186           drawArrays
 187           drawElements
 188           renderbufferStorage
 189         </pre>
 190         <p>
 191         For shaders not acquired this includes but is not limited to
 192         </p>
 193         <pre>
 194           attachShader
 195           compileShader
 196           deleteShader
 197           getShaderSource
 198           getShaderParameter
 199           isShader
 200           shaderSource
 201         </pre>
 202         <p>
 203         For shaders acquired in READ_ONLY mode this includes but is not limited to
 204         </p>
 205         <pre>
 206           deleteShader
 207           compileShader
 208           shaderSource
 209         </pre>
 210         <p>
 211         For textures not acquired this includes but is not limited to
 212         </p>
 213         <pre>
 214           bindTexture
 215           clear
 216           compressedTexImage2D
 217           compressedTexSubImage2D
 218           copyTexImage2D
 219           copyTexSubImage2D
 220           drawArrays
 221           drawElements
 222           deleteTexture
 223           framebufferTexture2D
 224           getTexParameter
 225           isTexture
 226           texImage2D
 227           texParameter
 228           texSubImage2D
 229         </pre>
 230         <p>
 231         For textures acquired in READ_ONLY mode this includes but is not limited to
 232         </p>
 233         <pre>
 234           clear
 235           compressedTexImage2D
 236           compressedTexSubImage2D
 237           copyTexImage2D
 238           copyTexSubImage2D
 239           drawArrays
 240           drawElements
 241           deleteTexture
 242           texImage2D
 243           texParameter
 244           texSubImage2D
 245         </pre>
 246         <p>
 247         The term "not limited to" is intended to point out that extension may enable
 248         other functions to which these rule should apply. For example drawArraysInstancedANGLE
 249         must follow the same rules as drawArrays.
 250         </p>
 251       </feature>
 252       <feature>
 253           <p>
 254           Calling checkFramebufferStatus with the argument FRAMEBUFFER or DRAW_FRAMEBUFFER must
 255           return FRAMEBUFFER_INCOMPLETE_ATTACHMENT if any of the resources referenced by the currently
 256           bound framebuffer are not acquired for EXCLUSIVE access.
 257           Calling checkFramebufferStatus with the argument READ_FRAMEBUFFER will return
 258           FRAMEBUFFER_INCOMPLETE_ATTACHMENT if any of the resources referenced by the currently bound
 259           framebuffer are not acquired for EXCLUSIVE or READ_ONLY access.
 260           </p>
 261           <p>
 262           Note: This extension exposes the constants READ_FRAMEBUFFER and DRAW_FRAMEBUFFER only for
 263           the purpose of calling checkFramebufferStatus. In particular, this extension does not enable
 264           calling bindFramebuffer with either constant.
 265           </p>
 266       </feature>
 267       <feature>
 268           <p>
 269           A context that is deleted automatically releases all resources it has acquired. Note that
 270           currently there is no way to explicitly delete a context. Contexts are deleted through
 271           garbage collection.
 272           </p>
 273       </feature>
 274       <feature>
 275         <p>
 276          Note that implementing this extension changes the base class of the sharable resources.
 277          Specifically: WebGLBuffer, WebGLProgram, WebGLRenderbuffer, WebGLShader, and WebGLTexture
 278          change their base class from WebGLObject to WebGLSharedObject.
 279         </p>
 280       </feature>
 281     </features>
 282   </overview>
 283   <issues>
 284     <ul>
 285       <li>
 286           <div>
 287               Q: What happens if one context deletes a resource another context is attempting to acquire?
 288           </div>
 289           <div>
 290               A: Nothing special. The acquire will succeed when the context that currently has the resource
 291               releases it. The context that acquires the resource can use the WebGLSharedObject
 292               (buffer, texture, etc...) and will get the normal WebGL behavior associated with using
 293               a deleted resource.
 294           </div>
 295       </li>
 296       <li>
 297           <div>
 298               Q: Can you attach a resources that you have not acquired to a container?
 299           </div>
 300           <div>
 301               A: No. An attachment can remain attached while it is released but it must be acquired
 302                  when attaching.
 303                  In particular a framebuffer attachment may not be attached to a framebuffer unless
 304                  the attachment is acquired. A shader may not be attached to a program unless the
 305                  shader is acquired. A buffer may not be attached to an attibute, vertexAttribPointer,
 306                  unless the buffer is acquired.
 307           </div>
 308       </li>
 309       <li>
 310           <div>
 311  Q: What happens if you try to acquire a resource you already have acquired?
 312           </div>
 313           <div>
 314  A: It will generate INVALID_OPERATION
 315           </div>
 316       </li>
 317     </ul>
 318   </issues>
 319   <idl xml:space="preserve">
 320 [NoInterfaceObject]
 321 interface WEBGL_shared_resources {
 322      const GLenum READ_ONLY  = 0x0001;
 323      const GLenum EXCLUSIVE  = 0x0004;
 324
 325      const GLenum READ_FRAMEBUFFER = 0x8CA8;
 326      const GLenum DRAW_FRAMEBUFFER = 0x8CA9;
 327
 328      readonly attribute WebGLShareGroup group;
 329
 330      long acquireSharedResource(
 331          WebGLSharedObject resource,
 332          GLenum mode,
 333          AcquireResourcesCallback callback);
 334      void releaseSharedResource(
 335          WebGLSharedObject resource);
 336      void cancelAcquireSharedResource(long id);
 337 };
 338
 339 callback AcquireSharedResourcesCallback = void ();
 340
 341 [NoInterfaceObject]
 342 interface WebGLShareGroup {
 343 }
 344
 345 interface WebGLSharedObject : WebGLObject {
 346 }
 347
 348 interface WebGLBuffer : WebGLSharedObject {
 349 }
 350
 351 interface WebGLProgram : WebGLSharedObject {
 352 }
 353
 354 interface WebGLRenderbuffer : WebGLSharedObject {
 355 }
 356
 357 interface WebGLShader : WebGLSharedObject {
 358 }
 359
 360 interface WebGLTexture : WebGLSharedObject {
 361 }
 362   </idl>
 363   <history>
 364     <revision date="2012/02/06">
 365       <change>Initial revision.</change>
 366     </revision>
 367     <revision date="2013/05/14">
 368       <change>Moved to draft after agreement in working group.</change>
 369     </revision>
 370     <revision date="2014/07/15">
 371       <change>Added NoInterfaceObject extended attribute to extension interface and WebGLShareGroup.</change>
 372     </revision>
 373   </history>
 374 </draft>