Name OES_texture_border_clamp Name Strings GL_OES_texture_border_clamp Contact Daniel Koch, NVIDIA (dkoch 'at' nvidia 'dot' com) Contributors Jussi Rasanen, NVIDIA Greg Roth, NVIDIA Dominik Witczak, Mobica Graham Connor, Imagination Ben Bowman, Imagination Jonathan Putsman, Imagination Maurice Ribble, Qualcomm Notice Copyright (c) 2014 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 ES 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 Approved by the OpenGL ES Working Group Ratified by the Khronos Board of Promoters on November 7, 2014 Version Last Modified Date: June 18, 2014 Revision: 1 Number OpenGL ES Extension #215 Dependencies OpenGL ES 2.0 is required. This extension is written against the OpenGL ES 3.0.2 specification. OpenGL ES 3.0 affects the definition of this extension. OES_texture_3D affects the definition of this extension. EXT_texture_compression_s3tc trivially affects the definition of this extension. KHR_texture_compression_astc_{ldr,hdr} trivially affect the definition of this extension. Overview OpenGL ES provides only a single clamping wrap mode: CLAMP_TO_EDGE. However, the ability to clamp to a constant border color can be useful to quickly detect texture coordinates that exceed their expected limits or to dummy out any such accesses with transparency or a neutral color in tiling or light maps. This extension defines an additional texture clamping algorithm. CLAMP_TO_BORDER_OES clamps texture coordinates at all mipmap levels such that NEAREST and LINEAR filters of clamped coordinates return only the constant border color. This does not add the ability for textures to specify borders using glTexImage2D, but only to clamp to a constant border value set using glTexParameter and glSamplerParameter. New Procedures and Functions void TexParameterIivOES(enum target, enum pname, const int *params); void TexParameterIuivOES(enum target, enum pname, const uint *params); void GetTexParameterIivOES(enum target, enum pname, int *params); void GetTexParameterIuivOES(enum target, enum pname, uint *params); void SamplerParameterIivOES(uint sampler, enum pname, const int *params); void SamplerParameterIuivOES(uint sampler, enum pname, const uint *params); void GetSamplerParameterIivOES(uint sampler, enum pname, int *params); void GetSamplerParameterIuivOES(uint sampler, enum pname, uint *params); New Tokens Accepted by the parameter of TexParameteriv, TexParameterfv, SamplerParameteriv, SamplerParameterfv, TexParameterIivOES, TexParameterIuivOES, SamplerParameterIivOES, SamplerParameterIuivOES, GetTexParameteriv, GetTexParameterfv, GetTexParameterIivOES, GetTexParameterIuivOES, GetSamplerParameteriv, GetSamplerParameterfv, GetSamplerParameterIivOES, and GetSamplerParameterIuivOES: TEXTURE_BORDER_COLOR_OES 0x1004 Accepted by the parameter of TexParameteri, TexParameterf, SamplerParameteri and SamplerParameterf, and by the parameter of TexParameteriv, TexParameterfv, TexParameterIivOES, TexParameterIuivOES, SamplerParameterIivOES, SamplerParameterIuivOES and returned by the parameter of GetTexParameteriv, GetTexParameterfv, GetTexParameterIivOES, GetTexParameterIuivOES, GetSamplerParameteriv, GetSamplerParameterfv, GetSamplerParameterIivOES, and GetSamplerParameterIuivOES when their parameter is TEXTURE_WRAP_S, TEXTURE_WRAP_T, or TEXTURE_WRAP_R: CLAMP_TO_BORDER_OES 0x812D Note that the {Get}TexParameterI{i ui}vOES and {Get}SamplerParameterI{i ui}vOES functions also accept all the same parameters and values as are accepted by the existing {Get}TexParameter{if}v and {Get}SamplerParameter{if}v commands, respectively. Additions to Chapter 3 of the OpenGL ES 3.0.2 Specification (Rasterization) Modifications to Section 3.8.2 "Sampler Objects" Add the following to the list of SamplerParameter commands (p.123): void SamplerParameterI{i ui}vOES(uint sampler, enum pname, const T *params); Modify the last sentence of the description of the commands to state: "In the first form of the command, is a value to which to set a single-valued parameter; in the remaining forms, is an array of parameters whose type depends on the parameter being set." Replace the last sentence of the 3rd paragraph on p.123 (beginning with "The values accepted in the parameter..." with the following: " must be one of the sampler state names in Table 6.10, otherwise an INVALID_ENUM error is generated. An INVALID_ENUM error is generated if SamplerParameter{if} is called for a non-scalar parameter (TEXTURE_BORDER_COLOR_OES)." Replace the 4th paragraph on p.123 (beginning with "Data conversions...") with the following: "Data conversions are performed as specified in section 2.3.1, except that if the values for TEXTURE_BORDER_COLOR_OES are specified with a call to SamplerParameterIiv or SamplerParameterIuiv, the values are unmodified and stored with an internal data type of integer. If specified with SamplerParameteriv, they are converted to floating point using equation 2.2. Otherwise, border color values are unmodified and stored as floating-point." Modifications to Section 3.8.6 "Compressed Texture Images" Add column to Table 3.16 with heading "Border Type" fill in the values as follows: "unorm" for the following compressed internal formats: COMPRESSED_R11_EAC, COMPRESSED_RG11_EAC, COMPRESSED_RGB8_ETC2, COMPRESSED_SRGB8_ETC2, COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2, COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2, COMPRESSED_RGBA8_ETC2_EAC, COMPRESSED_SRGB8_ALPHA8_ETC2_EAC, COMPRESSED_RGB_S3TC_DXT1_EXT, COMPRESSED_RGBA_S3TC_DXT1_EXT, COMPRESSED_RGBA_S3TC_DXT3_EXT, COMPRESSED_RGBA_S3TC_DXT5_EXT, COMPRESSED_RGBA_ASTC_*_KHR, COMPRESSED_SRGB8_ALPHA8_ASTC_*_KHR "snorm" for the following compressed internal formats: COMPRESSED_SIGNED_R11_EAC, COMPRESSED_SIGNED_RG11_EAC "float" for the following compressed internal formats: (currently none -- to be added by any extension adding BPTC support) Add the following to the table caption: "The 'Border Type' field determines how border colors are clamped as described in section 3.8.10." Modifications to Section 3.8.7 "Texture Parameters" Add the following to the list of TexParameter commands (p.223): void TexParameterI{i ui}vOES(enum target, enum pname, const T *params); Modify the last sentence of the description of the commands to state: "In the first form of the command, is a value to which to set a single-valued parameter; in the remaining forms, is an array of parameters whose type depends on the parameter being set." Add a new paragraph at the end of p.145 after the paragraph about data conversions: "In addition, if the values for TEXTURE_BORDER_COLOR_OES are specified with TexParameterIiv or TexParameterIuiv, the values are unmodified and stored with an internal data type of integer or unsigned integer, respectively. If specified with TexParameteriv, they are converted to floating-point using equation 2.2. Otherwise, the values are unmodified and stored as floating-point. An INVALID_ENUM error is generated if TexParameter{if} is called for a non-scalar parameters (TEXTURE_BORDER_COLOR_OES)." Modify Table 3.17, edit the following rows (adding CLAMP_TO_BORDER_OES to each of the wrap modes): Name Type Legal Values ============== ==== ==================== TEXTURE_WRAP_S enum CLAMP_TO_EDGE, REPEAT, MIRRORED_REPEAT, CLAMP_TO_BORDER_OES TEXTURE_WRAP_T enum CLAMP_TO_EDGE, REPEAT, MIRRORED_REPEAT, CLAMP_TO_BORDER_OES TEXTURE_WRAP_R enum CLAMP_TO_EDGE, REPEAT, MIRRORED_REPEAT, CLAMP_TO_BORDER_OES and add the following row: Name Type Legal Values ============== ======== ==================== TEXTURE_BORDER_COLOR_OES 4 floats, any 4 values ints, or uints Modifications to Section 3.8.9 "Cube Map Texture Selection" In the "Seamless Cube Map Filtering" subsection change the rule about LINEAR filtering to state: "* If LINEAR filtering is done within a miplevel, always apply wrap mode CLAMP_TO_BORDER_OES. Then, ..." Modifications to Section 3.8.10 "Texture Minification" Modify Table 3.19, edit the cell that says: "border clamping (used only for cube maps with LINEAR filter)" and replace it with "CLAMP_TO_BORDER_OES". In the subsection "Coordinate Wrapping and Texel Selection" add the following text at the end of the description for when TEXTURE_MIN_FILTER is NEAREST: "If the selected (i,j,k), (i,j) or i location refers to a border texel that satisfies any of the conditions: i < 0, j < 0, k < 0, i >= w_t, j >= h_t, k >= d_t then the border values defined by TEXTURE_BORDER_COLOR_OES are used in place of the non-existent texel. If the texture contains color components, the values of TEXTURE_BORDER_COLOR_OES are interpreted as an RGBA color to match the texture's internal format in a manner consistent with table 3.11. The internal data type of the border colors must be consistent with the type returned by the texture as described in chapter 3, or the result is undefined. Border values are clamped before they are used, according to the format in which the texture components are stored. For signed and unsigned normalized fixed-point formats, border values are clamped to [-1,1] and [0,1] respectively. For floating-point and integer formats, border values are clamped to the representable range of the format. For compressed formats, border values are clamped as signed normalized ("snorm"), unsigned normalized ("unorm"), or floating-point as described in Table 3.16 for each format. If the texture contains depth components, the first component of TEXTURE_BORDER_COLOR_OES is interpreted as a depth value." Add the following text at the end of the description for when TEXTURE_MIN_FILTER is LINEAR: "For any texel in the equation above that refers to a border texel outside the defined range of the image, the texel value is taken from the texture border color as with NEAREST filtering." Modifications to Section 3.7.14 "Texture state" Modify the second paragraph as follows: "Next, there are four sets of texture properties... Each set consists of the selected minification and magnification filters, the wrap modes for s, t, r (three-dimensional only), the TEXTURE_BORDER_COLOR_OES, two floating-point numbers ... In the initial state, ... wrap modes are set to REPEAT, and the value of TEXTURE_BORDER_COLOR_OES is (0,0,0,0). ..." Additions to Chapter 6 of the OpenGL ES 3.0.2 Specification (State and State Requests) Modifications to Section 6.1.3 "Enumerated Queries" Add the following command in a list with GetTexParameter{if}v: void GetTexParameterI{i ui}v(enum target, enum pname, T *data); Append the following to the description of the GetTexParameter* commands: "Querying TEXTURE_BORDER_COLOR_OES with GetTexParameterIiv or GetTexParameterIuiv returns the border color values as signed integers or unsigned integers, respectively; otherwise the values are returned as described in section 6.1.2. If the border color is queried with a type that does not match the original type with which it was specified, the result is undefined." Modifications to Section 6.1.5 "Sampler Queries" Add the following command in a list with GetSamplerParameter{if}v: void GetSamplerParameterI{i ui}v(uint sampler, enum pname, T *params); Append the following to the description of the GetSamplerParameter* commands: "Querying TEXTURE_BORDER_COLOR_OES with GetSamplerParameterIiv or GetSamplerParameterIuiv returns the border color values as signed integers or unsigned integers, respectively; otherwise the values are returned as described in section 6.1.2. If the border color is queried with a type that does not match the original type with which it was specified, the result is undefined." Errors An INVALID_ENUM error is generated if TexParameter{if} is called for a non-scalar parameter (TEXTURE_BORDER_COLOR_OES). An INVALID_ENUM error is generated by TexParameterI*v if is not one of the valid types of texture targets accepted by TexParameter{if}v. An INVALID_ENUM error is generated by TexParameterI*v if is not one of the values listed in Table 3.17. An INVALID_ENUM error is generated by TexParameterI*v if the type of the parameter specified by is enum, and the value(s) specified by is not among the legal values shown in Table 3.17. An INVALID_ENUM error is generated by GetTexParameterI*v if is not one of the valid types of texture targets accepted by GetTexParameter{if}v. An INVALID_ENUM error is generated by GetTexParameterI*v if is not one of values accepted by GetTexParameter{if}v. An INVALID_ENUM error is generated if SamplerParameter{if} is called for a non-scalar parameter (TEXTURE_BORDER_COLOR_OES). An INVALID_OPERATION error is generated by SamplerParameterI*v if is not the name of a sampler object previously returned from a call to GenSamplers. An INVALID_ENUM error is generated by SamplerParameterI*v if is not the name of a parameter accepted by SamplerParameter*. An INVALID_OPERATION error is generated by GetSamplerParameterI*v if is not the name of a sampler object previously returned from a call to GenSamplers. An INVALID_ENUM error is generated by GetSamplerParameterI*v if is not the name of a parameter accepted by GetSamplerParameter*. New State Modify table 6.10: Change the type information changes for these parameters. Initial Get Value Type Get Command Value Description Sec. --------- ------ ----------- ------- ----------- ---- TEXTURE_WRAP_S n x Z4 GetSamplerParameter (as before...) TEXTURE_WRAP_T n x Z4 GetSamplerParameter (as before...) TEXTURE_WRAP_R n x Z4 GetSamplerParameter (as before...) Add the following parameter: Get Value Type Get Command Value Description Sec. --------- ------ ----------- ------- ----------- ---- TEXTURE_BORDER_COLOR_OES 4 x C GetSamplerParameter 0.0,0.0,0.0,0.0 border color 3.8 Dependencies on OpenGL ES 3.0 If OpenGL ES 3.0 is not supported, but OES_texture_3D is supported, replace references to TEXTURE_WRAP_R with TEXTURE_WRAP_R_OES. If OpenGL ES 3.0 is not supported, delete all references to the TexParameterI*, GetTexParameterI*, SamplerParameterI*, and GetSamplerParameterI* entry points and all related text about signed and unsigned integer textures. Dependencies on OES_texture_3D If neither OpenGL ES 3.0 nor OES_texture_3D is supported, ignore all references to three-dimensional textures and the token TEXTURE_WRAP_R as well as any reference to r wrap modes. References to (i,j,k), k, and d_t in section 3.8.10 should also be removed. Dependencies on EXT_texture_compression_s3tc If EXT_texture_compression is not supported, ignore all references to S3TC compressed textures. Dependencies on KHR_texture_compression_astc_{ldr,hdr} If none of the KHR_texture_compression_astc extensions are supported, ignore all references to ASTC compressed textures. Issues (1) Which is the correct equation to use for converting TEXTURE_BORDER_COLOR_OES when specified via SamplerParameteriv or TexParameteriv? RESOLVED: Early versions of GL 4.4 referenced both equations 2.1 and 2.2. As per clarification in Bug 11185, the correct answer is equation 2.2. (2) Does SamplerParmeter{if} set an error if called with a non-scalar parameter? RESOLVED: Yes. This should be analogous to TexParameteriv. This error seems to be missing from GL 4.4. Filed bug 11186 to get this rectified. (3) Should the second argument to GetTexParameterI* be or ? RESOLVED: the GL specs call it , but the headers call it . The GetSamplerParameterI* version calls it , so we are doing the same here for consistency. This was corrected in OpenGL ES 3.1. Revision History Rev. Date Author Changes ---- -------- --------- ------------------------------------------------- 1 06/18/2014 dkoch Initial OES version based on EXT. No functional changes.