Name

    ANGLE_texture_multisample_array

Name Strings

    GL_ANGLE_texture_multisample_array

Contributors

    Olli Etuaho, NVIDIA Corporation
    Contributors to OpenGL ES 3.2, on which this extension is based

Contact

    Olli Etuaho (oetuaho 'at' nvidia.com)

Status

    Incomplete

Version

    Last Modified Date: August 23, 2018
    Author Revision: 1

Number

    OpenGL ES Extension XX

Dependencies

    OpenGL ES 3.0 and the ANGLE_texture_multisample extension, or OpenGL ES
    3.1 is required.

    Written against the OpenGL ES 3.1 specification.

Overview

    This extension provides support for a new type of texture -
    two-dimensional multisample array texture - as well as mechanisms to
    allocate storage and attach such textures to FBOs for rendering,
    to support such a texture in a shader, to fetch a specific sample
    from such a texture in a shader, and to query the dimensions of
    such a texture in a shader.

    This extension is based on functionality in the OpenGL ES 3.2
    specification.

IP Status

    No known IP claims.

New Tokens

    Accepted by the <target> parameter of BindTexture,
    TexStorage3DMultisampleANGLE, GetInternalformativ, TexParameter{if}*,
    GetTexParameter{if}v, GetTexLevelParameter{if}vANGLE and
    by the <textarget> parameter of FramebufferTexture2D:

        TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE                0x9102

    Accepted by the <pname> parameter of GetIntegerv:

        TEXTURE_BINDING_2D_MULTISAMPLE_ARRAY_ANGLE        0x9105

    Returned by the <type> parameter of GetActiveUniform:

        SAMPLER_2D_MULTISAMPLE_ARRAY_ANGLE                0x910B
        INT_SAMPLER_2D_MULTISAMPLE_ARRAY_ANGLE            0x910C
        UNSIGNED_INT_SAMPLER_2D_MULTISAMPLE_ARRAY_ANGLE   0x910D

New Procedures and Functions

    void TexStorage3DMultisampleANGLE(enum target,
                                      sizei samples,
                                      enum sizedinternalformat,
                                      sizei width,
                                      sizei height,
                                      sizei depth,
                                      boolean fixedsamplelocations);

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

    Modify Section 8.8, "Multisample Textures".

    (first paragraph of section 8.8)

    In addition to the texture types described in previous sections, two
    additional types of textures are supported. A multisample texture is
    similar to a two-dimensional or two-dimensional array texture,
    except it contains multiple samples per texel. Multisample textures do
    not have multiple image levels, and are immutable.

    (insert after description of TexStorage2DMultisampleANGLE)

    The command

        void TexStorage3DMultisampleANGLE(enum target, sizei samples,
                                          int sizedinternalformat,
                                          sizei width, sizei height, sizei depth,
                                          boolean fixedsamplelocations);

    establishes the data storage, format, dimensions, and number of
    samples of a multisample texture array's image. <target> must be
    TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE. <width>, <height> and <depth> are the
    dimensions in texels of the texture.

    Upon success, TexStorage3DMultisampleANGLE deletes any existing image
    for <target> and the contents of texels are undefined. The values of
    TEXTURE_WIDTH, TEXTURE_HEIGHT, TEXTURE_DEPTH, TEXTURE_SAMPLES_ANGLE,
    TEXTURE_INTERNAL_FORMAT and TEXTURE_FIXED_SAMPLE_LOCATIONS_ANGLE are
    set to <width>, <height>, the actual number of samples allocated,
    <sizedinternalformat>, and <fixedsamplelocations> respectively.

    (modify errors in Section 8.8)

    An INVALID_ENUM error is generated if target is not
    TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE in case of TexStorage3DMultisampleANGLE,
    or TEXTURE_2D_MULTISAMPLE_ANGLE in case of TexStorage2DMultisampleANGLE.
    An INVALID_VALUE is generated if <width>, <height> or <depth> is less than 1.

    (insert into errors is Section 8.8)

    An INVALID_VALUE error is generated by TexStorage3DMultisample if depth is
    greater than the value of MAX_ARRAY_TEXTURE_LAYERS.

    Modify Section 8.9, "Texture Parameters":

    Add TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE to the texture targets accepted by
    TexParameter*.

    (add to the end of Section 8.9)

    An INVALID_ENUM is generated if <target> is
    TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE and <pname> is any sampler state from
    table 20.11. An INVALID_OPERATION error is generated if <target> is
    TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE, and <pname> TEXTURE_BASE_LEVEL is set
    to any value other than zero.

    Modify Section 8.10.2, "Texture Parameter Queries":

    (modify the paragraph describing the <target> parameter of
    GetTexParameter*)

    <target> may be one of TEXTURE_2D, TEXTURE_3D, TEXTURE_2D_ARRAY,
    TEXTURE_CUBE_MAP, TEXTURE_2D_MULTISAMPLE_ANGLE, or
    TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE, indicating the currently bound
    two-dimensional, three-dimensional, two-dimensional array, cube map,
    two-dimensional multisample, or two-dimensional multisample array
    texture object, respectively.

    Modify Section 8.10.3, "Texture Level Parameter Queries"

    (modify the paragraph describing the <target> parameter of
    GetTexLevelParameter*)

    <target> may be one of TEXTURE_2D, TEXTURE_3D, TEXTURE_2D_ARRAY, one of
    the cube map face targets from table 8.21, TEXTURE_2D_MULTISAMPLE_ANGLE,
    or TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE indicating the two- or
    three-dimensional texture, two-dimensional array texture, one of the six
    distinct 2D images making up the cube map texture object, two-dimensional
    multisample texture or two-dimensional multisample array texture. Otherwise
    an INVALID_ENUM is generated.

Additions to Chapter 9 of the OpenGL ES 3.1 Specification (Framebuffers and
Framebuffer Objects)

    Modify section 9.2.8 "Attaching Texture Images to a Framebuffer".

    (modify description of FrameBufferTextureLayer p. 223)

    The command

        void FramebufferTextureLayer(enum target, enum attachment,
                                     uint texture, int level, int layer);

    operates similarly to FramebufferTexture2D, except that it attaches a
    single layer of a three-dimensional texture, two-dimensional array
    texture or two-dimensional multisample array texture level.

    The error INVALID_OPERATION is generated if texture is non-zero
    and is not the name of a three-dimensional texture, two-dimensional
    array texture or or two-dimensional multisample array texture.

    (insert into description of FrameBufferTextureLayer p. 224)

    If <texture> identifies a two-dimensional multisample array texture,
    then <level> must be zero. Otherwise, an INVALID_VALUE error is
    generated.

Additions to Chapter 11 of the OpenGL ES 3.1 Specification (Programmable Vertex Processing)

    Modify Section 11.1.3.3 "Multisample Texel Fetches":

    (modify the paragraph before the list of conditions for undefined results)

    If the context was created with robust buffer access enabled, the result
    of the texel fetch in the following cases is zero. If robust buffer
    access is not enabled, the result of the texel fetch is undefined in
    each case:

Additions to Chapter 19 of the OpenGL ES 3.1 Specification (Context State Queries)

    Modify Section 19.3, "Internal Format Queries":

    Add target TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE to table 19.1.

Additions to the AGL/EGL/GLX/WGL Specifications

    None

Additions to the OpenGL ES Shading Language Specification, Version 3.10.

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

      #extension GL_ANGLE_texture_multisample_array : <behavior>

    where <behavior> is as specified in section 3.5.

    A new preprocessor #define is added to the OpenGL ES Shading Language:

      #define GL_ANGLE_texture_multisample_array 1

    Add to section 3.8 "Keywords":

    The following new sampler types are added:

      sampler2DMSArray, isampler2DMSArray, usampler2DMSArray,

    Add to section 4.1 "Basic Types":

    Add the following sampler type to the "Floating Point Sampler
    Types (opaque)" table:

      sampler2DMSArray    handle for accessing a 2D multisample array texture

    Add the following sampler type to the "Unsigned Integer Sampler
    Types (opaque)" table:

      usampler2DMSArray    handle for accessing an unsigned integer 2D
                           multisample array texture

    Add the following sampler type to the "Integer Sampler Types" table:

      isampler2DMSArray    handle for accessing an integer 2D
                           multisample array texture

    Add to section 8.8 "Texture Lookup Functions":

    Add new functions to the set of allowed texture lookup functions:

    Syntax:

      gvec4 texelFetch(gsampler2DMSArray sampler, ivec3 P, int sample)

    Description:

      Use integer texture coordinate <P> to lookup a single sample
      <sample> on the texture bound to <sampler> as described in the OpenGL
      ES specification section 11.1.3.3 "Multisample Texel Fetches".

    Syntax:

      ivec3 textureSize(gsampler2DMSArray sampler)

    Description:

      Returns the dimensions, width, height and depth of level 0 for the
      texture bound to <sampler>, as described in  the OpenGL ES
      specification section 11.1.3.4 "Texture Queries".

Errors

    The error INVALID_ENUM is generated by TexStorage3DMultisampleANGLE if
    <target> is not TEXTURE_2D_MULTISAMPLE_ARRAY_ANGLE.

    The error INVALID_OPERATION is generated by TexStorage3DMultisampleANGLE
    if zero is bound to <target>.

    The error INVALID_VALUE is generated by TexStorage3DMultisampleANGLE if
    <width> or <height> is less than 1 or greater than the value of
    MAX_TEXTURE_SIZE.

    The error INVALID_VALUE is generated by TexStorage3DMultisampleANGLE if
    <depth> is less than 1 or greater than the value of
    MAX_ARRAY_TEXTURE_LAYERS.

    The error INVALID_VALUE is generated by TexStorage3DMultisampleANGLE if
    <samples> is zero.

    The error INVALID_ENUM is generated by TexStorage3DMultisampleANGLE if
    <sizedinternalformat> is not color-renderable, depth-renderable, or
    stencil-renderable.

    The error INVALID_ENUM is generated by TexStorage3DMultisampleANGLE if
    <internalformat> is one of the unsized base internal formats listed in
    table 8.11.

    The error INVALID_OPERATION is generated by TexStorage3DMultisampleANGLE
    if <samples> is greater than the maximum number of samples supported for
    this <target> and <sizedinternalformat>, The maximum number of samples
    supported can be determined by calling GetInternalformativ with a <pname>
    of SAMPLES.

    The error INVALID_OPERATION is generated by TexStorage3DMultisampleANGLE
    if the value of TEXTURE_IMMUTABLE_FORMAT for the texture currently bound
    to <target> on the active texture unit is TRUE.

    The error OUT_OF_MEMORY is generated by TexStorage3DMultisampleANGLE
    if the GL is unable to create a texture image of the requested size.

    The error INVALID_VALUE is generated by FramebufferTextureLayer if
    <texture> identifies a two-dimensional multisample array texture, and
    <level> is not zero.

Issues

    None
