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