API Reference

Class List

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

graphicsDevicepc.GraphicsDevice

The graphics device used to manage this texture.

optionsobject

Object for passing optional arguments.

options.namestring

The name of the texture.

options.widthnumber

The width of the texture in pixels. Defaults to 4.

options.heightnumber

The height of the texture in pixels. Defaults to 4.

options.depthnumber

The number of depth slices in a 3D texture (WebGL2 only). Defaults to 1 (single 2D image).

options.formatnumber

The pixel format of the texture. Can be:

options.minFilternumber

The minification filter type to use. Defaults to pc.FILTER_LINEAR_MIPMAP_LINEAR

options.magFilternumber

The magnification filter type to use. Defaults to pc.FILTER_LINEAR

options.anisotropynumber

The level of anisotropic filtering to use. Defaults to 1

options.addressUnumber

The repeat mode to use in the U direction. Defaults to pc.ADDRESS_REPEAT

options.addressVnumber

The repeat mode to use in the V direction. Defaults to pc.ADDRESS_REPEAT

options.addressWnumber

The repeat mode to use in the W direction. Defaults to pc.ADDRESS_REPEAT

options.mipmapsboolean

When enabled try to generate or use mipmaps for this texture. Default is true

options.cubemapboolean

Specifies whether the texture is to be a cubemap. Defaults to false.

options.volumeboolean

Specifies whether the texture is to be a 3D volume (WebGL2 only). Defaults to false.

options.typestring

Specifies the image type, see pc.TEXTURETYPE_DEFAULT

options.fixCubemapSeamsboolean

Specifies whether this cubemap texture requires special seam fixing shader code to look right. Defaults to false.

options.flipYboolean

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

If true, the alpha channel of the texture (if present) is multiplied into the color channels. Defaults to false.

options.compareOnReadboolean

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

Comparison function when compareOnRead is enabled (WebGL2 only). Defaults to pc.FUNC_LESS. Possible values:

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:

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

mipLevelnumber

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

optionsobject

Optional options object. Valid properties are as follows:

options.levelnumber

The mip level to lock with 0 being the top level. Defaults to 0.

options.facenumber

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

sourceHTMLCanvasElement, HTMLImageElement, HTMLVideoElement, HTMLCanvasElement[], HTMLImageElement[], HTMLVideoElement[]

A canvas, image or video element, or an array of 6 canvas, image or video elements.

mipLevelnumber

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.