kc3-lang/angle/extensions/ANGLE_get_image.txt

Branch : - branch - main - tag -

• Show log

  Commit

• Author : Jamie Madill
  Date : 2019-10-26 19:47:41
  Hash : 0964988b
  Message : Fixups to ANGLE_get_image boilerplate. - Remove level parameter from GetRenderbufferImage. - Add packed enum handling to GetTexImage. - Fix ext spec reference to table 8.4. Bug: angleproject:3944 Change-Id: I8f67608396217aaddb789dd95d0f3e2378ce918d Reviewed-on: https://chromium-review.googlesource.com/c/angle/angle/+/1879960 Reviewed-by: Cody Northrop <cnorthrop@google.com> Reviewed-by: Tim Van Patten <timvp@google.com> Commit-Queue: Jamie Madill <jmadill@chromium.org>

• extensions/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