Provided by: opengl-4-man-doc_1.0~svn22917-1_all bug

NAME

       glCopyImageSubData - perform a raw data copy between two images

C SPECIFICATION

       void glCopyImageSubData(GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX,
                               GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget,
                               GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ,
                               GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth);

PARAMETERS

       srcName
           The name of a texture or renderbuffer object from which to copy.

       srcTarget
           The target representing the namespace of the source name srcName.

       srcLevel
           The mipmap level to read from the source.

       srcX
           The X coordinate of the left edge of the souce region to copy.

       srcY
           The Y coordinate of the top edge of the souce region to copy.

       srcZ
           The Z coordinate of the near edge of the souce region to copy.

       dstName
           The name of a texture or renderbuffer object to which to copy.

       dstTarget
           The target representing the namespace of the destination name dstName.

       dstX
           The X coordinate of the left edge of the destination region.

       dstY
           The Y coordinate of the top edge of the destination region.

       dstZ
           The Z coordinate of the near edge of the destination region.

       srcWidth
           The width of the region to be copied.

       srcHeight
           The height of the region to be copied.

       srcDepth
           The depth of the region to be copied.

DESCRIPTION

       glCopyImageSubData may be used to copy data from one image (i.e. texture or renderbuffer)
       to another.  glCopyImageSubData does not perform general-purpose conversions such as
       scaling, resizing, blending, color-space, or format conversions. It should be considered
       to operate in a manner similar to a CPU memcpy. CopyImageSubData can copy between images
       with different internal formats, provided the formats are compatible.

       glCopyImageSubData also allows copying between certain types of compressed and
       uncompressed internal formats. This copy does not perform on-the-fly compression or
       decompression. When copying from an uncompressed internal format to a compressed internal
       format, each texel of uncompressed data becomes a single block of compressed data. When
       copying from a compressed internal format to an uncompressed internal format, a block of
       compressed data becomes a single texel of uncompressed data. The texel size of the
       uncompressed format must be the same size the block size of the compressed formats. Thus
       it is permitted to copy between a 128-bit uncompressed format and a compressed format
       which uses 8-bit 4x4 blocks, or between a 64-bit uncompressed format and a compressed
       format which uses 4-bit 4x4 blocks.

       The source object is identified by srcName and srcTarget and the destination object is
       identified by dstName and dstTarget. The interpretation of the name depends on the value
       of the corresponding target parameter. If target is GL_RENDERBUFFER, the name is
       interpreted as the name of a renderbuffer object. If the target parameter is a texture
       target, the name is interpreted as a texture object. All non-proxy texture targets are
       accepted, with the exception of GL_TEXTURE_BUFFER and the cubemap face selectors.

       srcLevel and dstLevel identify the source and destination level of detail. For textures,
       this must be a valid level of detail in the texture object. For renderbuffers, this value
       must be zero.

       srcX, srcY, and srcZ specify the lower left texel coordinates of a srcWidth-wide by
       srcHeight-high by srcDepth-deep rectangular subregion of the source texel array.
       Similarly, dstX, dstY and dstZ specify the coordinates of a subregion of the destination
       texel array. The source and destination subregions must be contained entirely within the
       specified level of the corresponding image objects.

       The dimensions are always specified in texels, even for compressed texture formats.
       However, it should be noted that if only one of the source and destination textures is
       compressed then the number of texels touched in the compressed image will be a factor of
       the block size larger than in the uncompressed image.

       Slices of a GL_TEXTURE_1D_ARRAY, GL_TEXTURE_2D_ARRAY,
       GL_TEXTURE_CUBE_MAP_ARRAYGL_TEXTURE_3D and faces of GL_TEXTURE_CUBE_MAP are all compatible
       provided they share a compatible internal format, and multiple slices or faces may be
       copied between these objects with a single call by specifying the starting slice with srcZ
       and dstZ, and the number of slices to be copied with srcDepth. Cubemap textures always
       have six faces which are selected by a zero-based face index.

       For the purposes of CopyImageSubData, two internal formats are considered compatible if
       any of the following conditions are met: * the formats are the same, * the formats are
       considered compatible according to the compatibility rules used for texture views as
       defined in section 3.9.X. In particular, if both internal formats are listed in the same
       entry of Table 3.X.2, they are considered compatible, or * one format is compressed and
       the other is uncompressed and Table 4.X.1 lists the two formats in the same row. If the
       formats are not compatible INVALID_OPERATION is generated.

       Table 1. Sized Internal Formats
       ┌────────────────────┬────────────────────────────────────┬────────────────────────────────────────────────────────────┐
       │                    │                                    │                                                            │
       │            Texel /UncompressedCompressed                                     │
       │Block SizeInternal FormatInternal Format(s)                                         │
       │                    │                                    │                                                            │
       ├────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────────────┤
       │64-bit              │ GL_RGBA32UI, GL_RGBA32I,           │ GL_COMPRESSED_RGBA_S3TC_DXT3_EXT,                          │
       │                    │ GL_RGBA32FGL_COMPRESSED_SRGB_ALPHA_S3TC_DXT3_EXT, │
       │                    │                                    │                    GL_COMPRESSED_RGBA_S3TC_DXT5_EXT,       │
       │                    │                                    │                    GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT, │
       │                    │                                    │                    GL_COMPRESSED_RG_RGTC2,                 │
       │                    │                                    │                    GL_COMPRESSED_SIGNED_RG_RGTC2,          │
       │                    │                                    │                    GL_COMPRESSED_RGBA_BPTC_UNORM,          │
       │                    │                                    │                    GL_COMPRESSED_SRGB_ALPHA_BPTC_UNORM,    │
       │                    │                                    │                    GL_COMPRESSED_RGB_BPTC_SIGNED_FLOAT,    │
       │                    │                                    │                    GL_COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT   │
       ├────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────────────┤
       │128-bit             │ GL_RGBA16UI,                       │ GL_COMPRESSED_RGB_S3TC_DXT1_EXT,                           │
       │                    │                    GL_RGBA16I,     │                    COMPRESSED_SRGB_S3TC_DXT1_EXT,          │
       │                    │                    GL_RGBA16F,     │                    COMPRESSED_RGBA_S3TC_DXT1_EXT,          │
       │                    │                    GL_RG32F,       │                    COMPRESSED_SRGB_ALPHA_S3TC_DXT1_EXT,    │
       │                    │                    GL_RG32UI,      │                    COMPRESSED_RED_RGTC1,                   │
       │                    │                    GL_RG32I,       │                    COMPRESSED_SIGNED_RED_RGTC1             │
       │                    │                    GL_RGBA16,      │                                                            │
       │                    │                    GL_RGBA16_SNORM │                                                            │
       └────────────────────┴────────────────────────────────────┴────────────────────────────────────────────────────────────┘

ERRORS

       GL_INVALID_OPERATION is generated if the texel size of the uncompressed image is not equal
       to the block size of the compressed image.

       GL_INVALID_ENUM is generated if either target parameter is not GL_RENDERBUFFER, a valid
       non-proxy texture target other than GL_TEXTURE_BUFFER, or is one of the cubemap face
       selectors.

       GL_INVALID_ENUM is generated if target does not match the type of the object.

       GL_INVALID_OPERATION is generated if either object is a texture and the texture is not
       complete.

       GL_INVALID_OPERATION is generated if the source and destination internal formats are not
       compatible, or if the number of samples do not match.

       GL_INVALID_VALUE is generated if either name does not correspond to a valid renderbuffer
       or texture object according to the corresponding target parameter.

       GL_INVALID_VALUE is generated if the specified level of either the source or destination
       is not a valid level for the corresponding image.

       GL_INVALID_VALUE is generated if the dimensions of the either subregion exceeds the
       boundaries of the corresponding image object, or if the image format is compressed and the
       dimensions of the subregion fail to meet the alignment constraints of the format.

ASSOCIATED GETS

       glGet() with argument GL_MAX_COMPUTE_WORK_GROUP_COUNT

SEE ALSO

       glDispatchComputeIndirect().

COPYRIGHT

       Copyright © 2012 Khronos Group. This material may be distributed subject to the terms and
       conditions set forth in the Open Publication License, v 1.0, 8 June 1999.
       http://opencontent.org/openpub/.

AUTHORS

       opengl.org