Name ARB_texture_stencil8 Name Strings GL_ARB_texture_stencil8 Contact Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) Contributors Piers Daniell, NVIDIA Daniel Koch, NVIDIA Jon Leech Notice Copyright (c) 2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Specification Update Policy Khronos-approved extension specifications are updated in response to issues and bugs prioritized by the Khronos OpenGL Working Group. For extensions which have been promoted to a core Specification, fixes will first appear in the latest version of that core Specification, and will eventually be backported to the extension document. This policy is described in more detail at https://www.khronos.org/registry/OpenGL/docs/update_policy.php Status Complete. Approved by the ARB on June 3, 2013. Ratified by the Khronos Board of Promoters on July 19, 2013. Version Last Modified Date: August 26, 2013 Revision: 5 Number ARB Extension #150 Dependencies This extension is written against the OpenGL 4.3 specification (Compatibility Profile). Overview This extension accepts STENCIL_INDEX8 as a texture internal format, and adds STENCIL_INDEX8 to the required internal format list. This removes the need to use renderbuffers if a stencil-only format is desired. New Procedures and Functions None. New Tokens Accepted by the parameter of TexImage3D, TexImage2D, TexImage1D, TexSubImage3D, TexSubImage2D, TexSubImage1D, or GetTexImage: STENCIL_INDEX 0x1901 /* existing enum */ Accepted by the parameter of TexImage3D, TexImage2D, TexImage1D, CopyTexImage2D, CopyTexImage1D, TexStorage3D, TexStorage2D, TexStorage1D, TexImage3DMultisample, TexImage2DMultisample, TexStorage3DMultisample, TexStorage2DMultisample: STENCIL_INDEX8 0x8D48 /* existing enum */ Additions to Chapter 8 of the OpenGL 4.3 (Compatibility Profile) Specification (Textures and Samplers) Modify Section 8.5 Texture Image Specification, p. 205 In the first paragraph, replace "The STENCIL_INDEX is not allowed" with "An INVALID_OPERATION error is generated if the is STENCIL_INDEX and the base internal format is not STENCIL_INDEX." Modify the last paragraph of p. 207 to include STENCIL_INDEX: "Textures with a base internal format of DEPTH_COMPONENT, DEPTH_STENCIL, or STENCIL_INDEX are supported by texture image specification commands only if is TEXTURE_1D, TEXTURE_2D, TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_RECTANGLE, TEXTURE_CUBE_MAP, TEXTURE_CUBE_MAP_ARRAY, TEXTURE_2D_MULTISAMPLE, TEXTURE_2D_MULTISAMPLE_ARRAY, PROXY_TEXTURE_1D, PROXY_TEXTURE_2D, PROXY_TEXTURE_1D_ARRAY, PROXY_TEXTURE_2D_ARRAY, PROXY_TEXTURE_RECTANGLE, PROXY_TEXTURE_CUBE_MAP, PROXY_TEXTURE_CUBE_MAP_ARRAY, PROXY_TEXTURE_2D_MULTISAMPLE or PROXY_TEXTURE_2D_MULTISAMPLE_ARRAY." Add a row to Table 8.18: Conversion from RGBA, depth, and stencil pixel components to internal texture, table, or filter components Base Internal Format RGBA, Depth, and Stencil Values Internal Components STENCIL_INDEX Stencil S Add to the list of required texture internal formats: - Stencil formats: STENCIL_INDEX8 Add rows to Table 8.21: Correspondence of sized internal depth and stencil formats to base internal formats, internal data type, and desired component resolutions for each sized internal format Sized Internal Format Base Internal Format D bits S bits STENCIL_INDEX8 STENCIL_INDEX 8 Modify Section 8.6 Alternate Texture Image Specification Commands, p. 222 ...The image is taken from the framebuffer exactly as if these arguments were passed to CopyPixels (see section 18.3) with argument type set to COLOR, DEPTH, DEPTH_STENCIL, or STENCIL_INDEX, depending on internalformat, stopping after pixel transfer processing is complete. Modify Section 8.11 Texture Queries, p. 246 If format is DEPTH_COMPONENT, DEPTH_STENCIL, or STENCIL_INDEX then each depth component and/or stencil index is assigned with the same ordering of rows and images. Modifications to the errors section for GetTexImage, p. 247, Delete the following error: An INVALID_ENUM error is generated if is STENCIL_INDEX. Add a bullet to the list of reasons for INVALID_OPERATION error: - is STENCIL_INDEX and the base internal format is not STENCIL_INDEX or DEPTH_STENCIL. Modify 8.17 Texture Completeness, p. 263 Modify the bullet point on p. 263 describing required texture filter modes for an integer texture in order to determine texture completeness, to add STENCIL_INDEX textures explicitly: - The internal format of the texture is integer (see tables 8.19-8.20) or STENCIL_INDEX, and either the magnification filter is not NEAREST, or the minification filter is neither NEAREST nor NEAREST_MIPMAP_NEAREST. Modify 8.22.1 Depth Texture Comparison Mode, p. 278 - If the base internal format is STENCIL_INDEX, then r = St Additions to Chapter 11 of the OpenGL 4.3 (Compatibility Profile) Specification (Programmable Vertex Processing) Modify 11.1.3.5 Texture Access p. 390 Texture lookups involving texture objects with an internal format of DEPTH_- STENCIL can read the stencil value as described in section 8.22 by setting the DEPTH_STENCIL_TEXTURE_MODE to STENCIL_COMPONENT. Textures with a STENCIL_INDEX base internal format may also be used to read stencil data. The stencil value is read as an integer and assigned to Rt. An unsigned integer sampler must be used to lookup the stencil component, otherwise the results are undefined. Additions to Chapter 15 of the OpenGL 4.3 (Compatibility Profile) Specification (Programmable Fragment Processing) Modify 15.2.1 Texture Access, p.510 Repace the paragraph "The stencil index texture internal component is ignored if the base internal format is DEPTH_STENCIL" with: Texture lookups involving textures with stencil index data generate a texture base color Cb by using stencil values St directly, if either the texture has a base internal format of STENCIL_INDEX or the texture has a base internal format of DEPTH_STENCIL and a DEPTH_STENCIL_TEXTURE_MODE of STENCIL_COMPONENT. New Implementation Dependent State None. New State None. Additions to the AGL/GLX/WGL Specifications None. GLX Protocol None. Modifications to the OpenGL Shading Language Specification, Version 4.30 None. Errors An INVALID_OPERATION error is generated by GetTexImage if is STENCIL_INDEX and the base internal format is not STENCIL_INDEX or DEPTH_STENCIL. An INVALID_OPERATION error is generated by TexImage3D, TexImage2D, TexImage1D, TexSubImage3D, TexSubImage2D, or TexSubImage1D if is STENCIL_INDEX and the base internal format is not . An INVALID_OPERATION error is generated by TexImage3D, TexImage2D, TexImage1D, TexSubImage3D, TexSubImage2D, or TexSubImage1D if is STENCIL_INDEX and is not one of TEXTURE_1D, TEXTURE_2D, TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_RECTANGLE, TEXTURE_CUBE_MAP, TEXTURE_CUBE_MAP_ARRAY, PROXY_TEXTURE_1D, PROXY_TEXTURE_2D, PROXY_TEXTURE_1D_ARRAY, PROXY_TEXTURE_2D_ARRAY, PROXY_TEXTURE_RECTANGLE, PROXY_TEXTURE_CUBE_MAP, or PROXY_TEXTURE_CUBE_MAP_ARRAY. Issues (1) What is the interaction with ARB_stencil_texturing's DEPTH_STENCIL_TEXTURE_MODE? RESOLVED: That piece of state is ignored because the base internal format of a STENCIL_INDEX texture is not DEPTH_STENCIL. (2) Does the presence of this extension imply that the implementation supports a true 8-bit stencil buffer? RESOLVED: No, some OpenGL implementations may internally expand a format like STENCIL_INDEX8 to DEPTH24_STENCIL8, but will make such a format behave as if there were no depth bits. Additionally, implementations may not support independent depth and stencil attachments; a framebuffer with a STENCIL_INDEX8 stencil attachment and a DEPTH_COMPONENT24 depth attachment may be treated as unsupported (FRAMEBUFFER_UNSUPPORTED). (3) Should we support stencil formats that have a number of bits that is not exactly supported in the implementation? 8-bits is universally supported, but 1/4/16-bits are not. RESOLVED: Only accept STENCIL_INDEX8, which is universally supported. Revision History Rev. Date Author Changes ---- -------- -------- ----------------------------------------------- 1 03/20/13 jbolz Internal revisions. 2 05/30/13 dgkoch Add tokens and errors section. Update errors for GetTexImage. 3 06/28/13 Jon Leech Fix dates in revision history. Change filter modes for texture completeness (Bug 10372). 4 08/08/13 pdaniell Fix the functions that accept STENCIL_INDEX8 as an parameter (Bug 10558). 5 08/26/13 pdaniell Fix the list of texture targets that support stencil (and depth and depth/stencil) textures to include the multisample targets (Bug 10558).