
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:
-
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?
| 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
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
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