WebGLRenderingContext: texImage2D() method
WebGL
WebGL
The texImage2D() method of the WebGLRenderingContext interface of the WebGL API specifies a two-dimensional texture image.
Syntax
// WebGL 1:
texImage2D(target, level, internalformat, width, height, border, format, type, srcData)
texImage2D(target, level, internalformat, format, type, source)
// Additionally available in WebGL 2:
texImage2D(target, level, internalformat, width, height, border, format, type, srcData, srcOffset)
texImage2D(target, level, internalformat, width, height, border, format, type, source)
texImage2D(target, level, internalformat, width, height, border, format, type, offset)
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 n-th mipmap reduction level.
internalformat- : A GLenum specifying how the texture should be stored after it's loaded. See below for available values.
width- : A GLsizei specifying the width of the texture in texels.
height- : A GLsizei specifying the height of the texture in texels.
border- : A GLint specifying the width of the border. Must be 0.
format- : A GLenum specifying how each integer element in the raw texel data should be interpreted as color components. In WebGL 1, this must be the same as
internalformat. See below for available values. type-
: A GLenum specifying the size of each integer element in the raw texel data.
The
internalformat,format, andtypevalues must be compatible with each other. Possible combinations in both WebGL 1 and WebGL 2 (these internal formats are unsized because you can't specify how many bytes each pixel takes internally):internalformatformattypeInput bytes per pixel Input pixel layout (bits per channel) RGBRGBUNSIGNED_BYTE3 (R, G, B) = (8, 8, 8) RGBRGBUNSIGNED_SHORT_5_6_52 (R, G, B) = (5, 6, 5) RGBARGBAUNSIGNED_BYTE4 (R, G, B, A) = (8, 8, 8, 8) RGBARGBAUNSIGNED_SHORT_4_4_4_42 (R, G, B, A) = (4, 4, 4, 4) RGBARGBAUNSIGNED_SHORT_5_5_5_12 (R, G, B, A) = (5, 5, 5, 1) LUMINANCE_ALPHALUMINANCE_ALPHAUNSIGNED_BYTE2 (L, A) = (8, 8) LUMINANCELUMINANCEUNSIGNED_BYTE1 (L) = (8) ALPHAALPHAUNSIGNED_BYTE1 (A) = (8) In WebGL 1, when the OES_texture_float extension is enabled,
typecan additionally beFLOAT. When the OES_texture_half_float extension is enabled,typecan additionally beext.HALF_FLOAT_OES(constant provided by the extension).When the EXT_sRGB extension is enabled,
internalformatcan additionally beext.SRGB_EXTorext.SRGB_ALPHA_EXT.In WebGL 2, when specifying the source as
srcDataoroffset, the following combinations are additionally available (these internal formats are sized because the internal pixel layout is exactly specified; we omit the input layout here because it works similarly to the one above). The Color renderable column describes formats that are color-renderable in WebGL 2 without additional extensions.internalformatformattypeInternal pixel layout Color renderable Texture filterable R8REDUNSIGNED_BYTE(R) = (8) Y Y R8_SNORMREDBYTE(R) = (s8) Y R16FREDHALF_FLOAT,FLOAT(R) = (f16) Y R32FREDFLOAT(R) = (f32) R8UIRED_INTEGERUNSIGNED_BYTE(R) = (ui8) Y R8IRED_INTEGERBYTE(R) = (i8) Y R16UIRED_INTEGERUNSIGNED_SHORT(R) = (ui16) Y R16IRED_INTEGERSHORT(R) = (i16) Y R32UIRED_INTEGERUNSIGNED_INT(R) = (ui32) Y R32IRED_INTEGERINT(R) = (i32) Y RG8RGUNSIGNED_BYTE(R, G) = (8, 8) Y Y RG8_SNORMRGBYTE(R, G) = (s8, s8) Y RG16FRGHALF_FLOAT,FLOAT(R, G) = (f16, f16) Y RG32FRGFLOAT(R, G) = (f32, f32) RG8UIRG_INTEGERUNSIGNED_BYTE(R, G) = (ui8, ui8) Y RG8IRG_INTEGERBYTE(R, G) = (i8, i8) Y RG16UIRG_INTEGERUNSIGNED_SHORT(R, G) = (ui16, ui16) Y RG16IRG_INTEGERSHORT(R, G) = (i16, i16) Y RG32UIRG_INTEGERUNSIGNED_INT(R, G) = (ui32, ui32) Y RG32IRG_INTEGERINT(R, G) = (i32, i32) Y RGB8RGBUNSIGNED_BYTE(R, G, B) = (8, 8, 8) Y Y SRGB8RGBUNSIGNED_BYTE(R, G, B) = (8, 8, 8) Y RGB565RGBUNSIGNED_BYTE,UNSIGNED_SHORT_5_6_5(R, G, B) = (5, 6, 5) Y Y RGB8_SNORMRGBBYTE(R, G, B) = (s8, s8, s8) Y R11F_G11F_B10FRGBUNSIGNED_INT_10F_11F_11F_REV,HALF_FLOAT,FLOAT(R, G, B) = (f11, f11, f10) Y RGB9_E5RGBUNSIGNED_INT_5_9_9_9_REV,HALF_FLOAT,FLOAT(R, G, B) = (f9, f9, f9), 5 shared bits Y RGB16FRGBHALF_FLOAT,FLOAT(R, G, B) = (f16, f16, f16) Y RGB32FRGBFLOAT(R, G, B) = (f32, f32, f32) RGB8UIRGB_INTEGERUNSIGNED_BYTE(R, G, B) = (ui8, ui8, ui8) Y RGB8IRGB_INTEGERBYTE(R, G, B) = (i8, i8, i8) Y RGB16UIRGB_INTEGERUNSIGNED_SHORT(R, G, B) = (ui16, ui16, ui16) Y RGB16IRGB_INTEGERSHORT(R, G, B) = (i16, i16, i16) Y RGB32UIRGB_INTEGERUNSIGNED_INT(R, G, B) = (ui32, ui32, ui32) Y RGB32IRGB_INTEGERINT(R, G, B) = (i32, i32, i32) Y RGBA8RGBAUNSIGNED_BYTE(R, G, B, A) = (8, 8, 8, 8) Y Y SRGB8_ALPHA8RGBAUNSIGNED_BYTE(R, G, B, A) = (8, 8, 8, 8) Y Y RGBA8_SNORMRGBABYTE(R, G, B, A) = (s8, s8, s8, s8) Y RGB5_A1RGBAUNSIGNED_BYTE,UNSIGNED_SHORT_5_5_5_1,UNSIGNED_INT_2_10_10_10_REV(R, G, B, A) = (5, 5, 5, 1) Y Y RGBA4RGBAUNSIGNED_BYTE,UNSIGNED_SHORT_4_4_4_4(R, G, B, A) = (4, 4, 4, 4) Y Y RGB10_A2RGBAUNSIGNED_INT_2_10_10_10_REV(R, G, B, A) = (10, 10, 10, 2) Y Y RGBA16FRGBAHALF_FLOAT,FLOAT(R, G, B, A) = (f16, f16, f16, f16) Y RGBA32FRGBAFLOAT(R, G, B, A) = (f32, f32, f32, f32) RGBA8UIRGBA_INTEGERUNSIGNED_BYTE(R, G, B, A) = (ui8, ui8, ui8, ui8) Y RGBA8IRGBA_INTEGERBYTE(R, G, B, A) = (i8, i8, i8, i8) Y RGBA10_A2UIRGBA_INTEGERUNSIGNED_INT_2_10_10_10_REV(R, G, B, A) = (ui10, ui10, ui10, ui2) Y RGBA16UIRGBA_INTEGERUNSIGNED_SHORT(R, G, B, A) = (ui16, ui16, ui16, ui16) Y RGBA16IRGBA_INTEGERSHORT(R, G, B, A) = (i16, i16, i16, i16) Y RGBA32UIRGBA_INTEGERUNSIGNED_INT(R, G, B, A) = (ui32, ui32, ui32, ui32) Y RGBA32IRGBA_INTEGERINT(R, G, B, A) = (i32, i32, i32, i32) Y [!NOTE] Some floating-point formats that are not color-renderable in WebGL 2 by default can become color-renderable when the appropriate extension is enabled. The EXT_color_buffer_float extension makes
R16F,RG16F,RGBA16F,R32F,RG32F,RGBA32F, andR11F_G11F_B10Fcolor-renderable. In WebGL 2, EXT_color_buffer_half_float can additionally makeR16F,RG16F,RGBA16Fcolor-renderable on platforms that support 16-bit floating-point render targets but not 32-bit floating-point render targets.In WebGL 2, when specifying the source as
srcDataoroffset, the following combinations are additionally available, and they can be enabled in WebGL 1 via the WEBGL_depth_texture extension:internalformatformattypeInternal pixel layout DEPTH_COMPONENT16DEPTH_COMPONENTUNSIGNED_SHORT,UNSIGNED_INT(D) = (16) DEPTH_COMPONENT24DEPTH_COMPONENTUNSIGNED_INT(D) = (24) DEPTH_COMPONENT32FDEPTH_COMPONENTFLOAT(D) = (f32) DEPTH24_STENCIL8DEPTH_STENCILUNSIGNED_INT_24_8(ext.UNSIGNED_INT_24_8_WEBGL)(D, S) = (24, 8) DEPTH32F_STENCIL8DEPTH_STENCILFLOAT_32_UNSIGNED_INT_24_8_REV(D, S) = (f32, 8) When the data source is a DOM pixel source, commonly each channel's representation is an unsigned integer type of at least 8 bits. Converting such representation to signed integers or unsigned integers with more bits is not clearly defined. For example, when converting
RGBA8toRGBA16UI, it is unclear whether or not the intention is to scale up values to the full range of a 16-bit unsigned integer. Therefore, only converting to unsigned integer of at most 8 bits, half float, or float is allowed.
The texture source can be provided in one of three ways: from an ArrayBuffer (possibly shared) using srcData and srcOffset; from a DOM pixel source; or, in WebGL 2, from gl.PIXEL_UNPACK_BUFFER using offset.
srcData-
: A TypedArray or DataView containing the image pixel data, or
nullto allocate texture storage without uploading pixels (the allocated texture will be initialized to zeros). If notnull, its type must match thetypeparameter:srcDatatypetypevalueInt8Array BYTEUint8Array, Uint8ClampedArray UNSIGNED_BYTEInt16Array SHORTUint16Array UNSIGNED_SHORT,UNSIGNED_SHORT_5_6_5,UNSIGNED_SHORT_5_5_5_1,UNSIGNED_SHORT_4_4_4_4,HALF_FLOATInt32Array INTUint32Array UNSIGNED_INT,UNSIGNED_INT_5_9_9_9_REV,UNSIGNED_INT_2_10_10_10_REV,UNSIGNED_INT_10F_11F_11F_REV,UNSIGNED_INT_24_8Float32Array FLOATWhen
typeisFLOAT_32_UNSIGNED_INT_24_8_REV,srcDatamust benull. -
srcOffset - : (WebGL 2 only) An integer specifying the index of
srcDatato 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, the
widthandheightare always inferred from the source. In WebGL 2, they can also be explicitly specified. -
offset - : (WebGL 2 only) A GLintptr specifying the starting address in the buffer bound to
gl.PIXEL_UNPACK_BUFFER.
Return value
None (undefined).
Examples
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
Specifications
Browser compatibility
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_texture_norm16
- EXT_sRGB