1991-2006
Silicon Graphics, Inc.
glCopyTexImage2D
3G

# glCopyTexImage2D

copy pixels into a 2D texture image

## C Specification

                    void glCopyTexImage2D
                    GLenum target
                    GLint level
                    GLenum internalformat
                    GLint x
                    GLint y
                    GLsizei width
                    GLsizei height
                    GLint border

## Parameters

`target`

  Specifies the target texture of the active texture unit. Must be `GL_TEXTURE_2D`, `GL_TEXTURE_CUBE_MAP_POSITIVE_X`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_X`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Y`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_Y`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Z`, or `GL_TEXTURE_CUBE_MAP_NEGATIVE_Z`.

`level`

  Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

`internalformat`

  Specifies the internal format of the texture. Must be one of the following symbolic constants: `GL_ALPHA`, `GL_LUMINANCE`, `GL_LUMINANCE_ALPHA`, `GL_RGB`, or `GL_RGBA`.

`x`
`y`

  Specify the window coordinates of the lower left corner of the rectangular region of pixels to be copied.

`width`

  Specifies the width of the texture image. All implementations support 2D texture images that are at least 64 texels wide and cube-mapped texture images that are at least 16 texels wide.

`height`

  Specifies the height of the texture image. All implementations support 2D texture images that are at least 64 texels high and cube-mapped texture images that are at least 16 texels high.

`border`

  Specifies the width of the border. Must be 0.

## Description

Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is active. Texturing is active when the current fragment shader or vertex shader makes use of built-in texture lookup functions.

`glCopyTexImage2D` defines a two-dimensional texture image or cube-map texture image with pixels from the current framebuffer (rather than from client memory, as is the case for glTexImage2D).

The screen-aligned pixel rectangle with lower left corner at (`x`, `y`) and with a width of `width` and a height of `height` defines the texture array at the mipmap level specified by `level`. `internalformat` specifies the internal format of the texture array.

The pixels in the rectangle are processed exactly as if glReadPixels had been called with `format` set to `GL_RGBA`, but the process stops just after conversion of RGBA values. Subsequent processing is identical to that described for glTexImage2D, beginning with the clamping of the R, G, B, and A values to the range 0 1 and then conversion to the texture's internal format for storage in the texel array.

The components required for `internalformat` must be a subset of those present in the framebuffer's format. For example, a `GL_RGBA` framebuffer can be used to supply components for any `internalformat`. However, a `GL_RGB` framebuffer can only be used to supply components for `GL_RGB` or `GL_LUMINANCE` base internal format textures, not `GL_ALPHA`, `GL_LUMINANCE_ALPHA`, or `GL_RGBA` textures.

Pixel ordering is such that lower x and y screen coordinates correspond to lower s and t texture coordinates.

If any of the pixels within the specified rectangle are outside the framebuffer associated with the current rendering context, then the values obtained for those pixels are undefined.

## Notes

A GL implementation may choose to store the texture array at any internal resolution it chooses.

An image with height or width of 0 indicates a NULL texture.

`glCopyTexImage2D` specifies a two-dimensional or cube-map texture for the current texture unit, specified with glActiveTexture.

## Errors

`GL_INVALID_ENUM` is generated if `target` is not `GL_TEXTURE_2D`, `GL_TEXTURE_CUBE_MAP_POSITIVE_X`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_X`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Y`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_Y`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Z`, or `GL_TEXTURE_CUBE_MAP_NEGATIVE_Z`.

`GL_INVALID_ENUM` is generated if `internalformat` is not an accepted format.

`GL_INVALID_VALUE` is generated if `target` is one of the six cube map 2D image targets and the width and height parameters are not equal.

`GL_INVALID_VALUE` is generated if `level` is less than 0.

`GL_INVALID_VALUE` may be generated if `level` is greater than log 2 &it; max , where max is the returned value of `GL_MAX_TEXTURE_SIZE` when `target` is `GL_TEXTURE_2D` or `GL_MAX_CUBE_MAP_TEXTURE_SIZE` when `target` is not `GL_TEXTURE_2D`.

`GL_INVALID_VALUE` is generated if `width` or `height` is less than 0 or greater than `GL_MAX_TEXTURE_SIZE` when `target` is `GL_TEXTURE_2D` or `GL_MAX_CUBE_MAP_TEXTURE_SIZE` when `target` is not `GL_TEXTURE_2D`.

`GL_INVALID_VALUE` is generated if `border` is not 0.

`GL_INVALID_OPERATION` is generated if the currently bound framebuffer's format does not contain a superset of the components required by the base format of `internalformat`.

`GL_INVALID_FRAMEBUFFER_OPERATION` is generated if the currently bound framebuffer is not framebuffer complete (i.e. the return value from glCheckFramebufferStatus is not `GL_FRAMEBUFFER_COMPLETE`).

## Associated Gets

glGet with argument `GL_MAX_TEXTURE_SIZE` or `GL_MAX_CUBE_MAP_TEXTURE_SIZE`

## See Also

glActiveTexture, glCheckFramebufferStatus, glCompressedTexImage2D, glCompressedTexSubImage2D, glCopyTexSubImage2D, glTexImage2D, glTexParameter, glTexSubImage2D

## Copyright

Copyright 1991-2006 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.