glCopyImageSubData man page on RedHat

glCopyImageSubData man page on RedHat

Man page or keyword search:
man Server 29550 pages
apropos Keyword Search (all sections)
Output format

GLCOPYIMAGESUBDATA(3G) OpenGL Manual GLCOPYIMAGESUBDATA(3G)

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_ARRAY GL_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 / │ Uncompressed │ Compressed │
│Block Size │ Internal Format │ Internal Format(s) │
│ │ │ │
├────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────────────┤
│64-bit │ GL_RGBA32UI, GL_RGBA32I, │ GL_COMPRESSED_RGBA_S3TC_DXT3_EXT, │
│ │ GL_RGBA32F │ GL_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