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