Class: Texture

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.

Constructor

new Texture(graphicsDevice, options)

Creates a new texture.
Parameters:
Name Type Description
graphicsDevice pc.GraphicsDevice The graphics device used to manage this texture.
options Object Object for passing optional arguments.
Properties
Name Type Description
width Number The width of the texture in pixels. Defaults to 4.
height Number The height of the texture in pixels. Defaults to 4.
depth Number The number of depth slices in a 3D texture (WebGL2 only). Defaults to 1 (single 2D image).
format Number The pixel format of the texture. Can be: Defaults to pc.PIXELFORMAT_R8_G8_B8_A8.
minFilter Number The minification filter type to use. Defaults to pc.FILTER_LINEAR_MIPMAP_LINEAR
magFilter Number The magnification filter type to use. Defaults to pc.FILTER_LINEAR
anisotropy Number The level of anisotropic filtering to use. Defaults to 1
addressU Number The repeat mode to use in the U direction. Defaults to pc.ADDRESS_REPEAT
addressV Number The repeat mode to use in the V direction. Defaults to pc.ADDRESS_REPEAT
mipmaps Boolean When enabled try to generate or use mipmaps for this texture. Default is true
cubemap Boolean Specifies whether the texture is to be a cubemap. Defaults to false.
volume Boolean Specifies whether the texture is to be a 3D volume (WebGL2 only). Defaults to false.
rgbm Boolean Specifies whether the texture contains RGBM-encoded HDR data. Defaults to false.
fixCubemapSeams Boolean Specifies whether this cubemap texture requires special seam fixing shader code to look right. Defaults to false.
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.
premultiplyAlpha Boolean If true, the alpha channel of the texture (if present) is multiplied into the color channels. Defaults to false.
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.
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:
Name Type Description
name String The name of the texture. Defaults to null.
Source:
Example
// 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();

Members

addressU :Number

The addressing mode to be applied to the texture horizontally. Can be:
Type:
  • Number
Source:

addressV :Number

The addressing mode to be applied to the texture vertically. Can be:
Type:
  • Number
Source:

addressW :Number

The addressing mode to be applied to the 3D texture depth (WebGL2 only). Can be:
Type:
  • Number
Source:

anisotropy :Number

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

(private) autoMipmap :Boolean

Toggles automatic mipmap generation. Can't be used on non power of two textures.
Type:
  • Boolean
Deprecated:
  • Yes
Source:

compareFunc :Number

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
Type:
  • Number
Source:

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).
Type:
  • Boolean
Source:

(readonly) cubemap :Boolean

Returns true if this texture is a cube map and false otherwise.
Type:
  • Boolean
Source:

(readonly) depth :Number

The number of depth slices in a 3D texture (WebGL2 only).
Type:
  • Number
Source:

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.
Type:
  • Boolean
Source:

(readonly) format :Number

Type:
  • Number
Source:

(readonly) height :Number

The height of the texture in pixels.
Type:
  • Number
Source:

magFilter :Number

The magnification filter to be applied to the texture. Can be:
Type:
  • Number
Source:

minFilter :Number

Type:
  • Number
Source:

mipmaps :Boolean

Defines if texture should generate/upload mipmaps if possible.
Type:
  • Boolean
Source:

(readonly) volume :Boolean

Returns true if this texture is a 3D volume and false otherwise.
Type:
  • Boolean
Source:

(readonly) width :Number

The width of the texture in pixels.
Type:
  • Number
Source:

Methods

destroy()

Forcibly free up the underlying WebGL resource owned by the texture.
Source:

getSource(mipLevel) → {HTMLImageElement}

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:
Name Type Description
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.
Source:
Returns:
The source image of this texture. Can be null if source not assigned for specific image level.
Type
HTMLImageElement

lock(options) → {ArrayBuffer}

Locks a miplevel of the texture, returning a typed array to be filled with pixel data.
Parameters:
Name Type Description
options Object Optional options object. Valid properties are as follows:
Properties
Name Type Description
level Number The mip level to lock with 0 being the top level. Defaults to 0.
face Number If the texture is a cubemap, this is the index of the face to lock.
Source:
Returns:
A typed array containing the pixel data of the locked mip level.
Type
ArrayBuffer

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:
Name Type Description
source HTMLCanvasElement | HTMLImageElement | HTMLVideoElement | Array 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.
Source:

unlock()

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

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.
Source: