1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/gfx/angle/extensions/ANGLE_depth_texture.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,402 @@
1.4 +Name
1.5 +
1.6 + ANGLE_depth_texture
1.7 +
1.8 +Name Strings
1.9 +
1.10 + GL_ANGLE_depth_texture
1.11 +
1.12 +Contributors
1.13 +
1.14 + Nicolas Capens, TransGaming
1.15 + Daniel Koch, TransGaming
1.16 + Shannon Woods, TransGaming
1.17 + Kenneth Russell, Google
1.18 + Vangelis Kokkevis, Google
1.19 + Gregg Tavares, Google
1.20 + Contributors to OES_depth_texture
1.21 + Contributors to OES_packed_depth_stencil
1.22 +
1.23 +Contact
1.24 +
1.25 + Shannon Woods, TransGaming (shannon 'dot' woods 'at' transgaming.com)
1.26 +
1.27 +Status
1.28 +
1.29 + Implemented in ANGLE.
1.30 +
1.31 +Version
1.32 +
1.33 + Last Modified Date: February 25, 2013
1.34 + Revision: #4
1.35 +
1.36 +Number
1.37 +
1.38 + TBD
1.39 +
1.40 +Dependencies
1.41 +
1.42 + OpenGL ES 2.0 is required.
1.43 + This extension is written against the OpenGL ES 2.0.25 specification
1.44 +
1.45 + OES_packed_depth_stencil affects the definition of this extension.
1.46 +
1.47 + EXT_texture_storage affects the definition of this extension.
1.48 +
1.49 +Overview
1.50 +
1.51 + This extension defines support for 2D depth and depth-stencil
1.52 + textures in an OpenGL ES implementation.
1.53 +
1.54 + This extension incorporates the depth texturing functionality of
1.55 + OES_depth_texture and OES_packed_depth_stencil, but does not
1.56 + provide the ability to load existing data via TexImage2D or
1.57 + TexSubImage2D. This extension also allows implementation
1.58 + variability in which components from a sampled depth texture
1.59 + contain the depth data. Depth textures created with this
1.60 + extension only support 1 level.
1.61 +
1.62 +New Procedures and Functions
1.63 +
1.64 + None
1.65 +
1.66 +New Tokens
1.67 +
1.68 + Accepted by the <format> parameter of TexImage2D and TexSubImage2D and
1.69 + <internalformat> parameter of TexImage2D:
1.70 +
1.71 + DEPTH_COMPONENT 0x1902
1.72 + DEPTH_STENCIL_OES 0x84F9
1.73 +
1.74 + Accepted by the <type> parameter of TexImage2D, TexSubImage2D:
1.75 +
1.76 + UNSIGNED_SHORT 0x1403
1.77 + UNSIGNED_INT 0x1405
1.78 + UNSIGNED_INT_24_8_OES 0x84FA
1.79 +
1.80 + Accepted by the <internalformat> parameter of TexStorage2DEXT:
1.81 +
1.82 + DEPTH_COMPONENT16 0x81A5
1.83 + DEPTH_COMPONENT32_OES 0x81A7
1.84 + DEPTH24_STENCIL8_OES 0x88F0
1.85 +
1.86 +Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation)
1.87 +
1.88 + Update Section 2.10.5 "Shader Execution" in the subsection titled
1.89 + "Texture Access" add a new paragraph before the last paragraph add
1.90 + this line:
1.91 +
1.92 + "The stencil index texture internal component is ignored if the base
1.93 + internal format is DEPTH_STENCIL_OES.
1.94 +
1.95 + If a vertex shader uses..."
1.96 +
1.97 +Additions to Chapter 3 of the OpenGL ES 2.0 specification (Rasterization)
1.98 +
1.99 + Add the following rows to Table 3.2 (page 62):
1.100 +
1.101 + type Parameter GL Data Type Special
1.102 + ------------------------------------------------
1.103 + ... ... ...
1.104 + UNSIGNED_SHORT ushort No
1.105 + UNSIGNED_INT uint No
1.106 + UNSIGNED_INT_24_8_OES uint Yes
1.107 +
1.108 + Add the following rows to Table 3.3 (page 62):
1.109 +
1.110 + Format Name Element Meaning and Order Target Buffer
1.111 + ------------------------------------------------------------------
1.112 + ... ... ...
1.113 + DEPTH_COMPONENT Depth Depth
1.114 + DEPTH_STENCIL_OES Depth and Stencil Index Depth and Stencil
1.115 + ... ... ...
1.116 +
1.117 + Add a row to Table 3.5 "Packed pixel formats" (page 64):
1.118 +
1.119 + type Parameter GL Type Components Pixel Formats
1.120 + ------------------------------------------------------------------
1.121 + ... ... ... ...
1.122 + UNSIGNED_INT_24_8_OES uint 2 DEPTH_STENCIL_OES
1.123 +
1.124 + Add a new table after Table 3.6 (page 64):
1.125 +
1.126 + UNSIGNED_INT_24_8_OES
1.127 +
1.128 + 31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0
1.129 + +----------------------------------+---------------+
1.130 + | 1st Component | 2nd Component |
1.131 + +----------------------------------+---------------+
1.132 +
1.133 + Table 3.6.B: UNSIGNED_INT formats
1.134 +
1.135 + Add a row to Table 3.7 "Packed pixel field assignments" (page 65):
1.136 +
1.137 + Format | 1st 2nd 3rd 4th
1.138 + ------------------+-------------------------------
1.139 + ... | ... ... ... ...
1.140 + DEPTH_STENCIL_OES | depth stencil N/A N/A
1.141 +
1.142 + Add the following paragraph to the end of the section "Conversion to
1.143 + floating-point" (page 65):
1.144 +
1.145 + "For groups of components that contain both standard components and index
1.146 + elements, such as DEPTH_STENCIL_OES, the index elements are not converted."
1.147 +
1.148 + In section 3.7.1 "Texture Image Specification", update page 67 to
1.149 + say:
1.150 +
1.151 + "The selected groups are processed as described in section 3.6.2, stopping
1.152 + just before final conversion. Each R, G, B, A, or depth value so generated
1.153 + is clamped to [0, 1], while the stencil index values are masked by 2^n-1,
1.154 + where n is the number of stencil bits in the internal format resolution
1.155 + (see below).
1.156 +
1.157 + Components are then selected from the resulting R, G, B, A, depth, or
1.158 + stencil index values to obtain a texture with the base internal format
1.159 + specified by <internalformat>. Table 3.8 summarizes the mapping of R, G,
1.160 + B, A, depth, or stencil values to texture components, as a function of the
1.161 + base internal format of the texture image. <internalformat> may be
1.162 + specified as one of the internal format symbolic constants listed in
1.163 + table 3.8. Specifying a value for <internalformat> that is not one of the
1.164 + above values generates the error INVALID_VALUE. If <internalformat> does
1.165 + not match <format>, the error INVALID_OPERATION is generated.
1.166 +
1.167 + Textures with a base internal format of DEPTH_COMPONENT or
1.168 + DEPTH_STENCIL_OES are supported by texture image specification commands
1.169 + only if <target> is TEXTURE_2D. Using these formats in conjunction with
1.170 + any other <target> will result in an INVALID_OPERATION error.
1.171 +
1.172 + Textures with a base internal format of DEPTH_COMPONENT or
1.173 + DEPTH_STENCIL_OES only support one level of image data. Specifying a
1.174 + non-zero value for <level> will result in an INVALID_OPERATION error.
1.175 +
1.176 + Textures with a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES
1.177 + require either depth component data or depth/stencil component data.
1.178 + Textures with other base internal formats require RGBA component data. The
1.179 + error INVALID_OPERATION is generated if the base internal format is
1.180 + DEPTH_COMPONENT or DEPTH_STENCIL_OES and <format> is not DEPTH_COMPONENT or
1.181 + DEPTH_STENCIL_OES, or if the base internal format is not DEPTH_COMPONENT or
1.182 + DEPTH_STENCIL_OES and <format> is DEPTH_COMPONENT or DEPTH_STENCIL_OES.
1.183 +
1.184 + Textures with a base internal format of DEPTH_COMPONENT or
1.185 + DEPTH_STENCIL_OES do not support loading image data via the TexImage
1.186 + commands. They can only have their contents specified by rendering
1.187 + to them. The INVALID_OPERATION error is generated by the TexImage2D
1.188 + command if <data> is not NULL for such textures."
1.189 +
1.190 + Add a row to table 3.8 (page 68), and update the title of the
1.191 + second column:
1.192 +
1.193 + Base Internal Format RGBA, Depth and Stencil Values Internal Components
1.194 + -------------------------------------------------------------------------
1.195 + ... ... ...
1.196 + DEPTH_COMPONENT Depth D
1.197 + DEPTH_STENCIL_OES Depth,Stencil D,S
1.198 + ... ... ...
1.199 +
1.200 + Update the caption for table 3.8 (page 68)
1.201 +
1.202 + "Table 3.8: Conversion from RGBA, depth, and stencil pixel components to
1.203 + internal texture components. Texture components R, G, B, A, and L are
1.204 + converted back to RGBA colors during filtering as shown in table 3.12.
1.205 + Texture components D are converted to RGBA colors as described in
1.206 + section 3.7.8-1/2."
1.207 +
1.208 + Add the following to section 3.7.2 "Alternate Texture Image Specification
1.209 + Commands":
1.210 +
1.211 + "CopyTexImage2D and CopyTexSubImage2D generate the INVALID_OPERATION
1.212 + error if the base internal format of the destination texture is
1.213 + DEPTH_COMPONENT or DEPTH_STENCIL_OES.
1.214 +
1.215 + TexSubImage2D generates the INVALID_OPERATION error if the base internal
1.216 + format of the texture is DEPTH_COMPONENT or DEPTH_STENCIL_OES."
1.217 +
1.218 + Add a new section between sections 3.7.8 and 3.7.9:
1.219 +
1.220 + "3.7.8-1/2 Depth/Stencil Textures
1.221 +
1.222 + If the currently bound texture's base internal format is DEPTH_COMPONENT or
1.223 + DEPTH_STENCIL_OES, then the output of the texture unit is as described
1.224 + below. Otherwise, the texture unit operates in the normal manner.
1.225 +
1.226 + Let <D_t> be the depth texture value, provided by the shader's texture lookup
1.227 + function. Then the effective texture value is computed as follows:
1.228 + <Tau> = <D_t>
1.229 +
1.230 + If the texture image has a base internal format of DEPTH_STENCIL_OES, then
1.231 + the stencil index texture component is ignored. The texture value <Tau> does
1.232 + not include a stencil index component, but includes only the depth
1.233 + component.
1.234 +
1.235 + The resulting <Tau> is assigned to <R_t>. In some implementations, <Tau> is
1.236 + also assigned to <G_t>, <B_t>, or <A_t>. Thus in table 3.12, textures with
1.237 + depth component data behave as if their base internal format is RGBA, with
1.238 + values in <G_t>, <B_t>, and <A_t> being implementation dependent."
1.239 +
1.240 + Add the following to section 3.7.11 "Mipmap Generation":
1.241 +
1.242 + "If the level zero array contains depth or depth-stencil data, the
1.243 + error INVALID_OPERATION is generated."
1.244 +
1.245 + Insert a new paragraph after the first paragraph of the "Texture Access"
1.246 + subsection of section 3.8.2 on page 87, which says:
1.247 +
1.248 + "Texture lookups involving textures with depth component data generate
1.249 + a texture source color by using depth data directly, as described in
1.250 + section 3.7.8-1/2. The stencil texture internal component is ignored
1.251 + if the base internal format is DEPTH_STENCIL_OES."
1.252 +
1.253 +Additions to Chapter 4 of the OpenGL ES 2.0 specification (Per-Fragment
1.254 +Operations and the Framebuffer)
1.255 +
1.256 + In section 4.4.5 "Framebuffer Completeness", replace the the 3rd
1.257 + paragraph with the following text:
1.258 +
1.259 + "* An internal format is color-renderable if it is one of the formats
1.260 + from table 4.5 noted as color-renderable or if it is unsized format
1.261 + RGBA or RGB. No other formats, including compressed internal formats,
1.262 + are color-renderable.
1.263 +
1.264 + * An internal format is depth-renderable if it is one of the sized
1.265 + internal formats from table 4.5 noted as depth-renderable, if it
1.266 + is the unsized format DEPTH_COMPONENT or if it is the internal
1.267 + format value of DEPTH24_STENCIL8_OES. No other formats are
1.268 + depth-renderable.
1.269 +
1.270 + * An internal format is stencil-renderable if it is one of the sized
1.271 + internal formats from table 4.5 noted as stencil-renderable or if it
1.272 + is DEPTH24_STENCIL8_OES. No other formats are stencil-renderable."
1.273 +
1.274 +Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special
1.275 +Functions)
1.276 +
1.277 + None.
1.278 +
1.279 +Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State
1.280 +Requests)
1.281 +
1.282 + None.
1.283 +
1.284 +Interactions with OES_packed_depth_stencil
1.285 +
1.286 + If OES_packed_depth_stencil is not supported, mentions of
1.287 + DEPTH_STENCIL_OES and UNSIGNED_INT_24_8_OES as a format/type combinations
1.288 + for TexImage2D and TexSubImage2D are omitted. Mentions of
1.289 + the internal format DEPTH24_STENCIL8_OES are also omitted.
1.290 +
1.291 +Interactions with EXT_texture_storage
1.292 +
1.293 + If EXT_texture_storage is supported the following internalformat
1.294 + to format/type mappings are used:
1.295 +
1.296 + <internalformat> <format> <type>
1.297 + ---------------- -------- ------
1.298 + DEPTH_COMPONENT16 DEPTH_COMPONENT UNSIGNED_SHORT
1.299 + DEPTH_COMPONENT32_OES DEPTH_COMPONENT UNSIGNED_INT
1.300 + DEPTH24_STENCIL8_OES DEPTH_STENCIL_OES UNSIGNED_INT
1.301 +
1.302 + Textures with the above <internalformats> only support one level of
1.303 + image data. Specifying a value other than one for the <levels> parameter
1.304 + to TexStorage2DEXT will result in an INVALID_OPERATION error.
1.305 +
1.306 + If EXT_texture_storage is not supported, ignore any references
1.307 + to TexStorage2DEXT.
1.308 +
1.309 +Errors
1.310 +
1.311 + The error INVALID_OPERATION is generated by TexImage2D if <format> and
1.312 + <internalformat> are DEPTH_COMPONENT and <type> is not UNSIGNED_SHORT,
1.313 + or UNSIGNED_INT.
1.314 +
1.315 + The error INVALID_OPERATION is generated by TexSubImage2D if <format> is
1.316 + DEPTH_COMPONENT and <type> is not UNSIGNED_SHORT, or UNSIGNED_INT.
1.317 +
1.318 + The error INVALID_OPERATION is generated by TexImage2D if <format> and
1.319 + <internalformat> are not DEPTH_COMPONENT and <type> is UNSIGNED_SHORT,
1.320 + or UNSIGNED_INT.
1.321 +
1.322 + The error INVALID_OPERATION is generated by TexSubImage2D if <format> is
1.323 + not DEPTH_COMPONENT and <type> is UNSIGNED_SHORT, or UNSIGNED_INT.
1.324 +
1.325 + The error INVALID_OPERATION is generated by TexImage2D if <format> and
1.326 + <internalformat> are DEPTH_STENCIL_OES and <type> is not
1.327 + UNSIGNED_INT_24_8_OES.
1.328 +
1.329 + The error INVALID_OPERATION is generated by TexSubImage2D if <format>
1.330 + is DEPTH_STENCIL_OES and <type> is not UNSIGNED_INT_24_8_OES.
1.331 +
1.332 + The error INVALID_OPERATION is generated by TexImage2D if <format> and
1.333 + <internalformat> is not DEPTH_STENCIL_OES and <type> is
1.334 + UNSIGNED_INT_24_8_OES.
1.335 +
1.336 + The error INVALID_OPERATION is generated by TexSubImage2D if <format>
1.337 + is not DEPTH_STENCIL_OES and <type> is UNSIGNED_INT_24_8_OES.
1.338 +
1.339 + The error INVALID_OPERATION is generated in the following situations:
1.340 + - TexImage2D is called with <format> and <internalformat> of
1.341 + DEPTH_COMPONENT or DEPTH_STENCIL_OES and
1.342 + - <target> is not TEXTURE_2D,
1.343 + - <data> is not NULL, or
1.344 + - <level> is not zero.
1.345 + - TexSubImage2D is called with <format> of DEPTH_COMPONENT or
1.346 + DEPTH_STENCIL_OES.
1.347 + - TexStorage2DEXT is called with <internalformat> of DEPTH_COMPONENT16,
1.348 + DEPTH_COMPONENT32_OES, or DEPTH24_STENCIL8_OES, and
1.349 + - <target> is not TEXTURE_2D, or
1.350 + - <levels> is not one.
1.351 + - CopyTexImage2D is called with an <internalformat> that has a base
1.352 + internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES.
1.353 + - CopyTexSubImage2D is called with a target texture that has a base
1.354 + internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES.
1.355 + - GenerateMipmap is called on a texture that has a base internal format
1.356 + of DEPTH_COMPONENT or DEPTH_STENCIL_OES.
1.357 +
1.358 +New State
1.359 +
1.360 + None.
1.361 +
1.362 +Issues
1.363 +
1.364 + 1) What are the differences between this extension and OES_depth_texture
1.365 + and OES_packed_depth_stencil?
1.366 +
1.367 + RESOLVED: This extension:
1.368 + - does not support loading pre-baked depth stencil data via
1.369 + TexImage2D or TexSubImage2D.
1.370 + - allows variability in the y-, z-, and w-components of the sample
1.371 + results from depth textures.
1.372 + - only supports one level textures.
1.373 + - explicitly lists the errors for unsupported functionality.
1.374 + Since these were not clearly specified in the OES_depth_texture
1.375 + extension there may be differences in error values between
1.376 + implementations of OES_depth_texture and ANGLE_depth_texture.
1.377 + This specification was also rebased to apply against the OpenGL ES 2.0
1.378 + specification instead of the OpenGL specification, making it more
1.379 + obvious what all the functionality changes are.
1.380 +
1.381 + 2) Why does TexSubImage2D accept the new format/type combinations even
1.382 + though it does not actually support loading data?
1.383 +
1.384 + RESOLVED: This was done to be more consistent with the OES_depth_texture
1.385 + extension and to make it easier to add support for loading texture
1.386 + data if it is possible to support in the future.
1.387 +
1.388 + 3) Why are only 1-level depth textures supported?
1.389 +
1.390 + RESOLVED: The only use for multiple levels of depth textures would
1.391 + be for fitlered texturing. However since it is not possible to
1.392 + render to non-zero-level texture levels in OpenGL ES 2.0, and since
1.393 + this extension forbids loading existing data and GenerateMipmap on
1.394 + depth textures, it is impossible to initialize or specify contents
1.395 + for non-zero levels of depth textures.
1.396 +
1.397 +Revision History
1.398 +
1.399 + 02/25/2013 swoods revise to allow texture lookup to guarantee depth values
1.400 + only in red channel of sample result.
1.401 + 06/04/2012 dgkoch fix errors, disallow multi-level depth textures.
1.402 + 05/30/2012 dgkoch minor updates and add issues.
1.403 + 05/23/2012 dgkoch intial revision based on OES_depth_texture and
1.404 + OES_packed_depth_stencil and rebased against the ES 2.0 spec
1.405 +
