glCopyTexImage2D Function

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.