twgl/textures

Low level texture related functions

You should generally not need to use these functions. They are provided
for those cases where you're doing something out of the ordinary
and you need lower level access.

For backward compatibility they are available at both twgl.textures and twgl
itself

See module:twgl for core functions

Methods

(static) canFilter(internalFormat) → {boolean}

Gets whether or not we can generate mips for the given format

Parameters:
Name Type Description
internalFormat number

The internalFormat parameter from texImage2D etc..

Returns:
Type:
boolean

true if we can generate mips

(static) canGenerateMipmap(gl, width, height, internalFormat) → {boolean}

Gets whether or not we can generate mips for the given
internal format.

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

width number

The width parameter from texImage2D etc..

height number

The height parameter from texImage2D etc..

internalFormat number

The internalFormat parameter from texImage2D etc..

Returns:
Type:
boolean

true if we can generate mips

(static) createTexture(gl, optionsopt, callbackopt) → {WebGLTexture}

Creates a texture based on the options passed in.

Note: may reset UNPACK_ALIGNMENT, UNPACK_ROW_LENGTH, UNPACK_IMAGE_HEIGHT, UNPACK_SKIP_IMAGES
UNPACK_SKIP_PIXELS, and UNPACK_SKIP_ROWS

UNPACK_FLIP_Y_WEBGL, UNPACK_PREMULTIPLY_ALPHA_WEBGL, UNPACK_COLORSPACE_CONVERSION_WEBGL
are left as is though you can pass in options for flipY, premultiplyAlpha, and colorspaceConversion
to override them.

As for the behavior of these settings

gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
t1 = twgl.createTexture({src: someImage }); // flipped
t2 = twgl.createTexture({src: someImage, flipY: true }); // flipped
t3 = twgl.createTexture({src: someImage, flipY: false }); // not flipped
t4 = twgl.createTexture({src: someImage }); // flipped
  • t1 is flipped because UNPACK_FLIP_Y_WEBGL is true
  • t2 is flipped because it was requested
  • t3 is not flipped because it was requested
  • t4 is flipped because UNPACK_FLIP_Y_WEBGL has been restored to true
Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

the WebGLRenderingContext

options module:twgl.TextureOptions <optional>

A TextureOptions object with whatever parameters you want set.

callback module:twgl.TextureReadyCallback <optional>

A callback called when an image has been downloaded and uploaded to the texture.

Returns:
Type:
WebGLTexture

the created texture.

(static) createTextures(gl, options, callbackopt) → {Object.<string, WebGLTexture>}

Creates a bunch of textures based on the passed in options.

Example:

const textures = twgl.createTextures(gl, {
  // a power of 2 image
  hftIcon: { src: "images/hft-icon-16.png", mag: gl.NEAREST },
  // a non-power of 2 image
  clover: { src: "images/clover.jpg" },
  // From a canvas
  fromCanvas: { src: ctx.canvas },
  // A cubemap from 6 images
  yokohama: {
    target: gl.TEXTURE_CUBE_MAP,
    src: [
      'images/yokohama/posx.jpg',
      'images/yokohama/negx.jpg',
      'images/yokohama/posy.jpg',
      'images/yokohama/negy.jpg',
      'images/yokohama/posz.jpg',
      'images/yokohama/negz.jpg',
    ],
  },
  // A cubemap from 1 image (can be 1x6, 2x3, 3x2, 6x1)
  goldengate: {
    target: gl.TEXTURE_CUBE_MAP,
    src: 'images/goldengate.jpg',
  },
  // A 2x2 pixel texture from a JavaScript array
  checker: {
    mag: gl.NEAREST,
    min: gl.LINEAR,
    src: [
      255,255,255,255,
      192,192,192,255,
      192,192,192,255,
      255,255,255,255,
    ],
  },
  // a 1x2 pixel texture from a typed array.
  stripe: {
    mag: gl.NEAREST,
    min: gl.LINEAR,
    format: gl.LUMINANCE,
    src: new Uint8Array([
      255,
      128,
      255,
      128,
      255,
      128,
      255,
      128,
    ]),
    width: 1,
  },
});

Now

  • textures.hftIcon will be a 2d texture
  • textures.clover will be a 2d texture
  • textures.fromCanvas will be a 2d texture
  • textures.yohohama will be a cubemap texture
  • textures.goldengate will be a cubemap texture
  • textures.checker will be a 2d texture
  • textures.stripe will be a 2d texture
Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

the WebGLRenderingContext

options Object.<string, module:twgl.TextureOptions>

A object of TextureOptions one per texture.

callback module:twgl.TexturesReadyCallback <optional>

A callback called when all textures have been downloaded.

Returns:
Type:
Object.<string, WebGLTexture>

the created textures by name

(static) getBytesPerElementForInternalFormat(internalFormat, type) → {number}

Gets the number of bytes per element for a given internalFormat / type

Parameters:
Name Type Description
internalFormat number

The internalFormat parameter from texImage2D etc..

type number

The type parameter for texImage2D etc..

Returns:
Type:
number

the number of bytes per element for the given internalFormat, type combo

(static) getFormatAndTypeForInternalFormat(internalFormat) → {module:twgl/textures.TextureFormatInfo}

Gets the format and type for a given internalFormat

Parameters:
Name Type Description
internalFormat number

The internal format

Returns:
Type:
module:twgl/textures.TextureFormatInfo

the corresponding format and type,

(static) getNumComponentsForFormat(format) → {number}

Gets the number of components for a given image format.

Parameters:
Name Type Description
format number

the format.

Returns:
Type:
number

the number of components for the format.

(static) loadTextureFromUrl(gl, tex, optionsopt, callbackopt) → {HTMLImageElement}

Loads a texture from an image from a Url as specified in options.src
If options.color !== false will set the texture to a 1x1 pixel color so that the texture is
immediately useable. It will be updated with the contents of the image once the image has finished
downloading. Filtering options will be set as appropriate for image unless options.auto === false.

Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

the WebGLRenderingContext

tex WebGLTexture

the WebGLTexture to set parameters for

options module:twgl.TextureOptions <optional>

A TextureOptions object with whatever parameters you want set.

callback module:twgl.TextureReadyCallback <optional>

A function to be called when the image has finished loading. err will
be non null if there was an error.

Returns:
Type:
HTMLImageElement

the image being downloaded.

(static) resizeTexture(gl, tex, options, widthopt, heightopt, depthopt)

Resizes a texture based on the options passed in.

Note: This is not a generic resize anything function.
It's mostly used by module:twgl.resizeFramebufferInfo
It will use options.src if it exists to try to determine a type
otherwise it will assume gl.UNSIGNED_BYTE. No data is provided
for the texture. Texture parameters will be set accordingly

Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

the WebGLRenderingContext

tex WebGLTexture

the texture to resize

options module:twgl.TextureOptions

A TextureOptions object with whatever parameters you want set.

width number <optional>

the new width. If not passed in will use options.width

height number <optional>

the new height. If not passed in will use options.height

depth number <optional>

the new depth. If not passed in will use options.depth

(static) setDefaultTextureColor(color)

Sets the default texture color.

The default texture color is used when loading textures from
urls. Because the URL will be loaded async we'd like to be
able to use the texture immediately. By putting a 1x1 pixel
color in the texture we can start using the texture before
the URL has loaded.

Deprecated:
Parameters:
Name Type Description
color Array.<number>

Array of 4 values in the range 0 to 1

(static) setEmptyTexture(gl, tex, options)

Sets a texture with no contents of a certain size. In other words calls gl.texImage2D with null.
You must set options.width and options.height.

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

tex WebGLTexture

the WebGLTexture to set parameters for

options module:twgl.TextureOptions

A TextureOptions object with whatever parameters you want set.

(static) setSamplerParameters(gl, sampler, options)

Sets the sampler parameters of a sampler.

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

sampler WebGLSampler

the WebGLSampler to set parameters for

options module:twgl.TextureOptions

A TextureOptions object with whatever parameters you want set.

(static) setTextureFilteringForSize(gl, tex, optionsopt, widthopt, heightopt, internalFormatopt)

Sets filtering or generates mips for texture based on width or height
If width or height is not passed in uses options.width and//or options.height

Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

the WebGLRenderingContext

tex WebGLTexture

the WebGLTexture to set parameters for

options module:twgl.TextureOptions <optional>

A TextureOptions object with whatever parameters you want set.
This is often the same options you passed in when you created the texture.

width number <optional>

width of texture

height number <optional>

height of texture

internalFormat number <optional>

The internalFormat parameter from texImage2D etc..

(static) setTextureFromArray(gl, tex, src, optionsopt)

Sets a texture from an array or typed array. If the width or height is not provided will attempt to
guess the size. See module:twgl.TextureOptions.

Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

the WebGLRenderingContext

tex WebGLTexture

the WebGLTexture to set parameters for

src Array.<number> | ArrayBufferView

An array or typed arry with texture data.

options module:twgl.TextureOptions <optional>

A TextureOptions object with whatever parameters you want set.
This is often the same options you passed in when you created the texture.

(static) setTextureFromElement(gl, tex, element, optionsopt)

Set a texture from the contents of an element. Will also set
texture filtering or generate mips based on the dimensions of the element
unless options.auto === false. If target === gl.TEXTURE_CUBE_MAP will
attempt to slice image into 1x6, 2x3, 3x2, or 6x1 images, one for each face.

Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

the WebGLRenderingContext

tex WebGLTexture

the WebGLTexture to set parameters for

element HTMLElement

a canvas, img, or video element.

options module:twgl.TextureOptions <optional>

A TextureOptions object with whatever parameters you want set.
This is often the same options you passed in when you created the texture.

(static) setTextureParameters(gl, tex, options)

Sets the texture parameters of a texture.

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

tex WebGLTexture

the WebGLTexture to set parameters for

options module:twgl.TextureOptions

A TextureOptions object with whatever parameters you want set.
This is often the same options you passed in when you created the texture.

(inner) copyOptionsAndApplyPackState(gl, options) → {module:twgl.TextureOptions}

Copy the options object and apply pack state

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

options module:twgl.TextureOptions

(inner) createTextureAsync(gl, optionsopt) → {Promise.<CreateTextureInfo>}

Creates a texture based on the options passed in.

see module:twgl/textures.createTexture.
The only difference is this function returns a promise
where as the other returns a texture and takes a callback.

Note: this is here for completeness. It is probably better to use
the non-async version as it returns a usable texture immediately
where as this one you have to wait for it to load.

Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

the WebGLRenderingContext

options module:twgl.TextureOptions <optional>

A TextureOptions object with whatever parameters you want set.

Returns:
Type:
Promise.<CreateTextureInfo>

The created texture and source.

(inner) createTexturesAsync(gl, options) → {Promise.<CreateTexturesInfo>}

Creates textures based on the options passed in.

see module:twgl/textures.createTextures.
The only difference is this function returns a promise
where as the other returns a texture and takes a callback.

Note: this is here for completeness. It is probably better to use
the non-async version as it returns usable textures immediately
where as this one you have to wait for them to load.

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

options Object.<string, module:twgl.TextureOptions>

A object of TextureOptions one per texture.

Returns:
Type:
Promise.<CreateTexturesInfo>

The created textures and sources.

(inner) getPackStateOption(gl, options, property, pname) → {module:twgl.TextureOptions}

returns the property if set or the corresponding state if undefined

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

options module:twgl.TextureOptions
property string

the name of the property to copy

pname number

Type Definitions

TextureFormatInfo

Info related to a specific texture internalFormat as returned
from module:twgl/textures.getFormatAndTypeForInternalFormat.

Properties:
Name Type Description
format number

Format to pass to texImage2D and related functions

type number

Type to pass to texImage2D and related functions

Type:
  • Object