xref: /third_party/openGLES/extensions/ARB/ARB_texture_query_levels.txt

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 <q> 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 <sampler>, as defined in the
      OpenGL Specification.  The value zero will be returned if no texture or
      an incomplete texture is associated with <sampler>.
      textureQueryLevels() is available in all shader stages.

Conformance Tests

    <TBD>

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
      <levels> 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
      <target>, 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