1Name
2
3    OES_texture_stencil8
4
5Name Strings
6
7    GL_OES_texture_stencil8
8
9Contact
10
11    Mathias Heyer, NVIDIA Corporation (mheyer 'at' nvidia.com)
12
13Contributors
14
15    Jeff Bolz, NVIDIA
16    Piers Daniell, NVIDIA
17    Daniel Koch, NVIDIA
18    Mathias Heyer, NVIDIA
19    Jon Leech
20
21Notice
22
23    Copyright (c) 2012-2015 The Khronos Group Inc. Copyright terms at
24        http://www.khronos.org/registry/speccopyright.html
25
26Specification Update Policy
27
28    Khronos-approved extension specifications are updated in response to
29    issues and bugs prioritized by the Khronos OpenGL ES Working Group. For
30    extensions which have been promoted to a core Specification, fixes will
31    first appear in the latest version of that core Specification, and will
32    eventually be backported to the extension document. This policy is
33    described in more detail at
34        https://www.khronos.org/registry/OpenGL/docs/update_policy.php
35
36Status
37
38    Complete.
39    Ratified by the Khronos Board of Promoters on 2014/03/14.
40
41Version
42
43    Last Modified Date:         May 13, 2015
44    Revision:                   10
45
46Number
47
48    OpenGL ES Extension #173
49
50Dependencies
51
52    OpenGL ES 3.1 is required.
53
54    This extension is written against the OpenGL ES 3.1 (April 29, 2015)
55    Specification.
56
57Overview
58
59    This extension accepts STENCIL_INDEX8 as a texture internal format, and
60    adds STENCIL_INDEX8 to the required internal format list. This removes the
61    need to use renderbuffers if a stencil-only format is desired.
62
63New Procedures and Functions
64
65    None.
66
67New Tokens
68
69    Accepted by the <format> parameter of TexImage3D, TexImage2D
70    TexSubImage3D and TexSubImage2D:
71
72        STENCIL_INDEX           0x1901  /* existing enum */
73
74    Accepted by the <internalformat> parameter of TexImage3D, TexImage2D,
75    TexStorage3D, TexStorage2D, TexStorage3DMultisample
76    and TexStorage2DMultisample:
77
78        STENCIL_INDEX8          0x8D48  /* existing enum */
79
80Additions to Section 8.4.2 of the OpenGL ES 3.1 Specification
81(Transfer of Pixel Rectangles)
82
83    Add to table 8.2 "Valid combinations of <format>, <type> and sized
84    <internalformat>":
85
86        Format          Type            External Bytes  Internal Format
87                                        per Pixel
88        --------------- --------------- --------------- ---------------
89        STENCIL_INDEX   UNSIGNED_BYTE   1               STENCIL_INDEX8
90
91    Add to table 8.5 "Pixel data formats":
92
93        Format Name   |  Element Meaning and Order | Target buffer
94        ----------------------------------------------------------
95        STENCIL_INDEX | Stencil Index              | Stencil
96
97Additions to Section 8.5 of the OpenGL ES 3.1 Specification
98(Texture Image Specification)
99
100    Modify the third paragraph from the bottom of p. 150 to include
101    STENCIL_INDEX:
102
103    "Textures with a base internal format of DEPTH_COMPONENT, DEPTH_STENCIL,
104    or STENCIL_INDEX are supported by texture image specification commands
105    only if <target> is..."
106
107Additions to Section 8.6 of the OpenGL ES 3.1 Specification
108(Alternate Texture Image Specification Commands)
109
110    In table 8.16 "Valid CopyTexImage source framebuffer/destination texture
111    base internal format combinations)", add row 'S' and column 'S' and
112    leave all the format combinations involving 'S' marked unsupported.
113
114Additions to Section 8.16 of the OpenGL ES 3.1 Specification
115(Texture Completeness)
116
117    Add a bullet to the list of reasons a texture would be incomplete, on p,
118    189:
119
120      - The internal format of the texture is STENCIL_INDEX and either the
121        magnification filter is not NEAREST, or the minification filter is
122        neither NEAREST nor NEAREST_MIPMAP_NEAREST.
123
124Additions to Section 8.19.1 of the OpenGL ES 3.1 Specification
125(Depth Texture Comparison Mode)
126
127    Modify the description of computing R_t on p. 195:
128
129   "Then the effective texture value is computed as follows:
130
131      - If the base internal format is STENCIL_INDEX, then r = St
132      - If the base internal format is DEPTH_STENCIL and ..."
133
134Changes to Section 11.1.3.5 of the OpenGL ES 3.1 Specification
135(Texture Access)
136
137    Change the next-to-last paragraph of the section (at the bottom of p.
138    272) to:
139
140   "Texture lookups involving texture objects with an internal format of
141    DEPTH_STENCIL can read the stencil value as described in section 8.19 by
142    setting the value of DEPTH_STENCIL_TEXTURE_MODE to STENCIL_INDEX.
143    Textures with a STENCIL_INDEX base internal format may also be used to
144    read stencil data. The stencil value is read as an integer and assigned
145    to R_t. An unsigned integer sampler should be used to lookup the stencil
146    component, otherwise the results are undefined.
147
148    If a sampler is used in a shader..."
149
150Additions to Section 16.1.2 of the OpenGL ES 3.1 Specification
151(ReadPixels):
152
153    Add STENCIL_INDEX to the third paragraph following the prototype
154    for ReadPixels on p. 338:
155
156   "The second is an implementation-chosen format from among those defined
157    in table 8.2, excluding formats DEPTH_COMPONENT, DEPTH_STENCIL and
158    STENCIL_INDEX. The values of <format> ..."
159
160New Implementation Dependent State
161
162    None.
163
164New State
165
166    None.
167
168Modifications to the OpenGL ES Shading Language Specification, Version 3.10
169
170    None.
171
172Errors
173
174    An INVALID_OPERATION error is generated by TexImage3D, TexImage2D,
175    TexSubImage3D, TexSubImage2D if <format> is STENCIL_INDEX and the
176    base internal format is not <STENCIL_INDEX>.
177
178    An INVALID_OPERATION error is generated by TexImage3D, TexImage2D,
179    TexSubImage3D or TexSubImage2D, if <format> is STENCIL_INDEX and
180    <target> is not one of TEXTURE_2D, TEXTURE_2D_ARRAY and TEXTURE_CUBE_MAP_*.
181
182    An INVALID_OPERATION error is generated by TexImage3D, TexImage2D,
183    TexSubImage3D or TexSubImage2D, if <format> is STENCIL_INDEX and
184    <type> is not <UNSIGNED_BYTE>
185
186    An INVALID_OPERATION error is generated by TexImage3D and TexImage2D,
187    if <format> is <STENCIL_INDEX> and internal format is not <STENCIL_INDEX8>
188
189Issues
190
191    (1) What is the interaction with OpenGL ES 3.1's
192        DEPTH_STENCIL_TEXTURE_MODE?
193
194    RESOLVED: That piece of state is ignored because the base internal format
195    of a STENCIL_INDEX texture is not DEPTH_STENCIL.
196
197    (2) Does the presence of this extension imply that the implementation
198    supports a true 8-bit stencil buffer?
199
200    RESOLVED: No, some OpenGL implementations may internally expand a
201    format like STENCIL_INDEX8 to DEPTH24_STENCIL8, but will make such a format
202    behave as if there were no depth bits.  Additionally, implementations may
203    not support independent depth and stencil attachments; a framebuffer with a
204    STENCIL_INDEX8 stencil attachment and a DEPTH_COMPONENT24 depth attachment
205    may be treated as unsupported (FRAMEBUFFER_UNSUPPORTED).
206
207    (3) Should we support stencil formats that have a number of bits that is
208    not exactly supported in the implementation? 8-bits is universally
209    supported, but 1/4/16-bits are not.
210
211    RESOLVED: Only accept STENCIL_INDEX8, which is universally supported.
212
213Revision History
214
215    Rev.    Date    Author    Changes
216    ----  --------  --------  -----------------------------------------------
217     1    03/20/12  jbolz     Internal revisions.
218     2    05/30/12  dgkoch    Add tokens and errors section.
219                              Update errors for GetTexImage.
220     3    07/23/13  mheyer    Take ARB_texture_stencil8 and reword it for
221                              ES 3.0
222     4    08/06/13  mheyer    Allow NEAREST_MIPMAP_NEAREST as filter.
223     5    08/30/13  mheyer    Add interactions with multisample textures.
224     6    09/03/13  mheyer    CopyTexImage2D does not support stencil textures
225     7    10/16/13  mheyer    Add entry to Table 3.5, added modification to
226                              section 2.11.9 and extended Errors section.
227     8    01/20/14  dkoch     Fix name of interacting extension.
228                              Remove trailing whitespace.
229     9    01/30/14  dkoch     Rename to OES.
230     10   05/13/15  Jon Leech Rebase on OpenGL ES 3.1, which is required
231                              in any case.
232