1Name 2 3 ARB_texture_query_levels 4 5Name Strings 6 7 GL_ARB_texture_query_levels 8 9Contact 10 11 Christophe Riccio, AMD (christophe.riccio'at'amd.com) 12 13Contributors 14 15 Pat Brown, NVIDIA 16 Bruce Merry 17 18Notice 19 20 Copyright (c) 2012-2013 The Khronos Group Inc. Copyright terms at 21 http://www.khronos.org/registry/speccopyright.html 22 23Specification Update Policy 24 25 Khronos-approved extension specifications are updated in response to 26 issues and bugs prioritized by the Khronos OpenGL Working Group. For 27 extensions which have been promoted to a core Specification, fixes will 28 first appear in the latest version of that core Specification, and will 29 eventually be backported to the extension document. This policy is 30 described in more detail at 31 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 32 33Status 34 35 Complete. 36 Approved by the ARB on 2012/06/12. 37 38Version 39 40 Last Modified Date: June 6, 2012 41 Revision: 10 42 43Number 44 45 ARB Extension #140 46 47Dependencies 48 49 OpenGL 3.0 is required. 50 51 OpenGL Shading Language 1.30 is required 52 53 This extension is written against the OpenGL 4.2 specification and 54 version 4.20 of the OpenGL Shading Language Specification. 55 56Overview 57 58 This extension provides a new set of texture functions 59 (textureQueryLevels) in the OpenGL Shading Language that exposes the 60 number of accessible mipmap levels in the texture associated with a GLSL 61 sampler variable. The set of accessible levels includes all the levels of 62 the texture defined either through TexImage*, TexStorage*, or TextureView* 63 (ARB_texture_view) APIs that are not below the TEXTURE_BASE_LEVEL or above 64 the TEXTURE_MAX_LEVEL parameters. For textures defined with TexImage*, 65 the set of resident levels is somewhat implementation-dependent. For 66 fully defined results, applications should use TexStorage*/TextureView 67 unless the texture has a full mipmap chain and is used with a mipmapped 68 minification filter. 69 70 These functions means that shaders are not required to manually recompute, 71 approximate, or maintain a uniform holding a pre-computed level count, 72 since the true level count is already available to the 73 implementation. This value can be used to avoid black or leaking pixel 74 artifacts for rendering methods which are using texture images as memory 75 pages (eg: virtual textures); methods that can't only rely on the fixed 76 pipeline texture functions which take advantage of TEXTURE_MAX_LEVEL for 77 their sampling. 78 79New Procedures and Functions 80 81 None. 82 83New Tokens 84 85 None. 86 87Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification 88(OpenGL Operation) 89 90 Modify Section 2.11.12, Shader Execution, p. 106 91 92 (retitle "Texture Size Query" sub-section, p. 109 to "Texture Queries") 93 94 (modify the first paragraph of "Texture Queries", p. 109, renaming 95 "texture size" to "textureSize()") The OpenGL Shading Language 96 textureSize() functions provide... 97 98 (add a new paragraph at the end of the now-renamed "Texture Queries" 99 section, p. 109) 100 101 The OpenGL Shading Language textureQueryLevels() functions provide the 102 ability to query the number of accessible mipmap levels in a texture 103 object associated with a sampler uniform. If the sampler is associated 104 with an immutable-format texture object (section 3.9.16), the value 105 returned will be: 106 107 min(TEXTURE_IMMUTABLE_LEVELS - 1, TEXTURE_MAX_LEVEL) - 108 TEXTURE_BASE_LEVEL + 1 109 110 where TEXTURE_IMMUTABLE_LEVELS gives the number of levels present in the 111 immutable-format texture and TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL are 112 the values of these texture parameters (section 3.9.8). Otherwise, the 113 value returned will be an implementation-dependent value between zero and 114 115 q - TEXTURE_BASE_LEVEL + 1 116 117 where <q> is the maximum mipmap level specified in the "Mipmapping" 118 section of section 3.9.11. The value returned in this case must satisfy 119 the following constraints: 120 121 - If all levels of the texture have zero size, zero must be returned. 122 123 - If the texture is complete, a non-zero value must be returned. 124 125 - If the texture object is complete and is accessed with a minification 126 filter requiring mipmaps, q - TEXTURE_BASE_LEVEL + 1 must be returned. 127 128 129Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification 130(Rasterization) 131 132 None. 133 134Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification 135(Per-Fragment Operations and the Frame Buffer) 136 137 None. 138 139Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification 140(Special Functions) 141 142 None. 143 144Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification 145(State and State Requests) 146 147 None. 148 149Errors 150 151 None. 152 153New State 154 155 None. 156 157New Implementation Dependent State 158 159 None. 160 161Modifications to The OpenGL Shading Language Specification, Version 4.20.8 162 163 Including the following line in a shader can be used to control the 164 language features described in this extension: 165 166 #extension GL_ARB_texture_query_levels 167 168 A new preprocessor #define is added to the OpenGL Shading Language: 169 170 #define GL_ARB_texture_query_levels 1 171 172 Add to section 8.9.1 "Texture Query Functions" 173 174 Syntax: 175 176 int textureQueryLevels(gsampler1D sampler); 177 int textureQueryLevels(gsampler2D sampler); 178 int textureQueryLevels(gsampler3D sampler); 179 int textureQueryLevels(gsamplerCube sampler); 180 int textureQueryLevels(gsampler1DArray sampler); 181 int textureQueryLevels(gsampler2DArray sampler); 182 int textureQueryLevels(gsamplerCubeArray sampler); 183 int textureQueryLevels(gsampler1DShadow sampler); 184 int textureQueryLevels(gsampler2DShadow sampler); 185 int textureQueryLevels(gsamplerCubeShadow sampler); 186 int textureQueryLevels(gsampler1DArrayShadow sampler); 187 int textureQueryLevels(gsampler2DArrayShadow sampler); 188 int textureQueryLevels(gsamplerCubeArrayShadow sampler); 189 190 Description: 191 192 The textureQueryLevels functions return the number of mipmap levels 193 accessible in the texture associated with <sampler>, as defined in the 194 OpenGL Specification. The value zero will be returned if no texture or 195 an incomplete texture is associated with <sampler>. 196 textureQueryLevels() is available in all shader stages. 197 198Conformance Tests 199 200 <TBD> 201 202Issues 203 204 (1) Is the value returned by textureQueryLevels clamped by the number of 205 levels present in a texture? (bug 7941) 206 207 RESOLVED: Yes, the set of accessible levels needs to be computed by 208 intersecting the set of levels present in the texture, with the range of 209 levels between TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL. 210 211 The number of accessible texture levels will be the value 212 213 TEXTURE_MAX_LEVEL - TEXTURE_BASE_LEVEL + 1 214 215 if both parameters are set to accurately reflect the set of resident 216 levels. However, it isn't necessary to set either texture parameter, 217 and the default value for TEXTURE_MAX_LEVEL (1000) doesn't accurately 218 reflect the total number of levels. As a result, the value returned 219 needs to intersect the range between the base and maximum levels with 220 the actual set of levels present in a texture. 221 222 For immutable format textures (from OpenGL 4.2 and ARB_texture_storage), 223 the set of present levels is well-defined, taken from the parameter 224 <levels> of TextureStorage*D. If a texture is created immutable then we 225 could clamp the value returned by textureQueryLevels to the number of 226 levels. For other textures, the set of levels present and resident in 227 the texture is less well-defined since levels can be added or removed at 228 random. 229 230 (2) What value is returned for textures that have an incomplete set of 231 mipmaps? 232 233 RESOLVED: The values returned in this case are largely 234 implementation-dependent. Textures have two different notions of 235 completeness: 236 237 - A texture is "mipmap complete" if it has a full set of mipmaps, from 238 the base level down to the smallest (1x1) level appropriate for the 239 base level. If a texture sets TEXTURE_MAX_LEVEL, any levels smaller 240 than the size of the maximum level need not be present for a texture 241 to be mipmap complete. Note that immutable format textures will 242 always be considered mipmap complete. 243 244 - A texture that is not "complete" typically can not be used for texture 245 mapping. A texture that is not mipmap complete can still be 246 considered complete, as long as it isn't used with a mipmapped 247 minification filter. 248 249 Immutable-format TexStorage* textures always specify a full set of 250 mipmap levels and are always considered mipmap complete; however, 251 applications can add (or delete) mipmap levels to TexImage* textures at 252 arbitrary times. 253 254 If the texture has some (but not all) of the mipmaps necessary to be 255 mipmap complete, an implementation might choose to manage the texture in 256 a number of different ways: 257 258 - don't allocate any texture memory (if the texture is incomplete) 259 260 - allocate memory for only the base level (which is the only one that 261 can be accessed with a non-mipmapped minification filter) 262 263 - allocate memory for the subset of the full mipmap chain that is 264 defined, even if some of these levels are inaccessible 265 266 - speculatively allocate memory for the entire mipmap chain 267 268 We specify the result to be implementation-dependent to (a) allow for 269 implementations of this function that return the number of levels 270 resident in the underlying texture memory allocation and (b) to not 271 force implementation to change their memory management of TexImage* 272 textures for this case. 273 274 We do require implementations to return a non-zero value for textures 275 that are complete, even if they aren't mipmap complete. For example, a 276 TexImage* texture with only the base level is usable when used with a 277 LINEAR minification filter and should have an allocation with at least 278 one level present. 279 280 (3) What values are returned by the built-in for textures that aren't 281 complete or aren't defined at all? 282 283 RESOLVED: As with the mipmap-incomplete case, the value returned is 284 largely implementation-dependent, even though the incomplete texture 285 can't be used for texture mapping. 286 287 With separate sampler objects, it's worth noting that the same texture 288 object may be considered complete when used in conjunction with one 289 sampler object but might be incomplete when used with a different 290 sampler object. For example, a texture with only a single level defined 291 will be complete when used with a minification filter of LINEAR, but not 292 with LINEAR_MIPMAP_LINEAR. We allow implementations to return zero in 293 this case, but would also allow them to return non-zero values (possibly 294 obtained because the texture object is actually usable in another 295 texture image unit). 296 297 We do require implementations to return zero if the texture has no 298 defined levels (the default state for a new texture object). 299 300 Note that in both the core and compatibility profiles of OpenGL 4.2, it 301 doesn't appear to be possible to have a texture image unit with no 302 texture bound. glBindTexture(target,0) binds the "default texture" for 303 <target>, not "no texture". The default texture may have images defined 304 if TexImage* is called when it is bound. If these default textures were 305 removed in a future version of OpenGL, textureQueryLevels() should 306 return zero if the associated texture image unit has no texture bound. 307 308 (4) For non-immutable format textures, what happens if 309 textureQueryLevels() is called for a texture that *is* mipmap complete 310 but is not accessed with a mipmapped minification filter? 311 312 RESOLVED: The value returned is implementation-dependent. 313 314 To get fully defined results with TexImage* textures, the texture should 315 be mipmap complete and accessed with a mipmapped minification filter. 316 In that case, the value returned is well-defined and must be consistent 317 with an allocation holding the full mipmap chain. 318 319 The undefined behavior here permit implementations to defer the download 320 of "extra" mipmap levels until they are actually required. For textures 321 without immutable formats, mipmap levels can be added or removed at any 322 time and implementations may choose to modify the set of levels resident 323 for a texture based on the minification filter. Consider the following 324 code sequence: 325 326 create level 0 of a 2D texture (256x256) 327 set the texture's min filter to LINEAR 328 (A) render using the texture 329 create level 1 of a 2D texture (128x128) 330 (B) render using the texture 331 create levels 2..8 of a 2D texture (64x64 down to 1x1) 332 (C) render using the texture 333 set the texture's min filter to LINEAR_MIPMAP_LINEAR 334 (D) render using the texture 335 set the texture's min filter to LINEAR 336 (E) render using the texture 337 338 This texture will be complete each time rendering will be performed, but 339 will be mipmap complete only for primitives (C), (D), and (E). For 340 primitives (A) and (B), only the 256x256 texture will be accessible. An 341 implementation might make the 128x128 level resident for (B), but it 342 might defer this operation since the 128x128 level isn't actually needed 343 and further mipmap level changes might occur. For primitive (C), the 344 texture is mipmap complete, but the non-zero mipmap levels still aren't 345 needed. For primitive (D), all nine levels need to be resident, and 346 that's what textureQueryLevels() should return. For primitive (E), it 347 seems likely that implementations will keep all levels resident, even 348 though only the base level is needed. However, they could theoretically 349 evict the non-base levels if required to free up texture memory. 350 351Revision History 352 353 Revision 10, 2012/06/06 (pbrown) 354 - Mark issues (2) through (4) as resolved. 355 - Add warnings in overview and issues about undefined values for 356 TexImage* textures and recommending the use of a mipmapped 357 minification filter for fully defined results. 358 359 Revision 9, 2012/06/01 (pbrown) 360 - Update issues (1) through (4) to reflect edits from previous revisions 361 of this spec. Leaving issues (2) through (4) unresolved pending final 362 approval of previous edits. 363 364 Revision 8, 2012/05/31 (pbrown) 365 - (bug 7941) Update the language describing the values returned for 366 TexImage* textures. The value is implementation-dependent, but must 367 be in the range 0..q-BASE_LEVEL+1, and must satisfy the following 368 constraints: 369 - fully undefined textures must return zero 370 - complete textures must return at least one 371 - complete textures with a mipmapped min filter must return 372 q-BASE_LEVEL+1 373 374 Revision 7, 2012/05/17 (criccio) 375 - Fix textureQueryLevels calculation for immutable texture. 376 min(TEXTURE_IMMUTABLE_LEVELS - 1, TEXTURE_MAX_LEVEL) instead of 377 min(TEXTURE_IMMUTABLE_LEVELS, TEXTURE_MAX_LEVEL) 378 379 Revision 6, 2012/05/16 (pbrown) 380 - Add explicit language describing the set of values that will be 381 returned for all the various cases (immutable format textures, mutable 382 textures that are mipmap complete or not, incomplete or unbound 383 textures). 384 - Specify the level count to include only those levels between the base 385 level and the maximum level. 386 - Update the introduction. 387 - Update the discussion for issues 1, 2, and 3. 388 - Add issue 4, describing what happens for mipmap complete textures that 389 don't need to be (because they're used with non-mipmapped filters). 390 Implementations are allowed but not required to treat the entire 391 mipmap chain as resident. 392 393 Revision 5, 2012/04/30 (criccio) 394 - Resolved issue 2 and 3 395 396 Revision 4, 2012/04/26 (criccio) 397 - Resolved issue 1 for mutable texture 398 - Added issue 2, 3 from Pat's comments 399 400 Revision 3, 2012/03/15 (criccio) 401 - Added issue 402 403 Revision 2, 2011/11/01 (criccio) 404 - Updated overview 405 406 Revision 1, 2011/10/24 (criccio) 407 - First draft 408