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:

the created texture.

Type
WebGLTexture

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

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

Example:

var 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:

the created textures by name

Type
Object.<string, WebGLTexture>

(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:

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

Type
number

(static) getNumComponentsForFormat(format) → {number}

Gets the number of compontents for a given image format.

Parameters:
Name Type Description
format number

the format.

Returns:

the number of components for the format.

Type
number

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

Loads a cubemap from 6 urls 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 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:

the image being downloaded.

Type
HTMLImageElement

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

Parameters:
Name Type Description
color Array.<number>

Array of 4 values in the range 0 to 1

Deprecated:

(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> | ArrayBuffer

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.