glCopyTexImage2D function
The glCopyTexImage2D function copies pixels from the framebuffer into a two-dimensional texture image.
Syntax
void WINAPI glCopyTexImage2D(
GLenum target,
GLint level,
GLenum internalFormat,
GLint x,
GLint y,
GLsizei width,
GLsizei height,
GLint border
);
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.
-
internalFormat
-
The internal format and resolution of the texture data. The values 1, 2, 3, and 4 are not accepted for internalFormat. The parameter can assume one of the following symbolic values.
Constant R Bits G Bits B Bits A Bits L Bits I Bits GL_ALPHA GL_ALPHA4 4 GL_ALPHA8 8 GL_ALPHA12 12 GL_ALPHA16 16 GL_LUMINANCE GL_LUMINANCE4 4 GL_LUMINANCE8 8 GL_LUMINANCE12 12 GL_LUMINANCE16 16 GL_LUMINANCE_ALPHA GL_LUMINANCE4_ALPHA4 4 4 GL_LUMINANCE6_ALPHA2 2 6 GL_LUMINANCE8_ALPHA8 8 8 GL_LUMINANCE12_ALPHA4 4 12 GL_LUMINANCE12_ALPHA12 12 12 GL_LUMINANCE16_ALPHA16 16 16 GL_INTENSITY GL_INTENSITY4 4 GL_INTENSITY8 8 GL_INTENSITY12 12 GL_INTENSITY16 16 GL_RGB GL_R3_G3_B2 3 3 2 GL_RGB4 4 4 4 GL_RGB5 5 5 5 GL_RGB8 8 8 8 GL_RGB10 10 10 10 GL_RGB12 12 12 12 GL_RGB16 16 16 16 GL_RGBA GL_RGBA2 2 2 2 2 GL_RGBA4 4 4 4 4 GL_RGB5_A1 5 5 5 1 GL_RGBA8 8 8 8 8 GL_RGB10_A2 10 10 10 2 GL_RGBA12 12 12 12 12 GL_RGBA16 16 16 16 16 -
x
-
The window x-plane coordinate of the lower-left corner of the rectangular region of pixels to be copied.
-
y
-
The window y-plane coordinate of the lower-left corner of the rectangular region of pixels to be copied.
-
width
-
The width of the texture image. Must be 2n + 2 * border for some integer n.
-
height
-
The height of the texture image. Must be 2n + 2 * border for some integer n.
-
border
-
The width of the border. Must be either zero or 1.
Return value
This function does not return a value.
Error codes
The following error codes can be retrieved by the glGetError function.
| Name | Meaning |
|---|---|
|
target was not an accepted value. |
|
level was less than zero or greater than log2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE. |
|
border was not zero or 1. |
|
width was less than zero, greater than 2 + GL_MAX_TEXTURE_SIZE, or width cannot be represented as 2n + 2 * border for some integer n. |
|
The function was called between a call to glBegin and the corresponding call to glEnd. |
Remarks
The glCopyTexImage2D function defines a two-dimensional texture image using pixels from the current framebuffer, rather than from main memory as is the case for glTexImage2D.
Using the mipmap level specified with level, texture arrays are defined as a rectangle of pixels with the lower-left corner located at the coordinates x and y, width equal to width + (2 * border), and a height equal to height + (2 * border). The internal format of the texture array is specified with the internalFormat parameter.
The glCopyTexImage2D 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 and y coordinates corresponding to lower s and t 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.
You cannot include calls to glCopyTexImage2D in display lists.
Note
The glCopyTexImage2D 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 glDrawPixels.
The following function retrieves information related to glCopyTexImage2D:
glIsEnabled with argument GL_TEXTURE_2D
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows 2000 Professional [desktop apps only] |
| Minimum supported server |
Windows 2000 Server [desktop apps only] |
| Header |
|
| Library |
|
| DLL |
|