Texture

A texture is a container for texel data that can be utilized in a fragment shader. Typically, the texel data represents an image that is mapped over geometry.

// Create a 8x8x24-bit texture
const texture = new pc.Texture(graphicsDevice, {
    width: 8,
    height: 8,
    format: pc.PIXELFORMAT_RGB8
});

// Fill the texture with a gradient
const pixels = texture.lock();
const count = 0;
for (let i = 0; i < 8; i++) {
    for (let j = 0; j < 8; j++) {
        pixels[count++] = i * 32;
        pixels[count++] = j * 32;
        pixels[count++] = 255;
    }
}
texture.unlock();

Summary

Properties

addressU	The addressing mode to be applied to the texture horizontally.
addressV	The addressing mode to be applied to the texture vertically.
addressW	The addressing mode to be applied to the 3D texture depth (not supported on WebGL1).
anisotropy	Integer value specifying the level of anisotropic to apply to the texture ranging from 1 (no anisotropic filtering) to the GraphicsDevice property maxAnisotropy.
compareFunc	Comparison function when compareOnRead is enabled (not supported on WebGL1).
compareOnRead	When enabled, and if texture format is PIXELFORMAT_DEPTH or PIXELFORMAT_DEPTHSTENCIL, hardware PCF is enabled for this texture, and you can get filtered results of comparison using texture() in your shader (not supported on WebGL1).
cubemap	Returns true if this texture is a cube map and false otherwise.
depth	The number of depth slices in a 3D texture.
flipY	Specifies whether the texture should be flipped in the Y-direction.
format	The pixel format of the texture.
height	The height of the texture in pixels.
magFilter	The magnification filter to be applied to the texture.
minFilter	The minification filter to be applied to the texture.
mipmaps	Defines if texture should generate/upload mipmaps if possible.
name	The name of the texture.
pot	Returns true if all dimensions of the texture are power of two, and false otherwise.
volume	Returns true if this texture is a 3D volume and false otherwise.
width	The width of the texture in pixels.

Methods

destroy	Frees resources associated with this texture.
getSource	Get the pixel data of the texture.
lock	Locks a miplevel of the texture, returning a typed array to be filled with pixel data.
setSource	Set the pixel data of the texture from a canvas, image, video DOM element.
unlock	Unlocks the currently locked mip level and uploads it to VRAM.
upload	Forces a reupload of the textures pixel data to graphics memory.

Details

Constructor

Texture(graphicsDevice, [options]) 

Create a new Texture instance.

// Create a 8x8x24-bit texture
const texture = new pc.Texture(graphicsDevice, {
    width: 8,
    height: 8,
    format: pc.PIXELFORMAT_RGB8
});

// Fill the texture with a gradient
const pixels = texture.lock();
const count = 0;
for (let i = 0; i < 8; i++) {
    for (let j = 0; j < 8; j++) {
        pixels[count++] = i * 32;
        pixels[count++] = j * 32;
        pixels[count++] = 255;
    }
}
texture.unlock();

Parameters

graphicsDevice	GraphicsDevice	The graphics device used to manage this texture.
options	object	Object for passing optional arguments.
options.name	string	The name of the texture. Defaults to null.
options.width	number	The width of the texture in pixels. Defaults to 4.
options.height	number	The height of the texture in pixels. Defaults to 4.
options.depth	number	The number of depth slices in a 3D texture (not supported by WebGl1). Defaults to 1 (single 2D image).
options.format	number	The pixel format of the texture. Can be: PIXELFORMAT_A8 PIXELFORMAT_L8 PIXELFORMAT_LA8 PIXELFORMAT_RGB565 PIXELFORMAT_RGBA5551 PIXELFORMAT_RGBA4 PIXELFORMAT_RGB8 PIXELFORMAT_RGBA8 PIXELFORMAT_DXT1 PIXELFORMAT_DXT3 PIXELFORMAT_DXT5 PIXELFORMAT_RGB16F PIXELFORMAT_RGBA16F PIXELFORMAT_RGB32F PIXELFORMAT_RGBA32F PIXELFORMAT_ETC1 PIXELFORMAT_PVRTC_2BPP_RGB_1 PIXELFORMAT_PVRTC_2BPP_RGBA_1 PIXELFORMAT_PVRTC_4BPP_RGB_1 PIXELFORMAT_PVRTC_4BPP_RGBA_1 PIXELFORMAT_111110F PIXELFORMAT_ASTC_4x4 PIXELFORMAT_ATC_RGB PIXELFORMAT_ATC_RGBA Defaults to PIXELFORMAT_RGBA8.
options.projection	string	The projection type of the texture, used when the texture represents an environment. Can be: TEXTUREPROJECTION_NONE TEXTUREPROJECTION_CUBE TEXTUREPROJECTION_EQUIRECT TEXTUREPROJECTION_OCTAHEDRAL Defaults to TEXTUREPROJECTION_CUBE if options.cubemap is true, otherwise TEXTUREPROJECTION_NONE.
options.minFilter	number	The minification filter type to use. Defaults to FILTER_LINEAR_MIPMAP_LINEAR.
options.magFilter	number	The magnification filter type to use. Defaults to FILTER_LINEAR.
options.anisotropy	number	The level of anisotropic filtering to use. Defaults to 1.
options.addressU	number	The repeat mode to use in the U direction. Defaults to ADDRESS_REPEAT.
options.addressV	number	The repeat mode to use in the V direction. Defaults to ADDRESS_REPEAT.
options.addressW	number	The repeat mode to use in the W direction. Defaults to ADDRESS_REPEAT.
options.mipmaps	boolean	When enabled try to generate or use mipmaps for this texture. Default is true.
options.cubemap	boolean	Specifies whether the texture is to be a cubemap. Defaults to false.
options.volume	boolean	Specifies whether the texture is to be a 3D volume (not supported by WebGL1). Defaults to false.
options.type	string	Specifies the texture type. Can be: TEXTURETYPE_DEFAULT TEXTURETYPE_RGBM TEXTURETYPE_RGBE TEXTURETYPE_RGBP TEXTURETYPE_SWIZZLEGGGR Defaults to TEXTURETYPE_DEFAULT.
options.fixCubemapSeams	boolean	Specifies whether this cubemap texture requires special seam fixing shader code to look right. Defaults to false.
options.flipY	boolean	Specifies whether the texture should be flipped in the Y-direction. Only affects textures with a source that is an image, canvas or video element. Does not affect cubemaps, compressed textures or textures set from raw pixel data. Defaults to false.
options.premultiplyAlpha	boolean	If true, the alpha channel of the texture (if present) is multiplied into the color channels. Defaults to false.
options.compareOnRead	boolean	When enabled, and if texture format is PIXELFORMAT_DEPTH or PIXELFORMAT_DEPTHSTENCIL, hardware PCF is enabled for this texture, and you can get filtered results of comparison using texture() in your shader (not supported by WebGL1). Defaults to false.
options.compareFunc	number	Comparison function when compareOnRead is enabled (not supported by WebGL1). Can be: FUNC_LESS FUNC_LESSEQUAL FUNC_GREATER FUNC_GREATEREQUAL FUNC_EQUAL FUNC_NOTEQUAL Defaults to FUNC_LESS.
options.levels	Uint8Array[], HTMLCanvasElement[], HTMLImageElement[], HTMLVideoElement[]	Array of Uint8Array or other supported browser interface.

Properties

numberaddressU 

The addressing mode to be applied to the texture horizontally. Can be:

numberaddressV 

The addressing mode to be applied to the texture vertically. Can be:

numberaddressW 

The addressing mode to be applied to the 3D texture depth (not supported on WebGL1). Can be:

numberanisotropy 

Integer value specifying the level of anisotropic to apply to the texture ranging from 1 (no anisotropic filtering) to the GraphicsDevice property maxAnisotropy.

numbercompareFunc 

Comparison function when compareOnRead is enabled (not supported on WebGL1). Possible values:

booleancompareOnRead 

When enabled, and if texture format is PIXELFORMAT_DEPTH or PIXELFORMAT_DEPTHSTENCIL, hardware PCF is enabled for this texture, and you can get filtered results of comparison using texture() in your shader (not supported on WebGL1).

booleancubemap 

Returns true if this texture is a cube map and false otherwise.

numberdepth 

The number of depth slices in a 3D texture.

booleanflipY 

Specifies whether the texture should be flipped in the Y-direction. Only affects textures with a source that is an image, canvas or video element. Does not affect cubemaps, compressed textures or textures set from raw pixel data. Defaults to true.

numberheight 

The height of the texture in pixels.

numbermagFilter 

The magnification filter to be applied to the texture. Can be:

numberminFilter 

The minification filter to be applied to the texture. Can be:

booleanmipmaps 

Defines if texture should generate/upload mipmaps if possible.

stringname 

The name of the texture.

booleanpot 

Returns true if all dimensions of the texture are power of two, and false otherwise.

booleanvolume 

Returns true if this texture is a 3D volume and false otherwise.

numberwidth 

The width of the texture in pixels.

Methods

destroy() 

Frees resources associated with this texture.

getSource([mipLevel]) 

Get the pixel data of the texture. If this is a cubemap then an array of 6 images will be returned otherwise a single image.

Parameters

mipLevel

number

A non-negative integer specifying the image level of detail. Defaults to 0, which represents the base image source. A level value of N, that is greater than 0, represents the image source for the Nth mipmap reduction level.

Returns

HTMLImageElement

The source image of this texture. Can be null if source not assigned for specific image level.

lock([options]) 

Locks a miplevel of the texture, returning a typed array to be filled with pixel data.

Parameters

options	object	Optional options object. Valid properties are as follows:
options.level	number	The mip level to lock with 0 being the top level. Defaults to 0.
options.face	number	If the texture is a cubemap, this is the index of the face to lock.
options.mode	number	The lock mode. Can be: TEXTURELOCK_READ TEXTURELOCK_WRITE Defaults to TEXTURELOCK_WRITE.

Returns

Uint8Array, Uint16Array, Float32Array

A typed array containing the pixel data of the locked mip level.

setSource(source, [mipLevel]) 

Set the pixel data of the texture from a canvas, image, video DOM element. If the texture is a cubemap, the supplied source must be an array of 6 canvases, images or videos.

Parameters

source	HTMLCanvasElement, HTMLImageElement, HTMLVideoElement, HTMLCanvasElement[], HTMLImageElement[], HTMLVideoElement[]	A canvas, image or video element, or an array of 6 canvas, image or video elements.
mipLevel	number	A non-negative integer specifying the image level of detail. Defaults to 0, which represents the base image source. A level value of N, that is greater than 0, represents the image source for the Nth mipmap reduction level.

unlock() 

Unlocks the currently locked mip level and uploads it to VRAM.

upload() 

Forces a reupload of the textures pixel data to graphics memory. Ordinarily, this function is called by internally by Texture#setSource and Texture#unlock. However, it still needs to be called explicitly in the case where an HTMLVideoElement is set as the source of the texture. Normally, this is done once every frame before video textured geometry is rendered.