1Name 2 3 OES_texture_border_clamp 4 5Name Strings 6 7 GL_OES_texture_border_clamp 8 9Contact 10 11 Daniel Koch, NVIDIA (dkoch 'at' nvidia 'dot' com) 12 13Contributors 14 15 Jussi Rasanen, NVIDIA 16 Greg Roth, NVIDIA 17 Dominik Witczak, Mobica 18 Graham Connor, Imagination 19 Ben Bowman, Imagination 20 Jonathan Putsman, Imagination 21 Maurice Ribble, Qualcomm 22 23Notice 24 25 Copyright (c) 2014 The Khronos Group Inc. Copyright terms at 26 http://www.khronos.org/registry/speccopyright.html 27 28Specification Update Policy 29 30 Khronos-approved extension specifications are updated in response to 31 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 32 extensions which have been promoted to a core Specification, fixes will 33 first appear in the latest version of that core Specification, and will 34 eventually be backported to the extension document. This policy is 35 described in more detail at 36 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 37 38Status 39 40 Approved by the OpenGL ES Working Group 41 Ratified by the Khronos Board of Promoters on November 7, 2014 42 43Version 44 45 Last Modified Date: June 18, 2014 46 Revision: 1 47 48Number 49 50 OpenGL ES Extension #215 51 52Dependencies 53 54 OpenGL ES 2.0 is required. 55 56 This extension is written against the OpenGL ES 3.0.2 57 specification. 58 59 OpenGL ES 3.0 affects the definition of this extension. 60 61 OES_texture_3D affects the definition of this extension. 62 63 EXT_texture_compression_s3tc trivially affects the definition 64 of this extension. 65 66 KHR_texture_compression_astc_{ldr,hdr} trivially affect the 67 definition of this extension. 68 69Overview 70 71 OpenGL ES provides only a single clamping wrap mode: CLAMP_TO_EDGE. 72 However, the ability to clamp to a constant border color can be 73 useful to quickly detect texture coordinates that exceed their 74 expected limits or to dummy out any such accesses with transparency 75 or a neutral color in tiling or light maps. 76 77 This extension defines an additional texture clamping algorithm. 78 CLAMP_TO_BORDER_OES clamps texture coordinates at all mipmap levels 79 such that NEAREST and LINEAR filters of clamped coordinates return 80 only the constant border color. This does not add the ability for 81 textures to specify borders using glTexImage2D, but only to clamp 82 to a constant border value set using glTexParameter and 83 glSamplerParameter. 84 85New Procedures and Functions 86 87 void TexParameterIivOES(enum target, enum pname, const int *params); 88 void TexParameterIuivOES(enum target, enum pname, const uint *params); 89 90 void GetTexParameterIivOES(enum target, enum pname, int *params); 91 void GetTexParameterIuivOES(enum target, enum pname, uint *params); 92 93 void SamplerParameterIivOES(uint sampler, enum pname, const int *params); 94 void SamplerParameterIuivOES(uint sampler, enum pname, const uint *params); 95 96 void GetSamplerParameterIivOES(uint sampler, enum pname, int *params); 97 void GetSamplerParameterIuivOES(uint sampler, enum pname, uint *params); 98 99New Tokens 100 101 Accepted by the <pname> parameter of TexParameteriv, TexParameterfv, 102 SamplerParameteriv, SamplerParameterfv, TexParameterIivOES, 103 TexParameterIuivOES, SamplerParameterIivOES, SamplerParameterIuivOES, 104 GetTexParameteriv, GetTexParameterfv, GetTexParameterIivOES, 105 GetTexParameterIuivOES, GetSamplerParameteriv, GetSamplerParameterfv, 106 GetSamplerParameterIivOES, and GetSamplerParameterIuivOES: 107 108 TEXTURE_BORDER_COLOR_OES 0x1004 109 110 Accepted by the <param> parameter of TexParameteri, TexParameterf, 111 SamplerParameteri and SamplerParameterf, and by the <params> parameter of 112 TexParameteriv, TexParameterfv, TexParameterIivOES, TexParameterIuivOES, 113 SamplerParameterIivOES, SamplerParameterIuivOES and returned by the 114 <params> parameter of GetTexParameteriv, GetTexParameterfv, 115 GetTexParameterIivOES, GetTexParameterIuivOES, GetSamplerParameteriv, 116 GetSamplerParameterfv, GetSamplerParameterIivOES, and 117 GetSamplerParameterIuivOES when their <pname> parameter 118 is TEXTURE_WRAP_S, TEXTURE_WRAP_T, or TEXTURE_WRAP_R: 119 120 CLAMP_TO_BORDER_OES 0x812D 121 122 Note that the {Get}TexParameterI{i ui}vOES and 123 {Get}SamplerParameterI{i ui}vOES functions also accept all the 124 same parameters and values as are accepted by the existing 125 {Get}TexParameter{if}v and {Get}SamplerParameter{if}v commands, 126 respectively. 127 128Additions to Chapter 3 of the OpenGL ES 3.0.2 Specification 129(Rasterization) 130 131 Modifications to Section 3.8.2 "Sampler Objects" 132 133 Add the following to the list of SamplerParameter commands (p.123): 134 135 void SamplerParameterI{i ui}vOES(uint sampler, enum pname, 136 const T *params); 137 138 Modify the last sentence of the description of the commands to state: 139 140 "In the first form of the command, <param> is a value to which to 141 set a single-valued parameter; in the remaining forms, <params> is an 142 array of parameters whose type depends on the parameter being set." 143 144 Replace the last sentence of the 3rd paragraph on p.123 (beginning with 145 "The values accepted in the <pname> parameter..." with the following: 146 147 "<pname> must be one of the sampler state names in Table 6.10, otherwise 148 an INVALID_ENUM error is generated. An INVALID_ENUM error is generated 149 if SamplerParameter{if} is called for a non-scalar parameter 150 (TEXTURE_BORDER_COLOR_OES)." 151 152 Replace the 4th paragraph on p.123 (beginning with "Data conversions...") 153 with the following: 154 155 "Data conversions are performed as specified in section 2.3.1, except 156 that if the values for TEXTURE_BORDER_COLOR_OES are specified with 157 a call to SamplerParameterIiv or SamplerParameterIuiv, the values are 158 unmodified and stored with an internal data type of integer. If specified 159 with SamplerParameteriv, they are converted to floating point using 160 equation 2.2. Otherwise, border color values are unmodified and stored 161 as floating-point." 162 163 Modifications to Section 3.8.6 "Compressed Texture Images" 164 165 Add column to Table 3.16 with heading "Border Type" fill in the 166 values as follows: 167 "unorm" for the following compressed internal formats: 168 COMPRESSED_R11_EAC, COMPRESSED_RG11_EAC, COMPRESSED_RGB8_ETC2, 169 COMPRESSED_SRGB8_ETC2, COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2, 170 COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2, COMPRESSED_RGBA8_ETC2_EAC, 171 COMPRESSED_SRGB8_ALPHA8_ETC2_EAC, 172 COMPRESSED_RGB_S3TC_DXT1_EXT, COMPRESSED_RGBA_S3TC_DXT1_EXT, 173 COMPRESSED_RGBA_S3TC_DXT3_EXT, COMPRESSED_RGBA_S3TC_DXT5_EXT, 174 COMPRESSED_RGBA_ASTC_*_KHR, COMPRESSED_SRGB8_ALPHA8_ASTC_*_KHR 175 "snorm" for the following compressed internal formats: 176 COMPRESSED_SIGNED_R11_EAC, COMPRESSED_SIGNED_RG11_EAC 177 "float" for the following compressed internal formats: 178 (currently none -- to be added by any extension adding BPTC support) 179 180 Add the following to the table caption: 181 "The 'Border Type' field determines how border colors are clamped as 182 described in section 3.8.10." 183 184 Modifications to Section 3.8.7 "Texture Parameters" 185 186 Add the following to the list of TexParameter commands (p.223): 187 188 void TexParameterI{i ui}vOES(enum target, enum pname, 189 const T *params); 190 191 192 Modify the last sentence of the description of the commands to state: 193 194 "In the first form of the command, <param> is a value to which to 195 set a single-valued parameter; in the remaining forms, <params> is an 196 array of parameters whose type depends on the parameter being set." 197 198 Add a new paragraph at the end of p.145 after the paragraph about data 199 conversions: 200 201 "In addition, if the values for TEXTURE_BORDER_COLOR_OES are specified 202 with TexParameterIiv or TexParameterIuiv, the values are unmodified and 203 stored with an internal data type of integer or unsigned integer, 204 respectively. If specified with TexParameteriv, they are converted to 205 floating-point using equation 2.2. Otherwise, the values are unmodified 206 and stored as floating-point. An INVALID_ENUM error is generated if 207 TexParameter{if} is called for a non-scalar parameters 208 (TEXTURE_BORDER_COLOR_OES)." 209 210 Modify Table 3.17, edit the following rows (adding 211 CLAMP_TO_BORDER_OES to each of the wrap modes): 212 213 Name Type Legal Values 214 ============== ==== ==================== 215 TEXTURE_WRAP_S enum CLAMP_TO_EDGE, REPEAT, MIRRORED_REPEAT, 216 CLAMP_TO_BORDER_OES 217 TEXTURE_WRAP_T enum CLAMP_TO_EDGE, REPEAT, MIRRORED_REPEAT, 218 CLAMP_TO_BORDER_OES 219 TEXTURE_WRAP_R enum CLAMP_TO_EDGE, REPEAT, MIRRORED_REPEAT, 220 CLAMP_TO_BORDER_OES 221 222 and add the following row: 223 224 Name Type Legal Values 225 ============== ======== ==================== 226 TEXTURE_BORDER_COLOR_OES 4 floats, any 4 values 227 ints, or 228 uints 229 230 Modifications to Section 3.8.9 "Cube Map Texture Selection" 231 232 In the "Seamless Cube Map Filtering" subsection change the rule 233 about LINEAR filtering to state: 234 235 "* If LINEAR filtering is done within a miplevel, always apply 236 wrap mode CLAMP_TO_BORDER_OES. Then, ..." 237 238 Modifications to Section 3.8.10 "Texture Minification" 239 240 Modify Table 3.19, edit the cell that says: 241 "border clamping (used only for cube maps with LINEAR filter)" 242 and replace it with "CLAMP_TO_BORDER_OES". 243 244 In the subsection "Coordinate Wrapping and Texel Selection" 245 add the following text at the end of the description for when 246 TEXTURE_MIN_FILTER is NEAREST: 247 248 "If the selected (i,j,k), (i,j) or i location refers to a border texel 249 that satisfies any of the conditions: 250 i < 0, j < 0, k < 0, i >= w_t, j >= h_t, k >= d_t 251 then the border values defined by TEXTURE_BORDER_COLOR_OES are used 252 in place of the non-existent texel. If the texture contains color 253 components, the values of TEXTURE_BORDER_COLOR_OES are interpreted 254 as an RGBA color to match the texture's internal format in a manner 255 consistent with table 3.11. The internal data type of the border 256 colors must be consistent with the type returned by the texture as 257 described in chapter 3, or the result is undefined. Border values are 258 clamped before they are used, according to the format in which the 259 texture components are stored. For signed and unsigned normalized 260 fixed-point formats, border values are clamped to [-1,1] and [0,1] 261 respectively. For floating-point and integer formats, border values 262 are clamped to the representable range of the format. For compressed 263 formats, border values are clamped as signed normalized ("snorm"), 264 unsigned normalized ("unorm"), or floating-point as described in 265 Table 3.16 for each format. If the texture contains depth components, 266 the first component of TEXTURE_BORDER_COLOR_OES is interpreted as a 267 depth value." 268 269 Add the following text at the end of the description for when 270 TEXTURE_MIN_FILTER is LINEAR: 271 272 "For any texel in the equation above that refers to a border texel 273 outside the defined range of the image, the texel value is taken 274 from the texture border color as with NEAREST filtering." 275 276 Modifications to Section 3.7.14 "Texture state" 277 278 Modify the second paragraph as follows: 279 280 "Next, there are four sets of texture properties... Each set consists 281 of the selected minification and magnification filters, the wrap modes 282 for s, t, r (three-dimensional only), the TEXTURE_BORDER_COLOR_OES, 283 two floating-point numbers ... In the initial state, ... wrap modes 284 are set to REPEAT, and the value of TEXTURE_BORDER_COLOR_OES is 285 (0,0,0,0). ..." 286 287Additions to Chapter 6 of the OpenGL ES 3.0.2 Specification 288(State and State Requests) 289 290 Modifications to Section 6.1.3 "Enumerated Queries" 291 292 Add the following command in a list with GetTexParameter{if}v: 293 294 void GetTexParameterI{i ui}v(enum target, enum pname, T *data); 295 296 Append the following to the description of the GetTexParameter* commands: 297 298 "Querying <pname> TEXTURE_BORDER_COLOR_OES with GetTexParameterIiv or 299 GetTexParameterIuiv returns the border color values as signed integers 300 or unsigned integers, respectively; otherwise the values are returned 301 as described in section 6.1.2. If the border color is queried with a 302 type that does not match the original type with which it was specified, 303 the result is undefined." 304 305 Modifications to Section 6.1.5 "Sampler Queries" 306 307 Add the following command in a list with GetSamplerParameter{if}v: 308 309 void GetSamplerParameterI{i ui}v(uint sampler, enum pname, T *params); 310 311 Append the following to the description of the GetSamplerParameter* 312 commands: 313 314 "Querying TEXTURE_BORDER_COLOR_OES with GetSamplerParameterIiv or 315 GetSamplerParameterIuiv returns the border color values as signed integers 316 or unsigned integers, respectively; otherwise the values are returned 317 as described in section 6.1.2. If the border color is queried with a 318 type that does not match the original type with which it was specified, 319 the result is undefined." 320 321Errors 322 323 An INVALID_ENUM error is generated if TexParameter{if} is called for 324 a non-scalar parameter (TEXTURE_BORDER_COLOR_OES). 325 326 An INVALID_ENUM error is generated by TexParameterI*v if 327 <target> is not one of the valid types of texture targets accepted 328 by TexParameter{if}v. 329 330 An INVALID_ENUM error is generated by TexParameterI*v if <pname> 331 is not one of the values listed in Table 3.17. 332 333 An INVALID_ENUM error is generated by TexParameterI*v if the type 334 of the parameter specified by <pname> is enum, and the value(s) 335 specified by <params> is not among the legal values shown in 336 Table 3.17. 337 338 An INVALID_ENUM error is generated by GetTexParameterI*v if 339 <target> is not one of the valid types of texture targets accepted 340 by GetTexParameter{if}v. 341 342 An INVALID_ENUM error is generated by GetTexParameterI*v if 343 <pname> is not one of values accepted by GetTexParameter{if}v. 344 345 An INVALID_ENUM error is generated if SamplerParameter{if} is called 346 for a non-scalar parameter (TEXTURE_BORDER_COLOR_OES). 347 348 An INVALID_OPERATION error is generated by SamplerParameterI*v 349 if <sampler> is not the name of a sampler object previously returned 350 from a call to GenSamplers. 351 352 An INVALID_ENUM error is generated by SamplerParameterI*v if 353 <pname> is not the name of a parameter accepted by SamplerParameter*. 354 355 An INVALID_OPERATION error is generated by GetSamplerParameterI*v 356 if <sampler> is not the name of a sampler object previously returned 357 from a call to GenSamplers. 358 359 An INVALID_ENUM error is generated by GetSamplerParameterI*v if 360 <pname> is not the name of a parameter accepted by GetSamplerParameter*. 361 362 363New State 364 365 Modify table 6.10: 366 367 Change the type information changes for these parameters. 368 Initial 369 Get Value Type Get Command Value Description Sec. 370 --------- ------ ----------- ------- ----------- ---- 371 TEXTURE_WRAP_S n x Z4 GetSamplerParameter (as before...) 372 TEXTURE_WRAP_T n x Z4 GetSamplerParameter (as before...) 373 TEXTURE_WRAP_R n x Z4 GetSamplerParameter (as before...) 374 375 Add the following parameter: 376 377 Get Value Type Get Command Value Description Sec. 378 --------- ------ ----------- ------- ----------- ---- 379 TEXTURE_BORDER_COLOR_OES 4 x C GetSamplerParameter 0.0,0.0,0.0,0.0 border color 3.8 380 381 382Dependencies on OpenGL ES 3.0 383 384 If OpenGL ES 3.0 is not supported, but OES_texture_3D is supported, 385 replace references to TEXTURE_WRAP_R with TEXTURE_WRAP_R_OES. 386 387 If OpenGL ES 3.0 is not supported, delete all references to the 388 TexParameterI*, GetTexParameterI*, SamplerParameterI*, and 389 GetSamplerParameterI* entry points and all related text about 390 signed and unsigned integer textures. 391 392Dependencies on OES_texture_3D 393 394 If neither OpenGL ES 3.0 nor OES_texture_3D is supported, ignore all 395 references to three-dimensional textures and the token TEXTURE_WRAP_R 396 as well as any reference to r wrap modes. References to (i,j,k), k, 397 and d_t in section 3.8.10 should also be removed. 398 399Dependencies on EXT_texture_compression_s3tc 400 401 If EXT_texture_compression is not supported, ignore all references to 402 S3TC compressed textures. 403 404Dependencies on KHR_texture_compression_astc_{ldr,hdr} 405 406 If none of the KHR_texture_compression_astc extensions are supported, 407 ignore all references to ASTC compressed textures. 408 409Issues 410 411 (1) Which is the correct equation to use for converting 412 TEXTURE_BORDER_COLOR_OES when specified via SamplerParameteriv 413 or TexParameteriv? 414 415 RESOLVED: Early versions of GL 4.4 referenced both equations 2.1 and 2.2. 416 As per clarification in Bug 11185, the correct answer is equation 2.2. 417 418 (2) Does SamplerParmeter{if} set an error if called with 419 a non-scalar parameter? 420 421 RESOLVED: Yes. This should be analogous to TexParameteriv. 422 This error seems to be missing from GL 4.4. Filed bug 11186 423 to get this rectified. 424 425 (3) Should the second argument to GetTexParameterI* be <value> or <pname>? 426 427 RESOLVED: the GL specs call it <value>, but the headers call it <pname>. 428 The GetSamplerParameterI* version calls it <pname>, so we are doing the 429 same here for consistency. This was corrected in OpenGL ES 3.1. 430 431Revision History 432 433 Rev. Date Author Changes 434 ---- -------- --------- ------------------------------------------------- 435 1 06/18/2014 dkoch Initial OES version based on EXT. 436 No functional changes. 437