Expand Minimize

texImage2D method

Loads the supplied pixel data into a texture.

IE11

 

Syntax

WebGLRenderingContext.texImage2D(target, level, internalformat, width, height, border, format, type, pixels);

Parameters

target [in]

Type: Number

The target texture of the active texture unit. 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 value.

internalformat [in]

Type: Number

Specifies the number of color components in the texture.

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.

 

width

Type: Number

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

height

Type: Number

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

border

Type: Number

Specifies the width of the border. Must be 0. Border value used only when UInt8Array or Float32Array for pixels is specified.

format [in]

Type: Number

Contains the format for the source pixel data. Must match internalformat (see above).

type [in]

Type: Number

The type of texture data.

ValueMeaning
gl.UNSIGNED_BYTE

Provides 8 bits per channel for gl.RGBA.

gl.FLOAT

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

gl.UNSIGNED_SHORT_5_6_5

Represents colors in a Uint16Array where red = 5 bits, green=6 bits, and blue=5 bits.

gl.UNSIGNED_SHORT_4_4_4_4

Represents colors in a Uint16Array where red = 4 bits, green=4 bits, blue=4 bits, and alpha=4 bits.

gl.UNSIGNED_SHORT_5_5_5_1

Represents colors in a Uint16Array where red = 5 bits, green=5 bits, blue=5 bits and alpha=1 bit.

 

pixels [in]

Type: ImageData | ArrayBufferView | canvas | img

The ImageData array, ArrayBufferView, HTMLCanvasElement, HTMLImageElement to use as a data source for the texture. For the ArrayBufferView overload, a buffer of sufficient size is automatically allocated and its contents is initialized to 0 if pixels is null.

Return value

This method does not return a value.

Exceptions

ExceptionCondition
gl.SECURITY_ERR

Occurs if an image or canvas is supplied as the pixel data source and isn't the same origin (same domain) 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_OPERATION
  • If the ArrayBufferView doesn't have enough data to fill the specified rectangle.
  • If format and internalformat don't match.
  • No texture is bound to target.
  • If type is gl.UNSIGNED_SHORT_5_6_5 and format isn't gl.RGB.
  • If type is gl.UNSIGNED_SHORT_4_4_4_4 or gl.UNSIGNED_SHORT_5_5_5_1 and the format isn't gl.RGBA
gl.INVALID_VALUE
  • target is a cube map target and width and height aren't equal.
  • If pixels is null for any of the non-ArrayBuffer overloads.
  • The incoming ArrayBufferView or image is bigger than max texture size. Max texture can be retrieved by calling getParameter and using the gl.MAX_CUBE_MAP_TEXTURE_SIZE and gl.MAX_TEXTURE_SIZE enums.
  • If level, width, or height is a negative value.
  • If level is greater than log 2(max), where max is the value of gl.MAX_TEXTURE_SIZE when target is gl.TEXTURE_2D.
  • If width or height are greater than the value of gl.MAX_TEXTURE_SIZE when target is gl.TEXTURE_2D.
  • If level is greater than log 2(max), where max is the value of gl.MAX_CUBE_MAP_TEXTURE_SIZE when target is not gl.TEXTURE_2D.
  • If width or height are greater than the value of gl.MAX_CUBE_MAP_TEXTURE_SIZE when target is not a cube map texture target.
gl.INVALID_ENUMIf target, format, internalformat, or type aren't one of the listed values.

 

Images that are used as textures are not allowed if the origin of the image isn't the same as the origin of the canvas element. Images are also blocked if they are from a canvas whose origin-clean flag set to false.

Examples

The following example uses texImage2D to upload an image into a texture. For more info on this example, see Get started with WebGL.


// Create a texture object that will contain the image.
var texture = gl.createTexture();

// Bind the texture the target (TEXTURE_2D) of the active texture unit.
gl.bindTexture(gl.TEXTURE_2D, texture);

// Flip the image's Y axis to match the WebGL texture coordinate space.
gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
    
// Set the parameters so we can render any size image.        
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); 
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);

  // Upload the resized canvas image into the texture.
//    Note: a canvas is used here but can be replaced by an image object. 
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, canvas);


See also

WebGLRenderingContext

 

 

Show:
© 2014 Microsoft