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.

Constructors

new Texture()

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.

options?

Object for passing optional arguments.

addressU?

number

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

addressV?

number

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

addressW?

number

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

anisotropy?

number

The level of anisotropic filtering to use. Defaults to 1.

arrayLength?

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.

compareFunc?

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.

compareOnRead?

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.

cubemap?

boolean

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

depth?

number

The number of depth slices in a 3D texture.

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

format?

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.

height?

number

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

levels?

Array of Uint8Array or other supported browser interface; or a two-dimensional array of Uint8Array if options.arrayLength is defined and greater than zero.

magFilter?

number

The magnification filter type to use. Defaults to FILTER_LINEAR.

minFilter?

number

The minification filter type to use. Defaults to FILTER_LINEAR_MIPMAP_LINEAR.

mipmaps?

boolean

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

name?

string

The name of the texture. Defaults to null.

numLevels?

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.

premultiplyAlpha?

boolean

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

projection?

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.

storage?

boolean

Defines if texture can be used as a storage texture by a compute shader. Defaults to false.

type?

string

Specifies the texture type. Can be:

TEXTURETYPE_DEFAULT
TEXTURETYPE_RGBM
TEXTURETYPE_RGBE
TEXTURETYPE_RGBP
TEXTURETYPE_SWIZZLEGGGR

Defaults to TEXTURETYPE_DEFAULT.

volume?

boolean

Specifies whether the texture is to be a 3D volume. Defaults to false.

width?

number

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

Returns

Texture

Example

// Create a 8x8x24-bit texture
const texture = new Texture(graphicsDevice, {
  width: 8,
  height: 8,
  format: 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

name

name: string

The name of the texture.

addressU

Get Signature

get addressU(): number

Gets the addressing mode to be applied to the texture horizontally.

Returns

number

Set Signature

set addressU(v: number): void

Sets the addressing mode to be applied to the texture horizontally. Can be:

ADDRESS_REPEAT
ADDRESS_CLAMP_TO_EDGE
ADDRESS_MIRRORED_REPEAT

Parameters

v

number

Returns

void

addressV

Get Signature

get addressV(): number

Gets the addressing mode to be applied to the texture vertically.

Returns

number

Set Signature

set addressV(v: number): void

Sets the addressing mode to be applied to the texture vertically. Can be:

ADDRESS_REPEAT
ADDRESS_CLAMP_TO_EDGE
ADDRESS_MIRRORED_REPEAT

Parameters

v

number

Returns

void

addressW

Get Signature

get addressW(): number

Gets the addressing mode to be applied to the 3D texture depth.

Returns

number

Set Signature

set addressW(addressW: number): void

Sets the addressing mode to be applied to the 3D texture depth. Can be:

ADDRESS_REPEAT
ADDRESS_CLAMP_TO_EDGE
ADDRESS_MIRRORED_REPEAT

Parameters

addressW

number

Returns

void

anisotropy

Get Signature

get anisotropy(): number

Gets the integer value specifying the level of anisotropy to apply to the texture.

Returns

number

Set Signature

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 Signature

get array(): boolean

Returns true if this texture is a 2D texture array and false otherwise.

Returns

boolean

arrayLength

Get Signature

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 Signature

get compareFunc(): number

Sets the comparison function when compareOnRead is enabled.

Returns

number

Set Signature

set compareFunc(v: number): void

Sets the comparison function when compareOnRead is enabled. Possible values:

FUNC_LESS
FUNC_LESSEQUAL
FUNC_GREATER
FUNC_GREATEREQUAL
FUNC_EQUAL
FUNC_NOTEQUAL

Parameters

v

number

Returns

void

compareOnRead

Get Signature

get compareOnRead(): boolean

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

Returns

boolean

Set Signature

set compareOnRead(v: boolean): void

Parameters

v

boolean

Returns

void

cubemap

Get Signature

get cubemap(): boolean

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

Returns

boolean

depth

Get Signature

get depth(): number

The number of depth slices in a 3D texture.

Returns

number

flipY

Get Signature

get flipY(): boolean

Gets whether the texture should be flipped in the Y-direction.

Returns

boolean

Set Signature

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 Signature

get format(): 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>/li>
PIXELFORMAT_ATC_RGB
PIXELFORMAT_ATC_RGBA

Returns

number

height

Get Signature

get height(): number

The height of the texture in pixels.

Returns

number

magFilter

Get Signature

get magFilter(): number

Gets the magnification filter to be applied to the texture.

Returns

number

Set Signature

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 Signature

get minFilter(): number

Gets the minification filter to be applied to the texture.

Returns

number

Set Signature

set minFilter(v: number): void

Sets the minification filter to be applied to the texture. Can be:

FILTER_NEAREST
FILTER_LINEAR
FILTER_NEAREST_MIPMAP_NEAREST
FILTER_NEAREST_MIPMAP_LINEAR
FILTER_LINEAR_MIPMAP_NEAREST
FILTER_LINEAR_MIPMAP_LINEAR

Parameters

v

number

Returns

void

mipmaps

Get Signature

get mipmaps(): boolean

Gets whether the texture should generate/upload mipmaps.

Returns

boolean

Set Signature

set mipmaps(v: boolean): void

Sets whether the texture should generate/upload mipmaps.

Parameters

v

boolean

Returns

void

numLevels

Get Signature

get numLevels(): number

Gets the number of mip levels.

Returns

number

pot

Get Signature

get pot(): boolean

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

Returns

boolean

srgb

Get Signature

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 Signature

get storage(): boolean

Defines if texture can be used as a storage texture by a compute shader.

Returns

boolean

volume

Get Signature

get volume(): boolean

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

Returns

boolean

width

Get Signature

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

mipLevel?

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

options?

Optional options object. Valid properties are as follows:

face?

number

If the texture is a cubemap, this is the index of the face to lock.

level?

number

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

mode?

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

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

mipLevel?

number = 0

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