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

Note on HDR texture format support:

As textures:
- float (i.e. PIXELFORMAT_RGBA32F), half-float (i.e. PIXELFORMAT_RGBA16F) and small-float (PIXELFORMAT_111110F) formats are always supported on both WebGL2 and WebGPU with point sampling.
- half-float and small-float formats are always supported on WebGL2 and WebGPU with linear sampling.
- float formats are supported on WebGL2 and WebGPU with linear sampling only if GraphicsDevice#textureFloatFilterable is true.
As renderable textures that can be used as color buffers in a RenderTarget:
- on WebGPU, rendering to float and half-float formats is always supported.
- on WebGPU, rendering to small-float format is supported only if GraphicsDevice#textureRG11B10Renderable is true.
- on WebGL2, rendering to these 3 formats formats is supported only if GraphicsDevice#textureFloatRenderable is true.
- on WebGL2, if GraphicsDevice#textureFloatRenderable is false, but GraphicsDevice#textureHalfFloatRenderable is true, rendering to half-float formats only is supported. This is the case of many mobile iOS devices.
- you can determine available renderable HDR format using GraphicsDevice#getRenderableHdrFormat.

Index

Constructors

constructor

new Texture(
    graphicsDevice: GraphicsDevice,
    options?: {
        addressU?: number;
        addressV?: number;
        addressW?: number;
        anisotropy?: number;
        arrayLength?: number;
        compareFunc?: number;
        compareOnRead?: boolean;
        cubemap?: boolean;
        depth?: number;
        flipY?: boolean;
        format?: number;
        height?: number;
        levels?:
            | Uint8Array<ArrayBufferLike>[]
            | Uint16Array<ArrayBufferLike>[]
            | Uint32Array<ArrayBufferLike>[]
            | Float32Array<ArrayBufferLike>[]
            | HTMLCanvasElement[]
            | HTMLImageElement[]
            | HTMLVideoElement[]
            | Uint8Array<ArrayBufferLike>[][];
        magFilter?: number;
        minFilter?: number;
        mipmaps?: boolean;
        name?: string;
        numLevels?: number;
        premultiplyAlpha?: boolean;
        projection?: string;
        storage?: boolean;
        type?: string;
        volume?: boolean;
        width?: number;
    },
): Texture
Create a new Texture instance.
Parameters
- graphicsDevice: GraphicsDevice
  The graphics device used to manage this texture.
- Optionaloptions: {
      addressU?: number;
      addressV?: number;
      addressW?: number;
      anisotropy?: number;
      arrayLength?: number;
      compareFunc?: number;
      compareOnRead?: boolean;
      cubemap?: boolean;
      depth?: number;
      flipY?: boolean;
      format?: number;
      height?: number;
      levels?:
          | Uint8Array<ArrayBufferLike>[]
          | Uint16Array<ArrayBufferLike>[]
          | Uint32Array<ArrayBufferLike>[]
          | Float32Array<ArrayBufferLike>[]
          | HTMLCanvasElement[]
          | HTMLImageElement[]
          | HTMLVideoElement[]
          | Uint8Array<ArrayBufferLike>[][];
      magFilter?: number;
      minFilter?: number;
      mipmaps?: boolean;
      name?: string;
      numLevels?: number;
      premultiplyAlpha?: boolean;
      projection?: string;
      storage?: boolean;
      type?: string;
      volume?: boolean;
      width?: number;
  } = {}
  Object for passing optional arguments.
  - OptionaladdressU?: number
    The repeat mode to use in the U direction. Defaults to ADDRESS_REPEAT.
  - OptionaladdressV?: number
    The repeat mode to use in the V direction. Defaults to ADDRESS_REPEAT.
  - OptionaladdressW?: number
    The repeat mode to use in the W direction. Defaults to ADDRESS_REPEAT.
  - Optionalanisotropy?: number
    The level of anisotropic filtering to use. Defaults to 1.
  - OptionalarrayLength?: number
    Specifies whether the texture is to be a 2D texture array. When passed in as undefined or < 1, this is not an array texture. If >= 1, this is an array texture. Defaults to undefined.
  - OptionalcompareFunc?: number
    Comparison function when compareOnRead is enabled. Can be:
    
    FUNC_LESS
    
    FUNC_LESSEQUAL
    
    FUNC_GREATER
    
    FUNC_GREATEREQUAL
    
    FUNC_EQUAL
    
    FUNC_NOTEQUAL
    
    Defaults to FUNC_LESS.
  - OptionalcompareOnRead?: 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. Defaults to false.
  - Optionalcubemap?: boolean
    Specifies whether the texture is to be a cubemap. Defaults to false.
  - Optionaldepth?: number
    The number of depth slices in a 3D texture.
  - OptionalflipY?: 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.
  - Optionalformat?: number
    The pixel format of the texture. Can be:
    
    PIXELFORMAT_R8
    
    PIXELFORMAT_RG8
    
    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.
  - Optionalheight?: number
    The height of the texture in pixels. Defaults to 4.
  - Optionallevels?:
        | Uint8Array<ArrayBufferLike>[]
        | Uint16Array<ArrayBufferLike>[]
        | Uint32Array<ArrayBufferLike>[]
        | Float32Array<ArrayBufferLike>[]
        | HTMLCanvasElement[]
        | HTMLImageElement[]
        | HTMLVideoElement[]
        | Uint8Array<ArrayBufferLike>[][]
    Array of Uint8Array or other supported browser interface; or a two-dimensional array of Uint8Array if options.arrayLength is defined and greater than zero.
  - OptionalmagFilter?: number
    The magnification filter type to use. Defaults to FILTER_LINEAR.
  - OptionalminFilter?: number
    The minification filter type to use. Defaults to FILTER_LINEAR_MIPMAP_LINEAR.
  - Optionalmipmaps?: boolean
    When enabled try to generate or use mipmaps for this texture. Default is true.
  - Optionalname?: string
    The name of the texture. Defaults to null.
  - OptionalnumLevels?: number
    Specifies the number of mip levels to generate. If not specified, the number is calculated based on the texture size. When this property is set, the mipmaps property is ignored.
  - OptionalpremultiplyAlpha?: boolean
    If true, the alpha channel of the texture (if present) is multiplied into the color channels. Defaults to false.
  - Optionalprojection?: 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.
  - Optionalstorage?: boolean
    Defines if texture can be used as a storage texture by a compute shader. Defaults to false.
  - Optionaltype?: string
    Specifies the texture type. Can be:
    
    TEXTURETYPE_DEFAULT
    
    TEXTURETYPE_RGBM
    
    TEXTURETYPE_RGBE
    
    TEXTURETYPE_RGBP
    
    TEXTURETYPE_SWIZZLEGGGR
    
    Defaults to TEXTURETYPE_DEFAULT.
  - Optionalvolume?: boolean
    Specifies whether the texture is to be a 3D volume. Defaults to false.
  - Optionalwidth?: number
    The width of the texture in pixels. Defaults to 4.
Returns Texture
Example
```
// 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();
```

Properties

`Protected`_invalid

_invalid: boolean = false

`Protected`_lockedLevel

_lockedLevel: number = -1

`Protected`_lockedMode

_lockedMode: number = TEXTURELOCK_NONE

`Protected`_numLevels

_numLevels: number = 0

`Protected`_numLevelsRequested

_numLevelsRequested: undefined | number

`Protected`_storage

_storage: boolean = false

`Protected`id

id: number = ...

name

name: string

The name of the texture.

Accessors

addressU

get addressU(): number
Gets the addressing mode to be applied to the texture horizontally.

Returns number
set addressU(v: number): void
Sets the addressing mode to be applied to the texture horizontally. Can be:
Parameters
- v: number
Returns void

addressV

get addressV(): number
Gets the addressing mode to be applied to the texture vertically.

Returns number
set addressV(v: number): void
Sets the addressing mode to be applied to the texture vertically. Can be:
Parameters
- v: number
Returns void

addressW

get addressW(): number
Gets the addressing mode to be applied to the 3D texture depth.

Returns number
set addressW(addressW: number): void
Sets the addressing mode to be applied to the 3D texture depth. Can be:
Parameters
- addressW: number
Returns void

anisotropy

get anisotropy(): number
Gets the integer value specifying the level of anisotropy to apply to the texture.

Returns number
set anisotropy(v: number): void
Sets the integer value specifying the level of anisotropy to apply to the texture ranging from 1 (no anisotropic filtering) to the GraphicsDevice property maxAnisotropy.
Parameters
- v: number
Returns void

array

get array(): boolean
Returns true if this texture is a 2D texture array and false otherwise.

Returns boolean

arrayLength

get arrayLength(): number
Returns the number of textures inside this texture if this is a 2D array texture or 0 otherwise.

Returns number

compareFunc

get compareFunc(): number
Sets the comparison function when compareOnRead is enabled.

Returns number
set compareFunc(v: number): void
Sets the comparison function when compareOnRead is enabled. Possible values:
Parameters
- v: number
Returns void

compareOnRead

get compareOnRead(): boolean
Gets whether you can get filtered results of comparison using texture() in your shader.

Returns boolean
set compareOnRead(v: boolean): void
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.
Parameters
- v: boolean
Returns void

cubemap

get cubemap(): boolean
Returns true if this texture is a cube map and false otherwise.

Returns boolean

depth

get depth(): number
The number of depth slices in a 3D texture.

Returns number

flipY

get flipY(): boolean
Gets whether the texture should be flipped in the Y-direction.

Returns boolean
set flipY(flipY: boolean): void
Sets 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.
Parameters
- flipY: boolean
Returns void

format

get format(): number
The pixel format of the texture. Can be:
Returns number

height

get height(): number
The height of the texture in pixels.

Returns number

magFilter

get magFilter(): number
Gets the magnification filter to be applied to the texture.

Returns number
set magFilter(v: number): void
Sets the magnification filter to be applied to the texture. Can be:
- FILTER_NEAREST
- FILTER_LINEAR
Parameters
- v: number
Returns void

minFilter

get minFilter(): number
Gets the minification filter to be applied to the texture.

Returns number
set minFilter(v: number): void
Sets the minification filter to be applied to the texture. Can be:
Parameters
- v: number
Returns void

mipmaps

get mipmaps(): boolean
Gets whether the texture should generate/upload mipmaps.

Returns boolean
set mipmaps(v: boolean): void
Sets whether the texture should generate/upload mipmaps.
Parameters
- v: boolean
Returns void

numLevels

get numLevels(): number
Gets the number of mip levels.

Returns number

pot

get pot(): boolean
Returns true if all dimensions of the texture are power of two, and false otherwise.

Returns boolean

srgb

get srgb(): boolean
Returns true if the texture is stored in an sRGB format, meaning it will be converted to linear space when sampled. Returns false if the texture is stored in a linear format.

Returns boolean

storage

get storage(): boolean
Defines if texture can be used as a storage texture by a compute shader.

Returns boolean

volume

get volume(): boolean
Returns true if this texture is a 3D volume and false otherwise.

Returns boolean

width

get width(): number
The width of the texture in pixels.

Returns number

Methods

destroy

destroy(): void
Frees resources associated with this texture.

Returns void

getSource

getSource(mipLevel?: number): 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
- OptionalmipLevel: number = 0
  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

lock(
    options?: { face?: number; level?: number; mode?: number },
):
    | Uint8Array<ArrayBufferLike>
    | Uint16Array<ArrayBufferLike>
    | Uint32Array<ArrayBufferLike>
    | Float32Array<ArrayBufferLike>
Locks a miplevel of the texture, returning a typed array to be filled with pixel data.
Parameters
- Optionaloptions: { face?: number; level?: number; mode?: number } = {}
  Optional options object. Valid properties are as follows:
  - Optionalface?: number
    If the texture is a cubemap, this is the index of the face to lock.
  - Optionallevel?: number
    The mip level to lock with 0 being the top level. Defaults to 0.
  - Optionalmode?: number
    The lock mode. Can be:
    
    TEXTURELOCK_READ
    
    TEXTURELOCK_WRITE Defaults to TEXTURELOCK_WRITE.
Returns
    | Uint8Array<ArrayBufferLike>
    | Uint16Array<ArrayBufferLike>
    | Uint32Array<ArrayBufferLike>
    | Float32Array<ArrayBufferLike>
A typed array containing the pixel data of the locked mip level.

setSource

setSource(
    source:
        | HTMLCanvasElement
        | HTMLImageElement
        | HTMLVideoElement
        | HTMLCanvasElement[]
        | HTMLImageElement[]
        | HTMLVideoElement[],
    mipLevel?: number,
): void
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.
- OptionalmipLevel: number = 0
  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 void

unlock

unlock(): void
Unlocks the currently locked mip level and uploads it to VRAM.

Returns void

upload

upload(): void
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.

Returns void

Class Texture

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

OptionaladdressU?: number

OptionaladdressV?: number

OptionaladdressW?: number

Optionalanisotropy?: number

OptionalarrayLength?: number

OptionalcompareFunc?: number

OptionalcompareOnRead?: boolean

Optionalcubemap?: boolean

Optionaldepth?: number

OptionalflipY?: boolean

Optionalformat?: number

Optionalheight?: number

Optionallevels?: | Uint8Array<ArrayBufferLike>[] | Uint16Array<ArrayBufferLike>[] | Uint32Array<ArrayBufferLike>[] | Float32Array<ArrayBufferLike>[] | HTMLCanvasElement[] | HTMLImageElement[] | HTMLVideoElement[] | Uint8Array<ArrayBufferLike>[][]

OptionalmagFilter?: number

OptionalminFilter?: number

Optionalmipmaps?: boolean

Optionalname?: string

OptionalnumLevels?: number

OptionalpremultiplyAlpha?: boolean

Optionalprojection?: string

Optionalstorage?: boolean

Optionaltype?: string

Optionalvolume?: boolean

Optionalwidth?: number

Returns Texture

Example

Properties

Protected_invalid

Protected_lockedLevel

Protected_lockedMode

Protected_numLevels

Protected_numLevelsRequested

Protected_storage

Protectedid

name

Accessors

addressU

Returns number

Parameters

Returns void

addressV

Returns number

Parameters

Returns void

addressW

Returns number

Parameters

Returns void

anisotropy

Returns number

Parameters

Returns void

array

Returns boolean

arrayLength

Returns number

compareFunc

Returns number

Parameters

Returns void

compareOnRead

Returns boolean

Parameters

Returns void

cubemap

Returns boolean

depth

Returns number

flipY

Returns boolean

Parameters

`Optional`addressU?: number

`Optional`addressV?: number

`Optional`addressW?: number

`Optional`anisotropy?: number

`Optional`arrayLength?: number

`Optional`compareFunc?: number

`Optional`compareOnRead?: boolean

`Optional`cubemap?: boolean

`Optional`depth?: number

`Optional`flipY?: boolean

`Optional`format?: number

`Optional`height?: number

`Optional`levels?:
| Uint8Array<ArrayBufferLike>[]
| Uint16Array<ArrayBufferLike>[]
| Uint32Array<ArrayBufferLike>[]
| Float32Array<ArrayBufferLike>[]
| HTMLCanvasElement[]
| HTMLImageElement[]
| HTMLVideoElement[]
| Uint8Array<ArrayBufferLike>[][]

`Optional`magFilter?: number

`Optional`minFilter?: number

`Optional`mipmaps?: boolean

`Optional`name?: string

`Optional`numLevels?: number

`Optional`premultiplyAlpha?: boolean

`Optional`projection?: string

`Optional`storage?: boolean

`Optional`type?: string

`Optional`volume?: boolean

`Optional`width?: number

`Protected`_invalid

`Protected`_lockedLevel

`Protected`_lockedMode

`Protected`_numLevels

`Protected`_numLevelsRequested

`Protected`_storage

`Protected`id

`Optional`face?: number

`Optional`level?: number

`Optional`mode?: number

Returns
| Uint8Array<ArrayBufferLike>
| Uint16Array<ArrayBufferLike>
| Uint32Array<ArrayBufferLike>
| Float32Array<ArrayBufferLike>