Name ARB_shader_texture_lod Name Strings GL_ARB_shader_texture_lod Contributors Bill Licea-Kane Evan Hart and contributors to the arb-gl2 working groups, the product of which provided the basis for this spec. Contact Bill Licea-Kane, ATI Research (bill 'at' ati.com) Notice Copyright (c) 2009-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 IP Status No known IP issues. Status Complete. Approved by the ARB on May 13, 2009. Version Last Modified Date: April 13, 2011 Revision: 11 Number ARB Extension #60 Dependencies This extension is written against the OpenGL 2.0 Specification. This extension is written against The OpenGL Shading Language, Language Version 1.10, Document Revision 59. ARB_shader_objects is required. This extension interacts with ATI_shader_texture_lod. This extension interacts with ARB_texture_rectangle. This extension interacts with EXT_texture_filter_anisotropic. Overview This extension adds additional texture functions to the OpenGL Shading Language which provide the shader writer with explicit control of LOD. Mipmap texture fetches and anisotropic texture fetches require an implicit derivatives to calculate rho, lambda and/or the line of anisotropy. These implicit derivatives will be undefined for texture fetches occurring inside non-uniform control flow or for vertex shader texture fetches, resulting in undefined texels. The additional texture functions introduced with this extension provide explict control of LOD (isotropic texture functions) or provide explicit derivatives (anisotropic texture functions). Anisotropic texture functions return defined texels for mipmap texture fetches or anisotropic texture fetches, even inside non-uniform control flow. Isotropic texture functions return defined texels for mipmap texture fetches, even inside non-uniform control flow. However, isotropic texture functions return undefined texels for anisotropic texture fetches. The existing isotropic vertex texture functions: texture1DLod, texture1DProjLod, texture2DLod, texture2DProjLod, texture3DLod, texture3DProjLod, textureCubeLod, shadow1DLod, shadow1DProjLod, shadow2DLod, shadow2DProjLod, are added to the built-in functions for fragment shaders. New anisotropic texture functions, providing explicit derivatives: texture1DGradARB( sampler1D sampler, float P, float dPdx, float dPdy ); texture1DProjGradARB( sampler1D sampler, vec2 P, float dPdx, float dPdy ); texture1DProjGradARB( sampler1D sampler, vec4 P, float dPdx, float dPdy ); texture2DGradARB( sampler2D sampler, vec2 P, vec2 dPdx, vec2 dPdy ); texture2DProjGradARB( sampler2D sampler, vec3 P, vec2 dPdx, vec2 dPdy ); texture2DProjGradARB( sampler2D sampler, vec4 P, vec2 dPdx, vec2 dPdy ); texture3DGradARB( sampler3D sampler, vec3 P, vec3 dPdx, vec3 dPdy ); texture3DProjGradARB( sampler3D sampler, vec4 P, vec3 dPdx, vec3 dPdy ); textureCubeGradARB( samplerCube sampler, vec3 P, vec3 dPdx, vec3 dPdy ); shadow1DGradARB( sampler1DShadow sampler, vec3 P, float dPdx, float dPdy ); shadow1DProjGradARB( sampler1DShadow sampler, vec4 P, float dPdx, float dPdy ); shadow2DGradARB( sampler2DShadow sampler, vec3 P, vec2 dPdx, vec2 dPdy ); shadow2DProjGradARB( sampler2DShadow sampler, vec4 P, vec2 dPdx, vec2 dPdy ); texture2DRectGradARB( sampler2DRect sampler, vec2 P, vec2 dPdx, vec2 dPdy ); texture2DRectProjGradARB( sampler2DRect sampler, vec3 P, vec2 dPdx, vec2 dPdy ); texture2DRectProjGradARB( sampler2DRect sampler, vec4 P, vec2 dPdx, vec2 dPdy ); shadow2DRectGradARB( sampler2DRectShadow sampler, vec3 P, vec2 dPdx, vec2 dPdy ); shadow2DRectProjGradARB( sampler2DRectShadow sampler, vec4 P, vec2 dPdx, vec2 dPdy ); are added to the built-in functions for vertex shaders and fragment shaders. New Procedures and Functions None New Tokens None Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) None Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) In Section 3.8.8, replace the final paragraph on p. 171 with: "Let s(x, y) be the function that associates an s texture coordinate with each set of window coordinates (x, y) that lie within a primitive; define t(x, y) and r(x, y) analogously. For a one-dimensional texture, define t(x, y) = 0 and r(x, y) = 0; for a two-dimensional texture, define r(x, y) = 0. Let u(x, y) = wt * s(x, y), v(x, y) = ht * t(x, y), and w(x, y) = dt * r(x, y), where wt, ht, and dt are as defined by equations 3.15, 3.16, and 3.17 with ws, hs, and ds equal to the width, height, and depth of the image array whose level is levelbase. However, for rectangular textures let u(x, y) = s(x, y), v(x, y) = t(x, y), and w(x, y) = r(x, y)." Let dUdx = wt*dSdx; dUdy = wt*dSdy; dVdx = ht*dTdx; dVdy = ht*dTdy; dWdx = dt*dRdx; dWdy = dt*dRdx; (3.21a) where dSdx indicates the derivative of s with respect to window x, and similarly for the other derivatives, and For a rectangular texture, let dUdx = dSdx; dUdy = dSdy; dVdx = dTdx; dVdy = dTdy; dWdx = 0.0; (3.21b) For a polygon, rho is given at a fragment with window coordinates (x, y) by rho = max ( sqrt(dUdx*dUdx + dVdx*dVdx + dWdx*dWdx), sqrt(dUdy*dUdy + dVdy*dVdy + dWdy*dWdy) ); (3.21c)" Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment Operations and the Frame Buffer) None Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) None Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State Requests) None Additions to Appendix A of the OpenGL 2.0 Specification (Invariance) None Additions to the AGL/GLX/WGL Specifications None Additions to version 1.10.59 of the OpenGL Shading Language Specification "A new preprocessor #define is added to the OpenGL Shading Language: #define GL_ARB_shader_texture_lod 1 Including the following line in a shader can be used to control the language features described in this extension: #extension GL_ARB_shader_texture_lod : Where is as specified in section 3.3." Additions to Chapter 8 of version 1.10.59 of the OpenGL Shading Language Specification 8.7 Texture Lookup Functions Delete the last paragraph, and replace with: "For the "Lod" functions, lod specifies lambda_base (see equation 3.18 in The OpenGL 2.0 Specification) and specifies dSdx, dTdx, dRdx = 0 and dSdy, dTdy, and dRdy = 0 (see equation 3.21a and 3.21b. in The OpenGL 2.0 Specification). The "Lod" functions are allowed in a vertex shader. If enabled by the preprocessor directive #extension, the "Lod" functions are also allowed in a fragment shader. For the "Grad" functions, dPdx is the explicit derivative of P with respect to window x, and similarly dPdy with respect to window y. For the “ProjGrad” functions, dPdx is the explicit derivative of the projected P with respect to window x, and similarly for dPdy with respect to window y. For a one-dimensional texture, dPdx and dPdy are float. For a two-dimensional texture, dPdx and dPdy are vec2. Otherwise, dPdx and dPdy are vec3. Let dSdx = dPdx.s; dSdy = dPdy.s; and / 0.0; for one-dimensional texture dTdx = ( \ dPdx.t; otherwise / 0.0; for one-dimensional texture dTdy = ( \ dPdy.t; otherwise and / 0.0; for one-dimenstional or two-dimensional texture dRdx = ( (including rectangular texture) \ dPdx.p; otherwise (including cubemap texture) / 0.0; for one dimensional or two-dimensional texture dRdy = ( (including rectangular texture) \ dPdy.p; otherwise (including cubemap texture) (See equation 3.21a and 3.21b in The OpenGL 2.0 Specification). If enabled by the preprocessor directive #extension, the "Grad" functions are allowed in vertex and fragment shaders. All other texture functions may require implicit derivatives. Implicit derivatives are undefined within non-uniform control flow or for vertex shader texture fetches." Add the following entries to the texture function table: texture1DGradARB( sampler1D sampler, float P, float dPdx, float dPdy ); texture1DProjGradARB( sampler1D sampler, vec2 P, float dPdx, float dPdy ); texture1DProjGradARB( sampler1D sampler, vec4 P, float dPdx, float dPdy ); texture2DGradARB( sampler2D sampler, vec2 P, vec2 dPdx, vec2 dPdy ); texture2DProjGradARB( sampler2D sampler, vec3 P, vec2 dPdx, vec2 dPdy ); texture2DProjGradARB( sampler2D sampler, vec4 P, vec2 dPdx, vec2 dPdy ); texture3DGradARB( sampler3D sampler, vec3 P, vec3 dPdx, vec3 dPdy ); texture3DProjGradARB( sampler3D sampler, vec4 P, vec3 dPdx, vec3 dPdy ); textureCubeGradARB( samplerCube sampler, vec3 P, vec3 dPdx, vec3 dPdy ); shadow1DGradARB( sampler1DShadow sampler, vec3 P, float dPdx, float dPdy ); shadow1DProjGradARB( sampler1DShadow sampler, vec4 P, float dPdx, float dPdy ); shadow2DGradARB( sampler2DShadow sampler, vec3 P, vec2 dPdx, vec2 dPdy ); shadow2DProjGradARB( sampler2DShadow sampler, vec4 P, vec2 dPdx, vec2 dPdy ); texture2DRectGradARB( sampler2DRect sampler, vec2 P, vec2 dPdx, vec2 dPdy ); texture2DRectProjGradARB( sampler2DRect sampler, vec3 P, vec2 dPdx, vec2 dPdy ); texture2DRectProjGradARB( sampler2DRect sampler, vec4 P, vec2 dPdx, vec2 dPdy ); shadow2DRectGradARB( sampler2DRectShadow sampler, vec3 P, vec2 dPdx, vec2 dPdy ); shadow2DRectProjGradARB( sampler2DRectShadow sampler, vec4 P, vec2 dPdx, vec2 dPdy ); Interactions with ATI_texture_shader_lod Each texture function added to the texture function table by ATI_texture_shader_lod is suffixed with "_ATI". The equivalent texture functions added to the texture function table by this extension are suffixed with "GradARB". It is anticipated that this extension might get promoted to core. The promoted texture functions added to the texture function table would then be suffixed with "Grad". Note that ATI_texture_shader_lod does not contain the interactions with ARB_texture_rectangle and EXT_texture_anisotropic. Nor does it overload the texture2DRect and shadow2DRect functions. This extension is a slight superset of ATI_texture_shader_lod. Interactions with ARB_texture_rectangle If ARB_texture_rectangle is not supported, delete references to rectangular textures and references to equation 3.21b. Interactions with EXT_texture_anisotropic The Lod functions set the derivatives ds/dx, dt/dx, dr/dx, dx/dy, dt/dy, and dr/dy = 0. Therefore Rhox and Rhoy = 0 0, Rhomax and Rhomin = 0. Issues (1) What should this extension be called? RESOLVED: ARB_shader_texture_lod (2) There are several existing built-in functions we could use. Should we use them, and do we need to name decorate them with suffix _ARB? It makes sense to use the existing built-ins suffixed with "Lod." We will simply drop the restriction that they are allowed only in the vertex shader. Since this extension simply extends the scope of the functions, I don't think we need to suffix with _ARB. RESOLVED: Yes, use existing "Lod" built-in names without an _ARB suffix. (3) Should we add additional texture functions with derivative built-ins? There are two approaches. Existing texture functions could be overloaded to accept optional derivatives. (Similar to the Lod bias texture functions.) These names *should* probably be name decorated with the suffix ARB." New texture functions suffixed with GradARB could be added. The advantage of overloading the existing functions is it reduces the plethora of texture function names. The disadvantage of overloading the existing functions is that not all of the existing texture functions make sense with explicit derivatives. (Example, projective texture fetch with explict derivatives.) We have two sets of precedent here. The existing absolute LOD texture functions use explicit name decoration. The existing LOD bias texture functions use overloading. RESOLVED: We will use existing built-in texture functions suffixed with "Lod" *WITHOUT* name decoration for absolute LOD functions. We will use existing built-in texture functions suffixed with GradARB for derivatives. We establish a precedent that new texture functions will have explicit names. The existing LOD bias texture functions are exceptions to the precedent. (4) What is done with the vec3 dPdx and vec3 dPdy for cube map texture fetches? For cube maps, it is incorrect to simply say "dPdx specificies ds/dx, dt/dx, and dr/dx, and dPdy specifies ds/dy, dt/dy and dr/dy (see equation 3.21a in The OpenGL 2.0 Specification)." This is currently tough to specify given the core specification. 3.8.6 covers cube map face selection and transformation of the incoming rx, ry, rz to s and t. 3.8.8 covers derivatives, and states: "Let s(x, y) be the function that associates an s texture coordinate with each set of window coordinates (x, y) that lie within a primitive; define t(x, y) and r(x, y) analogously." Because of the cube mape face selection of 3.8.6, s(x, y) and t(x, y) may be discontinuous within a primitive. A discontinuous function has undefined derivatives at the discontinuity. (This discontinuity occurs at the cube map edges.) The core spec is silent on how this discontinuity may be resolved. Nor does the core spec provide an alternative method for calculating rho given the continuous original rx, ry, rz, and their well specified derivatives (dPdx and dPdy). The changes required to the core spec are substantial and may require much discussion on the tradeoffs between tightly specifying a method and providing sufficient freedom for implementers. RESOLVED: For now, we will leave this as unspecified. Implementors are cautioned to take sufficient steps so that the calculation of rho based on explicit dPdx and dPdy provides comparable quality to the existing implicit derivative methods. (5) Should the projective versions of the anisotropic texture functions be added? ATI_shader_texture_lod resolved issue 3 to use overloaded functions (opposite of the way issue 3 is resolved here), including overloading the projective texture functions. We have insufficient feedback to permit removing them in this extension. We err on the side of caution and keep them. This extension is therefore a functional equivalent to ATI_shader_texture_lod. (Slight superset, see issue 6.) RESOLVED: Add them since ATI_shader_texture_lod introduced overloaded versions. (6) Should anisotropic rectangular texture functions be added? Even though derivatives are not required for Lod selection for rectangular textures (there is only the baselevel for rectangular textures) the derivatives are required for anisotropic texture fetches. (Perhaps ARB_texture_rectangle should have an interaction with EXT_texture_anisotropic clarifying this.) ATI_shader_texture_lod is silent on these interactions. Adding the interactions and functions makes this extension a slight superset of ATI_shader_texture_lod. RESOLVED: Add them. (7) How are ProjGrad functions handled? The dPdx and dPdy derivatives are of the projected P. The shader writer is responsible for this projection. That is, for a 2D texture, dPdx = dFdx( P.st/P.q ); dPdy = dFdy( P.st/P.q ); Revision History: 10 - 2011-04-13 (Jon Leech) * Remove nonexistent textureCubProjLod from list of existing isotropic vertex texture functions (Khronos Bug 7205). 9 - 2010-12-09 (Jon Leech) * Corrected typos where 1D texture functions were specified as taking sampler2D parameters (Khronos Bug 7008). 8 - 2009-05-24 (Jon Leech) * Added to the Registry * Corrected minor typos 7 - 2007-08-22 * Shipping status. 6 - 2006-07-06 * Clarified ProjGrad. * Added issue 7. * Clarified cubemap. 5 - 2006-06-08 * u(x,y),v(x,y) and w(x,y) are used for wrap calculations. Their definitions (with ARB_texture_rectangle interaction) are restored. * Clean up defined/undefined language of functions in overview. 4 - 2006-05-25 * Follow ASCII conventions. See examples in core spec equations 3.23, 3.24, & 3.25 and EXT_texture_3D. 3 - 2006-05-25 * Add #extension and #define * Explicitly reference page/paragraph in core edits. * Rework texture function descriptions. Add language to shading language spec that makes it clear that the extension must be enabled for the functions to be available. 2 - 2006-05-25 * Name changes. * Added interaction with ARB_texture_rectangle. * Added interaction with EXT_texture_anisotropic. * Clarified that implicit derivatives are undefined within non-uniform control flow and the vertex shader. * Relocated issues to the tail of the spec. 1 - 2006-05-17 Initial ARB version