1Name
2
3    ARB_texture_query_lod
4
5Name Strings
6
7    GL_ARB_texture_query_lod
8
9Contact
10
11    Eric Werness, NVIDIA Corporation (ewerness 'at' nvidia.com)
12    Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com)
13
14Contributors
15
16    Pat Brown, NVIDIA
17    Greg Roth, NVIDIA
18    Eric Werness, NVIDIA
19    Alejandro Piñeiro, Igalia, SL
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
36Status
37
38    Complete. Approved by the ARB on July 3, 2009.
39
40Version
41
42    Last Modified Date:         04/22/2020
43    Revision:                   8
44
45Number
46
47    ARB Extension #73
48
49Dependencies
50
51    OpenGL 3.0 is required.
52
53    OpenGL Shading Language 1.30 is required
54
55    EXT_gpu_shader4 is required.
56
57    EXT_texture_array is required.
58
59    This extension interacts trivially with ARB_texture_cube_map_array
60
61    This extension is written against the OpenGL 2.0 specification and
62    version 1.30 of the OpenGL Shading Language Specification.
63
64Overview
65
66    This extension provides a new set of fragment shader texture
67    functions (textureLOD) that return the results of automatic
68    level-of-detail computations that would be performed if a texture
69    lookup were performed.
70
71New Procedures and Functions
72
73    None.
74
75New Tokens
76
77    None.
78
79Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation)
80
81    None.
82
83Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization)
84
85    None.
86
87Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment
88Operations and the Frame Buffer)
89
90    None.
91
92Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions)
93
94    None.
95
96Additions to Chapter 6 of the OpenGL 2.0 Specification (State and
97State Requests)
98
99    None.
100
101Additions to the AGL/GLX/WGL Specifications
102
103    None
104
105GLX Protocol
106
107    TBD
108
109Errors
110
111    None.
112
113New State
114
115    None.
116
117New Implementation Dependent State
118
119    None.
120
121Modifications to The OpenGL Shading Language Specification, Version 1.10.59
122
123    Including the following line in a shader can be used to control the
124    language features described in this extension:
125
126      #extension GL_ARB_texture_query_lod
127
128    A new preprocessor #define is added to the OpenGL Shading Language:
129
130      #define GL_ARB_texture_query_lod 1
131
132    Add to section 8.7 "Texture Lookup Functions"
133
134    Syntax:
135
136      vec2 textureQueryLOD(gsampler1D sampler, float coord)
137      vec2 textureQueryLOD(gsampler2D sampler, vec2 coord)
138      vec2 textureQueryLOD(gsampler3D sampler, vec3 coord)
139      vec2 textureQueryLOD(gsamplerCube sampler, vec3 coord)
140      vec2 textureQueryLOD(gsampler1DArray sampler, float coord)
141      vec2 textureQueryLOD(gsampler2DArray sampler, vec2 coord)
142      vec2 textureQueryLOD(gsamplerCubeArray sampler, vec3 coord)
143      vec2 textureQueryLOD(sampler1DShadow sampler, float coord)
144      vec2 textureQueryLOD(sampler2DShadow sampler, vec2 coord)
145      vec2 textureQueryLOD(samplerCubeShadow sampler, vec3 coord)
146      vec2 textureQueryLOD(sampler1DArrayShadow sampler, float coord)
147      vec2 textureQueryLOD(sampler2DArrayShadow sampler, vec2 coord)
148      vec2 textureQueryLOD(samplerCubeArrayShadow sampler, vec3 coord)
149
150    Description:
151
152      The textureQueryLOD function takes the components of <coord> and
153      computes the LOD information that the texture pipe would use to
154      make an access of that texture. The computed level of detail
155      lambda_prime (equation 3.19), relative to the base level, is
156      returned in the y component of the result vector. The level of
157      detail is obtained after any LOD bias, but prior to clamping to
158      [TEXTURE_MIN_LOD, TEXTURE_MAX_LOD]. The x component of the result
159      vector contains information on the mipmap array(s) that would be
160      accessed by a normal texture lookup using the same coordinates. If
161      a single level of detail would be accessed, the level-of-detail
162      number relative to the base level is returned. If multiple levels
163      of detail are accessed, a floating-point number between the two
164      levels is returned, with the fractional part equal to the
165      fractional part of the computed and clamped level of detail. The
166      algorithm used is given by the following pseudo-code:
167
168      float ComputeAccessedLod(float computedLod)
169      {
170        // Clamp the computed LOD according to the texture LOD clamps.
171        if (computedLod < TEXTURE_MIN_LOD) computedLod = TEXTURE_MIN_LOD;
172        if (computedLod > TEXTURE_MAX_LOD) computedLod = TEXTURE_MAX_LOD;
173
174        // Clamp the computed LOD to the range of accessible levels.
175        if (computedLod < 0)
176            computedLod = 0.0;
177        if (computedLod > (float)
178            maxAccessibleLevel) computedLod = (float) maxAccessibleLevel;
179
180        // Return a value according to the min filter.
181        if (TEXTURE_MIN_FILTER is LINEAR or NEAREST) {
182          return 0.0;
183        } else if (TEXTURE_MIN_FILTER is NEAREST_MIPMAP_NEAREST
184                   or LINEAR_MIPMAP_NEAREST) {
185          return ceil(computedLod + 0.5) - 1.0;
186        } else {
187          return computedLod;
188        }
189      }
190
191      The value <maxAccessibleLevel> is the level number of the smallest
192      accessible level of the mipmap array (the value q in section
193      3.8.8) minus the base level.
194
195      The returned value is then:
196
197        vec2(ComputeAccessedLod(lambda_prime), lambda_prime);
198
199      If textureQueryLOD is called on an incomplete texture, the results
200      are undefined. textureQueryLOD is only available fragment shaders.
201
202Dependencies on ARB_texture_cube_map_array
203
204      If ARB_texture_cube_map_array is not supported, remove the
205      textureQueryLOD lookup functions taking cube map array samplers.
206
207Issues
208
209    (1) Should we provide texture LOD functions for shadow sampler
210        targets?
211
212      RESOLVED: Yes. The level of detail computations for a texture used
213      as a shadow map are completely identical to that for other
214      textures.
215
216      However, we provide separate data types for the two textures
217      (e.g., sampler2D vs. sampler2DShadow), and there is no mechanism
218      to cast from one to the other. If we didn't provide these
219      functions, the only way to perform an LOD computation for a
220      texture used as a shadow map would be to bind the same texture
221      object to two different texture image units, one associated with a
222      shadow sampler and the other associated with a normal sampler.
223
224      Unlike regular shadow texture lookups, the reference depth value
225      is not used for LOD calculations and is not accepted by the
226      corresponding textureQueryLOD() built-infunctions.
227
228    (2) Should LOD queries for array textures take a layer?
229
230      RESOLVED: No. The layer number has no effect on the LOD
231      calcuations, so can be safely ignored. As a result, LOD queries
232      for sampler1DArray, sampler2DArray, and samplerCubeArray samplers
233      take one, two, and three coordinates, respectively.
234
235    (3) The core specification uses the "Lod" spelling, not "LOD". Should
236        this extension be modified to use "Lod"?
237
238      RESOLVED: The "Lod" spelling is the correct spelling for the core
239      specification and the preferred spelling for use. However, use of
240      "LOD" also exists, as the extension predated the core specification,
241      so this extension won't remove use of "LOD".
242
243Revision History
244
245    Rev.    Date      Author    Changes
246    ----  ----------  --------  -----------------------------------------
247    8     04/22/2020  apinheiro Update OpenGL version required, to be
248                                consistent with GLSL version required (internal API
249                                issue 124)
250
251    7     04/10/2013  Jon Leech Add issue 3 regarding different spelling
252                                of "LOD" vs. "Lod" in extension & core.
253
254    6     08/02/2009  Jon Leech Reformat to 80 columns and assign ARB
255                                extension number.
256
257    5     07/14/2009  istewart  Fixed preprocessor define and pseudocode for
258                                ComputeAccessedLod.
259
260    4     06/26/2009  pbrown    Change prototype for textureQueryLOD for
261                                1D and 2D arrays to not take a layer.
262                                Cube map arrays already didn't take a layer.
263
264    3     06/25/2009  groth     Rename extension to ARB_texture_query_lod.
265
266    2     06/23/2009  groth     correct filtering mode conditional in psuedocode
267
268    1     05/13/2009  groth     Split off of gpu_shader4_1
269