glTexImage2D 函数

项目
10/12/2023

glTexImage2D 函数指定二维纹理图像。

语法

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

参数

目标

目标纹理。必须为 GL_TEXTURE_2D。

level

细节级别编号。级别 0 是基础图像级别。级别 n 是第 n 个 mipmap 缩减图像。

internalformat

纹理中颜色分量的数量。必须为 1、2、3 或 4 或以下符号常量之一：GL_ALPHA、GL_ALPHA4、GL_ALPHA8、GL_ALPHA12、GL_ALPHA16、GL_LUMINANCE、GL_LUMINANCE4、GL_LUMINANCE8、GL_LUMINANCE12、GL_LUMINANCE16、GL_LUMINANCE_ALPHA、GL_LUMINANCE4_ALPHA4、GL_LUMINANCE6_ALPHA2、GL_LUMINANCE8_ALPHA8、GL_LUMINANCE12_ALPHA4、GL_LUMINANCE12_ALPHA12、GL_LUMINANCE16_ALPHA16、GL_INTENSITY、GL_INTENSITY4、GL_INTENSITY8、GL_INTENSITY12、GL_INTENSITY16、GL_R3_G3_B2、GL_RGB、GL_RGB4、GL_RGB5、GL_RGB8、GL_RGB10、GL_RGB12、GL_RGB16、GL_RGBA、GL_RGBA2、GL_RGBA4、GL_RGB5_A1、GL_RGBA8、GL_RGB10_A2、GL_RGBA12 或 GL_RGBA16。

width

纹理图像的宽度。对于某些整数 n，必须为 2n + 2(border)。

height

纹理图像的高度。对于某些整数 m，必须为 2*^m* + 2(border)。

border

边框的宽度。必须为 0 或 1。

format

像素数据的格式。它可以假定 9 个符号值之一。

值	含义
GL_COLOR_INDEX	每个元素都是一个单独的值，即一个颜色索引。它将转换为固定点（二进制点右侧有未指定的 0 位数字），根据 GL_INDEX_SHIFT 的值和符号向左或向右移动，并添加到 GL_INDEX_OFFSET（请参阅 glPixelTransfer）。生成的索引使用 GL_PIXEL_MAP_I_TO_R、GL_PIXEL_MAP_I_TO_G、GL_PIXEL_MAP_I_TO_B 和 GL_PIXEL_MAP_I_TO_A 表转换为一组颜色分量，并限定在范围 [0,1] 内。
GL_RED	每个元素都是单个红色分量。它通过附加 0.0 表示绿色和蓝色，以及 1.0 表示 alpha，将其转换为浮点并组合为 RGBA 元素。然后，每个分量乘以有符号比例因子 GL_c_SCALE，添加到有符号偏差 GL_c_BIAS，并限定在范围 [0,1] 内（请参阅 glPixelTransfer）。
GL_GREEN	每个元素都是单个绿色分量。它通过附加 0.0 表示红色和蓝色，以及 1.0 表示 alpha，将其转换为浮点并组合为 RGBA 元素。然后，每个分量乘以有符号比例因子 GL_c_SCALE，添加到有符号偏差 GL_c_BIAS，并限定在范围 [0,1] 内（请参阅 glPixelTransfer）。
GL_BLUE	每个元素都是单个蓝色分量。它通过附加 0.0 表示红色和绿色，以及 1.0 表示 alpha，将其转换为浮点并组合为 RGBA 元素。然后，每个分量乘以有符号比例因子 GL_c_SCALE，添加到有符号偏差 GL_c_BIAS，并限定在范围 [0,1] 内（请参阅 glPixelTransfer）。
GL_ALPHA	每个元素都是单个红色分量。它通过附加 0.0 表示红色、绿色和蓝色，转换为浮点并组合为 RGBA 元素。然后，每个分量乘以有符号比例因子 GL_c_SCALE，添加到有符号偏差 GL_c_BIAS，并限定在范围 [0,1] 内（请参阅 glPixelTransfer）。
GL_RGB	每个元素都是 RGB 三元组。它通过附加 1.0 表示 alpha 来转换为浮点并组合为 RGBA 元素。然后，每个分量乘以有符号比例因子 GL_c_SCALE，添加到有符号偏差 GL_c_BIAS，并限定在范围 [0,1] 内（请参阅 glPixelTransfer）。
GL_RGBA	每个元素都是完整的 RGBA 元素。它转换为浮点。然后，每个分量乘以有符号比例因子 GL_c_SCALE，添加到有符号偏差 GL_c_BIAS，并限定在范围 [0,1] 内（请参阅 glPixelTransfer）。
GL_BGR_EXT	每个像素按以下顺序由三个分量组成：蓝色、绿色、红色。 GL_BGR_EXT 提供与 Windows 与设备无关的位图 (DIB) 的内存布局匹配的格式。因此，应用程序可以将相同的数据用于 Windows 函数调用和 OpenGL 像素函数调用。
GL_BGRA_EXT	每个像素按以下顺序由四个分量组成：蓝色、绿色、红色和 alpha。 GL_BGRA_EXT 提供与 Windows 与设备无关的位图 (DIB) 的内存布局匹配的格式。因此，应用程序可以将相同的数据用于 Windows 函数调用和 OpenGL 像素函数调用。
GL_LUMINANCE	每个元素都是单个亮度值。它通过复制亮度值三次表示红色、绿色和蓝色，并附加 1.0 表示 alpha，转换为浮点并将其组合成 RGBA 元素。然后，每个分量乘以有符号比例因子 GL_c_SCALE，添加到有符号偏差 GL_c_BIAS，并限定在范围 [0,1] 内（请参阅 glPixelTransfer）。
GL_LUMINANCE_ALPHA	每个元素都是亮度/alpha 对。它通过复制亮度值三次表示红色、绿色和蓝色，转换为浮点并将其组合成 RGBA 元素。然后，每个分量乘以有符号比例因子 GL_c_SCALE，添加到有符号偏差 GL_c_BIAS，并限定在范围 [0,1] 内（请参阅 glPixelTransfer）。

type

像素数据的数据类型。接受以下符号值：GL_UNSIGNED_BYTE、GL_BYTE、GL_BITMAP、GL_UNSIGNED_SHORT、GL_SHORT、GL_UNSIGNED_INT、GL_INT 和 GL_FLOAT。

像素

指向内存中图像数据的指针。

返回值

此函数不返回值。

错误代码

glGetError 函数可以检索以下错误代码。

名称	含义
GL_INVALID_ENUM	target 不是 GL_TEXTURE_2D。
GL_INVALID_ENUM	format 不是接受的格式常量。仅接受除 GL_STENCIL_INDEX 和 GL_DEPTH_COMPONENT 以外的格式常量。有关可能值的列表，请参阅格式的参数说明。
GL_INVALID_ENUM	type 不是类型常量。
GL_INVALID_ENUM	type 为 GL_BITMAP，format 不是 GL_COLOR_INDEX。
GL_INVALID_VALUE	level 小于零或大于 log2 max，其中 max 是返回的 GL_MAX_TEXTURE_SIZE 值。
GL_INVALID_VALUE	internalformat 不是 1、2、3 或 4。
GL_INVALID_VALUE	width 或 height 小于零或大于 2 + GL_MAX_TEXTURE_SIZE，或者对于某些整数值 n，不能将其表示为 2n + 2(border)。
GL_INVALID_VALUE	border 不是 0 或 1。
GL_INVALID_OPERATION	在 glBegin 的调用和 glEnd 的相应调用之间调用该函数。

注解

glTexImage2D 函数指定二维纹理图像。纹理会将指定纹理图像的一部分映射到启用纹理的每个图形基元。可使用 glEnable 和 glDisable 以及自变量 GL_TEXTURE_2D 来启用和禁用二维纹理。

纹理图像是使用 glTexImage2D 定义的。该自变量描述纹理图像的参数，如高度、宽度、边框宽度、细节级别编号（请参阅 glTexParameter）和提供的颜色分量数。最后三个自变量描述图像在内存中的表示方式。这些自变量与用于 glDrawPixels 的像素格式相同。

根据 type，数据会从像素读取为带符号或无符号字节、短或长或单精度浮点值序列。根据 format，这些值被分组为一个、两个、三个或四个值的集合，以形成元素。如果 type 为 GL_BITMAP，则数据被视为无符号字节字符串（并且 format 必须为 GL_COLOR_INDEX）。每个数据字节被视为 8 个 1 位元素，位排序由 GL_UNPACK_LSB_FIRST 确定（请参阅 glPixelStore）。有关 type 参数可接受的值的说明，请参阅 glDrawPixels。

纹理图像的每个纹理元素最多可以有四个分量，具体取决于分量数。单分量纹理图像仅使用从像素中提取的 RGBA 颜色的红色分量。双分量图像使用 R 和 A 值。三分量图像使用 R、G 和 B 值。四分量图像使用所有 RGBA 分量。

纹理在颜色索引模式下不起作用。

纹理图像可以用与 glDrawPixels 命令中的像素相同的数据格式表示，但不能使用 GL_STENCIL_INDEX 和 GL_DEPTH_COMPONENT。 glPixelStore 和 glPixelTransfer 模式按照它们影响 glDrawPixels 的方式影响纹理图像。

高度或宽度为零的纹理图像表示空纹理。如果为细节级别 0 指定了空纹理，则就像是禁用了纹理。

以下函数检索与 glTexImage2D 相关的信息：

glGetTexImage

自变量为 GL_TEXTURE_2D 的 glIsEnabled

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
Header	Gl.h
库	Opengl32.lib
DLL	Opengl32.dll

另请参阅

glBegin
glDrawPixels
glEnd
glFog
glIsEnabled
glPixelStore
glPixelTransfer
glTexEnv
glTexGen
glTexImage1D
glTexParameter

glTexImage2D 函数

语法

参数

返回值

错误代码

注解

要求

另请参阅

反馈

反馈

其他资源