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

addressUThe addressing mode to be applied to the texture horizontally.
addressVThe addressing mode to be applied to the texture vertically.
addressWThe addressing mode to be applied to the 3D texture depth (WebGL2 only).
anisotropyInteger value specifying the level of anisotropic to apply to the texture ranging from 1 (no anisotropic filtering) to the pc.GraphicsDevice property maxAnisotropy.
compareFuncComparison function when compareOnRead is enabled (WebGL2 only).
compareOnReadWhen enabled, and if texture format is pc.
cubemapReturns true if this texture is a cube map and false otherwise.[read only]
depthThe number of depth slices in a 3D texture (WebGL2 only).[read only]
formatThe pixel format of the texture.[read only]
heightThe height of the texture in pixels.[read only]
magFilterThe magnification filter to be applied to the texture.
minFilterThe minification filter to be applied to the texture.
mipmapsDefines if texture should generate/upload mipmaps if possible.
volumeReturns true if this texture is a 3D volume and false otherwise.[read only]
widthThe width of the texture in pixels.[read only]

Methods

destroyForcibly free up the underlying WebGL resource owned by the texture.
getSourceGet the pixel data of the texture.
lockLocks a miplevel of the texture, returning a typed array to be filled with pixel data.
setSourceSet the pixel data of the texture from a canvas, image, video DOM element.
unlockUnlocks the currently locked mip level and uploads it to VRAM.
uploadForces 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.GraphicsDeviceThe graphics device used to manage this texture.
optionsObjectObject for passing optional arguments.
options.widthNumberThe width of the texture in pixels. Defaults to 4.
options.heightNumberThe height of the texture in pixels. Defaults to 4.
options.depthNumberThe number of depth slices in a 3D texture (WebGL2 only). Defaults to 1 (single 2D image).
options.formatNumberThe pixel format of the texture. Can be: Defaults to pc.PIXELFORMAT_R8_G8_B8_A8.
options.minFilterNumberThe minification filter type to use. Defaults to pc.FILTER_LINEAR_MIPMAP_LINEAR
options.magFilterNumberThe magnification filter type to use. Defaults to pc.FILTER_LINEAR
options.anisotropyNumberThe level of anistropic filtering to use. Defaults to 1
options.addressUNumberThe repeat mode to use in the U direction. Defaults to pc.ADDRESS_REPEAT
options.addressVNumberThe repeat mode to use in the V direction. Defaults to pc.ADDRESS_REPEAT
options.mipmapsBooleanWhen enabled try to generate or use mipmaps for this texture. Default is true
options.cubemapBooleanSpecifies whether the texture is to be a cubemap. Defaults to false.
options.volumeBooleanSpecifies whether the texture is to be a 3D volume (WebGL2 only). Defaults to false.
options.rgbmBooleanSpecifies whether the texture contains RGBM-encoded HDR data. Defaults to false.
options.fixCubemapSeamsBooleanSpecifies whether this cubemap texture requires special seam fixing shader code to look right. Defaults to false.
options.compareOnReadBooleanWhen 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.compareFuncNumberComparison 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:

  • pc.FUNC_LESS
  • pc.FUNC_LESSEQUAL
  • pc.FUNC_GREATER
  • pc.FUNC_GREATEREQUAL
  • pc.FUNC_EQUAL
  • pc.FUNC_NOTEQUAL

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]

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.

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()

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.

Returns

HTMLImageElement The source image of this texture.

lock(options)

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

Parameters

optionsObjectOptional options object. Valid properties are as follows:
options.levelNumberThe mip level to lock with 0 being the top level. Defaults to 0.
options.faceNumberIf the texture is a cubemap, this is the index of the face to lock.

setSource(source)

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, ArrayA canvas, image or video element, or an array of 6 canvas, image or video elements.

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.