ThetexSubImage2D() method of theWebGLRenderingContext interface of theWebGL API specifies a two-dimensional sub-rectangle for a texture image.

Syntax

// 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)

Parameters

target

AGLenum specifying the binding point (target) of the active texture. Possible values:

• gl.TEXTURE_2D: A two-dimensional texture.
• gl.TEXTURE_CUBE_MAP_POSITIVE_X: Positive X face for a cube-mapped texture.
• gl.TEXTURE_CUBE_MAP_NEGATIVE_X: Negative X face for a cube-mapped texture.
• gl.TEXTURE_CUBE_MAP_POSITIVE_Y: Positive Y face for a cube-mapped texture.
• gl.TEXTURE_CUBE_MAP_NEGATIVE_Y: Negative Y face for a cube-mapped texture.
• gl.TEXTURE_CUBE_MAP_POSITIVE_Z: Positive Z face for a cube-mapped texture.
• gl.TEXTURE_CUBE_MAP_NEGATIVE_Z: Negative Z face for a cube-mapped texture.

level

AGLint specifying the level of detail. Level 0 is the base image level and leveln is the n-th mipmap reduction level.

xoffset

AGLint specifying the lower left texel x coordinate of a width-wide by height-wide rectangular subregion of the texture array.

yoffset

AGLint specifying the lower left texel y coordinate of a width-wide by height-wide rectangular subregion of the texture array.

width

AGLsizei specifying the width of the texture in texels.

height

AGLsizei specifying the height of the texture in texels.

format

AGLenum specifying how each integer element in the raw texel data should be interpreted as color components. Possible values:

• gl.ALPHA: Discards the red, green and blue components and reads the alpha component.
• gl.RGB: Discards the alpha components and reads the red, green and blue components.
• gl.RGBA: Red, green, blue and alpha components are read from the color buffer.
• gl.LUMINANCE: Each color component is a luminance component, alpha is 1.0.
• gl.LUMINANCE_ALPHA: Each component is a luminance/alpha component.

When using theEXT_sRGB extension:

• ext.SRGB_EXT
• ext.SRGB_ALPHA_EXT

When using aWebGL2RenderingContext, the following values are available additionally:

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

type

AGLenum specifying the size of each integer element in the raw texel data. For the combinations offormat andtype available, seeWebGLRenderingContext.texImage2D().

The texture source can be provided in one of three ways: from anArrayBuffer (possibly shared) usingsrcData andsrcOffset; from a DOM pixelsource; or, in WebGL 2, fromgl.PIXEL_UNPACK_BUFFER usingoffset.

srcData

ATypedArray orDataView containing the compressed texture data. Its type must match thetype parameter; seeWebGLRenderingContext.texImage2D().

srcOffsetOptional

(WebGL 2 only) An integer specifying the index ofsrcData to start reading from. Defaults to0.

source

Read from a DOM pixel source, which can be one of:

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

In WebGL 1, thewidth andheight are always inferred from the source. In WebGL 2, they can also be explicitly specified.

offset

(WebGL 2 only) AGLintptr specifying the starting address in the buffer bound togl.PIXEL_UNPACK_BUFFER.

Return value

None (undefined).

Examples

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

Specifications

Browser compatibility

See also

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