WebGLRenderingContext: texSubImage2D() 方法

语法

// WebGL 1:
texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, srcData)
texSubImage2D(target, level, xoffset, yoffset, format, type, source)

// Additionally available in WebGL 2:
texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, srcData, srcOffset)
texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, source)
texSubImage2D(target, level, xoffset, yoffset, width, height, 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 缩减级别。

xoffset

一个 GLint，指定纹理数组中宽度为 width、高度为 height 的矩形子区域的左下角纹素 x 坐标。

yoffset

一个 GLint，指定纹理数组中宽度为 width、高度为 height 的矩形子区域的左下角纹素 y 坐标。

width

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

height

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

格式（format）

一个 GLenum，指定原始纹素数据中每个整数元素应如何解释为颜色分量。可能的值有：

• gl.ALPHA: 丢弃红色、绿色和蓝色分量，读取 alpha 分量。
• gl.RGB: 丢弃 alpha 分量，读取红色、绿色和蓝色分量。
• gl.RGBA: 从颜色缓冲区读取红色、绿色、蓝色和 alpha 分量。
• gl.LUMINANCE: 每个颜色分量都是一个亮度分量，alpha 为 1.0。
• gl.LUMINANCE_ALPHA: 每个分量都是一个亮度/alpha 分量。

使用 EXT_sRGB 扩展时

• ext.SRGB_EXT
• ext.SRGB_ALPHA_EXT

当使用 WebGL2RenderingContext 时，还可以使用以下值：

• gl.RED
• gl.RED_INTEGER
• gl.RG
• gl.RG_INTEGER
• gl.RGB_INTEGER
• gl.RGBA_INTEGER
• gl.DEPTH_COMPONENT
• gl.DEPTH_STENCIL

type

一个 GLenum，指定原始纹素数据中每个整数元素的大小。有关可用的 format 和 type 组合，请参阅 WebGLRenderingContext.texImage2D()。

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

srcData

包含压缩纹理数据的 TypedArray 或 DataView。其类型必须与 type 参数匹配；请参阅 WebGLRenderingContext.texImage2D()。

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.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, gl.RGBA, gl.UNSIGNED_BYTE, image);

规范

浏览器兼容性

另见

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