glCopyTexSubImage2D function

The glCopyTexSubImage2D function copies a sub-image of a two-dimensional texture image from the framebuffer.

Syntax


void WINAPI 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. Must 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

The window x-plane coordinates of the lower-left corner of the row of pixels to be copied.

y

The window y-plane 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.

Return value

This function does not return a value.

Error codes

The following error codes can be retrieved by the glGetError function.

NameMeaning
GL_INVALID_ENUM

target was not an accepted value.

GL_INVALID_VALUE

level was less than zero or greater than log₂ (max), where max is the returned value of GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE

xoffset was less than border or (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 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 glTexImage1D operation.

GL_INVALID_OPERATION

The function was called between a call to glBegin and the corresponding call to glEnd.

Error codes

The following error codes can be retrieved by the glGetError function.

NameMeaning
GL_INVALID_ENUM

target was not an accepted value.

GL_INVALID_VALUE

level was less than zero or greater than log₂ (max), where max is the returned value of GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE

xoffset was less than border or (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 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 glTexImage1D operation.

GL_INVALID_OPERATION

The function was called between a call to glBegin and the corresponding call to glEnd.

Remarks

The glCopyTexSubImage2D function replaces a rectangular portion of a two-dimensional texture image with pixels from the current framebuffer, 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 framebuffer 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 framebuffer 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

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Gl.h

Library

Opengl32.lib

DLL

Opengl32.dll

See also

glBegin
glCopyPixels
glCopyTexSubImage1D
glDrawPixels
glEnd
glFog
glPixelStore
glPixelTransfer
glTexEnv
glTexGen
glTexImage2D
glTexSubImage2D
glTexParameter

 

 

Show: