Expand Minimize

texSubImage2D method

Replaces a portion of an existing 2D texture image with all of another image.

IE11

Syntax

WebGLRenderingContext.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, pixels);

Parameters

target [in]

Type: Number

The target texture. Must be one of the following:

ValueMeaning
gl.TEXTURE_2D

Uses a 2D image.

gl.TEXTURE_CUBE_MAP_POSITIVE_X

Image for the positive X face of the cube map.

gl.TEXTURE_CUBE_MAP_NEGATIVE_X

Image for the negative X face of the cube map.

gl.TEXTURE_CUBE_MAP_POSITIVE_Y

Image for the positive Y face of the cube map.

gl.TEXTURE_CUBE_MAP_NEGATIVE_Y

Image for the negative Y face of the cube map.

gl.TEXTURE_CUBE_MAP_POSITIVE_Z

Image for the positive Z face of the cube map.

gl.TEXTURE_CUBE_MAP_NEGATIVE_Z

Image for the negative Z face of the cube map.

 

level [in]

Type: Number

The level of detail to use with the texture. Level 0 supported currently.

xoffset [in]

Type: Number

The x (horizontal) offset within the texture image.

yoffset [in]

Type: Number

The y (vertical) offset within the texture image.

width

Type: Number

Width of texture sub-image. Value used only when UInt8Array or Float32Array for pixels is specified.

height

Type: Number

Height of texture sub-image. Value used only when UInt8Array or Float32Array for pixels is specified.

format [in]

Type: Number

The format of the source pixel data. The following values are supported:

ValueMeaning
gl.ALPHA

Each element is a single alpha component. The system converts it to floating point, clamped to the range [0, 1], and assembles it into an RGBA element by placing attaching 0.0 to the red, green and blue channels.

gl.LUMINANCE

Each element is a single luminance component. The system converts it to floating point value, clamped to the range [0, 1], and assembles it into an RGBA element by placing the luminance value in the red, green and blue channels, and attaching 1.0 to the alpha channel.

gl.LUMINANCE_ALPHA

Each element is an luminance/alpha double. The systems converts each component to floating point, clamped to the range [0, 1], and assembles them into an RGBA element by placing the luminance value in the red, green and blue channels.

gl.RGB

Red, green, and blue channels.

gl.RGBA

Red, green, blue, and alpha (transparency) channels.

 

type [in]

Type: Number

The data type of the pixel data. The following is supported:

ValueMeaning
gl.UNSIGNED_BYTE
gl.FLOAT

Call getExtension("gl.OES_texture_float") first to enable. This creates 128bit-per-pixel textures instead of 32bit-per-pixel for the image.

 

pixels [in]

Type: ImageData | ArrayBufferView | canvas | img

The ImageData array, ArrayBufferView, canvas element, image element to use for the texture.

Return value

This method does not return a value.

Exceptions

ExceptionCondition
gl.SECURITY_ERR

Occurs if an image or canvas is supplied and doesn't have the same origin of the canvas associated with the WebGLRenderingContext.

Remarks

When using an ArrayBufferView for pixels and gl.FLOAT for type, the array must be a Float32Array rather than a UInt8Array. The ImageData overload for pixels doesn't currently support floating point textures.

WebGL errorDescription
gl.INVALID_VALUE
  • If pixels is null.
  • If level is < 0, or greater than maximum allowable value.
  • If xoffset is greater than the width of the texture image.
  • If yoffset is greater than the height of the texture image.
gl.INVALID_OPERATION
  • If called without a currently bound texture.
  • The type doesn't match the type originally defined for the texture.
  • If type and format aren't compatible values.
gl.INVALID_ENUMIf target, format, or type aren't one of the listed values.

 

See also

WebGLRenderingContext
texImage2D

 

 

Show:
© 2014 Microsoft. All rights reserved.