• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    ARB_texture_stencil8
4
5Name Strings
6
7    GL_ARB_texture_stencil8
8
9Contact
10
11    Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com)
12
13Contributors
14
15    Piers Daniell, NVIDIA
16    Daniel Koch, NVIDIA
17    Jon Leech
18
19Notice
20
21    Copyright (c) 2013 The Khronos Group Inc. Copyright terms at
22        http://www.khronos.org/registry/speccopyright.html
23
24Specification Update Policy
25
26    Khronos-approved extension specifications are updated in response to
27    issues and bugs prioritized by the Khronos OpenGL Working Group. For
28    extensions which have been promoted to a core Specification, fixes will
29    first appear in the latest version of that core Specification, and will
30    eventually be backported to the extension document. This policy is
31    described in more detail at
32        https://www.khronos.org/registry/OpenGL/docs/update_policy.php
33
34Status
35
36    Complete. Approved by the ARB on June 3, 2013.
37    Ratified by the Khronos Board of Promoters on July 19, 2013.
38
39Version
40
41    Last Modified Date:         August 26, 2013
42    Revision:                   5
43
44Number
45
46    ARB Extension #150
47
48Dependencies
49
50    This extension is written against the OpenGL 4.3 specification
51    (Compatibility Profile).
52
53Overview
54
55    This extension accepts STENCIL_INDEX8 as a texture internal format, and
56    adds STENCIL_INDEX8 to the required internal format list. This removes the
57    need to use renderbuffers if a stencil-only format is desired.
58
59New Procedures and Functions
60
61    None.
62
63New Tokens
64
65    Accepted by the <format> parameter of TexImage3D, TexImage2D, TexImage1D,
66    TexSubImage3D, TexSubImage2D, TexSubImage1D, or GetTexImage:
67
68        STENCIL_INDEX           0x1901  /* existing enum */
69
70    Accepted by the <internalformat> parameter of TexImage3D, TexImage2D,
71    TexImage1D, CopyTexImage2D, CopyTexImage1D, TexStorage3D, TexStorage2D,
72    TexStorage1D, TexImage3DMultisample, TexImage2DMultisample,
73    TexStorage3DMultisample, TexStorage2DMultisample:
74
75        STENCIL_INDEX8          0x8D48  /* existing enum */
76
77Additions to Chapter 8 of the OpenGL 4.3 (Compatibility Profile) Specification
78(Textures and Samplers)
79
80    Modify Section 8.5 Texture Image Specification, p. 205
81
82    In the first paragraph, replace "The <format> STENCIL_INDEX is not allowed"
83    with "An INVALID_OPERATION error is generated if the <format> is
84    STENCIL_INDEX and the base internal format is not STENCIL_INDEX."
85
86
87    Modify the last paragraph of p. 207 to include STENCIL_INDEX:
88
89    "Textures with a base internal format of DEPTH_COMPONENT, DEPTH_STENCIL,
90    or STENCIL_INDEX are supported by texture image specification commands
91    only if <target> is TEXTURE_1D, TEXTURE_2D, TEXTURE_1D_ARRAY,
92    TEXTURE_2D_ARRAY, TEXTURE_RECTANGLE, TEXTURE_CUBE_MAP,
93    TEXTURE_CUBE_MAP_ARRAY, TEXTURE_2D_MULTISAMPLE,
94    TEXTURE_2D_MULTISAMPLE_ARRAY, PROXY_TEXTURE_1D, PROXY_TEXTURE_2D,
95    PROXY_TEXTURE_1D_ARRAY, PROXY_TEXTURE_2D_ARRAY, PROXY_TEXTURE_RECTANGLE,
96    PROXY_TEXTURE_CUBE_MAP, PROXY_TEXTURE_CUBE_MAP_ARRAY,
97    PROXY_TEXTURE_2D_MULTISAMPLE or PROXY_TEXTURE_2D_MULTISAMPLE_ARRAY."
98
99    Add a row to Table 8.18: Conversion from RGBA, depth, and stencil pixel
100    components to internal texture, table, or filter components
101
102        Base Internal Format    RGBA, Depth, and Stencil Values     Internal Components
103
104        STENCIL_INDEX           Stencil                             S
105
106
107    Add to the list of required texture internal formats:
108
109        - Stencil formats: STENCIL_INDEX8
110
111
112    Add rows to Table 8.21: Correspondence of sized internal depth and stencil
113    formats to base internal formats, internal data type, and desired component
114    resolutions for each sized internal format
115
116        Sized Internal Format       Base Internal Format    D bits      S bits
117
118        STENCIL_INDEX8              STENCIL_INDEX           <blank>     8
119
120    Modify Section 8.6 Alternate Texture Image Specification Commands, p. 222
121
122    ...The image is taken from the framebuffer exactly as if these arguments
123    were passed to CopyPixels (see section 18.3) with argument type set to
124    COLOR, DEPTH, DEPTH_STENCIL, or STENCIL_INDEX, depending on internalformat,
125    stopping after pixel transfer processing is complete.
126
127    Modify Section 8.11 Texture Queries, p. 246
128
129    If format is DEPTH_COMPONENT, DEPTH_STENCIL, or STENCIL_INDEX then each
130    depth component and/or stencil index is assigned with the same ordering of
131    rows and images.
132
133    Modifications to the errors section for GetTexImage, p. 247,
134
135    Delete the following error:
136
137    An INVALID_ENUM error is generated if <format> is STENCIL_INDEX.
138
139    Add a bullet to the list of reasons for INVALID_OPERATION error:
140
141    - <format> is STENCIL_INDEX and the base internal format is not
142      STENCIL_INDEX or DEPTH_STENCIL.
143
144    Modify 8.17 Texture Completeness, p. 263
145
146    Modify the bullet point on p. 263 describing required texture filter
147    modes for an integer texture in order to determine texture completeness,
148    to add STENCIL_INDEX textures explicitly:
149
150    - The internal format of the texture is integer (see tables 8.19-8.20)
151      or STENCIL_INDEX, and either the magnification filter is not NEAREST,
152      or the minification filter is neither NEAREST nor
153      NEAREST_MIPMAP_NEAREST.
154
155    Modify 8.22.1 Depth Texture Comparison Mode, p. 278
156
157    - If the base internal format is STENCIL_INDEX, then r = St
158
159Additions to Chapter 11 of the OpenGL 4.3 (Compatibility Profile) Specification
160(Programmable Vertex Processing)
161
162    Modify 11.1.3.5 Texture Access p. 390
163
164    Texture lookups involving texture objects with an internal format of DEPTH_-
165    STENCIL can read the stencil value as described in section 8.22 by setting
166    the DEPTH_STENCIL_TEXTURE_MODE to STENCIL_COMPONENT. Textures with a
167    STENCIL_INDEX base internal format may also be used to read stencil data.
168    The stencil value is read as an integer and assigned to Rt. An unsigned
169    integer sampler must be used to lookup the stencil component, otherwise
170    the results are undefined.
171
172
173Additions to Chapter 15 of the OpenGL 4.3 (Compatibility Profile) Specification
174(Programmable Fragment Processing)
175
176    Modify 15.2.1 Texture Access, p.510
177
178    Repace the paragraph "The stencil index texture internal component is
179    ignored if the base internal format is DEPTH_STENCIL" with:
180
181    Texture lookups involving textures with stencil index data generate a
182    texture base color Cb by using stencil values St directly, if either the
183    texture has a base internal format of STENCIL_INDEX or the texture has a
184    base internal format of DEPTH_STENCIL and a DEPTH_STENCIL_TEXTURE_MODE
185    of STENCIL_COMPONENT.
186
187
188New Implementation Dependent State
189
190    None.
191
192New State
193
194    None.
195
196Additions to the AGL/GLX/WGL Specifications
197
198    None.
199
200GLX Protocol
201
202    None.
203
204Modifications to the OpenGL Shading Language Specification, Version 4.30
205
206    None.
207
208Errors
209
210    An INVALID_OPERATION error is generated by GetTexImage if <format>
211    is STENCIL_INDEX and the base internal format is not STENCIL_INDEX or
212    DEPTH_STENCIL.
213
214    An INVALID_OPERATION error is generated by TexImage3D, TexImage2D,
215    TexImage1D, TexSubImage3D, TexSubImage2D, or TexSubImage1D
216    if <format> is STENCIL_INDEX and the base internal format is not
217    <STENCIL_INDEX>.
218
219    An INVALID_OPERATION error is generated by TexImage3D, TexImage2D,
220    TexImage1D, TexSubImage3D, TexSubImage2D, or TexSubImage1D if
221    <format> is STENCIL_INDEX and <target> is not one of TEXTURE_1D,
222    TEXTURE_2D, TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_RECTANGLE,
223    TEXTURE_CUBE_MAP, TEXTURE_CUBE_MAP_ARRAY, PROXY_TEXTURE_1D,
224    PROXY_TEXTURE_2D, PROXY_TEXTURE_1D_ARRAY, PROXY_TEXTURE_2D_ARRAY,
225    PROXY_TEXTURE_RECTANGLE, PROXY_TEXTURE_CUBE_MAP, or
226    PROXY_TEXTURE_CUBE_MAP_ARRAY.
227
228Issues
229
230
231    (1) What is the interaction with ARB_stencil_texturing's
232        DEPTH_STENCIL_TEXTURE_MODE?
233
234    RESOLVED: That piece of state is ignored because the base internal format
235    of a STENCIL_INDEX texture is not DEPTH_STENCIL.
236
237    (2) Does the presence of this extension imply that the implementation
238    supports a true 8-bit stencil buffer?
239
240    RESOLVED: No, some OpenGL implementations may internally expand a
241    format like STENCIL_INDEX8 to DEPTH24_STENCIL8, but will make such a format
242    behave as if there were no depth bits.  Additionally, implementations may
243    not support independent depth and stencil attachments; a framebuffer with a
244    STENCIL_INDEX8 stencil attachment and a DEPTH_COMPONENT24 depth attachment
245    may be treated as unsupported (FRAMEBUFFER_UNSUPPORTED).
246
247    (3) Should we support stencil formats that have a number of bits that is
248    not exactly supported in the implementation? 8-bits is universally
249    supported, but 1/4/16-bits are not.
250
251    RESOLVED: Only accept STENCIL_INDEX8, which is universally supported.
252
253Revision History
254
255    Rev.    Date    Author    Changes
256    ----  --------  --------  -----------------------------------------------
257     1    03/20/13  jbolz     Internal revisions.
258     2    05/30/13  dgkoch    Add tokens and errors section.
259                              Update errors for GetTexImage.
260     3    06/28/13  Jon Leech Fix dates in revision history. Change filter
261                              modes for texture completeness (Bug 10372).
262     4    08/08/13  pdaniell  Fix the functions that accept STENCIL_INDEX8 as
263                              an <internalformat> parameter (Bug 10558).
264     5    08/26/13  pdaniell  Fix the list of texture targets that support
265                              stencil (and depth and depth/stencil) textures
266                              to include the multisample targets (Bug 10558).
267