glTexImage2D

GL_APICALL void GL_APIENTRY glTexImage2D(
     GLenum target,
     GLint level,
     GLenum internalformat,
     GLsizei width,
     GLsizei height,
     GLint border,
     GLenum format,
     GLenum type,
     const void * pixels
);

	Name	Description
in	target	Target texture.
in	level	Mipmap level of the data to load.
in	internalformat	Internal texture format (the same as format).
in	width	Texture width.
in	height	Texture height.
in	border	Border width (`0` is the only valid value).
in	format	Texture format.
in	type	Texture type.
in	pixels	Pointer to the texture data.

No values are returned.

Configures 2D 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 main memory.
`NN_GX_MEM_VRAMA`	The GPU accesses VRAMA.
`NN_GX_MEM_VRAMB`	The GPU accesses VRAMB. By also specifying the following bitwise OR, you can specify whether to copy data to main memory.
`GL_COPY_FCRAM_DMP`	Create data copy in main memory.
`GL_NO_COPY_FCRAM_DMP`	Do not create data copy in main memory. These combinations cause data to be transferred as follows.
(`NN_GX_MEM_FCRAM` \| `GL_NO_COPY_FCRAM_DMP`)	The GPU directly accesses the region specified by data.
(`NN_GX_MEM_VRAMA` \| `GL_NO_COPY_FCRAM_DMP`)	A region is allocated in VRAMA; data is transferred to VRAMA via DMA; and then the GPU accesses VRAMA.
(`NN_GX_MEM_VRAMB` \| `GL_NO_COPY_FCRAM_DMP`)	A region is allocated in VRAMB; data is transferred to VRAMB via DMA; and then the GPU accesses VRAMB.
(`NN_GX_MEM_FCRAM` \| `GL_COPY_FCRAM_DMP`)	A region is allocated in main memory; data is copied to main memory by the CPU; and then the GPU accesses main memory.
(`NN_GX_MEM_VRAMA` \| `GL_COPY_FCRAM_DMP`)	A region is allocated in main memory and VRAMA; data is copied to main memory by the CPU; data is transferred via DMA from main memory to VRAMA, and then the GPU accesses VRAMA.
(`NN_GX_MEM_VRAMB` \| `GL_COPY_FCRAM_DMP`)	A region is allocated in main memory and VRAMB; data is copied to main memory by the CPU; data is transferred via DMA from main memory to VRAMB, and then the GPU accesses VRAMB.

If a GPU access region is not specified for the target argument and there is no specification about copying to main memory, then the processes (NN_GX_MEM_FCRAM | GL_COPY_FCRAM_DMP) are applied. However, if NULL is specified for pixels, then the processes (NN_GX_MEM_VRAMB | GL_NO_COPY_FCRAM_DMP) are applied.

Set width and height to the texture size. You must use powers of 2 between 8 and 1024. You must set width and height to the same value for cube-map textures.

You must set border equal to 0.

You must set internalformat and format to the same value. You can set internalformat and format to the following values.

`GL_RGBA`
`GL_RGB`
`GL_SHADOW_DMP`
`GL_GAS_DMP`
`GL_ALPHA`
`GL_LUMINANCE`
`GL_LUMINANCE_ALPHA`
`GL_HILO8_DMP`
`GL_RGBA_NATIVE_DMP`
`GL_RGB_NATIVE_DMP`
`GL_ALPHA_NATIVE_DMP`
`GL_LUMINANCE_NATIVE_DMP`
`GL_LUMINANCE_ALPHA_NATIVE_DMP`
GL_SHADOW_NATIVE_DMP
GL_GAS_NATIVE_DMP
`GL_HILO8_DMP_NATIVE_DMP`

If a *_NATIVE_DMP format is specified, then the data specified for pixels must be in the PICA native format. If the specified data is in any other format, a corrputed picture is displayed and no error is generated.

Set type to one of the following values.

`GL_UNSIGNED_BYTE`
`GL_UNSIGNED_SHORT`
`GL_UNSIGNED_INT`
`GL_UNSIGNED_SHORT_4_4_4_4`
`GL_UNSIGNED_SHORT_5_5_5_1`
`GL_UNSIGNED_SHORT_5_6_5`
`GL_UNSIGNED_BYTE_4_4_DMP`
`GL_UNSIGNED_4BITS_DMP`

The following restrictions apply to combinations of type and format.

type	format
`GL_UNSIGNED_BYTE`	Cannot specify `GL_GAS_DMP`, `GL_SHADOW_DMP`
`GL_UNSIGNED_SHORT`	Limited to `GL_GAS_DMP` and `GL_GAS_NATIVE_DMP`
`GL_UNSIGNED_INT`	Limited to `GL_SHADOW_DMP` and `GL_SHADOW_NATIVE_DMP`
`GL_UNSIGNED_SHORT_4_4_4_4` or `GL_UNSIGNED_SHORT_5_5_5_1`	Limited to `GL_RGBA`, `GL_RGBA_NATIVE_DMP`
`GL_UNSIGNED_SHORT_5_6_5`	Limited to `GL_RGB`, `GL_RGB_NATIVE_DMP`
`GL_UNSIGNED_BYTE_4_4_DMP`	Limited to `GL_LUMINANCE_ALPHA`, `GL_LUMINANCE_ALPHA_NATIVE_DMP`
`GL_UNSIGNED_4BITS_DMP`	Limited to `GL_ALPHA`, `GL_LUMINANCE`, `GL_ALPHA_NATIVE_DMP`, `GL_LUMINANCE_NATIVE_DMP`

The following restrictions apply to combinations of target, type and format.

target	type	format
`GL_TEXTURE_CUBE_MAP_NEGATIVE_X`, `GL_TEXTURE_CUBE_MAP_POSITIVE_X`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_Y`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Y`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_Z`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Z`	`GL_RGB`, `GL_RGB_NATIVE_DMP`	Limited to `GL_UNSIGNED_SHORT_5_6_5`

Mipmap levels are loaded all at once rather than individually. You cannot separately load data for multiple mipmap levels. Set level to the negative value of the number of mipmaps to load. (0 and -1 are treated the same. ) No value greater than 0 may be specified for level.

Set pixels to a pointer to the texture data to load. When data is loaded for multiple mipmap levels, it is stored in ascending level order starting with level 0. If 0 has been specified for pixels, a texture region is secured and nothing else.

The following errors occur in this function.

`GL_INVALID_ENUM`	The target, format, internalformat, or type argument was set to an invalid value.
`GL_INVALID_VALUE`	The width, height, or level argument was set to an invalid value.
`GL_INVALID_OPERATION`	An invalid combination of type and format was specified.
`GL_INVALID_OPERATION`	The format and internalformat arguments are set to different values.
`GL_INVALID_OPERATION`	`GL_NO_COPY_FCRAM_DMP \| NN_GX_MEM_FCRAM` was specified, and format is not a native format or pixels is 0.
`GL_INVALID_OPERATION`	`GL_NO_COPY_FCRAM_DMP \| NN_GX_MEM_VRAMA` (or `NN_GX_MEM_VRAMB`) was specified, pixels is nonzero, and format is not a native format.
`GL_INVALID_OPERATION`	`GL_COPY_FCRAM_DMP \| NN_GX_MEM_VRAMA` (or `NN_GX_MEM_VRAMB`) was specified and pixels is 0.
`GL_OUT_OF_MEMORY`	Failed to allocate texture memory.

2011/02/18: Fixed the omission of the GL_SHADOW_NATIVE_DMP and GL_GAS_NATIVE_DMP formats. Fixed an incorrect argument name, changing "data" to pixels.
2010/09/30: Added text about specifying a GPU access region and copying to main memory when the pixels argument is set to NULL.
2010/08/20: Matched the layout of the type and type and format tables.
2010/08/02: Revised layout of the Description section. Fixed accidental omission of type argument.
2010/05/07: Revised error conditions.
2010/03/11: Revised terminology. Added a description of the default value for the target argument.
2010/01/07: Initial version.

`glTexImage2D` Function

Syntax

Parameters

Return Values

Description