Draft ANGLE_texture_multisample_array spec

extensions/ANGLE_texture_multisample_array.txt

+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