API Docs for: 0.5.1
Show:

Texture Class

Defined in: lib/Texture.js:13
Module: kami

Creates a new texture with the optional width, height, and data.

If the constructor is passed no parameters other than WebGLContext, then it will not be initialized and will be non-renderable. You will need to manually uploadData or uploadImage yourself.

If you pass a width and height after context, the texture will be initialized with that size and null data (e.g. transparent black). If you also pass the format and data, it will be uploaded to the texture.

If you pass a String or Data URI as the second parameter, this Texture will load an Image object asynchronously. The optional third and fourth parameters are callback functions for success and failure, respectively. The optional fifrth parameter for this version of the constructor is genMipmaps, which defaults to false.

The arguments are kept in memory for future context restoration events. If this is undesirable (e.g. huge buffers which need to be GC'd), you should not pass the data in the constructor, but instead upload it after creating an uninitialized texture. You will need to manage it yourself, either by extending the create() method, or listening to restored events in WebGLContext.

Most users will want to use the AssetManager to create and manage their textures with asynchronous loading and context loss.

Constructor

Texture

(
  • context
  • width
  • height
  • format
  • dataType
  • data
  • genMipmaps
)

Defined in lib/Texture.js:13

Parameters:

  • context WebGLContext

    the WebGL context

  • width Number

    the width of this texture

  • height Number

    the height of this texture

  • format GLenum

    e.g. Texture.Format.RGBA

  • dataType GLenum

    e.g. Texture.DataType.UNSIGNED_BYTE (Uint8Array)

  • data GLenum

    the array buffer, e.g. a Uint8Array view

  • genMipmaps Boolean

    whether to generate mipmaps after uploading the data

Example:

    new Texture(context, 256, 256); //empty 256x256 texture
    new Texture(context, 1, 1, Texture.Format.RGBA, Texture.DataType.UNSIGNED_BYTE, 
                new Uint8Array([255,0,0,255])); //1x1 red texture
    new Texture(context, "test.png"); //loads image asynchronously
    new Texture(context, "test.png", successFunc, failFunc, useMipmaps); //extra params for image laoder

Methods

_checkPOT

() type private

Defined in lib/Texture.js:393

If FORCE_POT is false, we verify this texture to see if it is valid, as per non-power-of-two rules. If it is non-power-of-two, it must have a wrap mode of CLAMP_TO_EDGE, and the minification filter must be LINEAR or NEAREST. If we don't satisfy these needs, an error is thrown.

Returns:

type:

[description]

bind

(
  • unit
)

Defined in lib/Texture.js:419

Binds the texture. If unit is specified, it will bind the texture at the given slot (TEXTURE0, TEXTURE1, etc). If unit is not specified, it will simply bind the texture at whichever slot is currently active.

Parameters:

  • unit Number

    the texture unit index, starting at 0

create

()

Defined in lib/Texture.js:207

Called in the Texture constructor, and after the GL context has been re-initialized. Subclasses can override this to provide a custom data upload, e.g. cubemaps or compressed textures.

destroy

()

Defined in lib/Texture.js:242

Destroys this texture by deleting the GL resource, removing it from the WebGLContext management stack, setting its size to zero, and id and managed arguments to null.

Trying to use this texture after may lead to undefined behaviour.

getNumComponents

(
  • format
)
Number static

Defined in lib/Texture.js:583

Utility to get the number of components for the given GLenum, e.g. gl.RGBA returns 4. Returns null if the specified format is not of type DEPTH_COMPONENT, ALPHA, LUMINANCE, LUMINANCE_ALPHA, RGB, or RGBA.

Parameters:

  • format GLenum

    a texture format, i.e. Texture.Format.RGBA

Returns:

Number:

the number of components for this format

setFilter

(
  • min
  • mag
  • ignoreBind
)

Defined in lib/Texture.js:295

Sets the min and mag filter for this texture; if mag is undefined or falsy, then both min and mag will use the filter specified for min.

You can use Texture.Filter constants for convenience, to avoid needing a GL reference.

Parameters:

  • min GLenum

    the minification filter

  • mag GLenum

    the magnification filter

  • ignoreBind Boolean

    if true, the bind will be ignored.

setup

() protected

Defined in lib/Texture.js:146

This can be called after creating a Texture to load an Image object asynchronously, or upload image data directly. It takes the same parameters as the constructor, except for the context which has already been established.

Users will generally not need to call this directly.

setWrap

(
  • s
  • t
  • ignoreBind
)

Defined in lib/Texture.js:263

Sets the wrap mode for this texture; if the second argument is undefined or falsy, then both S and T wrap will use the first argument.

You can use Texture.Wrap constants for convenience, to avoid needing a GL reference.

Parameters:

  • s GLenum

    the S wrap mode

  • t GLenum

    the T wrap mode

  • ignoreBind Boolean

    (optional) if true, the bind will be ignored.

uploadData

(
  • width
  • height
  • format
  • type
  • data
  • genMipmaps
)

Defined in lib/Texture.js:326

A low-level method to upload the specified ArrayBufferView to this texture. This will cause the width and height of this texture to change.

Parameters:

  • width Number

    the new width of this texture, defaults to the last used width (or zero)

  • height Number

    the new height of this texture defaults to the last used height (or zero)

  • format GLenum

    the data format, default RGBA

  • type GLenum

    the data type, default UNSIGNED_BYTE (Uint8Array)

  • data ArrayBufferView

    the raw data for this texture, or null for an empty image

  • genMipmaps Boolean

    whether to generate mipmaps after uploading the data, default false

uploadImage

(
  • domObject
  • format
  • type
  • genMipmaps
)

Defined in lib/Texture.js:363

Uploads ImageData, HTMLImageElement, HTMLCanvasElement or HTMLVideoElement.

Parameters:

  • domObject Object

    the DOM image container

  • format GLenum

    the format, default gl.RGBA

  • type GLenum

    the data type, default gl.UNSIGNED_BYTE

  • genMipmaps Boolean

    whether to generate mipmaps after uploading the data, default false

Properties

height

Number the height

Defined in lib/Texture.js:88

The height of this texture, in pixels.

magFilter

GLenum

Defined in lib/Texture.js:118

The magnification filter.

managedArgs

Array the array of arguments, shifted to exclude the WebGLContext parameter

Defined in lib/Texture.js:124

When a texture is created, we keep track of the arguments provided to its constructor. On context loss and restore, these arguments are re-supplied to the Texture, so as to re-create it in its correct form.

This is mainly useful if you are procedurally creating textures and passing their data directly (e.g. for generic lookup tables in a shader). For image or media based textures, it would be better to use an AssetManager to manage the asynchronous texture upload.

Upon destroying a texture, a reference to this is also lost.

minFilter

GLenum

Defined in lib/Texture.js:112

The minifcation filter.

target

GLenum

Defined in lib/Texture.js:68

The target for this texture unit, i.e. TEXTURE_2D. Subclasses should override the create() method to change this, for correct usage with context restore.

Default: gl.TEXTURE_2D

width

Number the width

Defined in lib/Texture.js:79

The width of this texture, in pixels.

wrapS

GLenum

Defined in lib/Texture.js:102

The S wrap parameter.

wrapT

GLenum

Defined in lib/Texture.js:107

The T wrap parameter.

Attributes

DataType

Object static

Defined in lib/Texture.js:510

A set of DataType constants that match their GL counterparts. This is for convenience, to avoid the need for a GL rendering context.

Example:

    Texture.DataType.UNSIGNED_BYTE 
    Texture.DataType.FLOAT

DEFAULT_FILTER

GLenum static

Defined in lib/Texture.js:547

The default filter mode when creating new textures. If a custom provider was specified, it may choose to override this default mode.

Default: Texture.Filter.LINEAR

DEFAULT_WRAP

GLenum static

Defined in lib/Texture.js:536

The default wrap mode when creating new textures. If a custom provider was specified, it may choose to override this default mode.

Default: Texture.Wrap.CLAMP_TO_EDGE

Filter

Object static

Defined in lib/Texture.js:441

A set of Filter constants that match their GL counterparts. This is for convenience, to avoid the need for a GL rendering context.

Example:

    Texture.Filter.NEAREST
    Texture.Filter.NEAREST_MIPMAP_LINEAR
    Texture.Filter.NEAREST_MIPMAP_NEAREST
    Texture.Filter.LINEAR
    Texture.Filter.LINEAR_MIPMAP_LINEAR
    Texture.Filter.LINEAR_MIPMAP_NEAREST

FORCE_POT

Boolean static

Defined in lib/Texture.js:557

By default, we do some error checking when creating textures to ensure that they will be "renderable" by WebGL. Non-power-of-two textures must use CLAMP_TO_EDGE as their wrap mode, and NEAREST or LINEAR as their wrap mode. Further, trying to generate mipmaps for a NPOT image will lead to errors.

However, you can disable this error checking by setting FORCE_POT to true. This may be useful if you are running on specific hardware that supports POT textures, or in some future case where NPOT textures is added as a WebGL extension.

Default: false

Format

Object static

Defined in lib/Texture.js:487

A set of Format constants that match their GL counterparts. This is for convenience, to avoid the need for a GL rendering context.

Example:

    Texture.Format.RGB
    Texture.Format.RGBA
    Texture.Format.LUMINANCE_ALPHA

Wrap

Object static

Defined in lib/Texture.js:467

A set of Wrap constants that match their GL counterparts. This is for convenience, to avoid the need for a GL rendering context.

Example:

    Texture.Wrap.CLAMP_TO_EDGE
    Texture.Wrap.MIRRORED_REPEAT
    Texture.Wrap.REPEAT