xref: /third_party/openGLES/extensions/IMG/IMG_bindless_texture.txt

Name

    IMG_bindless_texture

Name Strings

    GL_IMG_bindless_texture

Contact

    Tobias Hector (tobias.hector 'at' imgtec.com)

Contributors

    Contributors to the original ARB_bindless_texture

Notice

    Copyright (c) 2013 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

Status

    Draft

Version

    Last Modified Date:   May 23, 2016
    Author Revision:      4

Number

    OpenGL ES Extension #270

Dependencies

    OpenGL ES 3.1 is required.

    This extension is written against the OpenGL ES Shading Language
    specification, Language Version 3.10, Document Revision 3 and the
    OpenGL ES 3.1 API specification.

    This extension interacts with EXT/OES_gpu_shader5.

    This extension interacts with EXT/OES_texture_buffer and EXT_buffer_storage.

    This extension interacts with OpenGL ES 3.2

Overview

    This extension allows OpenGL ES applications to access texture objects in
    shaders without first binding each texture to one of a limited number of
    texture image units.  Using this extension, an application can query a
    64-bit unsigned integer texture handle for each texture that it wants to
    access and then use that handle directly in GLSL ES. This extensions
    significantly reduces the amount of API and internal GL driver overhead
    needed to manage resource bindings.

    This extension adds no new data types to GLSL.  Instead, it uses existing
    sampler data types and allows them to be populated with texture handles.
    This extension also permits sampler types to be used as uniform block
    members as well as default uniforms. Additionally, new APIs are provided to
    load values for sampler uniforms with 64-bit handle inputs.  The use of
    existing integer-based Uniform* APIs is still permitted, in which case the
    integer specified will identify a texture image.  For samplers with values
    specified as texture image units, the GL implementation will translate the
    unit number to an internal handle as required.

New Procedures and Functions

    uint64 GetTextureHandleIMG(uint texture);
    uint64 GetTextureSamplerHandleIMG(uint texture, uint sampler);

    void UniformHandleui64IMG(int location, uint64 value);
    void UniformHandleui64vIMG(int location, sizei count, const uint64 *value);

    void ProgramUniformHandleui64IMG(uint program, int location,
                                     uint64 value);
    void ProgramUniformHandleui64vIMG(uint program, int location,
                                      sizei count, const uint64 *values);

New Tokens

    None

Additions to Chapter 5 of the OpenGL ES 3.1 API Specification, "Shared Objects
and Multiple Contexts"

    Insert a new section 5.4, "Object use by GPU Handles"

        GPU handles to objects are valid in all contexts in the share group that
        the originating object belongs to, irrespective of whether the object
        itself is shared. If the originating object for a handle is deleted or
        becomes otherwise invalid, the handle becomes immediately invalid in all
        contexts. Using an invalid handle can lead to undefined results,
        including program termination.

Additions to Chapter 7 of the OpenGL ES 3.1 API Specification, "Variables and
Types"

    Add the following sentence to Section 7.6, Uniform Variables, immediately
    before the error block on page 97:

        A sampler uniform will consume no more than 2 components.

    Add the following commands to the list of Uniform* functions in section
    7.6.1, Loading Uniform Variables in the Default Uniform Block:

        void UniformHandleui64IMG(int location, uint64 value);
        void UniformHandleui64vIMG(int location, sizei count,
                                   const uint64 *value);

    Delete the sentence "Only the Uniform1i{v} commands can be used to load
    sampler values (see section 7.9)", and add the following paragraph:

        The UniformHandleui64{v}IMG commands will load <count> 64-bit unsigned
        integer handles into a uniform location corresponding to sampler types.
        Only the UniformHandleui64{v}IMG and Uniform1i{v} commands can be used
        to load sampler values (see section 7.9).

    Add the following error condition to the list of errors for Uniform*
    functions:

        An INVALID_OPERATION error is generated if the UniformHandleui64{v}IMG
        commands are used on a sampler variable with the "bound_sampler" layout
        qualifier (see the Language specification, section 4.4.5bindless).

    Add the following commands to the list of ProgramUniform* functions in
    section 7.6.1, Loading Uniform Variables in the Default Uniform Block:

        void ProgramUniformHandleui64IMG(uint program, int location,
                                         uint64 value);
        void ProgramUniformHandleui64vIMG(uint program, int location,
                                          sizei count, const uint64 *values);

    Edit section 7.6.2.1, "Uniform Buffer Object Storage", to add the following
    rules for sampler types to the list at the beginning of p105:

      * Members of sampler types are extracted from a buffer object by
        reading a single 64-bit value at the specified offset.

    Replace Section 7.9, Samplers, with the following, adding the ability to use
    samplers in new places as well as describing the behavior of the new
    UniformHandleui64{v}IMG APIs:

    Samplers are special data types used by the OpenGL ES Shading Language to
    identify the texture object used for each texture lookup.  Sampler
    variables may be used as uniforms in the default block or in user-defined
    blocks.

    When used as uniforms in the default block, the value of sampler
    variables may be specified with either Uniform1i{v} or
    UniformHandleui64{v}IMG.  If a sampler uniform value is specified by
    Uniform1i{v}, the value passed to Uniform1i{v} indicates a texture image
    unit that will be accessed, and the value must be in the range from zero
    to the implementation-dependent maximum supported number of texture image
    units.   If a sampler uniform value is specified by UniformHandleui64{v}IMG,
    the value passed to UniformHandleui64{v}IMG directly specifies a texture
    object by handle, as defined in Section 8.2bindless (Bindless Textures).
    When a program is linked, all sampler uniforms are initialized to zero and
    considered to be references to texture image units.  When used as uniform
    block members, the value of the sampler is a 64-bit unsigned integer handle
    and never refers to a texture image unit.

    When the value of a sampler indicates a texture image unit, the type of
    the sampler identifies the target on the texture image unit.  The texture
    object bound to that texture image unit's target is used for any texture
    accesses using that sampler.  For example, a variable of type sampler2D
    selects the target TEXTURE_2D on its texture image unit.  Binding of
    texture objects to targets is done as usual with BindTexture. Selecting
    the texture image unit to bind to is done as usual with ActiveTexture.

    When the value of a sampler indicates a texture handle, the target of the
    texture referred to by the handle must match the type of the sampler.  For
    example, a variable of type sampler2D must be used in conjunction with a
    handle of a texture of target TEXTURE_2D.  If the value of a sampler
    variable is not a valid texture handle, the results of using that sampler
    during shader execution are undefined and may lead to program termination.
    If the value of a sampler variable is a valid handle of a texture with a
    target different from the variable type, the results of using that handle
    are undefined but may not include program termination.

    Sampler uniforms specified using handles do not count as using any texture
    image unit, even if a texture referred to by a handle is currently bound to
    one or more texture image units.

    Errors

        The error INVALID_VALUE is generated if a Uniform1i{v} call is used to
        set a sampler uniform to a value less than zero or greater than or
        equal to the value of MAX_TEXTURE_IMAGE_UNITS.

        It is not allowed to have uniform variables of different sampler types
        pointing to the same texture image unit within a program object.  This
        situation can only be detected at the next rendering command issued,
        and an INVALID_OPERATION error will then be generated.

    Active samplers are those samplers actually being used in a program
    object.  When a program is linked by LinkProgram, the GL determines
    whether each sampler is active or not.  There is no limit on the number of
    active sampler variables that may be used by a program or by any
    particular shader.  However, restrictions on the use of texture image
    units imposes an effective limit on the number of non-handle sampler
    uniforms.  Active samplers used uniforms in the default uniform block are
    counted toward implementation-dependent limits on the total number of
    uniform components supported by the program.  Each active sampler variable
    may count as two components against such limits.

Additions to Chapter 8 of the OpenGL ES 3.1 API Specification, "Textures and
Samplers"

    Insert a new section 8.2bindless, Bindless Textures, after Section 8.2,
    Sampler Objects:

    The previous sections describe mechanisms to make texture and sampler
    objects available to shaders or fixed-function fragment processing by
    binding the objects to texture image units.  Additionally, texture objects
    may be accessed by shader using texture handles, which are 64-bit unsigned
    integers identifying the state of a texture and/or sampler object.  The
    handle zero is reserved and will never be assigned to a valid texture
    handle.  To obtain a texture handle, use the commands:

      uint64 GetTextureHandleIMG(uint texture);
      uint64 GetTextureSamplerHandleIMG(uint texture, uint sampler);

    GetTextureHandleIMG will create a texture handle using the current state of
    the texture named <texture>, including any embedded sampler state.
    GetTextureSamplerHandleIMG will create a texture handle using the current
    non-sampler state from the texture named <texture> and the sampler state
    from the sampler object <sampler>.  In both cases, a 64-bit unsigned
    integer handle is returned. If an error occurs, a handle of zero is
    returned.

    The handle for each texture or texture/sampler pair is unique; the same
    handle will be returned if GetTextureHandleIMG is called multiple times
    for the same texture or if GetTextureSamplerHandleIMG is called multiple
    times for the same texture/sampler pair.

    When a texture object is referenced by one or more texture handles, the
    texture parameters of the object (Section 8.9) may not be changed. The
    contents of the images in a texture object may still be updated via commands
    such as TexSubImage*, CopyTexSubImage*, and CompressedTexSubImage*, and by
    rendering to a framebuffer object, even if the texture object is referenced
    by one or more texture handles. However, once a handle references a texture
    object, texel updates via API commands are no longer implicitly
    synchronised by the API. Updates to the texture will become visible to the
    server after an unspecified period of time, and may occur during other
    server operations - though they are guaranteed to be visible to subsequently
    issued GL commands with no further action. Applications are responsible for
    synchronizing access, to ensure operations have completed in the desired
    order - for instance by using FenceSync (see Chapter 4 - Event Model).

    [[ If EXT/OES_texture_buffer or OpenGL ES 3.2, and EXT_buffer_storage are supported ]]
    If the texture object is a buffer texture, the contents of the buffer object
    may still be updated by using MapBuffer* commands with the
    MAP_PERSISTENT_BIT_EXT, or via the texture update commands in the same way
    as other bindless textures, even if the buffer is bound to a texture while
    that buffer texture object is referenced by one or more texture handles.

    When a sampler object is referenced by one or more texture handles, the
    sampler parameters of the object may not be changed.

    Errors

        An INVALID_VALUE error is generated if <texture> is zero or is not the
        name of an existing texture object or if <sampler> is zero or is not the
        name of an existing sampler object.

    [[ If EXT/OES_texture_buffer or OpenGL ES 3.2, and EXT_buffer_storage are supported ]]
        An INVALID_OPERATION error is generated if the value of <texture>'s
        TEXTURE_IMMUTABLE_FORMAT is FALSE (section 8.17), or if <texture> is
        a texture buffer and the values of the backing buffer's BUFFER_-
        IMMUTABLE_STORAGE_EXT is FALSE, BUFFER_ACCESS_FLAGS includes
        DYNAMIC_STORAGE_BIT or does not include MAP_PERSISTENT_BIT_EXT.
    [[ Else ]]
        An INVALID_OPERATION error is generated if the value of <texture>'s
        TEXTURE_IMMUTABLE_FORMAT is FALSE (section 8.17).

    [[ If EXT/OES_texture_border_clamp or OpenGL ES 3.2 are supported ]]
        An INVALID_OPERATION error is generated if the border color (taken from
        the embedded sampler for GetTextureHandleIMG or from the <sampler> for
        GetTextureSamplerHandleIMG) is not one of the following allowed values.
        If the texture's base internal format is signed or unsigned integer,
        allowed values are (0,0,0,0), (0,0,0,1), (1,1,1,0), and (1,1,1,1). If
        the base internal format is not integer, allowed values are
        (0.0,0.0,0.0,0.0), (0.0,0.0,0.0,1.0), (1.0,1.0,1.0,0.0), and
        (1.0,1.0,1.0,1.0).

Additions to Chapter 11 of the OpenGL ES 3.1 API Specification, "Programmable
Vertex Processing"

    Add the following sentence to the end of the paragraph in Section 11.1.3.5,
    Texture Access, beginning "All active shaders combined cannot use more than
    the value of MAX_COMBINED_TEXTURE_IMAGE_UNITS...":

        Samplers accessed using texture handles (section 3.9.X) are not counted
        against this limit.

Modifications to The OpenGL ES 3.10 Shading Language Specification

    Including the following line in a shader can be used to control the
    language features described in this extension:

      #extension GL_IMG_bindless_texture : <behavior>

    where <behavior> is as specified in section 3.4.

    New preprocessor #defines are added to the OpenGL ES Shading Language:

      #define GL_IMG_bindless_texture         1


Additions to Chapter 4 of the OpenGL ES 3.1 Language Specification, "Variables
and Types"

    Add the following paragraph to the end of section 4.1.7.1, Samplers:

        The OpenGL ES API allows default block sampler uniforms to be assigned
        values referencing either a texture image unit number or a bindless
        texture handle, depending on the API function used.  All other sampler
        variables must be assigned a texture handle. A layout qualifier
        specifies which of these is used in the program.

    Remove the bullet point "sampler types are not allowed" Section 4.3.7,
    Interface Blocks.

    Add the following paragraph to the end of section 4.4.5, "Opaque Uniform
    Layout Qualifiers":

        Sampler variables declared in uniform blocks may not be qualified with
        a binding, and a compile-time error will be generated if a shader
        specifies this.

    Insert a new section 4.4.5bindless, "Bindless Sampler Layout Qualifiers",
    after section 4.4.5, "Opaque Uniform Layout Qualifiers":

        Sampler types accept a uniform layout qualifier identifier controlling
        whether the uniform may be used with a bindless handle:

            layout-qualifier-id
                bindless_sampler
                bound_sampler

        These modifiers control whether default-block uniforms of the
        corresponding types may have their values set via both UniformHandle*
        and Uniform1i (bindless_sampler) or only via Uniform1i (bound_sampler).
        These layouts may be specified at global scope to control the default
        behavior of uniforms of the corresponding types, e.g.

            layout (bindless_sampler) uniform;

        They may also be specified on a uniform variable declaration of a
        corresponding type, e.g.

            layout (bindless_sampler) uniform sampler2D mySampler;

        If both bindless_sampler and bound_sampler are declared at global scope
        in any compilation unit, a link-  time error will be generated. If these
        layout qualifiers are applied to other types of default block uniforms,
        a compile-time error will be generated. In the absence of these
        qualifiers, sampler uniforms are considered "bound". Additionally, if
        GL_IMG_bindless_texture is not enabled, these uniforms are considered
        "bound".

        Declaring a sampler in the uniform default-block with a binding point
        qualifier implicitly also declares it with "bound_sampler".

Errors

    The error INVALID_OPERATION is generated by SamplerParameter* if <sampler>
    identifies a sampler object referenced by one or more texture handles.

    The error INVALID_OPERATION is generated by TexParameter* if <target>
    identifies a texture object referenced by one or more texture handles.


    The error INVALID_OPERATION is generated by {Program}UniformHandleui64{v}IMG
    if the sampler or image uniform being updated has the "bound_sampler" layout
    qualifier, or an explicit binding qualifier.

    [[ If EXT/OES_texture_buffer or OpenGL ES 3.2, and EXT_buffer_storage are supported ]]
    The error INVALID_OPERATION is generated by TexBuffer*EXT if <target>
    identifies a texture object referenced by one or more texture handles.

    The error INVALID_OPERATION is generated by MapBuffer* if <target>
    identifies a buffer object bound to a texture that is referenced by one or
    more texture handles, and access does not include MAP_PERSISTENT_BIT_EXT.

Examples

    To loop through a collection of 256 textures in the OpenGL API using a
    conventional GLSL shader and without calling glBindTexture, one might do:

      #define NUM_TEXTURES      256
      GLuint   textures[NUM_TEXTURES];
      GLuint64 texHandles[NUM_TEXTURES];

      // Initialize the texture objects and handles.
      glGenTextures(NUM_TEXTURES, textures);
      for (int i = 0; i < NUM_TEXTURES; i++) {

        // Initialize the texture images with glTexStorage.
        // Initialize the texture parameters as required.

        // Get a handle for the texture.
        texHandles[i] = glGetTextureHandleIMG(textures[i]);

        // At this point, it's no longer possible to modify texture parameters
        // for "textures[i]". However, it's still possible to update texture
        // data via glTexSubImage.
      }

      // Compile GLSL shader using sampler uniform <u>.  The shader itself
      // needs no special #extension directive as long as <u> is a uniform in
      // the default partition, and doesn't declare an explicit binding point.
      // Link the program, and query the location of <u>, which we will store
      // in <location>.

      // Render a little bit using each of the texture handles in turn.
      for (int i = 0; i < NUM_TEXTURES; i++) {

        // Update the single sampler uniform <u> to point at "texHandles[i]".
        glUniformHandleui64IMG(location, texHandles[i]);

        drawStuff();
      }

    The GLSL portion of this extension removes the restriction that sampler
    variables must be uniforms in the default block.  You can store a large
    collection of samplers in a uniform block.

    To use a "dictionary" of samplers in a uniform block (in combination with
    either EXT_gpu_shader5, or OpenGL ES 3.2), you could use a shader like:

        #version 310 es
        #extension GL_IMG_bindless_texture : require
        #extension GL_EXT_gpu_shader5 : require
        #define NUM_TEXTURES 256

        uniform int whichSampler;
        in highp vec2 texCoord;
        out lowp vec4 finalColor;

        uniform Samplers {
            sampler2D allTheSamplers[NUM_TEXTURES];
        };

        void main()
        {
            finalColor = texture(allTheSamplers[whichSampler], texCoord);
        }

New State

    Add new table, Bindless Texture Handles

                                               Initial
    Get Value    Type   Get Command             Value     Description                  Sec.        Attribute
    ------------ ----  --------------------    -------    -------------------------   -----------  -------
    -            Z64   GetTextureHandleIMG       n/a      texture handle              8.2bindless     -
                        or GetTextureSampler-
                        HandleIMG
    -            Z+           -                  n/a      texture object used         8.2bindless     -
    -            Z+           -                  n/a      sampler object used         8.2bindless     -

Issues

    See original issues in ARB_bindless_texture.

    (1) How does IMG_bindless_texture differ from ARB_bindless_texture?

      RESOLVED:

      - Bindless images are not supported.
      - Bindless samplers are only supported via uniforms/uniform buffers.
      - No constructors between opaque and integer types
      - No residency functions
      - This extension does not add dynamic indexing, as it is introduced by EXT/OES_shader_gpu5 (or OpenGL ES 3.2)
      - Only immutable textures and buffers (for buffer textures) are usable with bindless handles.
      - Texture uploads are considered asynchronous to usage, and must be manually synchronized with fences in order to avoid race conditions
      - For buffer texture objects, the only allowed buffer update mechanism is persistent mapping

    (2) Should texture uploads/copies still be allowed?

      RESOLVED:

      The original ARB_bindless_texture allows texture uploads, with the
      expectation that the commands are still serialized relative to surrounding
      draw calls.

      Such an implementation would prove difficult for a tile-based
      architecture; attempting to serialize resource updates between draw calls
      requires significant amounts of additional overhead. Without bindless,
      the driver is able to track resources to make it work as expected - which
      is impossible with bindless textures.

      So we've decided to remove this particular requirement, instead
      saying that texture uploads and copies occur asynchronously to other
      commands, and require explicit synchronisation, in order to be
      completed at predictable times.

    (2) Should buffer uploads/copies for buffer texture objects still be allowed?

      RESOLVED:

      Only persistent mapping is allowed.

Revision History

    Rev.    Date      Author    Changes
    ----  ----------  --------  -----------------------------------------
     1    2015-08-21  thector   Initial revision
     2    2015-08-24  thector   Fixed references to "EXT_buffer_storage", added error for TexBuffer*EXT functions
     3    2015-12-04  thector   Texture data uploads are now entirely asynchronous
     4    2016-05-23  thector   Ensured that example in spec is actually compilable