1Name
2
3    ANGLE_depth_texture
4
5Name Strings
6
7    GL_ANGLE_depth_texture
8
9Contributors
10
11    Nicolas Capens, TransGaming
12    Daniel Koch, TransGaming
13    Shannon Woods, TransGaming
14    Kenneth Russell, Google
15    Vangelis Kokkevis, Google
16    Gregg Tavares, Google
17    Contributors to OES_depth_texture
18    Contributors to OES_packed_depth_stencil
19
20Contact
21
22    Shannon Woods, TransGaming (shannon 'dot' woods 'at' transgaming.com)
23
24Status
25
26    Implemented in ANGLE.
27
28Version
29
30    Last Modified Date: February 25, 2013
31    Revision: #4
32
33Number
34
35    TBD
36
37Dependencies
38
39    OpenGL ES 2.0 is required.
40    This extension is written against the OpenGL ES 2.0.25 specification
41
42    OES_packed_depth_stencil affects the definition of this extension.
43
44    EXT_texture_storage affects the definition of this extension.
45
46Overview
47
48    This extension defines support for 2D depth and depth-stencil
49    textures in an OpenGL ES implementation.
50
51    This extension incorporates the depth texturing functionality of 
52    OES_depth_texture and OES_packed_depth_stencil, but does not 
53    provide the ability to load existing data via TexImage2D or
54    TexSubImage2D. This extension also allows implementation 
55    variability in which components from a sampled depth texture
56    contain the depth data. Depth textures created with this
57    extension only support 1 level.
58
59New Procedures and Functions
60
61    None
62
63New Tokens
64
65    Accepted by the <format> parameter of TexImage2D and TexSubImage2D and
66    <internalformat> parameter of TexImage2D:
67    
68        DEPTH_COMPONENT             0x1902
69        DEPTH_STENCIL_OES           0x84F9
70        
71    Accepted by the <type> parameter of TexImage2D, TexSubImage2D: 
72
73        UNSIGNED_SHORT              0x1403
74        UNSIGNED_INT                0x1405
75        UNSIGNED_INT_24_8_OES       0x84FA
76
77    Accepted by the <internalformat> parameter of TexStorage2DEXT:
78
79        DEPTH_COMPONENT16           0x81A5
80        DEPTH_COMPONENT32_OES       0x81A7
81        DEPTH24_STENCIL8_OES        0x88F0
82
83Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation)
84
85    Update Section 2.10.5 "Shader Execution" in the subsection titled 
86    "Texture Access" add a new paragraph before the last paragraph add
87    this line:
88
89    "The stencil index texture internal component is ignored if the base
90    internal format is DEPTH_STENCIL_OES.
91
92    If a vertex shader uses..."
93
94Additions to Chapter 3 of the OpenGL ES 2.0 specification (Rasterization)
95
96    Add the following rows to Table 3.2 (page 62):
97
98      type Parameter           GL Data Type    Special
99      ------------------------------------------------
100      ...                      ...              ...
101      UNSIGNED_SHORT           ushort           No
102      UNSIGNED_INT             uint             No
103      UNSIGNED_INT_24_8_OES    uint             Yes
104
105    Add the following rows to Table 3.3 (page 62):
106
107      Format Name       Element Meaning and Order      Target Buffer
108      ------------------------------------------------------------------
109      ...               ...                            ...
110      DEPTH_COMPONENT   Depth                          Depth
111      DEPTH_STENCIL_OES Depth and Stencil Index        Depth and Stencil
112      ...               ...                            ...
113
114    Add a row to Table 3.5 "Packed pixel formats" (page 64):
115
116      type Parameter               GL Type  Components  Pixel Formats
117      ------------------------------------------------------------------
118      ...                          ...      ...         ...
119      UNSIGNED_INT_24_8_OES        uint     2           DEPTH_STENCIL_OES
120
121    Add a new table after Table 3.6 (page 64):
122
123    UNSIGNED_INT_24_8_OES
124
125       31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0
126      +----------------------------------+---------------+
127      |           1st Component          | 2nd Component |
128      +----------------------------------+---------------+
129
130      Table 3.6.B: UNSIGNED_INT formats
131
132    Add a row to Table 3.7 "Packed pixel field assignments" (page 65):
133
134      Format            |  1st     2nd     3rd     4th
135      ------------------+-------------------------------
136      ...               |  ...     ...     ...     ...
137      DEPTH_STENCIL_OES |  depth   stencil N/A     N/A
138
139    Add the following paragraph to the end of the section "Conversion to
140    floating-point" (page 65):
141
142    "For groups of components that contain both standard components and index
143    elements, such as DEPTH_STENCIL_OES, the index elements are not converted."
144
145    In section 3.7.1 "Texture Image Specification", update page 67 to
146    say:
147
148    "The selected groups are processed as described in section 3.6.2, stopping
149    just before final conversion.  Each R, G, B, A, or depth value so generated
150    is clamped to [0, 1], while the stencil index values are masked by 2^n-1,
151    where n is the number of stencil bits in the internal format resolution
152    (see below).
153
154    Components are then selected from the resulting R, G, B, A, depth, or
155    stencil index values to obtain a texture with the base internal format
156    specified by <internalformat>.  Table 3.8 summarizes the mapping of R, G,
157    B, A, depth, or stencil values to texture components, as a function of the
158    base internal format of the texture image.  <internalformat> may be
159    specified as one of the internal format symbolic constants listed in
160    table 3.8. Specifying a value for <internalformat> that is not one of the
161    above values generates the error INVALID_VALUE. If <internalformat> does
162    not match <format>, the error INVALID_OPERATION is generated.
163
164    Textures with a base internal format of DEPTH_COMPONENT or 
165    DEPTH_STENCIL_OES are supported by texture image specification commands
166    only if <target> is TEXTURE_2D.  Using these formats in conjunction with
167    any other <target> will result in an INVALID_OPERATION error.
168
169    Textures with a base internal format of DEPTH_COMPONENT or
170    DEPTH_STENCIL_OES only support one level of image data.  Specifying a
171    non-zero value for <level> will result in an INVALID_OPERATION error.
172
173    Textures with a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES
174    require either depth component data or depth/stencil component data.
175    Textures with other base internal formats require RGBA component data.  The
176    error INVALID_OPERATION is generated if the base internal format is
177    DEPTH_COMPONENT or DEPTH_STENCIL_OES and <format> is not DEPTH_COMPONENT or
178    DEPTH_STENCIL_OES, or if the base internal format is not DEPTH_COMPONENT or
179    DEPTH_STENCIL_OES and <format> is DEPTH_COMPONENT or DEPTH_STENCIL_OES.
180
181    Textures with a base internal format of DEPTH_COMPONENT or
182    DEPTH_STENCIL_OES do not support loading image data via the TexImage
183    commands. They can only have their contents specified by rendering
184    to them. The INVALID_OPERATION error is generated by the TexImage2D
185    command if <data> is not NULL for such textures."
186
187    Add a row to table 3.8 (page 68), and update the title of the
188    second column:
189
190      Base Internal Format  RGBA, Depth and Stencil Values  Internal Components
191      -------------------------------------------------------------------------
192      ...                   ...                             ...
193      DEPTH_COMPONENT       Depth                           D
194      DEPTH_STENCIL_OES     Depth,Stencil                   D,S
195      ...                   ...                             ...
196
197    Update the caption for table 3.8 (page 68)
198
199    "Table 3.8: Conversion from RGBA, depth, and stencil pixel components to
200    internal texture components.  Texture components R, G, B, A, and L are 
201    converted back to RGBA colors during filtering as shown in table 3.12.
202    Texture components D are converted to RGBA colors as described in 
203    section 3.7.8-1/2."
204
205    Add the following to section 3.7.2 "Alternate Texture Image Specification
206    Commands":
207
208    "CopyTexImage2D and CopyTexSubImage2D generate the INVALID_OPERATION 
209    error if the base internal format of the destination texture is 
210    DEPTH_COMPONENT or DEPTH_STENCIL_OES.
211
212    TexSubImage2D generates the INVALID_OPERATION error if the base internal
213    format of the texture is DEPTH_COMPONENT or DEPTH_STENCIL_OES."
214
215    Add a new section between sections 3.7.8 and 3.7.9:
216
217    "3.7.8-1/2 Depth/Stencil Textures
218
219    If the currently bound texture's base internal format is DEPTH_COMPONENT or
220    DEPTH_STENCIL_OES, then the output of the texture unit is as described
221    below. Otherwise, the texture unit operates in the normal manner.
222
223    Let <D_t> be the depth texture value, provided by the shader's texture lookup
224    function. Then the effective texture value is computed as follows:
225            <Tau> = <D_t>
226
227    If the texture image has a base internal format of DEPTH_STENCIL_OES, then
228    the stencil index texture component is ignored.  The texture value <Tau> does
229    not include a stencil index component, but includes only the depth
230    component.
231
232    The resulting <Tau> is assigned to <R_t>. In some implementations, <Tau> is
233    also assigned to <G_t>, <B_t>, or <A_t>. Thus in table 3.12, textures with
234    depth component data behave as if their base internal format is RGBA, with
235    values in <G_t>, <B_t>, and <A_t> being implementation dependent."
236
237    Add the following to section 3.7.11 "Mipmap Generation":
238
239    "If the level zero array contains depth or depth-stencil data, the
240     error INVALID_OPERATION is generated."
241
242    Insert a new paragraph after the first paragraph of the "Texture Access"
243    subsection of section 3.8.2 on page 87, which says:
244
245    "Texture lookups involving textures with depth component data generate
246    a texture source color by using depth data directly, as described in
247    section 3.7.8-1/2.  The stencil texture internal component is ignored
248    if the base internal format is DEPTH_STENCIL_OES."
249
250Additions to Chapter 4 of the OpenGL ES 2.0 specification (Per-Fragment
251Operations and the Framebuffer)
252
253    In section 4.4.5 "Framebuffer Completeness", replace the the 3rd
254    paragraph with the following text:
255
256     "* An internal format is color-renderable if it is one of the formats
257        from table 4.5 noted as color-renderable or if it is unsized format
258        RGBA or RGB. No other formats, including compressed internal formats,
259        are color-renderable.
260
261      * An internal format is depth-renderable if it is one of the sized
262        internal formats from table 4.5 noted as depth-renderable, if it
263        is the unsized format DEPTH_COMPONENT or if it is the internal 
264        format value of DEPTH24_STENCIL8_OES. No other formats are 
265        depth-renderable.
266
267      * An internal format is stencil-renderable if it is one of the sized 
268        internal formats from table 4.5 noted as stencil-renderable or if it
269        is DEPTH24_STENCIL8_OES. No other formats are stencil-renderable."
270
271Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special
272Functions)
273
274    None.
275
276Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State
277Requests)
278
279    None.
280
281Interactions with OES_packed_depth_stencil
282
283    If OES_packed_depth_stencil is not supported, mentions of
284    DEPTH_STENCIL_OES and UNSIGNED_INT_24_8_OES as a format/type combinations
285    for TexImage2D and TexSubImage2D are omitted. Mentions of
286    the internal format DEPTH24_STENCIL8_OES are also omitted.
287
288Interactions with EXT_texture_storage
289
290    If EXT_texture_storage is supported the following internalformat
291    to format/type mappings are used:
292
293        <internalformat>       <format>           <type>
294        ----------------       --------           ------
295        DEPTH_COMPONENT16      DEPTH_COMPONENT    UNSIGNED_SHORT
296        DEPTH_COMPONENT32_OES  DEPTH_COMPONENT    UNSIGNED_INT
297        DEPTH24_STENCIL8_OES   DEPTH_STENCIL_OES  UNSIGNED_INT
298
299    Textures with the above <internalformats> only support one level of
300    image data. Specifying a value other than one for the <levels> parameter
301    to TexStorage2DEXT will result in an INVALID_OPERATION error.
302
303    If EXT_texture_storage is not supported, ignore any references
304    to TexStorage2DEXT. 
305
306Errors
307
308    The error INVALID_OPERATION is generated by TexImage2D if <format> and 
309    <internalformat> are DEPTH_COMPONENT and <type> is not UNSIGNED_SHORT,
310    or UNSIGNED_INT.
311
312    The error INVALID_OPERATION is generated by TexSubImage2D if <format> is 
313    DEPTH_COMPONENT and <type> is not UNSIGNED_SHORT, or UNSIGNED_INT.
314
315    The error INVALID_OPERATION is generated by TexImage2D if <format> and
316    <internalformat> are not DEPTH_COMPONENT and <type> is UNSIGNED_SHORT,
317    or UNSIGNED_INT.
318
319    The error INVALID_OPERATION is generated by TexSubImage2D if <format> is
320    not DEPTH_COMPONENT and <type> is UNSIGNED_SHORT, or UNSIGNED_INT.
321
322    The error INVALID_OPERATION is generated by TexImage2D if <format> and
323    <internalformat> are DEPTH_STENCIL_OES and <type> is not
324    UNSIGNED_INT_24_8_OES. 
325
326    The error INVALID_OPERATION is generated by TexSubImage2D if <format>
327    is DEPTH_STENCIL_OES and <type> is not UNSIGNED_INT_24_8_OES. 
328
329    The error INVALID_OPERATION is generated by TexImage2D if <format> and
330    <internalformat> is not DEPTH_STENCIL_OES and <type> is 
331    UNSIGNED_INT_24_8_OES.
332
333    The error INVALID_OPERATION is generated by TexSubImage2D if <format>
334    is not DEPTH_STENCIL_OES and <type> is UNSIGNED_INT_24_8_OES.
335
336    The error INVALID_OPERATION is generated in the following situations:
337    - TexImage2D is called with <format> and <internalformat> of
338      DEPTH_COMPONENT or DEPTH_STENCIL_OES and
339       - <target> is not TEXTURE_2D,
340       - <data> is not NULL, or
341       - <level> is not zero.
342    - TexSubImage2D is called with <format> of DEPTH_COMPONENT or 
343      DEPTH_STENCIL_OES.
344    - TexStorage2DEXT is called with <internalformat> of DEPTH_COMPONENT16,
345      DEPTH_COMPONENT32_OES, or DEPTH24_STENCIL8_OES, and 
346       - <target> is not TEXTURE_2D, or
347       - <levels> is not one.
348    - CopyTexImage2D is called with an <internalformat> that has a base
349      internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES.
350    - CopyTexSubImage2D is called with a target texture that has a base
351      internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES.
352    - GenerateMipmap is called on a texture that has a base internal format
353      of DEPTH_COMPONENT or DEPTH_STENCIL_OES.
354    
355New State
356
357    None.
358
359Issues
360
361    1) What are the differences between this extension and OES_depth_texture
362       and OES_packed_depth_stencil?
363    
364       RESOLVED: This extension:
365         - does not support loading pre-baked depth stencil data via 
366           TexImage2D or TexSubImage2D.
367         - allows variability in the y-, z-, and w-components of the sample
368           results from depth textures.
369         - only supports one level textures.
370         - explicitly lists the errors for unsupported functionality.
371           Since these were not clearly specified in the OES_depth_texture
372           extension there may be differences in error values between 
373           implementations of OES_depth_texture and ANGLE_depth_texture.
374       This specification was also rebased to apply against the OpenGL ES 2.0
375       specification instead of the OpenGL specification, making it more 
376       obvious what all the functionality changes are.
377
378    2) Why does TexSubImage2D accept the new format/type combinations even
379       though it does not actually support loading data?
380
381       RESOLVED: This was done to be more consistent with the OES_depth_texture
382       extension and to make it easier to add support for loading texture
383       data if it is possible to support in the future.
384
385    3) Why are only 1-level depth textures supported? 
386
387       RESOLVED: The only use for multiple levels of depth textures would
388       be for fitlered texturing. However since it is not possible to
389       render to non-zero-level texture levels in OpenGL ES 2.0, and since
390       this extension forbids loading existing data and GenerateMipmap on 
391       depth textures, it is impossible to initialize or specify contents
392       for non-zero levels of depth textures.
393
394Revision History
395 
396    02/25/2013  swoods  revise to allow texture lookup to guarantee depth values
397                        only in red channel of sample result.
398    06/04/2012  dgkoch  fix errors, disallow multi-level depth textures.
399    05/30/2012  dgkoch  minor updates and add issues.
400    05/23/2012  dgkoch  intial revision based on OES_depth_texture and 
401                        OES_packed_depth_stencil and rebased against the ES 2.0 spec
402
403