xref: /third_party/openGLES/extensions/EXT/EXT_clear_texture.txt

Name

    EXT_clear_texture

Name Strings

    GL_EXT_clear_texture

Contact

    Tobias Hector, Imagination Technologies (tobias.hector 'at' imgtec.com)

Contributors

    Contributors to the original ARB_clear_texture
    Ian Romanick
    Daniel Koch

Notice

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

Status

    Draft

Version

    Last Modified Date: September 16, 2016
    Revision: 2

Number

    OpenGL ES Extension #269

Dependencies

    OpenGL ES 3.1 is required.

    This extension is written against the OpenGL ES 3.1 API specification.

    This extension interacts with EXT/OES_texture_buffer or OpenGL ES 3.2.

    This extension interacts with EXT/OES_texture_cube_map_array or
    OpenGL ES 3.2.

    This extension interacts with OES_texture_stencil8 or OpenGL ES 3.2.

Overview

    Texture objects are fundamental to the operation of OpenGL. They are
    used as a source for texture sampling and destination for rendering
    as well as being accessed in shaders for image load/store operations
    It is also possible to invalidate the contents of a texture. It is
    currently only possible to set texture image data to known values by
    uploading some or all of a image array from application memory or by
    attaching it to a framebuffer object and using the Clear or ClearBuffer
    commands.

    Both uploading initial texture data and clearing by attaching to a
    framebuffer have potential disadvantages when one simply wants to
    initialize texture data to a known value. Uploading initial data
    requires the application to allocate a (potentially large) chunk
    of memory and transferring that to the GL.  This can be a costly
    operation both in terms of memory bandwidth and power usage.
    Alternatively, attaching a texture level to a framebuffer to clear it
    may not be possible if the texture format isn't supported for
    rendering, or even if it is, attaching the image to a framebuffer object
    may cause the texture to be allocated in certain types of memory, which
    it may otherwise not need to be placed in.

    This extension solves these problems by providing a mechanism whereby
    the contents of a texture image array can be set to known values by
    using the ClearTexImageEXT or ClearTexSubImageEXT commands.  These commands
    can also be useful for initializing an image that will be used for
    atomic shader operations.

IP Status

    No known IP claims.

New Procedures and Functions

    void ClearTexImageEXT(uint texture, int level,
                          enum format, enum type,
                          const void * data);

    void ClearTexSubImageEXT(uint texture, int level,
                             int xoffset, int yoffset, int zoffset,
                             sizei width, sizei height, sizei depth,
                             enum format, enum type,
                             const void * data);

New Types

    None

New Tokens

    None

Additions to Chapter 7 of the OpenGL ES 3.1 API Specification (Programs and
Shaders)

    In section 7.11.2 (Shader Memory Access Synchronization) edit the
    description of the TEXTURE_UPDATE_BARRIER_BIT to add ClearTexImageEXT
    and ClearTexSubImageEXT to the list of commands that can write to
    texture images.

Additions to Chapter 8 of the OpenGL ES 3.1 API Specification (Textures and
Samplers)

    Add a new Section 8.x (Clearing Texture Image Data) after
    Section 8.17 (Immutable-Format Texture Images):

    "All or part of a texture image may be filled with a constant value
    by calling the command

      void ClearTexSubImageEXT(uint texture, int level,
                               int xoffset, int yoffset, int zoffset,
                               sizei width, sizei height, sizei depth,
                               enum format, enum type,
                               const void * data);

    with <texture> and <level> indicating which texture array image is being
    cleared.  It is an error if <texture> is zero or not the name of a texture
    object, if <texture> is a buffer texture, or if the texture image has
    a compressed internal format.

    Arguments <xoffset>, <yoffset>, and <zoffset> specify the lower left
    texel coordinates of a <width>-wide by <height>-high by <depth>-deep
    rectangular subregion of the texel array and are interpreted as they
    are in TexSubImage3D as described in section 8.6 (Alternate Texture
    Image Specification Commands). The subregion must lie within the bounds
    of the texture image, as described in that section.

    For 2D array textures, <zoffset> is interpreted as the first layer to be
    cleared and <depth> is the number of layers to clear. Cube map textures are
    treated as an array of six slices in the z-dimension, where the value
    of <zoffset> is interpreted as specifying the cube map face for the
    corresponding <layer> in table 8.25 (Layer numbers for cube map texture
    faces) and <depth> is the number of faces to clear. For cube map array
    textures, <zoffset> is the first layer-face to clear, and <depth> is the
    number of layer-faces to clear. Each layer-face is translated into an
    array layer and a cube map face as described for layer-face numbers in
    section 8.5.3 [in OpenGL ES 3.2].

    For texture types that do not have certain dimensions, this
    command treats those dimensions as having a size of 1.  For example,
    to clear a portion of a two-dimensional texture, the application would
    use <zoffset> equal to zero and <depth> equal to one.

    <format> and <type> specify the format and type of the source
    data and are interpreted as they are for TexImage3D, as described in
    section 8.4.2 (Transfer of Pixel Rectangles). Textures with a base
    internal format of DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL
    require depth component, stencil, or depth/stencil component data
    respectively. Textures with other base internal formats require RGBA
    formats. Textures with integer internal formats (see table 8.13) require
    integer data.

    <data> is a pointer to an array of between one and four components of
    texel data that will be used as the source for the constant fill value.
    The elements of <data> are converted by the GL into the
    <internalformat> of the texture image (that was specified when the level
    was defined by any of the TexImage, TexStorage or CopyTexImage
    commands) in the manner described in section 8.4.2 (Transfer of Pixel
    Rectangles), and then used to fill the specified range of the
    destination texture level.  If <data> is NULL, then the pointer is
    ignored and the sub-range of the texture image is filled with zeros.
    If <texture> is a multisample texture, all the samples in a texel
    are cleared to the value specified by <data>.

    Errors

        An INVALID_OPERATION error is generated if <texture> is zero or not the
        name of a texture object.

        An INVALID_OPERATION error is generated if <texture> is a buffer
        texture.

        An INVALID_OPERATION error is generated if <texture> has a compressed
        internal format.

        An INVALID_OPERATION error is generated if the base internal format is
        DEPTH_COMPONENT and <format> is not DEPTH_COMPONENT.

        An INVALID_OPERATION error is generated if the base internal format is
        DEPTH_STENCIL and <format> is not DEPTH_STENCIL.

        An INVALID_OPERATION error is generated if the base internal format is
        STENCIL_INDEX and <format> is not STENCIL_INDEX.

        An INVALID_OPERATION error is generated if the base internal format is
        RGBA and the <format> is DEPTH_COMPONENT, STENCIL_INDEX, or
        DEPTH_STENCIL.

        An INVALID_OPERATION error is generated if the internal format is
        integer and <format> does not specify integer data.

        An INVALID_OPERATION error is generated if the internal format is
        not integer and <format> does specify integer data.

        An INVALID_OPERATION error is generated if the specified subregion
        does not lie within the bounds of the texture image, as described
        for TexSubImage3D in section 8.6.

    The command

      void ClearTexImageEXT(uint texture, int level,
                            enum format, enum type,
                            const void * data);

    is equivalent to calling ClearTexSubImageEXT with <xoffset>, <yoffset>,
    and <zoffset> equal to 0 and <width>, <height>, and <depth> equal
    to the dimensions of the texture image (or zero and one for dimensions
    the texture doesn't have).

    Errors

        In addition to the errors generated by ClearTexSubImageEXT:

        An INVALID_OPERATION error is generated if the image array identified by
        <level> has not previously been defined by a TexImage* or TexStorage*
        command."

Interactions with EXT/OES_texture_buffer or OpenGL ES 3.2

    If EXT_texture_buffer or equivalent functionality is not supported,
    ignore all references to buffer textures.

Interactions with EXT/OES_texture_cube_map_array or OpenGL ES 3.2

    If EXT_texture_cube_map_array or equivalent functionality is not supported,
    ignore all references to cube map array textures.

Interactions with OES_texture_stencil8 or OpenGL ES 3.2

    If OES_texture_stencil8 or equivalent functionality is not supported,
    ignore all references to stencil textures.

Errors

    An INVALID_OPERATION error is generated by ClearTexImageEXT or
    ClearTexSubImageEXT if <texture> is zero or not the name of a texture object.

    An INVALID_OPERATION error is generated by ClearTexImageEXT or
    ClearTexSubImageEXT if <texture> is a buffer texture.

    An INVALID_OPERATION error is generated by ClearTexImageEXT or
    ClearTexSubImageEXT if <texture> has a compressed internal format.

    An INVALID_OPERATION error is generated by ClearTexImageEXT or
    ClearTexSubImageEXT if the base internal format is DEPTH_COMPONENT and
    <format> is not DEPTH_COMPONENT.

    An INVALID_OPERATION error is generated by ClearTexImageEXT or
    ClearTexSubImageEXT if the base internal format is STENCIL_INDEX and
    <format> is not STENCIL_INDEX.

    An INVALID_OPERATION error is generated by ClearTexImageEXT or
    ClearTexSubImageEXT if the base internal format is DEPTH_STENCIL and
    <format> is not DEPTH_STENCIL.

    An INVALID_OPERATION error is generated by ClearTexImageEXT or
    ClearTexSubImageEXT if the base internal format is RGBA and the <format>
    is DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL.

    An INVALID_OPERATION error is generated by ClearTexImageEXT or
    ClearTexSubImageEXT if the internal format is integer and <format> does not
    specify integer data.

    An INVALID_OPERATION error is generated by ClearTexImageEXT or
    ClearTexSubImageEXT if the internal format is not integer and <format>
    does specify integer data.

    An INVALID_OPERATION error is generated if the specified subregion
    does not lie within the bouds of the texture image, as described
    for TexSubImage3D in section 8.6.

    An INVALID_OPERATION error is generated by ClearTexImageEXT if the
    image array identified by <level> has not previously been defined.

New State

    None.

New Implementation Dependent State

    None.

Issues

    See ARB_clear_texture for relevant issues.

    1) How does this differ from ARB_clear_texture?

    RESOLVED:
      - Removed interactions with features not present in OpenGL ES:
        - 1D arrays
        - border texels
      - Removed CLEAR_TEXTURE token for GetInternalFormat* which relies
        on the ARB_internalformat_query2 extension which does not have
        equivalent functionality in OpenGL ES.
      - minor language updates to sync with OpenGL 4.5 language.

Revision History

    Revision 1, 2015/08/15, thector
      - Initial revision
    Revision 2, 2016/09/16, dgkoch
      - added interactions with texture cube map arrays and stencil textures
      - added missing suffixes on commands
      - removed CLEAR_TEXTURE, which relies on functionality not in ES.
      - minor language updates to sync with OpenGL 4.5 core language.
      - updated some section references.