一、描述

specify a two-dimensional texture image.

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.
纹理将指定纹理图像的一部分映射到纹理化为活动的每个图形基元上。当前片段着色器或顶点着色器使用内置纹理查找函数时，纹理处于活动状态。

To define texture images, call glTexImage2D. The arguments describe the parameters of the texture image, such as height, width, level-of-detail number (see glTexParameter), and format. The last three arguments describe how the image is represented in memory.
要定义纹理图像，请调用glTexImage2D。参数描述纹理图像的参数，如高度，宽度，细节级别（详见glTexParameter）以及格式。最后三个参数描述了图像在内存中的表示方式。

在调用该函数之前，必须调用glBindTexture(GL_TEXTURE_2D, mTextureID )以指定要操作的纹理ID。

二、C函数

// 指定一个二维的纹理图片，specify a two-dimensional texture image
void glTexImage2D (GLenum     target,         // 目标纹理
                   GLint     level,             // 纹理等级（多级纹理）
                   GLint     internalformat, // 纹理格式
                   GLsizei     width,             // 纹理宽度
                   GLsizei     height,         // 纹理高度
                   GLint     border,         // the width of the border.
                   GLenum     format,         // the format of the texel data
                   GLenum     type,             // the data type of the texel data
                   const GLvoid *data);        // a pointer to the image data in memory

参数_target

指定活动纹理单元的目标纹理。
Specifies the target texture of the active texture unit.
必须是以下值之一：

GL_TEXTURE_2D
GL_TEXTURE_CUBE_MAP_POSITIVE_X
GL_TEXTURE_CUBE_MAP_POSITIVE_Y
GL_TEXTURE_CUBE_MAP_POSITIVE_Z
GL_TEXTURE_CUBE_MAP_NEGATIVE_X
GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
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.
执行细节级别。0是最基本的图像级别，n表示第N级贴图细化级别。

参数_internalformat
Specifies the internal format of the texture.
必须是以下值之一：
GL_ALPHA
GL_LUMINANCE
GL_LUMINANCE_ALPHA
GL_RGB
GL_RGBA
参数_width/height
Specifies the width/height 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.
指定纹理图像的宽度/高度，必须是2的n次方。二维纹理图片至少要支持64个纹素的宽度/高度，立方体贴图纹理必须支持16个纹素宽度/高度。

width×height texels（纹素） are read from memory, starting at location data. By default, these texels are taken from adjacent memory locations, except that after all width texels are read, the read pointer is advanced to the next four-byte boundary. The four-byte row alignment is specified by glPixelStorei with argument GL_UNPACK_ALIGNMENT, and it can be set to 1, 2, 4, or 8 bytes.
The first element corresponds to the lower left corner of the texture image. Subsequent elements progress left-to-right through the remaining texels in the lowest row of the texture image, and then in successively higher rows of the texture image. The final element corresponds to the upper right corner of the texture image.

参数_border

指定边框的宽度。必须为0。
Specifies the width of the border. Must be 0.

参数_format

Specifies the format of the texel data. Must match internalformat.
format决定data中每个元素的组成。它可以采用以下符号值之一：

GL_ALPHA
- 每个元素就是单个alpha分量（alpha component），具体大小由type决定。
GL_RGB
- 每个元素有R、G、B三个分量（color component）。
GL_RGBA
- 每个元素有R、G、B、A四个分量组成。
GL_LUMINANCE
- 每个元素由R、G、B、A四个分量组成，R、G、B为复制的luminance值，A为1.0。
GL_LUMINANCE_ALPHA
- 每个元素由R、G、B、A四个分量组成，R、G、B为复制的luminance值。
  
  GL_ALPHA
  每个元素都是单个alpha分量。 GL将其转换为浮点并通过将rgb三通道赋值为0组装成RGBA元素。然后将每个元素的值范围截断于[0,1]。
  Each element is a single alpha component. The GL converts it to floating point and assembles it into an RGBA element by attaching 0 for red, green, and blue. Each component is then clamped to the range [0,1].
  
  GL_RGB
  每个元素都是RGB三元组。 GL将其转换为浮点，并通过为alpha赋值为1将其组装成RGBA元素。然后将每个元素的值范围截断于[0,1]。
  Each element is an RGB triple. The GL converts it to floating point and assembles it into an RGBA element by attaching 1 for alpha. Each component is then clamped to the range [0,1].
  
  GL_RGBA
  每个元素包含所有四个组件。 GL将其转换为浮点，然后将每个元素的值范围截断于[0,1]。
  Each element contains all four components. The GL converts it to floating point, then each component is clamped to the range [0,1].
  
  GL_LUMINANCE
  每个元素是单个亮度值。 GL将其转换为浮点，然后通过将亮度值复制三次（红色，绿色和蓝色）并将为alpha赋值为1来将其组合成RGBA元素。然后将每个元素的值范围截断于[0,1]。
  Each element is a single luminance value. The GL converts it to floating point, then assembles it into an RGBA element by replicating the luminance value three times for red, green, and blue and attaching 1 for alpha. Each component is then clamped to the range [0,1].
  
  GL_LUMINANCE_ALPHA
  每个元素是“亮度-α”对。 GL将其转换为浮点，然后通过将亮度值复制三次（红色，绿色和蓝色）将其组装成RGBA元素。然后将每个元素的值范围截断于[0,1]。
  Each element is a luminance/alpha pair. The GL converts it to floating point, then assembles it into an RGBA element by replicating the luminance value three times for red, green, and blue. Each component is then clamped to the range [0,1].
  
  参数_type
  Specifies the data type of the texel data.
  前面的format决定像素矩形每个元素的组成（分量），而type决定每个分量的大小。
  
  必须是以下值之一：
GL_UNSIGNED_BYTE
- 每个分量的大小为1个byte
GL_UNSIGNED_SHORT_5_6_5
- R、G、B分量的大小分别为5bits、6bits、5bits。
GL_UNSIGNED_SHORT_4_4_4_4
- R、G、B、A分量的大小为4bits
GL_UNSIGNED_SHORT_5_5_5_1
- R、G、B、A分量的大小为5bits、5bits、5bits、1bit。

颜色组件（color components）根据type转换为浮点。
当type是GL_UNSIGNED_BYTE时，每个组件除以2-1，每个分量是一个byte大小。
当type为GL_UNSIGNED_SHORT_5_6_5，
GL_UNSIGNED_SHORT_4_4_4_4，
GL_UNSIGNED_SHORT_5_5_5_1时，每个分量除以2-1，其中N是位域中的位数，所有分量总共占用一个short大小。

参数_data

图像数据指针，是一个ubyte或ushort数组。
Specifies a pointer to the image data in memory.

Data is read from data as a sequence of unsigned bytes or shorts, depending on type.
When type is GL_UNSIGNED_BYTE, each of the bytes is interpreted as one color component.
When type is one of GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4, or GL_UNSIGNED_SHORT_5_5_5_1, each unsigned short value is interpreted as containing all the components for a single texel, with the color components arranged according to format. Color components are treated as groups of one, two, three, or four values, again based on format. Groups of components are referred to as texels（纹理像素，简称纹素）.

三、示例

unsigned int mTextureID;
glGenTextures(1, &mTextureID);                // 返回一个没有被使用的纹理ID，保存在mTextureID上。
glBindTexture(GL_TEXTURE_2D, mTextureID );    // 后续的纹理操作都在mTextureID这个纹理上。
glTexParameteri(GL_TEXTURE_2D,GL_TEXTURE_MAG_FILTER,GL_LINEAR);    //纹理过滤参数设置
glTexParameteri(GL_TEXTURE_2D,GL_TEXTURE_MIN_FILTER,GL_LINEAR);
//上传为到GPU中
glTexImage2D(GL_TEXTURE_2D,     // target
             0,                 // level
             GL_RGB,             // internalformat
             width,                // width
             height,             // height
             0,                 // border
             GL_RGB,             // format
             GL_UNSIGNED_BYTE,     // type
             pData );            // data

四、注意

internalformat必须匹配format。纹理图像处理期间不支持格式之间的转换。 type可以用作提示来指定所需的精度，但GL实现可以选择以任何内部分辨率存储纹理数组。
data可能是一个空指针。在这种情况下，会分配纹理内存以适应宽度width和高度的纹理height。然后你可以下载子文本来初始化这个纹理内存。如果用户尝试将纹理图像的未初始化部分应用于基元，则图像未定义。
glTexImage2D是用来指定由glActiveTexture指定的纹理单元是二维纹理还是立体贴图纹理的。

五、错误

GL_INVALID_ENUM

如果target不是：
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，
GL_TEXTURE_CUBE_MAP_NEGATIVE_Z。

如果format或type不是可接受的值。

GL_INVALID_VALUE

如果target是立方体贴图中的一个2维贴图，但是宽和高却不相等。（立方体贴图每个维度都是相等的）

level比0小。

如果level大于log以2为低⁡max的对数。（max是target为GL_TEXTURE_2D时GL_MAX_TEXTURE_SIZE的返回值，或者当target不是GL_TEXTURE_2D时GL_MAX_CUBE_MAP_TEXTURE_SIZE的返回值）

当internalformat是一个不可接收的值。

当height或width的值value或者当target为GL_TEXTURE_2D时value大于GL_MAX_TEXTURE_SIZE，或者当target不为GL_TEXTURE_2D时value大于GL_MAX_CUBE_MAP_TEXTURE_SIZE。

当border的值不为0时。

GL_INVALID_OPERATION

format和internalformat不匹配。

type是GL_UNSIGNED_SHORT_5_6_5但是format不是GL_RGB。

type是GL_UNSIGNED_SHORT_4_4_4_4或者GL_UNSIGNED_SHORT_5_5_5_1但format不是GL_RGBA。

glTexImage2D

一、描述

二、C函数

参数_target

参数_level

参数_internalformat

参数_width/height

参数_border

参数_format

GL_ALPHA

GL_RGB

GL_RGBA

GL_LUMINANCE

GL_LUMINANCE_ALPHA