WebGLRenderingContext.texSubImage2D()

The WebGLRenderingContext.texSubImage2D() method of the WebGL API specifies a sub-rectangle of the current texture.

Syntax

// WebGL 1:
void gl.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, ArrayBufferView? pixels);
void gl.texSubImage2D(target, level, xoffset, yoffset, format, type, ImageData? pixels);
void gl.texSubImage2D(target, level, xoffset, yoffset, format, type, HTMLImageElement? pixels);
void gl.texSubImage2D(target, level, xoffset, yoffset, format, type, HTMLCanvasElement? pixels);
void gl.texSubImage2D(target, level, xoffset, yoffset, format, type, HTMLVideoElement? pixels);
void gl.texSubImage2D(target, level, xoffset, yoffset, format, type, ImageBitmap? pixels);

// WebGL 2:
void gl.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, GLintptr offset);
void gl.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, HTMLCanvasElement source);
void gl.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, HTMLImageElement source);
void gl.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, HTMLVideoElement source);
void gl.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, ImageBitmap source);
void gl.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, ImageData source);
void gl.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, ArrayBufferView srcData, srcOffset);

Parameters

target

A GLenum 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

A GLint specifying the level of detail. Level 0 is the base image level and level n is the nth mipmap reduction level.

xoffset

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

yoffset

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

width

A GLsizei specifying the width of the texture in texels.

height

A GLsizei specifying the height of the texture in texels.

format

A GLenum specifying the format of the texel data. 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 the EXT_sRGB extension:
  • ext.SRGB_EXT
  • ext.SRGB_ALPHA_EXT
• When using a WebGL 2 context, the following values are available additionally:
  • gl.RED
  • gl.RG
  • gl.RED_INTEGER
  • gl.RG_INTEGER
  • gl.RGB_INTEGER
  • gl.RGBA_INTEGER

type

A GLenum specifying the data type of the texel data. Possible values:

• gl.UNSIGNED_BYTE: 8 bits per channel for gl.RGBA
• gl.UNSIGNED_SHORT_5_6_5: 5 red bits, 6 green bits, 5 blue bits.
• gl.UNSIGNED_SHORT_4_4_4_4: 4 red bits, 4 green bits, 4 blue bits, 4 alpha bits.
• gl.UNSIGNED_SHORT_5_5_5_1: 5 red bits, 5 green bits, 5 blue bits, 1 alpha bit.
• When using the OES_texture_float extension:
  • gl.FLOAT
• When using the OES_texture_half_float extension:
  • gl.HALF_FLOAT_OES
• When using a WebGL 2 context, the following values are available additionally:
  • 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

One of the following objects can be used as a pixel source for the texture:

• ArrayBufferView,
  • A Uint8Array must be used if type is gl.UNSIGNED_BYTE.
  • A Uint16Array must be used if type is either gl.UNSIGNED_SHORT_5_6_5, gl.UNSIGNED_SHORT_4_4_4_4, gl.UNSIGNED_SHORT_5_5_5_1, or ext.HALF_FLOAT_OES.
  • A Float32Array must be used if type is gl.FLOAT.
• ImageData,
• HTMLImageElement,
• HTMLCanvasElement,
• HTMLVideoElement,
• ImageBitmap.

offset

(WebGL 2 only) A GLintptr byte offset into the WebGLBuffer's data store. Used to upload data to the currently bound WebGLTexture from the WebGLBuffer bound to the PIXEL_UNPACK_BUFFER target.

Return value

None.

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