ANGLE_get_image.txt

Name

    ANGLE_get_image

Name Strings

    GL_ANGLE_get_image

Contributors

    Jamie Madill

Contact

    Jamie Madill (jmadill 'at' google.com)

Notice

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

Status

    Draft

Version

    Version 1, October 21, 2019

Number

    OpenGL ES Extension #??

Dependencies

    Requires OpenGL ES 2.0

    Written against the OpenGL ES 3.2 specification.

Overview

    This extension allows the OpenGL application to query and read back Texture
    and Renderbuffer pixel data. The OpenGL context exposes new queries for the
    implementation pixel format and type similar to glReadPixels. The context
    also exposes new commands to read back pixel data with these parameters.

New Procedures and Functions

    void GetTexImageANGLE(GLenum target, GLint level, GLenum format, GLenum type,
                          void *pixels);

    void GetRenderbufferImageANGLE(GLenum target, GLint level, GLenum format,
                                   GLenum type, void *pixels);

New Tokens

    None

Additions to the OpenGL ES Specification

    Update section 8.11.2 "Texture Parameter Queries":

    Change "<pname> must be one of IMAGE_FORMAT_COMPATIBILITY_TYPE, TEXTURE_-
    IMMUTABLE_FORMAT, TEXTURE_IMMUTABLE_LEVELS, or one of the symbolic
    values in table 8.19." to "<pname> must be one of IMAGE_FORMAT_COMPATIBILITY_-
    TYPE, TEXTURE_IMMUTABLE_FORMAT, TEXTURE_IMMUTABLE_LEVELS, IMPLEMENTATION_-
    COLOR_READ_TYPE, IMPLEMENTATION_COLOR_READ_FORMAT or one of the symbolic
    values in table 8.19.".

    Add a paragrah: "Querying <pname> with IMPLEMENTATION_COLOR_READ_TYPE or
    IMPLEMENTATION_COLOR_READ_FORMAT returns the implementation-dependent read
    format and type for use with GetTexImageANGLE."

    Update section 9.2.6 "Renderbuffer Object Queries":

    Add a paragraph: "If <pname> is IMPLEMENTATION_COLOR_READ_TYPE or
    IMPLEMENTATION_COLOR_READ_FORMAT then <params> will contain the
    implementation-dependent read format and type for use with
    GetRenderbufferImageANGLE."

    Add a section "Texture and Renderbuffer Image Queries":

    Texture and Renderbuffer images may be obtained from a Texture or
    Renderbuffer with the commands

    void GetTexImageANGLE(GLenum target, GLint level, GLenum format, GLenum type,
                          void *pixels);

    void GetRenderbufferImageANGLE(GLenum target, GLenum format, GLenum type,
                                   void *pixels);

    For GetTexImageANGLE, <target> specifies the target to which the texture
    object is bound. target must be one of TEXTURE_2D, TEXTURE_3D,
    TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP_ARRAY, indicating a two- or three-
    dimensional, two-dimensional array, cube map array respectively. <target>
    may also be one of the targets from table 8.20, indicating the
    corresponding face of a cube map texture.

    For GetRenderbufferImageANGLE, <target> must be RENDERBUFFER.

    <level> is a level-of-detail number, <format> is a pixel format from table 8.5,
    and <type> is a pixel type from table 8.4.

    These commands obtain component groups from a texture or renderbuffer image
    with the indicated level-of-detail. If <format> is a color format then the
    components are assigned among R, G, B, and A, starting with the first group
    in the first row, and continuing by obtaining groups in order from each row
    and proceeding from the first row to the last, and from the first image to
    the last for three-dimensional textures. Two-dimensional array and cube map
    array textures are treated as three-dimensional images, where the layers are
    treated as rows or images. Cube map textures are treated as three-dimensional
    images with a depth of 6, where the cube map faces are ordered as image layers
    as shown in table 8.24.

    If <format> is DEPTH_COMPONENT, DEPTH_STENCIL, or STENCIL_INDEX, then
    each depth component and/or stencil index is assigned with the same ordering of
    rows and images.

    These groups are then packed and placed in client or pixel buffer object memory.
    If a pixel pack buffer is bound (as indicated by a non-zero value of PIXEL_-
    PACK_BUFFER_BINDING), <pixels> is an offset into the pixel pack buffer;
    otherwise, <pixels> is a pointer to client memory. Pixel storage modes that are
    applicable to ReadPixels are applied, as described in table 16.1 and section
    16.1.2.

    For three-dimensional, two-dimensional array, cube map array, and cube map
    textures pixel storage operations are applied as if the image were two-
    dimensional, except that the additional pixel storage state values
    PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES are applied. The correspondence of texels
    to memory locations is as defined for TexImage3D in section 8.5.

    The row length, number of rows, image depth, and number of images are determined
    by the size of the texture or renderbuffer image (including any borders).

    Errors:

    An INVALID_ENUM error is generated by GetTexImage if <target> is
    not one of TEXTURE_2D, TEXTURE_3D, TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP_ARRAY,
    or one of the targets from table 8.20.

    An INVALID_ENUM error is generated by GetRenderbufferImage is <target> is not
    RENDERBUFFER.

    An INVALID_VALUE error is generated if <level> is negative or larger than
    the maximum allowable level.

    An INVALID_OPERATION error is generated if any of the following mismatches
    between <format> and the internal format of the texture or renderbuffer image
    exist:

      * <format> is a color format (one of the formats in table 8.3 whose target is
        the color buffer) and the base internal format of the texture or renderbuffer
        image is not a color format.

      * <format> is DEPTH_COMPONENT and the base internal format is not
        DEPTH_COMPONENT or DEPTH_STENCIL.

      * <format> is DEPTH_STENCIL and the base internal format is not DEPTH_-
        STENCIL.

      * <format> is STENCIL_INDEX and the base internal format is not
        STENCIL_INDEX or DEPTH_STENCIL.

      * <format> is one of the integer formats in table 8.5 and the internal format
        of the texture or renderbuffer image is not integer, or <format> is not one
        of the integer formats in table 8.5 and the internal format is integer.

    An INVALID_OPERATION error is generated if a pixel pack buffer object
    is bound and packing the texture or renderbuffer image into the buffer’s
    memory would exceed the size of the buffer.

    An INVALID_OPERATION error is generated if a pixel pack buffer object
    is bound and <pixels> is not evenly divisible by the number of basic machine
    units needed to store in memory the GL data type corresponding to type (see
    table 8.4).

Dependencies on ARB_texture_rectangle

    TEXTURE_RECTANGLE is accepted by GetTexImageANGLE and GetRenderbufferImageANGLE.

    An INVALID_VALUE error is generated if <level> is non-zero and the effective
    <target> is TEXTURE_RECTANGLE.

New State

    Add to table 21.10 "Textures (state per texture object)":

    Get Value                         Type  Get Command            Initial Value   Description                  Section
    --------------------------------  ----  -----------            -------------   ---------------------------  -------
    IMPLEMENTATION_COLOR_READ_FORMAT  E     GetTextureParameteriv  empty           Implementation pixel format  8.11.2
    IMPLEMENTATION_COLOR_READ_TYPE    E     GetTextureParameteriv  empty           Implementation pixel type    8.11.2

    Add to table 21.17 "Renderbuffer (state per renderbuffer object)":

    Get Value                         Type  Get Command                 Initial Value   Description                  Section
    --------------------------------  ----  -----------                 -------------   ---------------------------  -------
    IMPLEMENTATION_COLOR_READ_FORMAT  E     GetRenderbufferParameteriv  empty           Implementation pixel format  9.2.6
    IMPLEMENTATION_COLOR_READ_TYPE    E     GetRenderbufferParameteriv  empty           Implementation pixel type    9.2.6

Issues

    1) Should GetTexImageANGLE/GetRenderbufferImageANGLE only accept IMPLEMENTATION-
       _COLOR_READ_FORMAT/TYPE or should they behave the same as GetTexImage in GL?

       Resolved: Keep the spec wording closer to the desktop GL version. It should
       not involve much additional implementation work except for validation.

Revision History

    Rev.    Date         Author                 Changes
    ----  -------------  ---------              ----------------------------------------
      1   Oct 24, 2019   jmadill                Initial version