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

   1 <?xml version="1.0"?>
   2
   3 <ratified href="WEBGL_depth_texture/">
   4   <name>WEBGL_depth_texture</name>
   5   <aliases>
   6     <alias>WEBKIT_WEBGL_depth_texture</alias>
   7     <alias>MOZ_WEBGL_depth_texture</alias>
   8   </aliases>
   9   <contact>
  10     <a href="https://www.khronos.org/webgl/public-mailing-list/">WebGL working group</a> (public_webgl 'at' khronos.org)
  11   </contact>
  12   <contributors>
  13     <contributor>Members of the WebGL working group</contributor>
  14     <contributor>Florian B&#246;sch (pyalot 'at' gmail.com)</contributor>
  15   </contributors>
  16   <number>9</number>
  17   <depends>
  18     <api version="1.0"/>
  19   </depends>
  20   <overview>
  21     <p>This extension exposes the
  22       <a href="http://angleproject.googlecode.com/svn/trunk/extensions/ANGLE_depth_texture.txt">ANGLE_depth_texture</a>
  23       functionality to WebGL. ANGLE_depth_texture provides a subset of the
  24       functionality from the OpenGL ES 2.0 extensions
  25       <a href="http://www.khronos.org/registry/gles/extensions/OES/OES_depth_texture.txt">OES_depth_texture</a>
  26       and
  27       <a href="http://www.khronos.org/registry/gles/extensions/OES/OES_packed_depth_stencil.txt">OES_packed_depth_stencil</a>, with certain restrictions added for portability reasons. Specifically:</p>
  28
  29       <ul>
  30       <li> ANGLE_depth_texture provides both depth and depth/stencil textures. </li>
  31       <li> ANGLE_depth_texture does not provide the <code>DEPTH24_STENCIL8_OES</code> renderbuffer internal format from the OES_packed_depth_stencil extension. The core WebGL specification already supports allocation of depth/stencil renderbuffers. </li>
  32       <li> ANGLE_depth_texture does not support loading image data via the TexImage or TexSubImage commands. Depth and depth/stencil textures created via this extension can only have their contents specified by rendering to them. </li>
  33       </ul>
  34
  35     <p>Consult the Errors section below for specific restrictions.
  36     </p>
  37
  38     <features>
  39       <feature>
  40         The <code>texImage2D</code> entry point is extended to accept the
  41         <code>format</code> parameter <code>DEPTH_COMPONENT</code> and
  42         <code>DEPTH_STENCIL</code>
  43       </feature>
  44       <feature>
  45         The <code>texImage2D</code> entry point is extended to accept the
  46         <code>internalFormat</code> parameter <code>DEPTH_COMPONENT</code>
  47         and <code>DEPTH_STENCIL</code>
  48       </feature>
  49       <feature>
  50         The <code>texImage2D</code> entry point is extended to accept
  51         the <code>type</code> parameter <code>UNSIGNED_SHORT</code>,
  52         <code>UNSIGNED_INT</code>, and
  53         <code>UNSIGNED_INT_24_8_WEBGL</code>
  54       </feature>
  55       <feature>
  56         The <code>framebufferTexture2D</code> entry point is extended to
  57         accept the <code>target</code> parameter
  58         <code>DEPTH_ATTACHMENT</code> and
  59         <code>DEPTH_STENCIL_ATTACHMENT</code>
  60       </feature>
  61       <feature>
  62         The <code>texImage2D</code> entry point is extended to accept
  63         <code>ArrayBufferView</code> of type <code>Uint16Array</code> and
  64         <code>Uint32Array</code>
  65       </feature>
  66       <feature>
  67         <p>
  68           The WebGL-specific constraints about <a href="http://www.khronos.org/registry/webgl/specs/1.0/#FBO_ATTACHMENTS">Framebuffer Object Attachments</a> are extended:</p>
  69
  70           <ul>
  71           <li> A texture attached to an FBO's <code>DEPTH_ATTACHMENT</code> attachment point must be allocated with the <code>DEPTH_COMPONENT</code> internal format. </li>
  72           <li> A texture attached to the <code>DEPTH_STENCIL_ATTACHMENT</code> attachment point must be allocated with the <code>DEPTH_STENCIL</code> internal format. </li>
  73           </ul>
  74
  75         <p>
  76           In the WebGL API, it is an error to concurrently attach either
  77           renderbuffers or textures to the following combinations of
  78           attachment points:</p>
  79
  80           <ul>
  81           <li> <code>DEPTH_ATTACHMENT</code> + <code>DEPTH_STENCIL_ATTACHMENT</code> </li>
  82           <li> <code>STENCIL_ATTACHMENT</code> + <code>DEPTH_STENCIL_ATTACHMENT</code> </li>
  83           <li> <code>DEPTH_ATTACHMENT</code> + <code>STENCIL_ATTACHMENT</code> </li>
  84           </ul>
  85
  86         <p>
  87           See the section
  88           <a href="http://www.khronos.org/registry/webgl/specs/1.0/#FBO_ATTACHMENTS">Framebuffer Object Attachments</a>
  89           in the WebGL specification for the behavior if these
  90           constraints are violated.
  91         </p>
  92       </feature>
  93     </features>
  94   </overview>
  95   <idl xml:space="preserve">
  96 interface WEBGL_depth_texture {
  97   const GLenum UNSIGNED_INT_24_8_WEBGL = 0x84FA;
  98 };
  99   </idl>
 100   <errors>
 101     <error>
 102       The error <code>INVALID_OPERATION</code> is generated by
 103       <code>texImage2D</code> if the <code>format</code> parameter is
 104       <code>DEPTH_COMPONENT</code> or <code>DEPTH_STENCIL</code> and the
 105       <code>target</code> is
 106       <code>TEXTURE_CUBE_MAP_{POSITIVE,NEGATIVE}_{X,Y,Z}</code>.
 107     </error>
 108     <error>
 109       The error <code>INVALID_OPERATION</code> is generated by
 110       <code>texImage2D</code> if <code>format</code> and
 111       <code>internalformat</code> are <code>DEPTH_COMPONENT</code> and
 112       <code>type</code> is not <code>UNSIGNED_SHORT</code> or
 113       <code>UNSIGNED_INT</code>.
 114     </error>
 115     <error>
 116        The error <code>INVALID_OPERATION</code> is generated by
 117        <code>texImage2D</code> if <code>format</code> and
 118        <code>internalformat</code> are not <code>DEPTH_COMPONENT</code>
 119        and <code>type</code> is <code>UNSIGNED_SHORT</code> or
 120        <code>UNSIGNED_INT</code>.
 121     </error>
 122     <error>
 123       The error <code>INVALID_OPERATION</code> is generated by
 124       <code>texImage2D</code> if <code>format</code> and
 125       <code>internalformat</code> are <code>DEPTH_STENCIL</code> and
 126       <code>type</code> is not <code>UNSIGNED_INT_24_8_WEBGL</code>.
 127     </error>
 128     <error>
 129       The error <code>INVALID_OPERATION</code> is generated by
 130       <code>texImage2D</code> if <code>format</code> and
 131       <code>internalformat</code> are not <code>DEPTH_STENCIL</code> and
 132       <code>type</code> is <code>UNSIGNED_INT_24_8_WEBGL</code>.
 133     </error>
 134     <error>
 135       The error <code>INVALID_OPERATION</code> is generated in the following situations:
 136       <ul>
 137         <li>
 138           <code>texImage2D</code> is called with <code>format</code> and
 139           <code>internalformat</code> of <code>DEPTH_COMPONENT</code> or
 140           <code>DEPTH_STENCIL</code> and
 141           <ul>
 142             <li> <code>target</code> is not TEXTURE_2D, </li>
 143             <li> <code>data</code> is not NULL, or </li>
 144             <li> <code>level</code> is not zero. </li>
 145           </ul>
 146         </li>
 147         <li>
 148           <code>texSubImage2D</code> is called with <code>format</code> of
 149           <code>DEPTH_COMPONENT</code> or <code>DEPTH_STENCIL</code>.
 150         </li>
 151         <li>
 152           <code>copyTexImage2D</code> is called with an
 153           <code>internalformat</code> that has a base internal format of
 154           <code>DEPTH_COMPONENT</code> or <code>DEPTH_STENCIL</code>.
 155         </li>
 156         <li>
 157           <code>copyTexSubImage2D</code> is called with a target texture
 158           that has a base internal format of <code>DEPTH_COMPONENT</code>
 159           or <code>DEPTH_STENCIL</code>.
 160         </li>
 161         <li>
 162           <code>generateMipmap</code> is called on a texture that has a
 163           base internal format of <code>DEPTH_COMPONENT</code> or
 164           <code>DEPTH_STENCIL</code>.
 165         </li>
 166       </ul>
 167     </error>
 168   </errors>
 169   <issues>
 170     <p>
 171       As per the ANGLE_depth_texture specification, when a depth
 172       texture is sampled, the value is stored into the RED channel.
 173       The contents of the GREEN, BLUE and ALPHA channels are
 174       implementation dependent. It is therefore recommended to use
 175       only the <code>r</code> component of variables in GLSL shaders
 176       that are used to reference depth textures.
 177     </p>
 178   </issues>
 179   <history>
 180     <revision date="2012/01/23">
 181       <change>Initial revision.</change>
 182     </revision>
 183     <revision date="2012/01/25">
 184       <change>Added provisions to exclude cube depth textures.</change>
 185     </revision>
 186     <revision date="2012/02/06">
 187       <change>Changed referenced WebGL API version from 2.0 to 1.0</change>
 188     </revision>
 189     <revision date="2012/02/24">
 190       <change>Removed the enumerants from the IDL which are contained in the context and added aliases to the extension name</change>
 191     </revision>
 192     <revision date="2012/03/01">
 193       <change>
 194         Renamed with OES prefix and removed the addendum due to expected harmonization between OES_depth_texture and ARB_depth_texture
 195         (depth cube maps).
 196       </change>
 197     </revision>
 198     <revision date="2012/06/04">
 199       <change>
 200         Renamed to WEBGL prefix, and changed to reference ANGLE_depth_texture, because of
 201         limitations preventing the current ANGLE library from loading of image data to depth
 202         textures. Incorporated errors from ANGLE_depth_texure extension specification.
 203       </change>
 204     </revision>
 205     <revision date="2012/06/20">
 206       <change>
 207         Incorporated depth/stencil support and UNSIGNED_INT_24_8_WEBGL enum after discussion on
 208         public_webgl mailing list, including supported behavior and additional error behavior.
 209         Extended rules in Section 6.5 ("Framebuffer Object Attachments") to handle texture
 210         attachments.
 211       </change>
 212     </revision>
 213     <revision date="2012/06/27">
 214       <change>
 215         Updated references to texSubImage2D. Added
 216         DEPTH_STENCIL_ATTACHMENT to framebufferTexture2D.
 217       </change>
 218     </revision>
 219     <revision date="2013/01/26">
 220       <change>Moved from draft to community approved status</change>
 221     </revision>
 222     <revision date="2013/02/28">
 223       <change>Updated to track ANGLE_depth_texture, indicating that only red channel is guaranteed.</change>
 224     </revision>
 225     <revision date="2013/05/15">
 226       <change>Ratified by Khronos Board of Promoters.</change>
 227     </revision>
 228   </history>
 229 </ratified>