Texture Class
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
Parameters:
-
context
WebGLContextthe WebGL context
-
width
Numberthe width of this texture
-
height
Numberthe height of this texture
-
format
GLenume.g. Texture.Format.RGBA
-
dataType
GLenume.g. Texture.DataType.UNSIGNED_BYTE (Uint8Array)
-
data
GLenumthe array buffer, e.g. a Uint8Array view
-
genMipmaps
Booleanwhether 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
Item Index
Methods
Attributes
Methods
_checkPOT
()
type
private
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:
[description]
bind
-
unit
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
Numberthe texture unit index, starting at 0
create
()
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
()
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
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
GLenuma texture format, i.e. Texture.Format.RGBA
Returns:
the number of components for this format
setFilter
-
min
-
mag
-
ignoreBind
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
GLenumthe minification filter
-
mag
GLenumthe magnification filter
-
ignoreBind
Booleanif true, the bind will be ignored.
setup
()
protected
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
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
GLenumthe S wrap mode
-
t
GLenumthe T wrap mode
-
ignoreBind
Boolean(optional) if true, the bind will be ignored.
uploadData
-
width
-
height
-
format
-
type
-
data
-
genMipmaps
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
Numberthe new width of this texture, defaults to the last used width (or zero)
-
height
Numberthe new height of this texture defaults to the last used height (or zero)
-
format
GLenumthe data format, default RGBA
-
type
GLenumthe data type, default UNSIGNED_BYTE (Uint8Array)
-
data
ArrayBufferViewthe raw data for this texture, or null for an empty image
-
genMipmaps
Booleanwhether to generate mipmaps after uploading the data, default false
uploadImage
-
domObject
-
format
-
type
-
genMipmaps
Uploads ImageData, HTMLImageElement, HTMLCanvasElement or HTMLVideoElement.
Parameters:
-
domObject
Objectthe DOM image container
-
format
GLenumthe format, default gl.RGBA
-
type
GLenumthe data type, default gl.UNSIGNED_BYTE
-
genMipmaps
Booleanwhether to generate mipmaps after uploading the data, default false
Properties
height
Number the height
The height of this texture, in pixels.
magFilter
GLenum
The magnification filter.
managedArgs
Array the array of arguments, shifted to exclude the WebGLContext parameter
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
The minifcation filter.
target
GLenum
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
The width of this texture, in pixels.
wrapS
GLenum
The S wrap parameter.
wrapT
GLenum
The T wrap parameter.
Attributes
DataType
Object
static
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
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
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
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
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