xref: /aosp_15_r20/external/angle/extensions/CHROMIUM_copy_texture.txt (revision 8975f5c5ed3d1c378011245431ada316dfb6f244)

Name

    CHROMIUM_copy_texture

Name Strings

    GL_CHROMIUM_copy_texture

Version

    Last Modifed Date: March 24, 2017

Dependencies

    OpenGL ES 2.0 or OpenGL ES 3.0 is required.

    EXT_texture_format_BGRA8888 affects the definition of this extension.
    ARB_texture_rg affects the definition of this extension.
    CHROMIUM_ycbcr_422_image affects the definition of this extension.

Overview

    This extension expands on the functionality provided by the
    glCopyTexImage2D command.  A new function is exported,
    glCopyTextureCHROMIUM, that performs the same copy operation as
    glCopyTexImage2D.

    The extension also supports copying BGRA textures and copying
    EXTERNAL_OES texture to BGRA texture, which is not explicitly
    granted by EXT_texture_format_BGRA8888.

New Procedures and Functions

    void CopyTextureCHROMIUM(uint sourceId,
                             int sourceLevel,
                             enum destTarget,
                             uint destId,
                             int destLevel,
                             int internalFormat,
                             enum destType,
                             boolean unpackFlipY,
                             boolean unpackPremultiplyAlpha,
                             boolean unpackUnmultiplyAlpha)


    void CopySubTextureCHROMIUM(uint sourceId,
                                int sourceLevel,
                                enum destTarget,
                                uint destId,
                                int destLevel,
                                int xoffset,
                                int yoffset,
                                int x,
                                int y,
                                sizei width,
                                sizei height,
                                boolean unpackFlipY,
                                boolean unpackPremultiplyAlpha,
                                boolean unpackUnmultiplyAlpha)

Additions to the OpenGL ES 2.0 Specification

    The command

        CopyTextureCHROMIUM

    Copies the contents of <sourceLevel> level of <sourceId> texture to
    <destLevel> level and <destTarget> target of <destId> texture.

    <destTarget> must be TEXTURE_2D,
    TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_NEGATIVE_X,
    TEXTURE_CUBE_MAP_POSITIVE_Y, TEXTURE_CUBE_MAP_NEGATIVE_Y,
    TEXTURE_CUBE_MAP_POSITIVE_Z, TEXTURE_CUBE_MAP_NEGATIVE_Z,
    TEXTURE_RECTANGLE_ARB.

    The internal format of the destination texture is converted to that
    specified by <internalFormat>.

    When source texture doens't contain a superset of the component
    required by <internalFormat>, fill the components by following rules.

       source format           color components
       ----------------------------------------
       ALPHA                   (0, 0, 0, A)
       RED                     (R, 0, 0, 1)
       LUMINANCE               (L, L, L, 1)
       LUMINANCE_ALPHA         (L, L, L, A)
       RGB                     (R, G, B, 1)
       RGB8                    (R, G, B, 1)
       RGBA                    (R, G, B, A)
       RGBA8                   (R, G, B, A)
       BGRA_EXT                (R, G, B, A)
       BGRA8_EXT               (R, G, B, A)
       RGB_YCBCR_420V_CHROMIUM (R, G, B, 1)
       RGB_YCBCR_422_CHROMIUM  (R, G, B, 1)

    The format type of the destination texture is converted to that specified
    by <destType>.

    If <flipY> is true, vertically flip texture image data.

    If <unpackPremultiplyAlpha> and <unpackUnmultiplyAlpha> are true,
    no alpha processing occurs.  This is the equivalent of having neither flag
    set.

    When <sourceId> refers to a stream texture, the texture matrix will be
    applied as part of the copy operation.

    INVALID_OPERATION is generated if <internalFormat> is not one of the
    formats in Table 1.0.

    INVALID_OPERATION is generated if the internal format of <sourceId> is not
    one of formats in Table 1.1.

    INVALID_VALUE is generated if <sourceId> or <destId> are not valid texture
    objects.

    INVALID_ENUM is generated if <destTarget> is not one of the valid targets
    described above.

    INVALID_OPERATION is generated if the bound target of destination texture
    does not match <target>.

    INVALID_VALUE is generated if textures corresponding to <destId> have not
    been bound as TEXTURE_2D, TEXTURE_CUBE_MAP, or
    TEXTURE_RECTANGLE_ARB objects.

    INVALID_VALUE is generated if textures corresponding to <sourceId> have not
    been bound as TEXTURE_2D, TEXTURE_RECTANGLE_ARB or
    TEXTURE_EXTERNAL_OES objects.

    INVALID_VALUE is generated if <sourceLevel> is not 0 for ES 2.0, or if
    <sourceLevel> or <destLevel> is less than 0 for ES 3.0.

    INVALID_VALUE is generated if <sourceLevel> of the source texture is not
    defined.

    The command

        CopySubTextureCHROMIUM

    Copies the sub contents of texture referred to by <sourceId> to <destId>
    texture without redefining <destId> texture.

    See CopyTextureCHROMIUM for the interpretation of the <destTarget>,
    <sourceLevel>, <destLevel>, <flipY>, <premultiplyAlpha>, and
    <unmultiplyAlpha> arguments.

    <xoffset> and <yoffset> specify a texel offset in the x and y direction
    respectively within the destination texture.

    <x> and <y> specify specify a texel offset in the x and y direction
    respectively within the source texture.

    <width> specifies the width of the texture subimage.

    <height> specifies the width of the texture subimage.

    INVALID_VALUE is generated if either <sourceId> texture or <destId>
    texture is not defined.

    INVALID_OPERATION is generated if the internal format of <sourceId> or
    <destId> is not one of formats in Table 1.1.

    INVALID_OPERATION is generated if the destination texture array has not
    been defined.

    INVALID_VALUE is generated if <destId> texture is not bound as
    TEXTURE_2D or TEXTURE_RECTANGLE_ARB.

    INVALID_VALUE is generated if level 0 of the source texture or
    the destination texture is not defined.

    INVALID_VALUE is generated if (<xoffset> + <width>) > destWidth,
    or (<yoffset> + <height>) > destHeight.

    Table 1.0 Valid internal formats for CopyTextureCHROMIUM:

        <internalFormat>
        ---------------
        ALPHA
        BGRA8_EXT
        BGRA_EXT
        LUMINANCE
        LUMINANCE_ALPHA
        R11F_G11F_B10F
        R16F
        R32F
        R8
        R8UI
        RG16F
        RG32F
        RG8
        RG8UI
        RGB
        RGB10_A2
        RGB16F
        RGB32F
        RGB565
        RGB5_A1
        RGB8
        RGB8UI
        RGB9_E5
        RGBA
        RGBA16F
        RGBA32F
        RGBA4
        RGBA8
        RGBA8UI
        RGBX8_ANGLE
        SRGB8
        SRGB8_ALPHA8
        SRGB_ALPHA_EXT
        SRGB_EXT

    Table 1.1 Valid source texture internal formats for CopyTextureCHROMIUM and
    source and destination formats for CopySubTextureCHROMIUM:

        internal format
        ---------------
        RED
        ALPHA
        LUMINANCE
        LUMINANCE_ALPHA
        RGB
        RGBA
        RGB8
        RGBA8
        BGRA_EXT
        BGRA8_EXT
        RGB_YCBCR_420V_CHROMIUM
        RGB_YCBCR_422_CHROMIUM

Dependencies on ARB_texture_rg

    If ARB_texture_rg is not supported:
     * delete any reference to the R8 format.

Dependencies on CHROMIUM_ycbcr_422_image

    If CHROMIUM_ycbcr_422_image is not supported:
     * delete any reference to the RGB_YCBCR_422_CHROMIUM format.

Errors

    None.

New Tokens

    None.

New State

    None.

Revision History

    8/1/2011    Documented the extension
    7/4/2013    Add a new parameter dest_type to glCopyTextureCHROMIUM()
    16/7/2014   Add TEXTURE_RECTANGLE_ARB as valid source_id target
    19/6/2015   Add arguments unpack_flip_y, unpack_premultiply_alpha, and
                unpack_unmultiply_alpha to both commands.
    4/1/2016    Removed the argument target.
    4/1/2016    Added TEXTURE_RECTANGLE_ARB as valid dest_id target.
    19/12/2016  Supported more ES 3.0 formats.
    18/1/2017   Supported source_level and dest_level.
    19/1/2017   Added TEXTURE_CUBE_MAP as valid dest_id target.
    24/3/2017   Clean up naming and move formats into tables.