skia / external / github.com / KhronosGroup / OpenGL-Registry / bc93187978b46e0baae0b8556071d6b292b0bb97 / . / extensions / ARB / ARB_shader_texture_lod.txt

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 : <behavior> | |

Where <behavior> 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 |