1Name 2 3 ARB_shader_texture_lod 4 5Name Strings 6 7 GL_ARB_shader_texture_lod 8 9Contributors 10 11 Bill Licea-Kane 12 Evan Hart 13 14 and contributors to the arb-gl2 working groups, the product 15 of which provided the basis for this spec. 16 17Contact 18 19 Bill Licea-Kane, ATI Research (bill 'at' ati.com) 20 21Notice 22 23 Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at 24 http://www.khronos.org/registry/speccopyright.html 25 26Specification Update Policy 27 28 Khronos-approved extension specifications are updated in response to 29 issues and bugs prioritized by the Khronos OpenGL Working Group. For 30 extensions which have been promoted to a core Specification, fixes will 31 first appear in the latest version of that core Specification, and will 32 eventually be backported to the extension document. This policy is 33 described in more detail at 34 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 35 36IP Status 37 38 No known IP issues. 39 40Status 41 42 Complete. Approved by the ARB on May 13, 2009. 43 44Version 45 46 Last Modified Date: April 13, 2011 47 Revision: 11 48 49Number 50 51 ARB Extension #60 52 53Dependencies 54 55 This extension is written against the OpenGL 2.0 Specification. 56 57 This extension is written against The OpenGL Shading Language, 58 Language Version 1.10, Document Revision 59. 59 60 ARB_shader_objects is required. 61 62 This extension interacts with ATI_shader_texture_lod. 63 64 This extension interacts with ARB_texture_rectangle. 65 66 This extension interacts with EXT_texture_filter_anisotropic. 67 68Overview 69 70 This extension adds additional texture functions to the 71 OpenGL Shading Language which provide the shader writer 72 with explicit control of LOD. 73 74 Mipmap texture fetches and anisotropic texture fetches 75 require an implicit derivatives to calculate rho, lambda 76 and/or the line of anisotropy. These implicit derivatives 77 will be undefined for texture fetches occurring inside 78 non-uniform control flow or for vertex shader texture 79 fetches, resulting in undefined texels. 80 81 The additional texture functions introduced with 82 this extension provide explict control of LOD 83 (isotropic texture functions) or provide explicit 84 derivatives (anisotropic texture functions). 85 86 Anisotropic texture functions return defined texels 87 for mipmap texture fetches or anisotropic texture fetches, 88 even inside non-uniform control flow. Isotropic texture 89 functions return defined texels for mipmap texture fetches, 90 even inside non-uniform control flow. However, isotropic 91 texture functions return undefined texels for anisotropic 92 texture fetches. 93 94 The existing isotropic vertex texture functions: 95 96 texture1DLod, texture1DProjLod, 97 texture2DLod, texture2DProjLod, 98 texture3DLod, texture3DProjLod, 99 textureCubeLod, 100 shadow1DLod, shadow1DProjLod, 101 shadow2DLod, shadow2DProjLod, 102 103 are added to the built-in functions for fragment shaders. 104 105 New anisotropic texture functions, providing explicit 106 derivatives: 107 108 texture1DGradARB( sampler1D sampler, 109 float P, float dPdx, float dPdy ); 110 texture1DProjGradARB( sampler1D sampler, 111 vec2 P, float dPdx, float dPdy ); 112 texture1DProjGradARB( sampler1D sampler, 113 vec4 P, float dPdx, float dPdy ); 114 115 texture2DGradARB( sampler2D sampler, 116 vec2 P, vec2 dPdx, vec2 dPdy ); 117 texture2DProjGradARB( sampler2D sampler, 118 vec3 P, vec2 dPdx, vec2 dPdy ); 119 texture2DProjGradARB( sampler2D sampler, 120 vec4 P, vec2 dPdx, vec2 dPdy ); 121 122 texture3DGradARB( sampler3D sampler, 123 vec3 P, vec3 dPdx, vec3 dPdy ); 124 texture3DProjGradARB( sampler3D sampler, 125 vec4 P, vec3 dPdx, vec3 dPdy ); 126 127 textureCubeGradARB( samplerCube sampler, 128 vec3 P, vec3 dPdx, vec3 dPdy ); 129 130 shadow1DGradARB( sampler1DShadow sampler, 131 vec3 P, float dPdx, float dPdy ); 132 shadow1DProjGradARB( sampler1DShadow sampler, 133 vec4 P, float dPdx, float dPdy ); 134 135 shadow2DGradARB( sampler2DShadow sampler, 136 vec3 P, vec2 dPdx, vec2 dPdy ); 137 shadow2DProjGradARB( sampler2DShadow sampler, 138 vec4 P, vec2 dPdx, vec2 dPdy ); 139 140 141 texture2DRectGradARB( sampler2DRect sampler, 142 vec2 P, vec2 dPdx, vec2 dPdy ); 143 texture2DRectProjGradARB( sampler2DRect sampler, 144 vec3 P, vec2 dPdx, vec2 dPdy ); 145 texture2DRectProjGradARB( sampler2DRect sampler, 146 vec4 P, vec2 dPdx, vec2 dPdy ); 147 148 shadow2DRectGradARB( sampler2DRectShadow sampler, 149 vec3 P, vec2 dPdx, vec2 dPdy ); 150 shadow2DRectProjGradARB( sampler2DRectShadow sampler, 151 vec4 P, vec2 dPdx, vec2 dPdy ); 152 153 are added to the built-in functions for vertex shaders 154 and fragment shaders. 155 156New Procedures and Functions 157 158 None 159 160New Tokens 161 162 None 163 164Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 165 166 None 167 168Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 169 170 In Section 3.8.8, replace the final paragraph on p. 171 with: 171 172 "Let s(x, y) be the function that associates an s texture coordinate 173 with each set of window coordinates (x, y) that lie within a 174 primitive; define t(x, y) and r(x, y) analogously. For a 175 one-dimensional texture, define t(x, y) = 0 and r(x, y) = 0; for a 176 two-dimensional texture, define r(x, y) = 0. 177 178 Let u(x, y) = wt * s(x, y), v(x, y) = ht * t(x, y), and 179 w(x, y) = dt * r(x, y), where wt, ht, and dt are as defined by equations 180 3.15, 3.16, and 3.17 with ws, hs, and ds equal to the width, height, 181 and depth of the image array whose level is levelbase. However, for 182 rectangular textures let u(x, y) = s(x, y), v(x, y) = t(x, y), and 183 w(x, y) = r(x, y)." 184 185 Let 186 dUdx = wt*dSdx; dUdy = wt*dSdy; 187 dVdx = ht*dTdx; dVdy = ht*dTdy; 188 dWdx = dt*dRdx; dWdy = dt*dRdx; (3.21a) 189 190 where dSdx indicates the derivative of s with respect to window x, 191 and similarly for the other derivatives, and 192 193 For a rectangular texture, let 194 dUdx = dSdx; dUdy = dSdy; 195 dVdx = dTdx; dVdy = dTdy; 196 dWdx = 0.0; (3.21b) 197 198 For a polygon, rho is given at a fragment with window coordinates 199 (x, y) by 200 201 rho = max ( 202 sqrt(dUdx*dUdx + dVdx*dVdx + dWdx*dWdx), 203 sqrt(dUdy*dUdy + dVdy*dVdy + dWdy*dWdy) 204 ); (3.21c)" 205 206 207 208Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment Operations 209and the Frame Buffer) 210 211 None 212 213Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 214 215 None 216 217Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State 218Requests) 219 220 None 221 222Additions to Appendix A of the OpenGL 2.0 Specification (Invariance) 223 224 None 225 226Additions to the AGL/GLX/WGL Specifications 227 228 None 229 230 231Additions to version 1.10.59 of the OpenGL Shading Language Specification 232 233 "A new preprocessor #define is added to the OpenGL Shading Language: 234 235 #define GL_ARB_shader_texture_lod 1 236 237 Including the following line in a shader can be used to control the 238 language features described in this extension: 239 240 #extension GL_ARB_shader_texture_lod : <behavior> 241 242 Where <behavior> is as specified in section 3.3." 243 244 245Additions to Chapter 8 of version 1.10.59 of the OpenGL Shading Language 246Specification 247 248 249 8.7 Texture Lookup Functions 250 251 Delete the last paragraph, and replace with: 252 253 "For the "Lod" functions, lod specifies lambda_base (see equation 3.18 in 254 The OpenGL 2.0 Specification) and specifies dSdx, dTdx, dRdx = 0 and 255 dSdy, dTdy, and dRdy = 0 (see equation 3.21a and 3.21b. in The OpenGL 256 2.0 Specification). The "Lod" functions are allowed in a vertex shader. 257 If enabled by the preprocessor directive #extension, the "Lod" functions 258 are also allowed in a fragment shader. 259 260 For the "Grad" functions, dPdx is the explicit derivative of P with respect 261 to window x, and similarly dPdy with respect to window y. For the “ProjGrad” 262 functions, dPdx is the explicit derivative of the projected P with respect 263 to window x, and similarly for dPdy with respect to window y. For a 264 one-dimensional texture, dPdx and dPdy are float. For a two-dimensional 265 texture, dPdx and dPdy are vec2. Otherwise, dPdx and dPdy are vec3. 266 267 268 269 Let 270 271 dSdx = dPdx.s; 272 dSdy = dPdy.s; 273 274 and 275 276 / 0.0; for one-dimensional texture 277 dTdx = ( 278 \ dPdx.t; otherwise 279 280 / 0.0; for one-dimensional texture 281 dTdy = ( 282 \ dPdy.t; otherwise 283 284 and 285 / 0.0; for one-dimenstional or two-dimensional texture 286 dRdx = ( (including rectangular texture) 287 \ dPdx.p; otherwise 288 (including cubemap texture) 289 290 / 0.0; for one dimensional or two-dimensional texture 291 dRdy = ( (including rectangular texture) 292 \ dPdy.p; otherwise 293 (including cubemap texture) 294 295 (See equation 3.21a and 3.21b in The OpenGL 2.0 Specification). 296 297 If enabled by the preprocessor directive #extension, the "Grad" functions 298 are allowed in vertex and fragment shaders. 299 300 All other texture functions may require implicit derivatives. Implicit 301 derivatives are undefined within non-uniform control flow or for vertex 302 shader texture fetches." 303 304 Add the following entries to the texture function table: 305 306 texture1DGradARB( sampler1D sampler, 307 float P, float dPdx, float dPdy ); 308 texture1DProjGradARB( sampler1D sampler, 309 vec2 P, float dPdx, float dPdy ); 310 texture1DProjGradARB( sampler1D sampler, 311 vec4 P, float dPdx, float dPdy ); 312 313 texture2DGradARB( sampler2D sampler, 314 vec2 P, vec2 dPdx, vec2 dPdy ); 315 texture2DProjGradARB( sampler2D sampler, 316 vec3 P, vec2 dPdx, vec2 dPdy ); 317 texture2DProjGradARB( sampler2D sampler, 318 vec4 P, vec2 dPdx, vec2 dPdy ); 319 320 texture3DGradARB( sampler3D sampler, 321 vec3 P, vec3 dPdx, vec3 dPdy ); 322 texture3DProjGradARB( sampler3D sampler, 323 vec4 P, vec3 dPdx, vec3 dPdy ); 324 325 textureCubeGradARB( samplerCube sampler, 326 vec3 P, vec3 dPdx, vec3 dPdy ); 327 328 shadow1DGradARB( sampler1DShadow sampler, 329 vec3 P, float dPdx, float dPdy ); 330 shadow1DProjGradARB( sampler1DShadow sampler, 331 vec4 P, float dPdx, float dPdy ); 332 333 shadow2DGradARB( sampler2DShadow sampler, 334 vec3 P, vec2 dPdx, vec2 dPdy ); 335 shadow2DProjGradARB( sampler2DShadow sampler, 336 vec4 P, vec2 dPdx, vec2 dPdy ); 337 338 339 texture2DRectGradARB( sampler2DRect sampler, 340 vec2 P, vec2 dPdx, vec2 dPdy ); 341 texture2DRectProjGradARB( sampler2DRect sampler, 342 vec3 P, vec2 dPdx, vec2 dPdy ); 343 texture2DRectProjGradARB( sampler2DRect sampler, 344 vec4 P, vec2 dPdx, vec2 dPdy ); 345 346 shadow2DRectGradARB( sampler2DRectShadow sampler, 347 vec3 P, vec2 dPdx, vec2 dPdy ); 348 shadow2DRectProjGradARB( sampler2DRectShadow sampler, 349 vec4 P, vec2 dPdx, vec2 dPdy ); 350 351 352Interactions with ATI_texture_shader_lod 353 354 Each texture function added to the texture function table 355 by ATI_texture_shader_lod is suffixed with "_ATI". 356 357 The equivalent texture functions added to the texture 358 function table by this extension are suffixed with "GradARB". 359 360 It is anticipated that this extension might get promoted 361 to core. The promoted texture functions added to the 362 texture function table would then be suffixed with "Grad". 363 364 Note that ATI_texture_shader_lod does not contain the 365 interactions with ARB_texture_rectangle and EXT_texture_anisotropic. 366 Nor does it overload the texture2DRect and shadow2DRect functions. 367 This extension is a slight superset of ATI_texture_shader_lod. 368 369Interactions with ARB_texture_rectangle 370 371 If ARB_texture_rectangle is not supported, delete references 372 to rectangular textures and references to equation 3.21b. 373 374Interactions with EXT_texture_anisotropic 375 376 The Lod functions set the derivatives ds/dx, dt/dx, dr/dx, 377 dx/dy, dt/dy, and dr/dy = 0. Therefore Rhox and Rhoy = 0 378 0, Rhomax and Rhomin = 0. 379 380Issues 381 382 (1) What should this extension be called? 383 384 RESOLVED: ARB_shader_texture_lod 385 386 (2) There are several existing built-in functions we 387 could use. Should we use them, and do we need to 388 name decorate them with suffix _ARB? 389 390 It makes sense to use the existing built-ins suffixed 391 with "Lod." We will simply drop the restriction that 392 they are allowed only in the vertex shader. 393 394 Since this extension simply extends the scope of 395 the functions, I don't think we need to suffix with _ARB. 396 397 RESOLVED: Yes, use existing "Lod" built-in names without 398 an _ARB suffix. 399 400 401 (3) Should we add additional texture functions with derivative 402 built-ins? 403 404 There are two approaches. 405 406 Existing texture functions could be overloaded to 407 accept optional derivatives. (Similar to the Lod bias 408 texture functions.) These names *should* probably 409 be name decorated with the suffix ARB." 410 411 New texture functions suffixed with GradARB 412 could be added. 413 414 The advantage of overloading the existing functions 415 is it reduces the plethora of texture function names. 416 417 The disadvantage of overloading the existing functions 418 is that not all of the existing texture functions 419 make sense with explicit derivatives. (Example, 420 projective texture fetch with explict derivatives.) 421 422 We have two sets of precedent here. The existing absolute 423 LOD texture functions use explicit name decoration. 424 The existing LOD bias texture functions use overloading. 425 426 RESOLVED: We will use existing built-in texture functions 427 suffixed with "Lod" *WITHOUT* name decoration for absolute 428 LOD functions. 429 430 We will use existing built-in texture functions suffixed with 431 GradARB for derivatives. 432 433 We establish a precedent that new texture functions 434 will have explicit names. The existing LOD bias texture 435 functions are exceptions to the precedent. 436 437 (4) What is done with the vec3 dPdx and vec3 dPdy for 438 cube map texture fetches? 439 440 For cube maps, it is incorrect to simply say "dPdx 441 specificies ds/dx, dt/dx, and dr/dx, and dPdy specifies 442 ds/dy, dt/dy and dr/dy (see equation 3.21a in The 443 OpenGL 2.0 Specification)." 444 445 This is currently tough to specify given the core specification. 446 447 3.8.6 covers cube map face selection and transformation of 448 the incoming rx, ry, rz to s and t. 449 450 3.8.8 covers derivatives, and states: 451 452 "Let s(x, y) be the function that associates an s texture 453 coordinate with each set of window coordinates (x, y) that 454 lie within a primitive; define t(x, y) and r(x, y) analogously." 455 456 Because of the cube mape face selection of 3.8.6, s(x, y) 457 and t(x, y) may be discontinuous within a primitive. A discontinuous 458 function has undefined derivatives at the discontinuity. (This 459 discontinuity occurs at the cube map edges.) 460 461 The core spec is silent on how this discontinuity may be resolved. 462 Nor does the core spec provide an alternative method for calculating 463 rho given the continuous original rx, ry, rz, and their well 464 specified derivatives (dPdx and dPdy). 465 466 The changes required to the core spec are substantial and may 467 require much discussion on the tradeoffs between tightly 468 specifying a method and providing sufficient freedom for implementers. 469 470 RESOLVED: For now, we will leave this as unspecified. 471 Implementors are cautioned to take sufficient steps so 472 that the calculation of rho based on explicit dPdx 473 and dPdy provides comparable quality to the existing 474 implicit derivative methods. 475 476 (5) Should the projective versions of the anisotropic texture 477 functions be added? 478 479 ATI_shader_texture_lod resolved issue 3 to use overloaded 480 functions (opposite of the way issue 3 is resolved here), 481 including overloading the projective texture functions. 482 We have insufficient feedback to permit removing them in this 483 extension. We err on the side of caution and keep them. 484 This extension is therefore a functional equivalent to 485 ATI_shader_texture_lod. (Slight superset, see issue 6.) 486 487 RESOLVED: Add them since ATI_shader_texture_lod introduced 488 overloaded versions. 489 490 (6) Should anisotropic rectangular texture functions be added? 491 492 Even though derivatives are not required for Lod selection 493 for rectangular textures (there is only the baselevel for 494 rectangular textures) the derivatives are required for 495 anisotropic texture fetches. (Perhaps 496 ARB_texture_rectangle should have an interaction with 497 EXT_texture_anisotropic clarifying this.) 498 499 ATI_shader_texture_lod is silent on these interactions. 500 Adding the interactions and functions makes this extension 501 a slight superset of ATI_shader_texture_lod. 502 503 RESOLVED: Add them. 504 505 (7) How are ProjGrad functions handled? 506 507 The dPdx and dPdy derivatives are of the projected P. The shader 508 writer is responsible for this projection. That is, for a 2D 509 texture, dPdx = dFdx( P.st/P.q ); dPdy = dFdy( P.st/P.q ); 510 511Revision History: 512 51310 - 2011-04-13 (Jon Leech) 514 * Remove nonexistent textureCubProjLod from list of existing 515 isotropic vertex texture functions (Khronos Bug 7205). 516 5179 - 2010-12-09 (Jon Leech) 518 * Corrected typos where 1D texture functions were specified 519 as taking sampler2D parameters (Khronos Bug 7008). 520 5218 - 2009-05-24 (Jon Leech) 522 * Added to the Registry 523 * Corrected minor typos 524 5257 - 2007-08-22 526 * Shipping status. 527 5286 - 2006-07-06 529 * Clarified ProjGrad. 530 * Added issue 7. 531 * Clarified cubemap. 532 5335 - 2006-06-08 534 * u(x,y),v(x,y) and w(x,y) are used for wrap calculations. 535 Their definitions (with ARB_texture_rectangle interaction) 536 are restored. 537 * Clean up defined/undefined language of functions in 538 overview. 539 5404 - 2006-05-25 541 * Follow ASCII conventions. See examples in core 542 spec equations 3.23, 3.24, & 3.25 and EXT_texture_3D. 543 5443 - 2006-05-25 545 * Add #extension and #define 546 * Explicitly reference page/paragraph in core edits. 547 * Rework texture function descriptions. Add language 548 to shading language spec that makes it clear that the 549 extension must be enabled for the functions to be 550 available. 551 5522 - 2006-05-25 553 * Name changes. 554 * Added interaction with ARB_texture_rectangle. 555 * Added interaction with EXT_texture_anisotropic. 556 * Clarified that implicit derivatives are undefined 557 within non-uniform control flow and the vertex shader. 558 * Relocated issues to the tail of the spec. 559 5601 - 2006-05-17 561 Initial ARB version 562