The WebGLRenderingContext.texImage2D()
method of the WebGL API specifies a two-dimensional texture image.
Syntax
// WebGL1: void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ArrayBufferView? pixels); void gl.texImage2D(target, level, internalformat, format, type, ImageData? pixels); void gl.texImage2D(target, level, internalformat, format, type, HTMLImageElement? pixels); void gl.texImage2D(target, level, internalformat, format, type, HTMLCanvasElement? pixels); void gl.texImage2D(target, level, internalformat, format, type, HTMLVideoElement? pixels); void gl.texImage2D(target, level, internalformat, format, type, ImageBitmap? pixels); // WebGL2: void gl.texImage2D(target, level, internalformat, width, height, border, format, type, GLintptr offset); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, HTMLCanvasElement source); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, HTMLImageElement source); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, HTMLVideoElement source); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ImageBitmap source); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ImageData source); void gl.texImage2D(target, level, internalformat, width, height, border, 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.
internalformat
A GLenum
specifying the color components in the texture.
Possible values in both WebGL1 and WebGL2
Format | Type | Channels | Bytes per pixel |
---|---|---|---|
RGBA | UNSIGNED_BYTE | 4 | 4 |
RGB | UNSIGNED_BYTE | 3 | 3 |
RGBA | UNSIGNED_SHORT_4_4_4_4 | 4 | 2 |
RGBA | UNSIGNED_SHORT_5_5_5_1 | 4 | 2 |
RGB | UNSIGNED_SHORT_5_6_5 | 3 | 2 |
LUMINANCE_ALPHA | UNSIGNED_BYTE | 2 | 2 |
LUMINANCE | UNSIGNED_BYTE | 1 | 1 |
ALPHA | UNSIGNED_BYTE | 1 | 1 |
Other possible values in WebGL2 for the versions of texImage2D
that take an ArrayBufferView
or a GLintptr offset
Sized
Format |
Base
Format |
R
bits |
G
bits |
B
bits |
A
bits |
Shared
bits |
Color
renderable |
Texture
filterable |
---|---|---|---|---|---|---|---|---|
R8 | RED | 8 | ● | ● | ||||
R8_SNORM | RED | s8 | ● | |||||
RG8 | RG | 8 | 8 | ● | ● | |||
RG8_SNORM | RG | s8 | s8 | ● | ||||
RGB8 | RGB | 8 | 8 | 8 | ● | ● | ||
RGB8_SNORM | RGB | s8 | s8 | s8 | ● | |||
RGB565 | RGB | 5 | 6 | 5 | ● | ● | ||
RGBA4 | RGBA | 4 | 4 | 4 | 4 | ● | ● | |
RGB5_A1 | RGBA | 5 | 5 | 5 | 1 | ● | ● | |
RGBA8 | RGBA | 8 | 8 | 8 | 8 | ● | ● | |
RGBA8_SNORM | RGBA | s8 | s8 | s8 | s8 | ● | ||
RGB10_A2 | RGBA | 10 | 10 | 10 | 2 | ● | ● | |
RGB10_A2UI | RGBA | ui10 | ui10 | ui10 | ui2 | ● | ||
SRGB8 | RGB | 8 | 8 | 8 | ● | |||
SRGB8_ALPHA8 | RGBA | 8 | 8 | 8 | 8 | ● | ● | |
R16F | RED | f16 | ● | |||||
RG16F | RG | f16 | f16 | ● | ||||
RGB16F | RGB | f16 | f16 | f16 | ● | |||
RGBA16F | RGBA | f16 | f16 | f16 | f16 | ● | ||
R32F | RED | f32 | ||||||
RG32F | RG | f32 | f32 | |||||
RGB32F | RGB | f32 | f32 | f32 | ||||
RGBA32F | RGBA | f32 | f32 | f32 | f32 | |||
R11F_G11F_B10F | RGB | f11 | f11 | f10 | ● | |||
RGB9_E5 | RGB | 9 | 9 | 9 | 5 | ● | ||
R8I | RED | i8 | ● | |||||
R8UI | RED | ui8 | ● | |||||
R16I | RED | i16 | ● | |||||
R16UI | RED | ui16 | ● | |||||
R32I | RED | i32 | ● | |||||
R32UI | RED | ui32 | ● | |||||
RG8I | RG | i8 | i8 | ● | ||||
RG8UI | RG | ui8 | ui8 | ● | ||||
RG16I | RG | i16 | i16 | ● | ||||
RG16UI | RG | ui16 | ui16 | ● | ||||
RG32I | RG | i32 | i32 | ● | ||||
RG32UI | RG | ui32 | ui32 | ● | ||||
RGB8I | RGB | i8 | i8 | i8 | ||||
RGB8UI | RGB | ui8 | ui8 | ui8 | ||||
RGB16I | RGB | i16 | i16 | i16 | ||||
RGB16UI | RGB | ui16 | ui16 | ui16 | ||||
RGB32I | RGB | i32 | i32 | i32 | ||||
RGB32UI | RGB | ui32 | ui32 | ui32 | ||||
RGBA8I | RGBA | i8 | i8 | i8 | i8 | ● | ||
RGBA8UI | RGBA | ui8 | ui8 | ui8 | ui8 | ● | ||
RGBA16I | RGBA | i16 | i16 | i16 | i16 | ● | ||
RGBA16UI | RGBA | ui16 | ui16 | ui16 | ui16 | ● | ||
RGBA32I | RGBA | i32 | i32 | i32 | i32 | ● | ||
RGBA32UI | RGBA | ui32 | ui32 | ui32 | ui32 | ● |
Possible values in WebGL2 for the versions of texImage2D
that take a texture an HTMLImageElement
, HTMLCanvasElement
, HTMLVideoElement
, ImageBitmap
, or ImageData
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
WEBGL_depth_texture
extension:gl.DEPTH_COMPONENT
gl.DEPTH_STENCIL
- 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.R8
gl.R16F
gl.R32F
gl.R8UI
gl.RG8
gl.RG16F
gl.RG32F
gl.RG8UI
gl.RG16UI
gl.RG32UI
gl.RGB8
gl.SRGB8
gl.RGB565
gl.R11F_G11F_B10F
gl.RGB9_E5
gl.RGB16F
gl.RGB32F
gl.RGB8UI
gl.RGBA8
gl.SRGB8_ALPHA8
gl.RGB5_A1
gl.RGB10_A2
gl.RGBA4
gl.RGBA16F
gl.RGBA32F
gl.RGBA8UI
width
A GLsizei
specifying the width of the texture.
height
A GLsizei
specifying the height of the texture.
border
A GLint
specifying the width of the border. Must be 0.
format
A GLenum
specifying the format of the texel data. In WebGL 1, this must be the same as internalformat
(see above). in WebGL 2, the combinations are listed in this table.
type
A GLenum
specifying the data type of the texel data. Possible values:
gl.UNSIGNED_BYTE
: 8 bits per channel forgl.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
WEBGL_depth_texture
extension:gl.UNSIGNED_SHORT
gl.UNSIGNED_INT
ext.UNSIGNED_INT_24_8_WEBGL
(constant provided by the extension)
- When using the
OES_texture_float
extension:gl.FLOAT
- When using the
OES_texture_half_float
extension:ext.HALF_FLOAT_OES
(constant provided by the extension)
- 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 benull
)
pixels
One of the following objects can be used as a pixel source for the texture:
ArrayBufferView
,- A
Uint8Array
must be used iftype
isgl.UNSIGNED_BYTE
. - A
Uint16Array
must be used iftype
is eithergl.UNSIGNED_SHORT_5_6_5
,gl.UNSIGNED_SHORT_4_4_4_4
,gl.UNSIGNED_SHORT_5_5_5_1
,gl.UNSIGNED_SHORT
orext.HALF_FLOAT_OES
. - A
Uint32Array
must be used iftype
isgl.UNSIGNED_INT
orext.UNSIGNED_INT_24_8_WEBGL
. - A
Float32Array
must be used iftype
isgl.FLOAT
.
- A
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.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
Specifications
Specification | Status | Comment |
WebGL 1.0The definition of 'texImage2D' in that specification. | Recommendation | Initial definition for WebGL. |
OpenGL ES 2.0The definition of 'glTexImage2D' in that specification. | Standard | Man page of the (similar) OpenGL ES 2.0 API. |
WebGL 2.0The definition of 'texImage2D' in that specification. | Editor's Draft | Updated definition for WebGL. |
OpenGL ES 3.0The definition of 'glTexImage2D' in that specification. | Standard | Man page of the (similar) OpenGL ES 3.0 API. |
Browser compatibility
The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
texImage2D
|
Chrome
Full support 9 |
Edge
Full support 12 |
Firefox
Full support 4 |
IE
Full support 11 |
Opera
Full support 12 |
Safari
Full support 5.1 |
WebView Android
Full support Yes |
Chrome Android
Full support 25 |
Firefox Android
Full support Yes |
Opera Android
Full support 12 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support 1.5 |
WebGL2
|
Chrome
Full support 56 |
Edge
Full support 79 |
Firefox
Full support 51 |
IE
No support No |
Opera
Full support 43 |
Safari
No support No |
WebView Android
Full support 58 |
Chrome Android
Full support 58 |
Firefox Android
Full support 51 |
Opera Android
Full support 43 |
Safari iOS
No support No |
Samsung Internet Android
Full support 7.0 |
Legend
- Full support
- Full support
- No support
- No support
See also
WebGLRenderingContext.createTexture()
WebGLRenderingContext.bindTexture()
WebGLRenderingContext.texSubImage2D()
WebGLRenderingContext.compressedTexImage2D()
WebGLRenderingContext.copyTexImage2D()
WebGLRenderingContext.getTexParameter()
WEBGL_depth_texture
OES_texture_float
OES_texture_half_float
EXT_sRGB
WebGLRenderingContext.texImage2D() by Mozilla Contributors is licensed under CC-BY-SA 2.5.