WebGLRenderingContext.texImage2D()

WebGL API 的WebGLRenderingContext.texImage2D() 方法指定了二维纹理图像。

语法

// WebGL1:
void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ArrayBufferView? pixels);
void gl.texImage2D(target, level, internalformat, format, type, ImageData? pixels);
void gl.texImage2D(target, level, internalformat, format, type, HTMLImageElement? pixels);
void gl.texImage2D(target, level, internalformat, format, type, HTMLCanvasElement? pixels);
void gl.texImage2D(target, level, internalformat, format, type, HTMLVideoElement? pixels);
void gl.texImage2D(target, level, internalformat, format, type, ImageBitmap? pixels);

// WebGL2:
void gl.texImage2D(target, level, internalformat, width, height, border, format, type, GLintptr offset);
void gl.texImage2D(target, level, internalformat, width, height, border, format, type, HTMLCanvasElement source);
void gl.texImage2D(target, level, internalformat, width, height, border, format, type, HTMLImageElement source); 
void gl.texImage2D(target, level, internalformat, width, height, border, format, type, HTMLVideoElement source); 
void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ImageBitmap source);
void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ImageData source);
void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ArrayBufferView srcData, srcOffset);

参数

target

 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个金字塔简化级.

internalformat

 GLenum 指定纹理中的颜色组件.

在 WebGL1 和 WebGL2 中可能的值：

Format	Type	Channels	Bytes per pixel
RGBA	UNSIGNED_BYTE	4	4
RGB	UNSIGNED_BYTE	3	3
RGBA	UNSIGNED_SHORT_4_4_4_4	4	2
RGBA	UNSIGNED_SHORT_5_5_5_1	4	2
RGB	UNSIGNED_SHORT_5_6_5	3	2
LUMINANCE_ALPHA	UNSIGNED_BYTE	2	2
LUMINANCE	UNSIGNED_BYTE	1	1
ALPHA	UNSIGNED_BYTE	1	1

在WebGL2 中，对带有 ArrayBufferView 或 GLintptr offset的  texImage2D 版本，其它可能的值

 在WebGL2 中，使用HTMLImageElement, HTMLCanvasElement, HTMLVideoElement, ImageBitmap, 或 ImageData作为texImage2D 纹理的版本中，可能的值有：

• gl.ALPHA: 抛弃红色、绿色和蓝色组件并读取alpha组件。
• gl.RGB:抛弃alpha组件，读取红色、绿色和蓝色组件。
• gl.RGBA: 从颜色缓冲区读取红色、绿色、蓝色和alpha组件。
• gl.LUMINANCE: E每个颜色组件是一个亮度组件，alpha值为1.0。
• gl.LUMINANCE_ALPHA: 每个组件都是亮度/alpha组件。
• 当时用 WEBGL_depth_texture 扩展：
  • gl.DEPTH_COMPONENT
  • gl.DEPTH_STENCIL
• 当时用 EXT_sRGB 扩展：
  • ext.SRGB_EXT
  • ext.SRGB_ALPHA_EXT
• 当时用 WebGL 2 context, 另外还提供以下值：
  • gl.R8
  • gl.R16F
  • gl.R32F
  • gl.R8UI
  • gl.RG8
  • gl.RG16F
  • gl.RG32F
  • gl.RG8UI
  • gl.RG16UI
  • gl.RG32UI
  • gl.RGB8
  • gl.SRGB8
  • gl.RGB565
  • gl.R11F_G11F_B10F
  • gl.RGB9_E5
  • gl.RGB16F
  • gl.RGB32F
  • gl.RGB8UI
  • gl.RGBA8
  • gl.SRGB8_ALPHA8
  • gl.RGB5_A1
  • gl.RGB10_A2
  • gl.RGBA4
  • gl.RGBA16F
  • gl.RGBA32F
  • gl.RGBA8UI

width

 GLsizei 指定纹理的宽度。

height

GLsizei 指定纹理的高度

border

GLint 指定纹理的边框宽度。必须为 0。

format

 GLenum 指定texel数据格式。在 WebGL 1中，它必须与 internalformat 相同（查看上面). 在WebGL 2中, 这张表中列出了这些组合。

type

 GLenum 指定texel数据的数据类型。可能的值:

• gl.UNSIGNED_BYTE:  gl.RGBA每个通道8位
• gl.UNSIGNED_SHORT_5_6_5: 5 bits红, 6 bits绿, 5 bits蓝
• gl.UNSIGNED_SHORT_4_4_4_4: 4 bits红, 4 bits绿, 4 bits蓝, 4 alpha bits.
• gl.UNSIGNED_SHORT_5_5_5_1: 5 bits红, 5 bits绿, 5 bits蓝, 1 alpha bit.
• 当使用 WEBGL_depth_texture 扩展:
  • gl.UNSIGNED_SHORT
  • gl.UNSIGNED_INT
  • ext.UNSIGNED_INT_24_8_WEBGL (constant provided by the extension)
• 当使用 OES_texture_float扩展 :
  • gl.FLOAT
• 当使用 OES_texture_half_float 扩展:
  • ext.HALF_FLOAT_OES (constant provided by the extension)
• 当使用 WebGL 2 context,下面的值也是可用的:
  • gl.BYTE
  • gl.UNSIGNED_SHORT
  • gl.SHORT
  • gl.UNSIGNED_INT
  • gl.INT
  • gl.HALF_FLOAT
  • gl.FLOAT
  • gl.UNSIGNED_INT_2_10_10_10_REV
  • gl.UNSIGNED_INT_10F_11F_11F_REV
  • gl.UNSIGNED_INT_5_9_9_9_REV
  • gl.UNSIGNED_INT_24_8
  • gl.FLOAT_32_UNSIGNED_INT_24_8_REV (pixels must be null)

pixels

下列对象之一可以用作纹理的像素源:

• ArrayBufferView,
  • Uint8Array  如果 type 是 gl.UNSIGNED_BYTE则必须使用
  • Uint16Array 如果 type 是 gl.UNSIGNED_SHORT_5_6_5, gl.UNSIGNED_SHORT_4_4_4_4, gl.UNSIGNED_SHORT_5_5_5_1, gl.UNSIGNED_SHORT 或ext.HALF_FLOAT_OES则必须使用
  •  Uint32Array 如果type 是 gl.UNSIGNED_INT 或ext.UNSIGNED_INT_24_8_WEBGL则必须使用
  •  Float32Array 如果type 是 gl.FLOAT则必须使用
• ImageData,
• HTMLImageElement,
• HTMLCanvasElement,
• HTMLVideoElement,
• ImageBitmap.

offset

 GLintptr 类型偏移到 WebGLBuffer的数据存储中。 用于上传数据到当前范围 WebGLTexture 从WebGLBuffer 范围到PIXEL_UNPACK_BUFFER 目标。(仅在WebGL 2中 )

返回值

None.

示例

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

说明

浏览器兼容性

The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.

另见

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