Mirror Engine
V7
How To
Mirror Engine Logo

Mirror Engine API


Mirror Engine API / Texture

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:

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

  2. 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 &ge; 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?

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

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

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

HTMLCanvasElement | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement[] | HTMLImageElement[] | HTMLVideoElement[]

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

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

Mirror Engine Logo