glCopyTexImage2D

GL_APICALL void GL_APIENTRY glCopyTexImage2D(
     GLenum target,
     GLint level,
     GLenum internalformat,
     GLint x,
     GLint y,
     GLsizei width,
     GLsizei height,
     GLint border
);

	Name	Description
in	target	Target texture.
in	level	Mipmap level of the data to load.
in	internalformat	Texture format.
in	x	X coordinate at the lower-left corner of the color buffer's copy region.
in	y	Y coordinate at the lower-left corner of the color buffer's copy region.
in	width	Width of the region read from the color buffer.
in	height	Height of the region read from the color buffer.
in	border	Border width (`0` is the only valid value).

There is no return value.

Copies the content of the current color buffer into texture data.

You can set target to one of the following values.

`GL_TEXTURE_2D`	2D texture.
`GL_TEXTURE_CUBE_MAP_NEGATIVE_X`	Face of a cube-map texture in the negative x direction.
`GL_TEXTURE_CUBE_MAP_POSITIVE_X`	Face of a cube-map texture in the positive x direction.
`GL_TEXTURE_CUBE_MAP_NEGATIVE_Y`	Face of a cube-map texture in the negative y direction.
`GL_TEXTURE_CUBE_MAP_POSITIVE_Y`	Face of a cube-map texture in the positive y direction.
`GL_TEXTURE_CUBE_MAP_NEGATIVE_Z`	Face of a cube-map texture in the negative z direction.
`GL_TEXTURE_CUBE_MAP_POSITIVE_Z`	Face of a cube-map texture in the positive z direction.

To specify the region that is accessed by the GPU, set target to a bitwise OR of the aforementioned and the following values.

NN_GX_MEM_FCRAM	The GPU accesses FCRAM.
`NN_GX_MEM_VRAMA`	The GPU accesses VRAMA.
`NN_GX_MEM_VRAMB`	The GPU accesses VRAMB.

If you have not specified which region is accessed by the GPU, NN_GX_MEM_FCRAM is used. (These settings cannot be specified for POD.）

When you specify -2 or less for the level argument, all textures other than for the lowest mipmap level are automatically generated. Automatic mipmap generation is only supported for some texture formats. Also, the minimum generatable texture widths and heights (LOD upper limit) are different for each texture format. The following table shows the supported values for format and type and the minimum generatable sizes.

format	type	Minimum automatically generatable size (in texels)
`GL_RGBA`	`GL_UNSIGNED_SHORT_4_4_4_4`	64
`GL_RGBA`	`GL_UNSIGNED_SHORT_5_5_5_1`	64
`GL_RGBA`	`GL_UNSIGNED_BYTE`	32
`GL_RGB`	`GL_UNSIGNED_SHORT_5_6_5`	64
`GL_RGB`	`GL_UNSIGNED_BYTE`	32
`GL_RGBA_NATIVE_DMP`	`GL_UNSIGNED_SHORT_4_4_4_4`	64
`GL_RGBA_NATIVE_DMP`	`GL_UNSIGNED_SHORT_5_5_5_1`	64
`GL_RGBA_NATIVE_DMP`	`GL_UNSIGNED_BYTE`	32
`GL_RGB_NATIVE_DMP`	`GL_UNSIGNED_SHORT_5_6_5`	64
`GL_RGB_NATIVE_DMP`	`GL_UNSIGNED_BYTE`	32

Specifying a value for level that does not conform to the minimum sizes of the generated mipmaps listed above causes a GL_INVALID_OPERATION error.

Set internalformat to GL_RGBA, GL_RGB, or GL_GAS_DMP.

Set x and y to the coordinates at the lower-left corner of the color buffer region to copy. The x and y arguments must be multiples of 8.

Specify the width and height of the region read from the color buffer in the width and height arguments. Since this specifies the size of a texture, the values must be a power of 2 from 8 to 1024.

You must set border equal to 0.

You cannot properly render a color buffer that was rendered with 32-block mode set by glRenderBlockMode, even if you use this function to copy the buffer to a texture.

You can copy the current depth buffer to a texture and use that. Call the glEnable function and specify GL_DEPTH_STENCIL_COPY_DMP to enable the depth stencil copy feature. Call the glDisable function to disable this feature. Call the glIsEnabled function and specify GL_DEPTH_STENCIL_COPY_DMP to find if the depth stencil copy feature is enabled.

The format of the target texture for copying is determined by the format of the current depth buffer. Format conversion when copying is not supported. The format of the current depth buffer corresponds to the format of the target texture for copying as follows.

Depth Buffer Format	Depth Buffer Content	Corresponding Texture Format (Texture Type)
`GL_DEPTH24_STENCIL8_EXT`	R: 8-bit stencil value G: 24-bit depth value, bits [23:16] B: 24-bit depth value, bits [15:8] A: 24-bit depth value, bits [7:0]	`GL_RGBA` (`GL_UNSIGNED_BYTE`), `GL_RGBA_NATIVE_DMP` (`GL_UNSIGNED_BYTE`)
`GL_DEPTH_COMPONENT24_OES`	R: 24-bit depth value, bits [23:16] G: 24-bit depth value, bits [15:8] B: 24-bit depth value, bits [7:0]	`GL_RGB` (`GL_UNSIGNED_BYTE`), `GL_RGB_NATIVE_DMP` (`GL_UNSIGNED_BYTE`)
`GL_DEPTH_COMPONENT16`	R: 16-bit depth value, bits [15:8] G: 16-bit depth value, bits [7:0]	`GL_HILO8_DMP` (`GL_UNSIGNED_BYTE`), `GL_HILO8_NATIVE_DMP` (`GL_UNSIGNED_BYTE`)

For example, if the current depth buffer format is GL_DEPTH24_STENCIL8_EXT, the internalformat argument to glCopyTexImage2D must be either GL_RGBA or GL_RGBA_NATIVE_DMP. (Both have the same effect.)

The following errors occur in this function.

`GL_INVALID_OPERATION`	The target argument was set to an invalid GPU access region.
`GL_INVALID_VALUE`	The width, height, border, or level argument was set to an invalid value.
`GL_INVALID_ENUM`	The internalformat argument was set to a different format than the current color buffer.
`GL_INVALID_ENUM`	The texture format specified for internalformat does not correspond to the current depth buffer format.
`GL_OUT_OF_MEMORY`	Failed to allocate a texture data region.
`GL_INVALID_FRAMEBUFFER_OPERATION`	A color buffer has not been configured correctly for the current framebuffer.
`GL_INVALID_OPERATION`	This function was called without any command-list objects bound.

2010/09/15: Added explanation of automatic mipmap generation to the level argument description.
2010/08/12: Explained the depth stencil copy feature.
2010/07/07: Changed description of width and height arguments.
2010/01/07: Initial version.

`glCopyTexImage2D` Function

Syntax

Arguments

Return Values

Description