xref: /aosp_15_r20/external/angle/extensions/ANGLE_stencil_texturing.txt (revision 8975f5c5ed3d1c378011245431ada316dfb6f244) 
1Name
2
3    ANGLE_stencil_texturing
4
5Name Strings
6
7    GL_ANGLE_stencil_texturing
8
9Contributors
10
11    Contributors to ARB_stencil_texturing
12    Members of the WebGL working group
13
14Status
15
16    Draft
17
18Version
19
20    Last Modified Date: March 1, 2023
21    Revision: 1
22
23Number
24
25    OpenGL ES Extension XX
26
27Dependencies
28
29    This extension is written against the OpenGL ES 3.0 Specification.
30
31    OpenGL ES 3.0 and OpenGL ES Shading Language 3.00 are required.
32
33Overview
34
35    This extension allows texturing of the stencil component of a packed depth
36    stencil texture. Stencil values are returned as unsigned integers. It is
37    not possible to sample both depth and stencil values from the same
38    texture, and this extension allows the app to select which is sampled for
39    the bound texture.
40
41    This extension provides similar functionality to that of OpenGL ES 3.1.
42
43New Procedures and Functions
44
45    None
46
47New Tokens
48
49    Accepted by the <pname> parameter of TexParameter* and GetTexParameter*:
50
51        DEPTH_STENCIL_TEXTURE_MODE_ANGLE                 0x90EA
52        STENCIL_INDEX_ANGLE                              0x1901
53
54Additions to the OpenGL ES 3.0 Specification
55
56Changes to Section 3.9.2.1 (Texture Access), page 167
57
58Add a new new bullet point on page 168:
59
60    "* The sampler used in a texture lookup function is one of the shadow
61    sampler types, the texture object's internal format is DEPTH_STENCIL,
62    and the DEPTH_STENCIL_TEXTURE_MODE_ANGLE is not DEPTH_COMPONENT."
63
64Then change the following paragraph that reads:
65
66    "The stencil texture internal component is ignored if the base internal
67    format is DEPTH_STENCIL."
68
69To the following:
70
71    "The stencil index texture internal component is ignored if the base
72    internal format is DEPTH_STENCIL and the value of
73    DEPTH_STENCIL_TEXTURE_MODE_ANGLE is not STENCIL_INDEX_ANGLE.
74
75    Texture lookups involving texture objects with an internal format
76    of DEPTH_STENCIL can read the stencil value as described in section
77    3.8 by setting the DEPTH_STENCIL_TEXTURE_MODE_ANGLE to STENCIL_INDEX_ANGLE.
78    The stencil value is read as an integer and assigned to R_t. An unsigned
79    integer sampler should be used to lookup the stencil component, otherwise
80    the results are undefined."
81
82Changes to Section 3.8.7 (Texture Parameters), page 150
83
84In Table 3.20 (Texture parameters and their values) add the following
85entry:
86
87    "
88    Name                              Type  Legal Values
89    -------------                     ----  ------------------------------------
90    DEPTH_STENCIL_TEXTURE_MODE_ANGLE  enum  DEPTH_COMPONENT, STENCIL_INDEX_ANGLE
91    "
92
93Changes to Section 3.8.12 (Combined Depth/Stencil Textures), page 160
94
95Modify the paragraph to read:
96
97    "If the texture image has a base internal format of DEPTH_STENCIL, then
98    the stencil index texture component is ignored by default. The texture
99    value <T> does not include a stencil index component, but includes
100    only the depth component.
101
102    In order to access the stencil index texture component, the
103    DEPTH_STENCIL_TEXTURE_MODE_ANGLE texture parameter should be set to
104    STENCIL_INDEX_ANGLE. When this mode is set the depth component is ignored
105    and the texture value includes only the stencil index component.
106    The stencil index value is treated as an unsigned integer texture and
107    returns an unsigned integer value when sampled. When sampling the stencil
108    index only NEAREST filtering is supported.
109    The DEPTH_STENCIL_TEXTURE_MODE_ANGLE is ignored for non depth/stencil
110    textures."
111
112Changes to Section 3.8.13 (Texture Completeness), page 161
113
114Add a new bullet point for the conditions that cause the texture
115to not be complete:
116
117    "* The internal format of the texture is DEPTH_STENCIL, the value of
118    DEPTH_STENCIL_TEXTURE_MODE_ANGLE for the texture is STENCIL_INDEX_ANGLE,
119    and either the magnification filter is not NEAREST or the minification
120    filter is neither NEAREST nor NEAREST_MIPMAP_NEAREST."
121
122Changes to Section 3.8.15 (Texture Comparison Modes), page 163
123
124Modify the following paragraph:
125
126    "Let Dt be the depth texture value and St be the stencil index component
127    of a depth/stencil texture. If there is no stencil component the value of
128    St is undefined. Let Dref be the reference value..."
129
130Insert a new paragraph after the paragraphs that ends:
131
132    "Then the effective texture value is computed as follows:
133        If the base internal format is DEPTH_STENCIL and the value of
134    DEPTH_STENCIL_TEXTURE_MODE_ANGLE is STENCIL_INDEX_ANGLE, then
135            r = St
136        Otherwise, if the value of TEXTURE_COMPARE_MODE is NONE, then
137            r = Dt
138        Otherwise, if the value of TEXTURE_COMPARE_MODE is
139    COMPARE_REF_TO_TEXTURE, then r depends on the texture comparison
140    function as shown in table 3.23.
141        The resulting r is assigned ..."
142
143New State
144
145    (Table 6.9, Textures) add the following entry:
146
147    Get Value                        Type  Get Command        Initial Value    Description                 Section
148    -------------------------------- ----  -----------------  ---------------  --------------------------  -------
149    DEPTH_STENCIL_TEXTURE_MODE_ANGLE  Z2   GetTexParameteriv  DEPTH_COMPONENT  Depth stencil texture mode  3.8.7
150
151Revision History
152
153    3/1/2023   First revision
154