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 compatibily they are available at both twgl.textures and twgl
itself

See module:twgl for core functions

Methods

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

Creates a texture based on the options passed in.

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) getNumComponentsForFormat(format) → {number}

Gets the number of compontents for a given image format.

Parameters:
Name Type Description
format number

the format.

Returns:
Type:
number

the number of components for the format.

(static) loadCubemapFromUrls(gl, tex, options, callbackopt)

Loads a cubemap from 6 urls or TexImageSources as specified in options.src. Will set the cubemap to a 1x1 pixel color
so that it is usable immediately unless option.color === false.

Parameters:
Name Type Attributes 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.

callback module:twgl.CubemapReadyCallback <optional>

A function to be called when all the images have finished loading. err will
be non null if there was an error.

(static) loadSlicesFromUrls(gl, tex, options, callbackopt)

Loads a 2d array or 3d texture from urls OR TexImageSources as specified in options.src.
Will set the texture to a 1x1 pixel color
so that it is usable immediately unless option.color === false.

If the width and height is not specified the width and height of the first
image loaded will be used. Note that since images are loaded async
which image downloads first is unknown.

If an image is not the same size as the width and height it will be scaled
to that width and height.

Parameters:
Name Type Attributes 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.

callback module:twgl.ThreeDReadyCallback <optional>

A function to be called when all the images have finished loading. err will
be non null if there was an error.

(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 approriate 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)

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

(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, typeopt)

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..

type number <optional>

The type parameter for 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.

(static) setTextureTo1PixelColor(gl, tex, optionsopt)

Sets a texture to a 1x1 pixel color. If options.color === false is nothing happens. If it's not set
the default texture color is used which can be set by calling setDefaultTextureColor.

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.

(inner) canFilter(internalFormat, type) → {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..

type number

The type parameter for texImage2D etc..

Returns:
Type:
boolean

true if we can generate mips

(inner) canGenerateMipmap(internalFormat, type) → {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..

type number

The type parameter for texImage2D etc..

Returns:
Type:
boolean

true if we can generate mips

(inner) createSampler(gl, options) → {Object.<string, WebGLSampler>}

Creates a new sampler object and sets parameters.

Example:

 const sampler = twgl.createSampler(gl, {
   minMag: gl.NEAREST,         // sets both TEXTURE_MIN_FILTER and TEXTURE_MAG_FILTER
   wrap: gl.CLAMP_TO_NEAREST,  // sets both TEXTURE_WRAP_S and TEXTURE_WRAP_T and TEXTURE_WRAP_R
 });
Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

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

A object of TextureOptions one per sampler.

Returns:
Type:
Object.<string, WebGLSampler>

the created samplers by name

(inner) createSamplers(gl, optionsopt)

Creates a multiple sampler objects and sets parameters on each.

Example:

 const samplers = twgl.createSamplers(gl, {
   nearest: {
     minMag: gl.NEAREST,
   },
   nearestClampS: {
     minMag: gl.NEAREST,
     wrapS: gl.CLAMP_TO_NEAREST,
   },
   linear: {
     minMag: gl.LINEAR,
   },
   nearestClamp: {
     minMag: gl.NEAREST,
     wrap: gl.CLAMP_TO_EDGE,
   },
   linearClamp: {
     minMag: gl.LINEAR,
     wrap: gl.CLAMP_TO_EDGE,
   },
   linearClampT: {
     minMag: gl.LINEAR,
     wrapT: gl.CLAMP_TO_EDGE,
   },
 });
Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

the WebGLRenderingContext

options module:twgl.TextureOptions <optional>

A TextureOptions object with whatever parameters you want set on the sampler

(inner) getCubeFaceOrder(gl, options) → {Array.<number>}

Gets an array of cubemap face enums

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

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.

Returns:
Type:
Array.<number>

cubemap face enums

(inner) getCubeFacesWithNdx(gl, options) → {Array.<FaceInfo>}

Gets an array of FaceInfos
There's a bug in some NVidia drivers that will crash the driver if
gl.TEXTURE_CUBE_MAP_POSITIVE_X is not uploaded first. So, we take
the user's desired order from his faces to WebGL and make sure we
do the faces in WebGL order

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

options module:twgl.TextureOptions

A TextureOptions object with whatever parameters you want set.

Returns:
Type:
Array.<FaceInfo>

cubemap face infos. Arguably the face property of each element is redundent but
it's needed internally to sort the array of ndx properties by face.

(inner) getFormatAndTypeForInternalFormat(internalFormat) → {Object}

Gets the format for a given internalFormat

Parameters:
Name Type Description
internalFormat number

The internal format

Returns:
Type:
Object

the corresponding format and type

(inner) getTextureTypeForArrayType(gl) → {number}

Gets the texture type for a given array type.

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

Returns:
Type:
number

the gl texture type

(inner) isAsyncSrc(src) → {bool}

Check if a src is an async request.
if src is a string we're going to download an image
if src is an array of strings we're going to download cubemap images

Parameters:
Name Type Description
src *

The src from a TextureOptions

Returns:
Type:
bool

true if src is async.

(inner) isPowerOf2(value)

Returns true if value is power of 2

Parameters:
Name Type Description
value number

number to check.

Returns:

true if value is power of 2

(inner) isTexImageSource(obj) → {boolean}

check if object is a TexImageSource

Parameters:
Name Type Description
obj Object

Object to test

Returns:
Type:
boolean

true if object is a TexImageSource

(inner) loadAndUseImage(obj, crossOrigin, callbackopt)

if obj is an TexImageSource then just
uses it otherwise if obj is a string
then load it first.

Parameters:
Name Type Attributes Description
obj string | TexImageSource
crossOrigin string
callback function <optional>

a callback that's passed an error and the image. The error will be non-null
if there was an error

(inner) loadImage(url, crossOrigin, callbackopt) → {HTMLImageElement}

Loads an image

Parameters:
Name Type Attributes Description
url string

url to image

crossOrigin string
callback function <optional>

a callback that's passed an error and the image. The error will be non-null
if there was an error

Returns:
Type:
HTMLImageElement

the image being loaded.

(inner) make1Pixel(coloropt) → {Uint8Array}

Makes a 1x1 pixel
If no color is passed in uses the default color which can be set by calling setDefaultTextureColor.

Parameters:
Name Type Attributes Description
color Array.<number> | ArrayBufferView <optional>

The color using 0-1 values

Returns:
Type:
Uint8Array

Unit8Array with color.

(inner) restorePackState(options, gl)

Restores any packing state that was set based on the options.

Parameters:
Name Type Description
options module:twgl.TextureOptions

A TextureOptions object with whatever parameters you want set.

gl WebGLRenderingContext

the WebGLRenderingContext

(inner) restoreSkipState(gl)

Restores state related to data size

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

(inner) savePackState(options, gl)

Saves any packing state that will be set based on the options.

Parameters:
Name Type Description
options module:twgl.TextureOptions

A TextureOptions object with whatever parameters you want set.

gl WebGLRenderingContext

the WebGLRenderingContext

(inner) saveSkipState(gl)

Saves state related to data size

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

(inner) setTextureSamplerParameters(gl, target, parameteriFn, tex, options)

Sets the parameters of a texture or sampler

Parameters:
Name Type Description
gl WebGLRenderingContext

the WebGLRenderingContext

target number | WebGLSampler

texture target or sampler

parameteriFn function

texParamteri or samplerParameteri fn

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.