1Name
2
3    ARB_stencil_texturing
4
5Name Strings
6
7    GL_ARB_stencil_texturing
8
9Contact
10
11    Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com)
12
13Contributors
14
15    Bruce Merry
16    Jeff Bolz, NVIDIA
17    Pat Brown, NVIDIA
18
19Notice
20
21    Copyright (c) 2012-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.
37    Approved by the ARB on 2012/06/12.
38
39Version
40
41    Last Modified Date:         March 19, 2013
42    Revision:                   5
43
44Number
45
46    ARB Extension #138
47
48Dependencies
49
50    OpenGL 1.1, ARB_depth_texture and EXT_packed_depth_stencil are required.
51
52    This extension is written against The OpenGL 4.2 (Compatibility Profile)
53    specification.
54
55Overview
56
57    This extension allows texturing of the stencil component of a packed depth
58    stencil texture. Stencil values are returned as unsigned integers. It is
59    not possible to sample both depth and stencil values from the same
60    texture, and this extension allows the app to select which is sampled for
61    the bound texture.
62
63New Procedures and Functions
64
65    None
66
67New Tokens
68
69    Accepted by the <pname> parameter of TexParameter* and GetTexParameter*:
70
71        DEPTH_STENCIL_TEXTURE_MODE                       0x90EA
72
73Additions to the OpenGL 4.2 (Compatibility Profile) Specification
74
75Changes to Section 2.14.12 (Shader Execution), page 144
76
77Add a new new bullet point on page 149:
78
79    "* The sampler used in a texture lookup function is one of the shadow
80    sampler types, the texture object's internal format is DEPTH_STENCIL,
81    and the DEPTH_STENCIL_TEXTURE_MODE is not DEPTH_COMPONENT."
82
83Then change the following paragraph that reads:
84
85    "The stencil index texture internal component is ignored if the base
86    internal format is DEPTH_STENCIL."
87
88To the following:
89
90    "The stencil index texture internal component is ignored if the base
91    internal format is DEPTH_STENCIL and the DEPTH_STENCIL_TEXTURE_MODE
92    is not STENCIL_INDEX.
93
94    Texture lookups involving texture objects with an internal format of
95    DEPTH_STENCIL can read the stencil value as described in section
96    3.10.18 by setting the DEPTH_STENCIL_TEXTURE_MODE to STENCIL_INDEX.
97    The stencil value is read as an integer and assigned to R_t. An unsigned
98    integer sampler should be used to lookup the stencil component, otherwise
99    the results are undefined."
100
101Changes to Section 3.10.8 (Texture Parameters), page 322
102
103In Table 3.22 (Texture parameters and their values) add the following
104entry:
105
106    "
107    Name                        Type  Legal Values
108    -------------               ----  ------------------------------
109    DEPTH_STENCIL_TEXTURE_MODE  enum  DEPTH_COMPONENT, STENCIL_INDEX
110    "
111
112Changes to Section 3.10.13 (Combined Depth/Stencil Textures), page 342
113
114Modify the paragraph to read:
115
116    "If the texture image has a base internal format of DEPTH_STENCIL, then
117    the stencil index texture component is ignored by default. The texture
118    value <T> does not include a stencil index component, but includes
119    only the depth component. In order to access the stencil index texture
120    component the DEPTH_STENCIL_TEXTURE_MODE texture parameter should be
121    set to STENCIL_INDEX. When this mode is set the depth component is ignored
122    and the texture value includes only the stencil index component. The
123    stencil index value is treated as an unsigned integer texture and
124    returns an unsigned integer value when sampled. When sampling the stencil
125    index only NEAREST filtering is supported. The DEPTH_STENCIL_TEXTURE_MODE
126    is ignored for non depth/stencil textures."
127
128Changes to Section 3.10.14 (Texture Completeness), page 343
129
130Add a new bullet point for the conditions that cause the texture
131to not be complete:
132
133    "* The internal format of the texture is DEPTH_STENCIL, the
134    DEPTH_STENCIL_TEXTURE_MODE for the texture is STENCIL_INDEX and either the
135    magnification filter or the minification filter is not NEAREST."
136
137Changes to Section 3.10.18 (Texture Comparison Modes), page 356
138
139Modify the following paragraph:
140
141    "Let Dt be the depth texture value and St be the stencil index component
142    of a depth/stencil texture. If there is no stencil component the value of
143    St is undefined. Let Dref be the reference value..."
144
145Insert a new paragraph after the paragraphs that ends:
146
147    "Then the effective texture value is computed as follows:
148        If the base internal format is DEPTH_STENCIL and the value of
149    DEPTH_STENCIL_TEXTURE_MODE is STENCIL_INDEX, then
150            r = St
151        Otherwise if the value of TEXTURE_COMPARE_MODE is NONE, then
152            r = Dt
153        Otherwise if the value of TEXTURE_COMPARE_MODE is
154    COMPARE_REF_TO_TEXTURE, then r depends on the texture comparison
155    function as shown in table 3.31.
156        The resulting r is assigned ..."
157
158Additions to Chapter 8 of the OpenGL Shading Language 4.20.6 Specification
159
160Insert a new paragraph at the end of Section 8.9:
161
162    "For depth/stencil textures, the sampler type should match the component
163    being accessed as set through the OpenGL API. When the depth/stencil texture
164    mode is set to DEPTH_COMPONENT, a floating-point sampler type should be used.
165    When the depth/stencil texture mode is set to STENCIL_INDEX, an unsigned integer
166    sampler type should be used. Doing a texture lookup with an unsupported
167    combination will return undefined values."
168
169Additions to the AGL/GLX/WGL Specifications
170
171    None
172
173Errors
174
175    None
176
177New State
178
179    (Table 6.24, Textures) add the following entry:
180
181    Get Value                       Type  Get Command        Initial Value   Description                             Section
182    -------------                   ----  -----------        -------------   -----------                             -------
183    DEPTH_STENCIL_TEXTURE_MODE      n*Z2  GetTexParameteriv  DEPTH_COMPONENT Depth stencil texture mode              3.10.8
184
185New Implementation Dependent State
186
187    None
188
189Issues
190
191    1) Should we support combined depth/stencil in one lookup?
192
193       RESOLVED: No because depth is float and stencil is integer and we
194       have no way to return both with the existing samplers. Also some
195       implementations may not have an easy way to retrive both depth and
196       stencil in one lookup.
197
198    2) How does this interact with texture filters (e.g., LINEAR)?
199
200       RESOLVED: Sampling the stencil values will behave like integer textures.
201       There is no filtering.
202
203    3) I assume DEPTH_STENCIL_TEXTURE_MODE is ignored unless the texture
204       itself has a DEPTH_STENCIL internal format?
205
206       RESOLVED: Correct.
207
208Revision History
209
210    Rev.    Date    Author    Changes
211    ----  --------  --------  -----------------------------------------------
212    5     03/19/13  Jon Leech Fix STENCIL_COMPONENT -> STENCIL_INDEX typo
213                              (Bug 10077).
214
215    4     05/04/12  pdaniell  Add missing spec stating how the stencil value
216                              is assigned to the color vector result of the
217                              texture lookup function. Clarified the filtering
218                              used for stencil index sampling.
219
220    3     05/03/12  pdaniell  Add enum value. Use DEPTH_COMPONENT and
221                              STENCIL_INDEX instead of DEPTH and STENCIL for
222                              the valid DEPTH_STENCIL_TEXTURE_MODEs. These
223                              better represent "Pixel Formats".
224
225    2     03/15/12  pdaniell  Fixes based on feedback from Bruce Merry.
226
227    1     10/25/11  pdaniell  Initial version.
228