Name ARB_texture_query_levels Name Strings GL_ARB_texture_query_levels Contact Christophe Riccio, AMD (christophe.riccio'at'amd.com) Contributors Pat Brown, NVIDIA Bruce Merry Notice Copyright (c) 2012-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 Status Complete. Approved by the ARB on 2012/06/12. Version Last Modified Date: June 6, 2012 Revision: 10 Number ARB Extension #140 Dependencies OpenGL 3.0 is required. OpenGL Shading Language 1.30 is required This extension is written against the OpenGL 4.2 specification and version 4.20 of the OpenGL Shading Language Specification. Overview This extension provides a new set of texture functions (textureQueryLevels) in the OpenGL Shading Language that exposes the number of accessible mipmap levels in the texture associated with a GLSL sampler variable. The set of accessible levels includes all the levels of the texture defined either through TexImage*, TexStorage*, or TextureView* (ARB_texture_view) APIs that are not below the TEXTURE_BASE_LEVEL or above the TEXTURE_MAX_LEVEL parameters. For textures defined with TexImage*, the set of resident levels is somewhat implementation-dependent. For fully defined results, applications should use TexStorage*/TextureView unless the texture has a full mipmap chain and is used with a mipmapped minification filter. These functions means that shaders are not required to manually recompute, approximate, or maintain a uniform holding a pre-computed level count, since the true level count is already available to the implementation. This value can be used to avoid black or leaking pixel artifacts for rendering methods which are using texture images as memory pages (eg: virtual textures); methods that can't only rely on the fixed pipeline texture functions which take advantage of TEXTURE_MAX_LEVEL for their sampling. New Procedures and Functions None. New Tokens None. Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification (OpenGL Operation) Modify Section 2.11.12, Shader Execution, p. 106 (retitle "Texture Size Query" sub-section, p. 109 to "Texture Queries") (modify the first paragraph of "Texture Queries", p. 109, renaming "texture size" to "textureSize()") The OpenGL Shading Language textureSize() functions provide... (add a new paragraph at the end of the now-renamed "Texture Queries" section, p. 109) The OpenGL Shading Language textureQueryLevels() functions provide the ability to query the number of accessible mipmap levels in a texture object associated with a sampler uniform. If the sampler is associated with an immutable-format texture object (section 3.9.16), the value returned will be: min(TEXTURE_IMMUTABLE_LEVELS - 1, TEXTURE_MAX_LEVEL) - TEXTURE_BASE_LEVEL + 1 where TEXTURE_IMMUTABLE_LEVELS gives the number of levels present in the immutable-format texture and TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL are the values of these texture parameters (section 3.9.8). Otherwise, the value returned will be an implementation-dependent value between zero and q - TEXTURE_BASE_LEVEL + 1 where is the maximum mipmap level specified in the "Mipmapping" section of section 3.9.11. The value returned in this case must satisfy the following constraints: - If all levels of the texture have zero size, zero must be returned. - If the texture is complete, a non-zero value must be returned. - If the texture object is complete and is accessed with a minification filter requiring mipmaps, q - TEXTURE_BASE_LEVEL + 1 must be returned. Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification (Rasterization) None. Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification (Per-Fragment Operations and the Frame Buffer) None. Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification (Special Functions) None. Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification (State and State Requests) None. Errors None. New State None. New Implementation Dependent State None. Modifications to The OpenGL Shading Language Specification, Version 4.20.8 Including the following line in a shader can be used to control the language features described in this extension: #extension GL_ARB_texture_query_levels A new preprocessor #define is added to the OpenGL Shading Language: #define GL_ARB_texture_query_levels 1 Add to section 8.9.1 "Texture Query Functions" Syntax: int textureQueryLevels(gsampler1D sampler); int textureQueryLevels(gsampler2D sampler); int textureQueryLevels(gsampler3D sampler); int textureQueryLevels(gsamplerCube sampler); int textureQueryLevels(gsampler1DArray sampler); int textureQueryLevels(gsampler2DArray sampler); int textureQueryLevels(gsamplerCubeArray sampler); int textureQueryLevels(gsampler1DShadow sampler); int textureQueryLevels(gsampler2DShadow sampler); int textureQueryLevels(gsamplerCubeShadow sampler); int textureQueryLevels(gsampler1DArrayShadow sampler); int textureQueryLevels(gsampler2DArrayShadow sampler); int textureQueryLevels(gsamplerCubeArrayShadow sampler); Description: The textureQueryLevels functions return the number of mipmap levels accessible in the texture associated with , as defined in the OpenGL Specification. The value zero will be returned if no texture or an incomplete texture is associated with . textureQueryLevels() is available in all shader stages. Conformance Tests Issues (1) Is the value returned by textureQueryLevels clamped by the number of levels present in a texture? (bug 7941) RESOLVED: Yes, the set of accessible levels needs to be computed by intersecting the set of levels present in the texture, with the range of levels between TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL. The number of accessible texture levels will be the value TEXTURE_MAX_LEVEL - TEXTURE_BASE_LEVEL + 1 if both parameters are set to accurately reflect the set of resident levels. However, it isn't necessary to set either texture parameter, and the default value for TEXTURE_MAX_LEVEL (1000) doesn't accurately reflect the total number of levels. As a result, the value returned needs to intersect the range between the base and maximum levels with the actual set of levels present in a texture. For immutable format textures (from OpenGL 4.2 and ARB_texture_storage), the set of present levels is well-defined, taken from the parameter of TextureStorage*D. If a texture is created immutable then we could clamp the value returned by textureQueryLevels to the number of levels. For other textures, the set of levels present and resident in the texture is less well-defined since levels can be added or removed at random. (2) What value is returned for textures that have an incomplete set of mipmaps? RESOLVED: The values returned in this case are largely implementation-dependent. Textures have two different notions of completeness: - A texture is "mipmap complete" if it has a full set of mipmaps, from the base level down to the smallest (1x1) level appropriate for the base level. If a texture sets TEXTURE_MAX_LEVEL, any levels smaller than the size of the maximum level need not be present for a texture to be mipmap complete. Note that immutable format textures will always be considered mipmap complete. - A texture that is not "complete" typically can not be used for texture mapping. A texture that is not mipmap complete can still be considered complete, as long as it isn't used with a mipmapped minification filter. Immutable-format TexStorage* textures always specify a full set of mipmap levels and are always considered mipmap complete; however, applications can add (or delete) mipmap levels to TexImage* textures at arbitrary times. If the texture has some (but not all) of the mipmaps necessary to be mipmap complete, an implementation might choose to manage the texture in a number of different ways: - don't allocate any texture memory (if the texture is incomplete) - allocate memory for only the base level (which is the only one that can be accessed with a non-mipmapped minification filter) - allocate memory for the subset of the full mipmap chain that is defined, even if some of these levels are inaccessible - speculatively allocate memory for the entire mipmap chain We specify the result to be implementation-dependent to (a) allow for implementations of this function that return the number of levels resident in the underlying texture memory allocation and (b) to not force implementation to change their memory management of TexImage* textures for this case. We do require implementations to return a non-zero value for textures that are complete, even if they aren't mipmap complete. For example, a TexImage* texture with only the base level is usable when used with a LINEAR minification filter and should have an allocation with at least one level present. (3) What values are returned by the built-in for textures that aren't complete or aren't defined at all? RESOLVED: As with the mipmap-incomplete case, the value returned is largely implementation-dependent, even though the incomplete texture can't be used for texture mapping. With separate sampler objects, it's worth noting that the same texture object may be considered complete when used in conjunction with one sampler object but might be incomplete when used with a different sampler object. For example, a texture with only a single level defined will be complete when used with a minification filter of LINEAR, but not with LINEAR_MIPMAP_LINEAR. We allow implementations to return zero in this case, but would also allow them to return non-zero values (possibly obtained because the texture object is actually usable in another texture image unit). We do require implementations to return zero if the texture has no defined levels (the default state for a new texture object). Note that in both the core and compatibility profiles of OpenGL 4.2, it doesn't appear to be possible to have a texture image unit with no texture bound. glBindTexture(target,0) binds the "default texture" for , not "no texture". The default texture may have images defined if TexImage* is called when it is bound. If these default textures were removed in a future version of OpenGL, textureQueryLevels() should return zero if the associated texture image unit has no texture bound. (4) For non-immutable format textures, what happens if textureQueryLevels() is called for a texture that *is* mipmap complete but is not accessed with a mipmapped minification filter? RESOLVED: The value returned is implementation-dependent. To get fully defined results with TexImage* textures, the texture should be mipmap complete and accessed with a mipmapped minification filter. In that case, the value returned is well-defined and must be consistent with an allocation holding the full mipmap chain. The undefined behavior here permit implementations to defer the download of "extra" mipmap levels until they are actually required. For textures without immutable formats, mipmap levels can be added or removed at any time and implementations may choose to modify the set of levels resident for a texture based on the minification filter. Consider the following code sequence: create level 0 of a 2D texture (256x256) set the texture's min filter to LINEAR (A) render using the texture create level 1 of a 2D texture (128x128) (B) render using the texture create levels 2..8 of a 2D texture (64x64 down to 1x1) (C) render using the texture set the texture's min filter to LINEAR_MIPMAP_LINEAR (D) render using the texture set the texture's min filter to LINEAR (E) render using the texture This texture will be complete each time rendering will be performed, but will be mipmap complete only for primitives (C), (D), and (E). For primitives (A) and (B), only the 256x256 texture will be accessible. An implementation might make the 128x128 level resident for (B), but it might defer this operation since the 128x128 level isn't actually needed and further mipmap level changes might occur. For primitive (C), the texture is mipmap complete, but the non-zero mipmap levels still aren't needed. For primitive (D), all nine levels need to be resident, and that's what textureQueryLevels() should return. For primitive (E), it seems likely that implementations will keep all levels resident, even though only the base level is needed. However, they could theoretically evict the non-base levels if required to free up texture memory. Revision History Revision 10, 2012/06/06 (pbrown) - Mark issues (2) through (4) as resolved. - Add warnings in overview and issues about undefined values for TexImage* textures and recommending the use of a mipmapped minification filter for fully defined results. Revision 9, 2012/06/01 (pbrown) - Update issues (1) through (4) to reflect edits from previous revisions of this spec. Leaving issues (2) through (4) unresolved pending final approval of previous edits. Revision 8, 2012/05/31 (pbrown) - (bug 7941) Update the language describing the values returned for TexImage* textures. The value is implementation-dependent, but must be in the range 0..q-BASE_LEVEL+1, and must satisfy the following constraints: - fully undefined textures must return zero - complete textures must return at least one - complete textures with a mipmapped min filter must return q-BASE_LEVEL+1 Revision 7, 2012/05/17 (criccio) - Fix textureQueryLevels calculation for immutable texture. min(TEXTURE_IMMUTABLE_LEVELS - 1, TEXTURE_MAX_LEVEL) instead of min(TEXTURE_IMMUTABLE_LEVELS, TEXTURE_MAX_LEVEL) Revision 6, 2012/05/16 (pbrown) - Add explicit language describing the set of values that will be returned for all the various cases (immutable format textures, mutable textures that are mipmap complete or not, incomplete or unbound textures). - Specify the level count to include only those levels between the base level and the maximum level. - Update the introduction. - Update the discussion for issues 1, 2, and 3. - Add issue 4, describing what happens for mipmap complete textures that don't need to be (because they're used with non-mipmapped filters). Implementations are allowed but not required to treat the entire mipmap chain as resident. Revision 5, 2012/04/30 (criccio) - Resolved issue 2 and 3 Revision 4, 2012/04/26 (criccio) - Resolved issue 1 for mutable texture - Added issue 2, 3 from Pat's comments Revision 3, 2012/03/15 (criccio) - Added issue Revision 2, 2011/11/01 (criccio) - Updated overview Revision 1, 2011/10/24 (criccio) - First draft