Chevron Down
Table of Contents
Chevron DownGetting Started
Chevron DownAPI Reference

Texture

A Texture is a WebGL object that contains one or more images that all have the same image format. Shaders can read from textures (through a sampler uniform) and they can be set up as render targets (by attaching them to a framebuffer).

Note: This section describes the Texture base class that implements functionality common to all four types of WebGL:

  • Texture2D - Contains a "normal" image texture
  • TextureCube - Holds 6 textures representing sides of a cube.
  • Texture3D (WebGL2) - Holds a "stack" of textures which enables 3D interpolation.

For more details see OpenGL Wiki.

Note that textures have a lot of optional capabilities made available by extensions, see the Limits section below.

Usage

  • For additional usage examples, Texture inherits from Resource.

Configuring a Texture

const texture = new Texture2D(gl);
texture.setParameters({
  [GL.TEXTURE_WRAP_S]: GL.CLAMP
});

Using Textures

const texture = new Texture2D(gl, ...);

// For ease of use, the `Model` class can bind textures for a draw call
model.draw({
  uniforms({uMVMatrix: matrix, texture1: texture, texture2: texture})
});

// Alternatively, bind the textures using the `Texture` API directly
texture.bind(0);
texture.bind(1);
model.draw({
  uniforms({uMVMatrix: matrix})
});

Members

A number of read only accessors are available:

  • width - width of one face of the cube map
  • height - height of one face of the cube map
  • format - internal format of the face textures
  • border - Always 0.
  • type - type used to create face textures
  • dataFormat - data format used to create face textures.
  • offset - offset used to create face textures. Always 0, unless specified using WebGL2 buffer constructor.
  • handle - The underlying WebGL object.
  • id - An identifying string that is intended to help debugging.

Sampler parameters can be accessed using Texture.getParameter, e.g:

texture.getParameter(GL.TEXTURE_MAG_FILTER);

Methods

constructor(gl : WebGLRenderingContext, props : Object)

The texture class cannot be constructed directly. It is a base class that provides common methods the the concrete texture classes.

The constructors for these classes should be used to create textures. They constructors all take common parameters, many of which are specified in this document.

resize(options : Object) : Texture2D

Call to resize a texture. If size has changed, reinitializes texture with current format. Note: calling resize clears image and mipmaps.

  • width (GLint) - width to resize to.
  • height (GLint) - height to resize to.
  • mipmaps (bool) - turn on/off mipmapping. default false.

generateMipmap() : Texture2D

Call to regenerate mipmaps after modifying texture(s)

WebGL References gl.generateMipmap

setImageData(options : Object) : Texture2D

Allocates storage and sets image data

  Texture.setImageData({
    target = this.target,
    pixels = null,
    data = null,
    width,
    height,
    level = 0,
    format = GL.RGBA,
    type,
    dataFormat,
    offset = 0,
    border = 0,
    compressed = false,
    parameters= {}
  });
  • data (*) - Image data. Can be one of several data types see table below
  • pixels (*) - alternative to data
  • width (GLint) -
  • height (GLint) -
  • level (GLint) -
  • format (GLenum) - format of image data.
  • type (GLenum)
  • format of array (autodetect from type) or
  • (WEBGL2) format of buffer
  • offset (Number) - (WEBGL2) offset from start of buffer
  • border (GLint) - must be 0.
  • compressed (Boolean) -
  • parameters (Object) - GL parameters to be temporarily applied (most of the time, pixelStorage parameters) when updating the texture.

Valid image data types:

  • null - create empty texture of specified format
  • Typed array - initializes from image data in typed array according to format
  • Buffer|WebGLBuffer - (WEBGL2) initialized from image data in WebGLBuffer accoeding to format.
  • HTMLImageElement|Image - Initializes with content of image. Auto deduces texture width/height from image.
  • HTMLCanvasElement - Inits with contents of canvas. Auto width/height.
  • HTMLVideoElement - Creates video texture that continuously updates. Auto width/height.

setSubImageData(options : Object) : Texture2D

Redefines an area of an existing texture Note: does not allocate storage

  Texture.setSubImageData({
    target = this.target,
    pixels = null,
    data = null,
    x = 0,
    y = 0,
    width,
    height,
    level = 0,
    format = GL.RGBA,
    type,
    dataFormat,
    compressed = false,
    offset = 0,
    border = 0,
    parameters = {}
  });
  • x (GLint) - xOffset from where texture to be updated
  • y (GLint) - yOffset from where texture to be updated
  • width (GLint) - width of the sub image to be updated
  • height (GLint) - height of the sub image to be updated
  • level (GLint) - mip level to be updated
  • format (GLenum) - internal format of image data.
  • typ (GLenum) - format of array (autodetect from type) or (WEBGL2) format of buffer or ArrayBufferView
  • dataFormat (GLenum) - format of image data.
  • offset (Number) - (WEBGL2) offset from start of buffer
  • border (GLint) - must be 0.
  • parameters - temporary settings to be applied, can be used to supply pixel store settings.

See also gl.compressedTexSubImage2D, gl.texSubImage2D, gl.bindTexture, gl.bindBuffer

getActiveUnit()

Returns number of active textures.

bind()

Binds itself to given textureUnit.

The following WebGL APIs are called in the function gl.activeTexture, gl.bindTexture

unbind()

The following WebGL APIs are called in the function gl.activeTexture, gl.bindTexture

Texture Image Data

WebGL allows textures to be created from a number of different data sources.

TypeDescription
nullA texture will be created with the appropriate format, size and width. Bytes will be "uninitialized".
typed arrayBytes will be interpreted according to format/type parameters and pixel store parameters.
Buffer or WebGLBuffer (WebGL2)Bytes will be interpreted according to format/type parameters and pixel store parameters.
Image (HTMLImageElement)image will be used to fill the texture. width and height will be deduced.
Video (HTMLVideoElement)video will be played, continously updating the texture. width and height will be deduced.
Canvas (HTMLCanvasElement)canvas will be used to fill the texture. width and height will be deduced.
ImageDatacanvas.getImageData() - Used to fill the texture. width and height will be deduced.

Texture Formats

Internal Format

If an application wants to store the texture at a certain resolution or in a certain format, it can request the resolution and format with internalFormat. WebGL will choose an internal representation with least the internal component sizes, and exactly the component types shown for that format, although it may not match exactly.

WebGL2 adds sized internal formats which enables the application to request specific components sizes and types (float and integer formats). While sized formats offer more control, unsized formats do give the GPU freedom to select the most performant internal representation.

Unsized Internal FormatComponentsDescription
GL.RGB3sampler reads the red, green and blue components, alpha is 1.0
GL.RGBA4Red, green, blue and alpha components are sampled from the color buffer.
GL.LUMINANCE1Each color contains a single luminance value. When sampled, rgb are all set to this luminance, alpha is 1.0.
GL.LUMINANCE_ALPHA2Each component is a luminance/alpha double. When sampled, rgb are all set to luminance, alpha from component.
GL.ALPHA1Discards the red, green and blue components and reads the alpha component.
GL.DEPTH_COMPONENT1WebGL2 or WEBGL_depth_texture
GL.DEPTH_STENCIL2WebGL2 or WEBGL_depth_texture
Sized Internal FormatComp.SizeDescription
GL.R8 (WebGL2)18 bitsred component
GL.R16F (WebGL2)116 bitshalf float red component
GL.R32F (WebGL2)132 bitsfloat red component
GL.R8UI (WebGL2)18 bitsunsigned int red component, usampler, no filtering
GL.RG8 (WebGL2)116 bitsred and green components
GL.RG16F (WebGL2)232 bitsred and green components, half float
GL.RG32F (WebGL2)264 bitsred and green components, float
GL.RGUI (WebGL2)216 bitsred and green components, usampler, no filtering
GL.RGB8 (WebGL2)324 bitsred, green and blue components
GL.SRGB8 (WebGL2, EXT_sRGB)324 bitsColor values are encoded to/decoded from sRGB before being written to/read from framebuffer
GL.RGB565 (WebGL2)316 bits5 bit red, 6 bit green, 5 bit blue
GL.R11F_G11F_B10F (WebGL2)332 bits11 and 10 bit floating point colors
GL.RGB9_E5 (WebGL2)332 bits14 bit floating point RGB, shared exponent
GL.RGB16F (WebGL2)348 bitshalf float RGB
GL.RGB32F (WebGL2)396 bitsfloat RBG
GL.RGB8UI (WebGL2)324 bitsunsigned integer 8 bit RGB: use usampler, no filtering
GL.RGBA8 (WebGL2)432 bits8 bit RGBA, typically what GL.RGBA "resolves" to
GL.SRGB_APLHA8 (WebGL2, EXT_sRGB)432 bitsColor values are encoded to/decoded from sRGB before being written to/read from framebuffer
GL.RGB5_A1 (WebGL2)416 bits5 bit RGB, 1 bit alpha
GL.RGBA4444 (WebGL2)416 bits4 bit RGBA
GL.RGBA16F (WebGL2)464 bitshalf float RGBA
GL.RGBA32F (WebGL2)4128 bitsfloat RGA
GL.RGBA8UI (WebGL2)432 bitsunsigned integer 8 bit RGBA, usampler, no filtering

Texture Component Type

Describes the layout of each color component in memory.

ValueWebGL2WebGL1Description
GL.UNSIGNED_BYTEYesYesGLbyte 8 bits per channel for GL.RGBA
GL.UNSIGNED_SHORT_5_6_5YesYes5 red bits, 6 green bits, 5 blue bits
GL.UNSIGNED_SHORT_4_4_4_4YesYes4 red bits, 4 green bits, 4 blue bits, 4 alpha bits
GL.UNSIGNED_SHORT_5_5_5_1YesYes5 red bits, 5 green bits, 5 blue bits, 1 alpha bit
GL.BYTEYesNo
GL.UNSIGNED_SHORTYesWEBGL_depth_texture
GL.SHORTYesNo
GL.UNSIGNED_INTYesWEBGL_depth_texture
GL.INTYesNo
GL.HALF_FLOATYesOES_texture_half_float
GL.FLOATYesOES_texture_float
GL.UNSIGNED_INT_2_10_10_10_REVYesNo
GL.UNSIGNED_INT_10F_11F_11F_REVYesNo
GL.UNSIGNED_INT_5_9_9_9_REVYesNo
GL.UNSIGNED_INT_24_8YesWEBGL_depth_texture
GL.FLOAT_32_UNSIGNED_INT_24_8_REVYesNo(pixels must be null)

Texture Format Combinations

This a simplified table illustrating what combinations of internal formats work with what data formats and types. Note that luma.gl deduces dataFormat and type from format by taking the first value from the data format and data type entries in this table.

For more details, see tables in:

Internal FormatData FormatData Type
GL.RGBGL.RGBGL.UNSIGNED_BYTE GL.UNSIGNED_SHORT_5_6_5
GL.RGBAGL.RGBAGL.UNSIGNED_BYTE GL.UNSIGNED_SHORT_4_4_4_4 GL.UNSIGNED_SHORT_5_5_5_1
GL.LUMINANCE_ALPHAGL.LUMINANCE_ALPHAGL.UNSIGNED_BYTE
GL.LUMINANCEGL.LUMINANCEGL.UNSIGNED_BYTE
GL.ALPHAGL.ALPHAGL.UNSIGNED_BYTE
GL.R8GL.REDGL.UNSIGNED_BYTE
GL.R16FGL.REDGL.HALF_FLOAT GL.FLOAT
GL.R32FGL.REDGL.FLOAT
GL.R8UIGL.RED_INTEGERGL.UNSIGNED_BYTE
GL.RG8GL.RGGL.UNSIGNED_BYTE
GL.RG16FGL.RGGL.HALF_FLOAT GL.FLOAT
GL.RG32FGL.RGGL.FLOAT
GL.RG8UIGL.RG_INTEGERGL.UNSIGNED_BYTE
GL.RGB8GL.RGBGL.UNSIGNED_BYTE
GL.SRGB8GL.RGBGL.UNSIGNED_BYTE
GL.RGB565GL.RGBGL.UNSIGNED_BYTE GL.UNSIGNED_SHORT_5_6_5
GL.R11F_G11F_B10FGL.RGBGL.UNSIGNED_INT_10F_11F_11F_REV GL.HALF_FLOAT GL.FLOAT
GL.RGB9_E5GL.RGBGL.HALF_FLOAT GL.FLOAT
GL.RGB16FGGL.RGBGL.HALF_FLOAT GL.FLOAT
GL.RGB32FGL.RGBGL.FLOAT
GL.RGB8UIGL.RGB_INTEGERGL.UNSIGNED_BYTE
GL.RGBA8GL.RGBAGL.UNSIGNED_BYTE
GL.SRGB8_ALPHA8GL.RGBAGL.UNSIGNED_BYTE
GL.RGB5_A1GL.RGBAGL.UNSIGNED_BYTE GL.UNSIGNED_SHORT_5_5_5_1
GL.RGBA4GL.RGBAGL.UNSIGNED_BYTE GL.UNSIGNED_SHORT_4_4_4_4
GL.RGBA16FGL.RGBAGL.HALF_FLOAT GL.FLOAT
GL.RGBA32FGL.RGBAGL.FLOAT
GL.RGBA8UIGL.RGBA_INTEGERGL.UNSIGNED_BYTE

Limits and Capabilities

Optional capabilitiescontrolled by extensions
Create floating point textures (GL.NEAREST sampling only)TEXTURE_FLOAT
Create half-floating point textures (GL.NEAREST sampling)TEXTURE_HALF_FLOAT
Floating point textures are color-renderable and readableCOLOR_BUFFER_FLOAT
Half float textures are color-renderable and readableCOLOR_BUFFER_HALF_FLOAT
sRGB format supportSRGB
depth texture supportDEPTH_TEXTURE
anisotropic filteringTEXTURE_FILTER_ANISOTROPIC
GL.LINEAR_* sampling of floating point texturesTEXTURE_FILTER_LINEAR_FLOAT
GL.LINEAR_* sampling of half-floating point texturesTEXTURE_FILTER_LINEAR_HALF_FLOAT

NPOT Textures (WebGL1)

  • Any texture with a non power of two dimension (width or height) is referred as NPOT texture, under WebGL1 NPOT textures have following limitations.
StateLimitation
MipmappingShould be disabled
GL.TEXTURE_MIN_FILTERMust be either GL.LINEAR or GL.NEAREST
GL.TEXTURE_WRAP_SMust be GL.CLAMP_TO_EDGE
GL.TEXTURE_WRAP_TMust be GL.CLAMP_TO_EDGE
  • 'Texture' class will perform above settings when NPOT texture resource is created. When un-supported filtering is set using Texture.setParameters, those will be overwritten with above supported values (GL.TEXTURE_MIN_FILTER will be set to GL.LINEAR). This only happens for NPOT textures when using WebGL1, and a warning log will be printed every time a setting is overwritten.

Remarks

  • Textures can be supplied as uniforms to shaders that can sample them using texture coordinates and color pixels accordingly.
  • Parameters that affect texture sampling can be set on textures or sampler objects.
  • Textures can be created from a number of different sources, including typed arrays, HTML Images, HTML Canvases, HTML Videos and WebGLBuffers (WebGL2).
  • The WebGL Context has global "pixel store" parameters that control how pixel data is laid out, including Y direction, color space etc.
  • Textures are read from supplied data and written to the specified format/type parameters and pixel store parameters.