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       <feature>
  94         <p>
  95           As per the OpenGL ES spec, there is no guarantee that the OpenGL ES implementation
  96           will use the texture type to determine how to store the depth texture internally.
  97           It may choose to downsample the 32-bit depth values to 16-bit or even 24-bit.
  98           When a depth or depth/stencil texture is attached to a framebuffer object, calls to getParameter
  99           with the DEPTH_BITS and STENCIL_BITS enums return the following:
 100           <table>
 101             <tr>
 102               <th>Texture Type</th>
 103               <th>DEPTH_BITS (GLint)</th>
 104               <th>STENCIL_BITS (GLint)</th>
 105             </tr>
 106             <tr>
 107               <td>UNSIGNED_SHORT</td>
 108               <td>>= 16</td>
 109               <td>0</td>
 110             </tr>
 111             <tr>
 112               <td>UNSIGNED_INT</td>
 113               <td>>= 16</td>
 114               <td>0</td>
 115             </tr>
 116             <tr>
 117               <td>UNSIGNED_INT_24_8_WEBGL</td>
 118               <td>>= 24</td>
 119               <td>>= 8</td>
 120             </tr>
 121           </table>
 122         </p>
 123       </feature>
 124     </features>
 125   </overview>
 126   <idl xml:space="preserve">
 127 [NoInterfaceObject]
 128 interface WEBGL_depth_texture {
 129   const GLenum UNSIGNED_INT_24_8_WEBGL = 0x84FA;
 130 };
 131   </idl>
 132   <errors>
 133     <error>
 134       The error <code>INVALID_OPERATION</code> is generated by
 135       <code>texImage2D</code> if the <code>format</code> parameter is
 136       <code>DEPTH_COMPONENT</code> or <code>DEPTH_STENCIL</code> and the
 137       <code>target</code> is
 138       <code>TEXTURE_CUBE_MAP_{POSITIVE,NEGATIVE}_{X,Y,Z}</code>.
 139     </error>
 140     <error>
 141       The error <code>INVALID_OPERATION</code> is generated by
 142       <code>texImage2D</code> if <code>format</code> and
 143       <code>internalformat</code> are <code>DEPTH_COMPONENT</code> and
 144       <code>type</code> is not <code>UNSIGNED_SHORT</code> or
 145       <code>UNSIGNED_INT</code>.
 146     </error>
 147     <error>
 148        The error <code>INVALID_OPERATION</code> is generated by
 149        <code>texImage2D</code> if <code>format</code> and
 150        <code>internalformat</code> are not <code>DEPTH_COMPONENT</code>
 151        and <code>type</code> is <code>UNSIGNED_SHORT</code> or
 152        <code>UNSIGNED_INT</code>.
 153     </error>
 154     <error>
 155       The error <code>INVALID_OPERATION</code> is generated by
 156       <code>texImage2D</code> if <code>format</code> and
 157       <code>internalformat</code> are <code>DEPTH_STENCIL</code> and
 158       <code>type</code> is not <code>UNSIGNED_INT_24_8_WEBGL</code>.
 159     </error>
 160     <error>
 161       The error <code>INVALID_OPERATION</code> is generated by
 162       <code>texImage2D</code> if <code>format</code> and
 163       <code>internalformat</code> are not <code>DEPTH_STENCIL</code> and
 164       <code>type</code> is <code>UNSIGNED_INT_24_8_WEBGL</code>.
 165     </error>
 166     <error>
 167       The error <code>INVALID_OPERATION</code> is generated in the following situations:
 168       <ul>
 169         <li>
 170           <code>texImage2D</code> is called with <code>format</code> and
 171           <code>internalformat</code> of <code>DEPTH_COMPONENT</code> or
 172           <code>DEPTH_STENCIL</code> and
 173           <ul>
 174             <li> <code>target</code> is not TEXTURE_2D, </li>
 175             <li> <code>data</code> is not NULL, or </li>
 176             <li> <code>level</code> is not zero. </li>
 177           </ul>
 178         </li>
 179         <li>
 180           <code>texSubImage2D</code> is called with <code>format</code> of
 181           <code>DEPTH_COMPONENT</code> or <code>DEPTH_STENCIL</code>.
 182         </li>
 183         <li>
 184           <code>copyTexImage2D</code> is called with an
 185           <code>internalformat</code> that has a base internal format of
 186           <code>DEPTH_COMPONENT</code> or <code>DEPTH_STENCIL</code>.
 187         </li>
 188         <li>
 189           <code>copyTexSubImage2D</code> is called with a target texture
 190           that has a base internal format of <code>DEPTH_COMPONENT</code>
 191           or <code>DEPTH_STENCIL</code>.
 192         </li>
 193         <li>
 194           <code>generateMipmap</code> is called on a texture that has a
 195           base internal format of <code>DEPTH_COMPONENT</code> or
 196           <code>DEPTH_STENCIL</code>.
 197         </li>
 198       </ul>
 199     </error>
 200   </errors>
 201   <issues>
 202     <p>
 203       As per the ANGLE_depth_texture specification, when a depth
 204       texture is sampled, the value is stored into the RED channel.
 205       The contents of the GREEN, BLUE and ALPHA channels are
 206       implementation dependent. It is therefore recommended to use
 207       only the <code>r</code> component of variables in GLSL shaders
 208       that are used to reference depth textures.
 209     </p>
 210   </issues>
 211   <history>
 212     <revision date="2012/01/23">
 213       <change>Initial revision.</change>
 214     </revision>
 215     <revision date="2012/01/25">
 216       <change>Added provisions to exclude cube depth textures.</change>
 217     </revision>
 218     <revision date="2012/02/06">
 219       <change>Changed referenced WebGL API version from 2.0 to 1.0</change>
 220     </revision>
 221     <revision date="2012/02/24">
 222       <change>Removed the enumerants from the IDL which are contained in the context and added aliases to the extension name</change>
 223     </revision>
 224     <revision date="2012/03/01">
 225       <change>
 226         Renamed with OES prefix and removed the addendum due to expected harmonization between OES_depth_texture and ARB_depth_texture
 227         (depth cube maps).
 228       </change>
 229     </revision>
 230     <revision date="2012/06/04">
 231       <change>
 232         Renamed to WEBGL prefix, and changed to reference ANGLE_depth_texture, because of
 233         limitations preventing the current ANGLE library from loading of image data to depth
 234         textures. Incorporated errors from ANGLE_depth_texure extension specification.
 235       </change>
 236     </revision>
 237     <revision date="2012/06/20">
 238       <change>
 239         Incorporated depth/stencil support and UNSIGNED_INT_24_8_WEBGL enum after discussion on
 240         public_webgl mailing list, including supported behavior and additional error behavior.
 241         Extended rules in Section 6.5 ("Framebuffer Object Attachments") to handle texture
 242         attachments.
 243       </change>
 244     </revision>
 245     <revision date="2012/06/27">
 246       <change>
 247         Updated references to texSubImage2D. Added
 248         DEPTH_STENCIL_ATTACHMENT to framebufferTexture2D.
 249       </change>
 250     </revision>
 251     <revision date="2013/01/26">
 252       <change>Moved from draft to community approved status</change>
 253     </revision>
 254     <revision date="2013/02/28">
 255       <change>Updated to track ANGLE_depth_texture, indicating that only red channel is guaranteed.</change>
 256     </revision>
 257     <revision date="2013/05/15">
 258       <change>Ratified by Khronos Board of Promoters.</change>
 259     </revision>
 260     <revision date="2014/07/15">
 261       <change>Added NoInterfaceObject extended attribute.</change>
 262     </revision>
 263   </history>
 264 </ratified>