pc.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
var texture = new pc.Texture(graphicsDevice, {
    width: 8,
    height: 8,
    format: pc.PIXELFORMAT_R8_G8_B8
});

// Fill the texture with a gradient
var pixels = texture.lock();
var count = 0;
for (var i = 0; i < 8; i++) {
    for (var 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 (WebGL2 only).
anisotropy	Integer value specifying the level of anisotropic to apply to the texture ranging from 1 (no anisotropic filtering) to the pc.GraphicsDevice property maxAnisotropy.
compareFunc	Comparison function when compareOnRead is enabled (WebGL2 only).
compareOnRead	When enabled, and if texture format is pc.
cubemap	Returns true if this texture is a cube map and false otherwise.[read only]
depth	The number of depth slices in a 3D texture (WebGL2 only).[read only]
flipY	Specifies whether the texture should be flipped in the Y-direction.
format	The pixel format of the texture.[read only]
height	The height of the texture in pixels.[read only]
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.[read only]
volume	Returns true if this texture is a 3D volume and false otherwise.[read only]
width	The width of the texture in pixels.[read only]

Methods

destroy	Forcibly free up the underlying WebGL resource owned by the 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]) 

Creates a new texture.

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

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

Parameters

graphicsDevice	pc.GraphicsDevice	The graphics device used to manage this texture.
options	object	Object for passing optional arguments.
options.name	string	The name of the texture.
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 (WebGL2 only). Defaults to 1 (single 2D image).
options.format	number	The pixel format of the texture. Can be: pc.PIXELFORMAT_A8 pc.PIXELFORMAT_L8 pc.PIXELFORMAT_L8_A8 pc.PIXELFORMAT_R5_G6_B5 pc.PIXELFORMAT_R5_G5_B5_A1 pc.PIXELFORMAT_R4_G4_B4_A4 pc.PIXELFORMAT_R8_G8_B8 pc.PIXELFORMAT_R8_G8_B8_A8 pc.PIXELFORMAT_DXT1 pc.PIXELFORMAT_DXT3 pc.PIXELFORMAT_DXT5 pc.PIXELFORMAT_RGB16F pc.PIXELFORMAT_RGBA16F pc.PIXELFORMAT_RGB32F pc.PIXELFORMAT_RGBA32F pc.PIXELFORMAT_ETC1 pc.PIXELFORMAT_PVRTC_2BPP_RGB_1 pc.PIXELFORMAT_PVRTC_2BPP_RGBA_1 pc.PIXELFORMAT_PVRTC_4BPP_RGB_1 pc.PIXELFORMAT_PVRTC_4BPP_RGBA_1 pc.PIXELFORMAT_111110F pc.PIXELFORMAT_ASTC_4x4>/li> pc.PIXELFORMAT_ATC_RGB pc.PIXELFORMAT_ATC_RGBA Defaults to pc.PIXELFORMAT_R8_G8_B8_A8.
options.minFilter	number	The minification filter type to use. Defaults to pc.FILTER_LINEAR_MIPMAP_LINEAR
options.magFilter	number	The magnification filter type to use. Defaults to pc.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 pc.ADDRESS_REPEAT
options.addressV	number	The repeat mode to use in the V direction. Defaults to pc.ADDRESS_REPEAT
options.addressW	number	The repeat mode to use in the W direction. Defaults to pc.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 (WebGL2 only). Defaults to false.
options.rgbm	boolean	Specifies whether the texture contains RGBM-encoded HDR data. Defaults to false.
options.swizzleGGGR	boolean	Specifies whether the texture contains swizzled GGGR data for use with tangent space normal maps. The R component is stored in alpha and G is stored in RGB. This packing can result in higher quality when the texture data is compressed. Defaults to false.
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 true.
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 pc.PIXELFORMAT_DEPTH or pc.PIXELFORMAT_DEPTHSTENCIL, hardware PCF is enabled for this texture, and you can get filtered results of comparison using texture() in your shader (WebGL2 only). Defaults to false.
options.compareFunc	number	Comparison function when compareOnRead is enabled (WebGL2 only). Defaults to pc.FUNC_LESS. Possible values: pc.FUNC_LESS pc.FUNC_LESSEQUAL pc.FUNC_GREATER pc.FUNC_GREATEREQUAL pc.FUNC_EQUAL pc.FUNC_NOTEQUAL

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 (WebGL2 only). Can be:

numberanisotropy 

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

numbercompareFunc 

Comparison function when compareOnRead is enabled (WebGL2 only). Possible values:

booleancompareOnRead 

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

booleancubemap 

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

[read only]

numberdepth 

The number of depth slices in a 3D texture (WebGL2 only).

[read only]

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.

[read only]

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. Defaults to null.

booleanpot 

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

[read only]

booleanvolume 

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

[read only]

numberwidth 

The width of the texture in pixels.

[read only]

Methods

destroy() 

Forcibly free up the underlying WebGL resource owned by the 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.

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 pc.Texture#setSource and pc.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.