WebGLRenderingContext: texImage2D() 方法

语法

// WebGL 1:
texImage2D(target, level, internalformat, width, height, border, format, type, srcData)
texImage2D(target, level, internalformat, format, type, source)

// Additionally available in WebGL 2:
texImage2D(target, level, internalformat, width, height, border, format, type, srcData, srcOffset)
texImage2D(target, level, internalformat, width, height, border, format, type, source)
texImage2D(target, level, internalformat, width, height, border, format, type, offset)

参数

目标

一个 GLenum，指定活动纹理的绑定点（目标）。可能的值有：

• gl.TEXTURE_2D：一个二维纹理。
• gl.TEXTURE_CUBE_MAP_POSITIVE_X：立方体贴图纹理的正 X 面。
• gl.TEXTURE_CUBE_MAP_NEGATIVE_X：立方体贴图纹理的负 X 面。
• gl.TEXTURE_CUBE_MAP_POSITIVE_Y：立方体贴图纹理的正 Y 面。
• gl.TEXTURE_CUBE_MAP_NEGATIVE_Y：立方体贴图纹理的负 Y 面。
• gl.TEXTURE_CUBE_MAP_POSITIVE_Z：立方体贴图纹理的正 Z 面。
• gl.TEXTURE_CUBE_MAP_NEGATIVE_Z：立方体贴图纹理的负 Z 面。

level

一个 GLint，指定细节级别。级别 0 是基本图像级别，级别 n 是第 n 个 mipmap 缩减级别。

internalformat

一个 GLenum，指定纹理加载后应如何存储。可用值见下文。

width

一个 GLsizei，指定纹理的宽度（以 texel 为单位）。

height

一个 GLsizei，指定纹理的高度（以 texel 为单位）。

border

一个 GLint，指定边框的宽度。必须为 0。

格式（format）

一个 GLenum，指定原始 texel 数据中的每个整数元素应如何解释为颜色分量。在 WebGL 1 中，这必须与 internalformat 相同。可用值见下文。

type

一个 GLenum，指定原始 texel 数据中每个整数元素的大小。

internalformat、format 和 type 值必须相互兼容。WebGL 1 和 WebGL 2 中可能的组合（这些内部格式是*无大小限制*的，因为你无法指定每个像素在内部占用多少字节）

internalformat	格式（format）	type	每个像素的输入字节数	输入像素布局（每通道位数）
RGB	RGB	UNSIGNED_BYTE	3	(R, G, B) = (8, 8, 8)
RGB	RGB	UNSIGNED_SHORT_5_6_5	2	(R, G, B) = (5, 6, 5)
RGBA	RGBA	UNSIGNED_BYTE	4	(R, G, B, A) = (8, 8, 8, 8)
RGBA	RGBA	UNSIGNED_SHORT_4_4_4_4	2	(R, G, B, A) = (4, 4, 4, 4)
RGBA	RGBA	UNSIGNED_SHORT_5_5_5_1	2	(R, G, B, A) = (5, 5, 5, 1)
LUMINANCE_ALPHA	LUMINANCE_ALPHA	UNSIGNED_BYTE	2	(L, A) = (8, 8)
LUMINANCE	LUMINANCE	UNSIGNED_BYTE	1	(L) = (8)
ALPHA	ALPHA	UNSIGNED_BYTE	1	(A) = (8)

当 OES_texture_float 扩展启用时，type 还可以是 FLOAT。当 OES_texture_half_float 扩展启用时，type 还可以是 ext.HALF_FLOAT_OES（由扩展提供的常量）。

当 EXT_sRGB 扩展启用时，internalformat 还可以是 ext.SRGB_EXT 或 ext.SRGB_ALPHA_EXT。

在 WebGL 2 中，当将源指定为 srcData 或 offset 时，还可使用以下组合（这些内部格式是*有大小限制*的，因为内部像素布局已精确指定；我们在此省略输入布局，因为它与上述类似）

internalformat	格式（format）	type	内部像素布局	可渲染颜色	可过滤纹理
R8	RED	UNSIGNED_BYTE	(R) = (8)	Y	Y
R8_SNORM	RED	BYTE	(R) = (s8)		Y
R16F	RED	HALF_FLOAT, FLOAT	(R) = (f16)		Y
R32F	RED	FLOAT	(R) = (f32)
R8UI	RED_INTEGER	UNSIGNED_BYTE	(R) = (ui8)	Y
R8I	RED_INTEGER	BYTE	(R) = (i8)	Y
R16UI	RED_INTEGER	UNSIGNED_SHORT	(R) = (ui16)	Y
R16I	RED_INTEGER	SHORT	(R) = (i16)	Y
R32UI	RED_INTEGER	UNSIGNED_INT	(R) = (ui32)	Y
R32I	RED_INTEGER	INT	(R) = (i32)	Y
RG8	RG	UNSIGNED_BYTE	(R, G) = (8, 8)	Y	Y
RG8_SNORM	RG	BYTE	(R, G) = (s8, s8)		Y
RG16F	RG	HALF_FLOAT, FLOAT	(R, G) = (f16, f16)		Y
RG32F	RG	FLOAT	(R, G) = (f32, f32)
RG8UI	RG_INTEGER	UNSIGNED_BYTE	(R, G) = (ui8, ui8)	Y
RG8I	RG_INTEGER	BYTE	(R, G) = (i8, i8)	Y
RG16UI	RG_INTEGER	UNSIGNED_SHORT	(R, G) = (ui16, ui16)	Y
RG16I	RG_INTEGER	SHORT	(R, G) = (i16, i16)	Y
RG32UI	RG_INTEGER	UNSIGNED_INT	(R, G) = (ui32, ui32)	Y
RG32I	RG_INTEGER	INT	(R, G) = (i32, i32)	Y
RGB8	RGB	UNSIGNED_BYTE	(R, G, B) = (8, 8, 8)	Y	Y
SRGB8	RGB	UNSIGNED_BYTE	(R, G, B) = (8, 8, 8)		Y
RGB565	RGB	UNSIGNED_BYTE, UNSIGNED_SHORT_5_6_5	(R, G, B) = (5, 6, 5)	Y	Y
RGB8_SNORM	RGB	BYTE	(R, G, B) = (s8, s8, s8)		Y
R11F_G11F_B10F	RGB	UNSIGNED_INT_10F_11F_11F_REV, HALF_FLOAT, FLOAT	(R, G, B) = (f11, f11, f10)		Y
RGB9_E5	RGB	UNSIGNED_INT_5_9_9_9_REV, HALF_FLOAT, FLOAT	(R, G, B) = (f9, f9, f9), 5 个共享位		Y
RGB16F	RGB	HALF_FLOAT, FLOAT	(R, G, B) = (f16, f16, f16)		Y
RGB32F	RGB	FLOAT	(R, G, B) = (f32, f32, f32)
RGB8UI	RGB_INTEGER	UNSIGNED_BYTE	(R, G, B) = (ui8, ui8, ui8)	Y
RGB8I	RGB_INTEGER	BYTE	(R, G, B) = (i8, i8, i8)	Y
RGB16UI	RGB_INTEGER	UNSIGNED_SHORT	(R, G, B) = (ui16, ui16, ui16)	Y
RGB16I	RGB_INTEGER	SHORT	(R, G, B) = (i16, i16, i16)	Y
RGB32UI	RGB_INTEGER	UNSIGNED_INT	(R, G, B) = (ui32, ui32, ui32)	Y
RGB32I	RGB_INTEGER	INT	(R, G, B) = (i32, i32, i32)	Y
RGBA8	RGBA	UNSIGNED_BYTE	(R, G, B, A) = (8, 8, 8, 8)	Y	Y
SRGB8_ALPHA8	RGBA	UNSIGNED_BYTE	(R, G, B, A) = (8, 8, 8, 8)	Y	Y
RGBA8_SNORM	RGBA	BYTE	(R, G, B, A) = (s8, s8, s8, s8)		Y
RGB5_A1	RGBA	UNSIGNED_BYTE, UNSIGNED_SHORT_5_5_5_1, UNSIGNED_INT_2_10_10_10_REV	(R, G, B, A) = (5, 5, 5, 1)	Y	Y
RGBA4	RGBA	UNSIGNED_BYTE, UNSIGNED_SHORT_4_4_4_4	(R, G, B, A) = (4, 4, 4, 4)	Y	Y
RGB10_A2	RGBA	UNSIGNED_INT_2_10_10_10_REV	(R, G, B, A) = (10, 10, 10, 2)	Y	Y
RGBA16F	RGBA	HALF_FLOAT, FLOAT	(R, G, B, A) = (f16, f16, f16, f16)		Y
RGBA32F	RGBA	FLOAT	(R, G, B, A) = (f32, f32, f32, f32)
RGBA8UI	RGBA_INTEGER	UNSIGNED_BYTE	(R, G, B, A) = (ui8, ui8, ui8, ui8)	Y
RGBA8I	RGBA_INTEGER	BYTE	(R, G, B, A) = (i8, i8, i8, i8)	Y
RGBA10_A2UI	RGBA_INTEGER	UNSIGNED_INT_2_10_10_10_REV	(R, G, B, A) = (ui10, ui10, ui10, ui2)	Y
RGBA16UI	RGBA_INTEGER	UNSIGNED_SHORT	(R, G, B, A) = (ui16, ui16, ui16, ui16)	Y
RGBA16I	RGBA_INTEGER	SHORT	(R, G, B, A) = (i16, i16, i16, i16)	Y
RGBA32UI	RGBA_INTEGER	UNSIGNED_INT	(R, G, B, A) = (ui32, ui32, ui32, ui32)	Y
RGBA32I	RGBA_INTEGER	INT	(R, G, B, A) = (i32, i32, i32, i32)	Y

在 WebGL 2 中，当将源指定为 srcData 或 offset 时，还可以使用以下组合，并且可以通过 WEBGL_depth_texture 扩展在 WebGL 1 中启用它们

internalformat	格式（format）	type	内部像素布局
DEPTH_COMPONENT16	DEPTH_COMPONENT	UNSIGNED_SHORT, UNSIGNED_INT	(D) = (16)
DEPTH_COMPONENT24	DEPTH_COMPONENT	UNSIGNED_INT	(D) = (24)
DEPTH_COMPONENT32F	DEPTH_COMPONENT	FLOAT	(D) = (f32)
DEPTH24_STENCIL8	DEPTH_STENCIL	UNSIGNED_INT_24_8 (ext.UNSIGNED_INT_24_8_WEBGL)	(D, S) = (24, 8)
DEPTH32F_STENCIL8	DEPTH_STENCIL	FLOAT_32_UNSIGNED_INT_24_8_REV	(D, S) = (f32, 8)

当数据源是 DOM 像素源时，通常每个通道的表示都是至少 8 位的无符号整数类型。将这种表示转换为有符号整数或位数更多的无符号整数的定义不明确。例如，在将 RGBA8 转换为 RGBA16UI 时，不清楚意图是否是将值按比例放大到 16 位无符号整数的完整范围。因此，只允许转换为最多 8 位的无符号整数、半浮点数或浮点数。

纹理源可以通过三种方式提供：通过 srcData 和 srcOffset 从 ArrayBuffer（可能共享）；从 DOM 像素 source；或者，在 WebGL 2 中，从 gl.PIXEL_UNPACK_BUFFER 使用 offset。

srcData

一个 TypedArray 或 DataView，包含压缩纹理数据。其类型必须与 type 参数匹配

srcData 类型	type 值
Int8Array	BYTE
Uint8Array, Uint8ClampedArray	UNSIGNED_BYTE
Int16Array	SHORT
Uint16Array	UNSIGNED_SHORT, UNSIGNED_SHORT_5_6_5, UNSIGNED_SHORT_5_5_5_1, UNSIGNED_SHORT_4_4_4_4, HALF_FLOAT
Int32Array	INT
Uint32Array	UNSIGNED_INT, UNSIGNED_INT_5_9_9_9_REV, UNSIGNED_INT_2_10_10_10_REV, UNSIGNED_INT_10F_11F_11F_REV, UNSIGNED_INT_24_8
Float32Array	FLOAT

当 type 为 FLOAT_32_UNSIGNED_INT_24_8_REV 时，srcData 必须为 null。

srcOffset 可选

（仅限 WebGL 2）一个整数，指定 srcData 开始读取的索引。默认为 0。

source

从 DOM 像素源读取，它可以是以下之一：

• ImageBitmap
• ImageData
• HTMLImageElement
• HTMLCanvasElement
• HTMLVideoElement
• OffscreenCanvas
• VideoFrame

在 WebGL 1 中，width 和 height 总是从源推断。在 WebGL 2 中，它们也可以显式指定。

offset

（仅限 WebGL 2）一个 GLintptr，指定绑定到 gl.PIXEL_UNPACK_BUFFER 的缓冲区中的起始地址。

返回值

无（undefined）。

示例

gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);

规范

浏览器兼容性

另见

• WebGLRenderingContext.createTexture()
• WebGLRenderingContext.bindTexture()
• WebGLRenderingContext.texSubImage2D()
• WebGLRenderingContext.compressedTexImage2D()
• WebGLRenderingContext.copyTexImage2D()
• WebGLRenderingContext.getTexParameter()
• WEBGL_depth_texture
• OES_texture_float
• OES_texture_half_float
• EXT_texture_norm16
• EXT_sRGB