glCopyTexSubImage2D
[New
- Windows 95, OEM Service Release 2]
The glCopyTexSubImage2D
function copies a sub-image of a two-dimensional texture image from the frame
buffer.
void glCopyTexSubImage2D(
|
GLenum target, |
|
|
GLint level, |
|
|
GLint xoffset, |
|
|
GLint yoffset, |
|
|
GLint x, |
|
|
GLint y, |
|
|
GLsizei width, |
|
|
GLsizei height |
|
|
); |
|
Parameters
target
The target to
which the image data will be changed and can only have the value GL_TEXTURE_2D.
level
The
level-of-detail number. Level 0 is the base image. Level n is the nth
mipmap reduction image.
xoffset
The texel
offset in the x direction within the texture array.
yoffset
The texel
offset in the y direction within the texture array.
x, y
The window
coordinates of the lower-left corner of the row of pixels to be copied.
width
The width of
the sub-image of the texture image. Specifying a texture sub-image with zero
width has no effect.
height
The height of
the sub-image of the texture image. Specifying a texture sub-image with zero
width has no effect.
Remarks
The glCopyTexSubImage2D
function replaces a rectangular portion of a two-dimensional texture image with
pixels from the current frame buffer, rather than from main memory as is the
case for glTexSubImage2D.
A rectangle
of pixels beginning with the x and y window coordinates and with
the dimensions width and height replaces the portion of the
texture array with the indexes xoffset through xoffset + (width
- 1), with the indexes yoffset
through yoffset + (width - 1) at the mipmap level specified by level. The destination
rectangle in the texture array cannot include any texels outside the originally
specified texture array.
The glCopyTexSubImage2D
function processes the pixels in a row in the same way as glCopyPixels except that before the
final conversion of the pixels, all pixel component values are clamped to the
range [0, 1] and converted to the texture s internal format for storage in the
texture array. Pixel ordering is determined with lower x coordinates
corresponding to lower texture coordinates. If any of the pixels within a
specified row of the current frame buffer are outside the window associated
with the current rendering context, then their values are undefined.
If any of the
pixels within the specified rectangle of the current frame buffer are outside
the read window associated with the current rendering context, then the values
obtained for those pixels are undefined. No change is made to the internalFormat,
width, height, or border parameter of the specified
texture array or to texel values outside the specified texture sub-image.
You cannot
include calls to glCopyTexSubImage2D in display lists.
Note The glCopyTexSubImage2D
function is only available in OpenGL version 1.1 or later.
Texturing has
no effect in color-index mode. The glPixelStore and glPixelTransfer functions affect texture
images in exactly the way they affect the way pixels are drawn using glDrawPixels.
The following
functions retrieve information related to glCopyTexSubImage2D:
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D.
Error Codes
The following
are the error codes generated and their conditions.
|
Error
Code |
Condition |
|
GL_INVALID_ENUM
|
target was not an accepted value. |
|
GL_INVALID_VALUE
|
level was less than zero or greater than log sub 2(max),
where max is the returned value of GL_MAX_TEXTURE_SIZE. |
|
GL_INVALID_VALUE |
xoffset was less than border, (xoffset + width)
was greater than (w + border), yoffset was less than border,
or (yoffset + height) was greater than (h + border),
where w is GL_TEXTURE_WIDTH, h is GL_TEXTURE_HEIGHT, and border
is GL_TEXTURE_BORDER. Note that w includes twice the border width. |
|
GL_INVALID_VALUE |
width was less than border or y was less
than border, where border is the border width of the texture
array. |
|
GL_INVALID_OPERATION
|
The texture
array was not defined by a previous glTexImage2D operation. |
|
GL_INVALID_OPERATION
|
glCopyTexSubImage2D was called between a call to glBegin and the
corresponding call to glEnd. |
See Also