# Texture

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/platform/graphics/texture.js#L70

Represents a texture, which is typically an image composed of pixels (texels). Textures are
fundamental resources for rendering graphical objects. They are commonly used by
[Material](https://api.playcanvas.com/engine/classes/Material.md)s and sampled in [Shader](https://api.playcanvas.com/engine/classes/Shader.md)s (usually fragment shaders) to define the visual
appearance of a 3D model's surface. Beyond storing color images, textures can hold various data
types like normal maps, environment maps (cubemaps), or custom data for shader computations. Key
properties control how the texture data is sampled, including filtering modes and coordinate
wrapping.

Note on **HDR texture format** support:
1. **As textures**:
    - float (i.e. [PIXELFORMAT_RGBA32F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA32F.md)), half-float (i.e. [PIXELFORMAT_RGBA16F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA16F.md)) and
small-float ([PIXELFORMAT_111110F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_111110F.md)) 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](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#texturefloatfilterable) is true.
    - [PIXELFORMAT_RGB9E5](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB9E5.md) is a compact HDR format with shared exponent, supported for
sampling on both WebGL2 and WebGPU, but cannot be used as a render target.

2. **As renderable textures** that can be used as color buffers in a [RenderTarget](https://api.playcanvas.com/engine/classes/RenderTarget.md):
    - 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](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#texturerg11b10renderable) is true.
    - on WebGL2, rendering to these 3 formats is supported only if
[GraphicsDevice#textureFloatRenderable](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#texturefloatrenderable) is true.
    - on WebGL2, if [GraphicsDevice#textureFloatRenderable](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#texturefloatrenderable) is false, but
[GraphicsDevice#textureHalfFloatRenderable](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#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](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#getrenderablehdrformat).
    - [PIXELFORMAT_RGB10A2](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB10A2.md) provides 10 bits per RGB channel with 2-bit alpha, offering
higher precision than [PIXELFORMAT_RGBA8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA8.md) at the same memory cost. It is renderable on
both WebGL2 and WebGPU. [PIXELFORMAT_RGB10A2U](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB10A2U.md) is the unsigned integer variant.

## Constructors

### constructor

```ts
new Texture(graphicsDevice: GraphicsDevice, options?: object)
```

Create a new Texture instance.

**Parameters**

- `graphicsDevice` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device used to manage this texture.
- `options` (`object`, optional, default `{}`): Object for passing optional arguments.
    - `options.addressU` (`number`, optional): The repeat mode to use in the U direction. Defaults to
      [ADDRESS_REPEAT](https://api.playcanvas.com/engine/variables/ADDRESS_REPEAT.md).
    - `options.addressV` (`number`, optional): The repeat mode to use in the V direction. Defaults to
      [ADDRESS_REPEAT](https://api.playcanvas.com/engine/variables/ADDRESS_REPEAT.md).
    - `options.addressW` (`number`, optional): The repeat mode to use in the W direction. Defaults to
      [ADDRESS_REPEAT](https://api.playcanvas.com/engine/variables/ADDRESS_REPEAT.md).
    - `options.anisotropy` (`number`, optional): The level of anisotropic filtering to use. Defaults
      to 1.
    - `options.arrayLength` (`number`, optional): 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.
    - `options.compareFunc` (`number`, optional): Comparison function when compareOnRead is enabled.
      Can be:

      - [FUNC_LESS](https://api.playcanvas.com/engine/variables/FUNC_LESS.md)
      - [FUNC_LESSEQUAL](https://api.playcanvas.com/engine/variables/FUNC_LESSEQUAL.md)
      - [FUNC_GREATER](https://api.playcanvas.com/engine/variables/FUNC_GREATER.md)
      - [FUNC_GREATEREQUAL](https://api.playcanvas.com/engine/variables/FUNC_GREATEREQUAL.md)
      - [FUNC_EQUAL](https://api.playcanvas.com/engine/variables/FUNC_EQUAL.md)
      - [FUNC_NOTEQUAL](https://api.playcanvas.com/engine/variables/FUNC_NOTEQUAL.md)

      Defaults to [FUNC_LESS](https://api.playcanvas.com/engine/variables/FUNC_LESS.md).
    - `options.compareOnRead` (`boolean`, optional): When enabled, and if texture format is
      [PIXELFORMAT_DEPTH](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DEPTH.md) or [PIXELFORMAT_DEPTHSTENCIL](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DEPTHSTENCIL.md), hardware PCF is enabled for
      this texture, and you can get filtered results of comparison using texture() in your shader.
      Defaults to false.
    - `options.cubemap` (`boolean`, optional): Specifies whether the texture is to be a cubemap.
      Defaults to false.
    - `options.depth` (`number`, optional): The number of depth slices in a 3D texture.
    - `options.flipY` (`boolean`, optional): 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.
    - `options.format` (`number`, optional): The pixel format of the texture. Can be:

      - [PIXELFORMAT_R8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_R8.md)
      - [PIXELFORMAT_RG8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RG8.md)
      - [PIXELFORMAT_RGB565](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB565.md)
      - [PIXELFORMAT_RGBA5551](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA5551.md)
      - [PIXELFORMAT_RGBA4](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA4.md)
      - [PIXELFORMAT_RGB8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB8.md)
      - [PIXELFORMAT_RGBA8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA8.md)
      - [PIXELFORMAT_DXT1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DXT1.md)
      - [PIXELFORMAT_DXT3](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DXT3.md)
      - [PIXELFORMAT_DXT5](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DXT5.md)
      - [PIXELFORMAT_RGB16F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB16F.md)
      - [PIXELFORMAT_RGBA16F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA16F.md)
      - [PIXELFORMAT_RGB32F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB32F.md)
      - [PIXELFORMAT_RGBA32F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA32F.md)
      - [PIXELFORMAT_ETC1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_ETC1.md)
      - [PIXELFORMAT_PVRTC_2BPP_RGB_1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_PVRTC_2BPP_RGB_1.md)
      - [PIXELFORMAT_PVRTC_2BPP_RGBA_1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_PVRTC_2BPP_RGBA_1.md)
      - [PIXELFORMAT_PVRTC_4BPP_RGB_1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_PVRTC_4BPP_RGB_1.md)
      - [PIXELFORMAT_PVRTC_4BPP_RGBA_1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_PVRTC_4BPP_RGBA_1.md)
      - [PIXELFORMAT_111110F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_111110F.md)
      - [PIXELFORMAT_ASTC_4x4](https://api.playcanvas.com/engine/variables/PIXELFORMAT_ASTC_4x4.md)
      - [PIXELFORMAT_ATC_RGB](https://api.playcanvas.com/engine/variables/PIXELFORMAT_ATC_RGB.md)
      - [PIXELFORMAT_ATC_RGBA](https://api.playcanvas.com/engine/variables/PIXELFORMAT_ATC_RGBA.md)

      Defaults to [PIXELFORMAT_RGBA8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA8.md).
    - `options.height` (`number`, optional): The height of the texture in pixels. Defaults to 4.
    - `options.levels` (`Uint8Array<ArrayBufferLike>[] | Uint8ClampedArray<ArrayBufferLike>[] | Uint16Array<ArrayBufferLike>[] | Uint32Array<ArrayBufferLike>[] | Float32Array<ArrayBufferLike>[] | HTMLCanvasElement[] | HTMLImageElement[] | HTMLVideoElement[] | Uint8Array<ArrayBufferLike>[][]`, optional): Array of Uint8Array or other supported browser interface; or a two-dimensional array
      of Uint8Array if options.arrayLength is defined and greater than zero.
    - `options.magFilter` (`number`, optional): The magnification filter type to use. Defaults to
      [FILTER_LINEAR](https://api.playcanvas.com/engine/variables/FILTER_LINEAR.md).
    - `options.minFilter` (`number`, optional): The minification filter type to use. Defaults to
      [FILTER_LINEAR_MIPMAP_LINEAR](https://api.playcanvas.com/engine/variables/FILTER_LINEAR_MIPMAP_LINEAR.md).
    - `options.mipmaps` (`boolean`, optional): When enabled try to generate or use mipmaps for this
      texture. Default is true.
    - `options.name` (`string`, optional): The name of the texture. Defaults to null.
    - `options.numLevels` (`number`, optional): 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.
    - `options.premultiplyAlpha` (`boolean`, optional): If true, the alpha channel of the texture (if
      present) is multiplied into the color channels. Defaults to false.
    - `options.projection` (`string`, optional): The projection type of the texture, used when the
      texture represents an environment. Can be:

      - [TEXTUREPROJECTION_NONE](https://api.playcanvas.com/engine/variables/TEXTUREPROJECTION_NONE.md)
      - [TEXTUREPROJECTION_CUBE](https://api.playcanvas.com/engine/variables/TEXTUREPROJECTION_CUBE.md)
      - [TEXTUREPROJECTION_EQUIRECT](https://api.playcanvas.com/engine/variables/TEXTUREPROJECTION_EQUIRECT.md)
      - [TEXTUREPROJECTION_OCTAHEDRAL](https://api.playcanvas.com/engine/variables/TEXTUREPROJECTION_OCTAHEDRAL.md)

      Defaults to [TEXTUREPROJECTION_CUBE](https://api.playcanvas.com/engine/variables/TEXTUREPROJECTION_CUBE.md) if options.cubemap is true, otherwise
      [TEXTUREPROJECTION_NONE](https://api.playcanvas.com/engine/variables/TEXTUREPROJECTION_NONE.md).
    - `options.samples` (`number`, optional): The number of MSAA samples. A value greater than 1
      creates a multisampled texture (WebGPU only, ignored with a warning on other devices, and
      rounded up to the device's supported sample count). A multisampled texture can only be
      rendered into, and its individual samples read in a shader using `textureLoad` - it cannot
      be sampled with a sampler, uploaded to or read back. It must be a 2D non-array
      texture with a format that supports multisampling, cannot be a storage texture, and has no
      mipmaps (the mipmaps option is ignored). Defaults to 1.
    - `options.srgb` (`boolean`, optional): When true, the texture is created in the sRGB variant of
      the requested format, if one exists, and is automatically converted to linear space when
      sampled. When the format has no sRGB variant, this option is ignored. Defaults to false.
    - `options.storage` (`boolean`, optional): Defines if texture can be used as a storage texture by
      a compute shader. Defaults to false.
    - `options.type` (`string`, optional): Specifies the texture type. Can be:

      - [TEXTURETYPE_DEFAULT](https://api.playcanvas.com/engine/variables/TEXTURETYPE_DEFAULT.md)
      - [TEXTURETYPE_RGBM](https://api.playcanvas.com/engine/variables/TEXTURETYPE_RGBM.md)
      - [TEXTURETYPE_RGBE](https://api.playcanvas.com/engine/variables/TEXTURETYPE_RGBE.md)
      - [TEXTURETYPE_RGBP](https://api.playcanvas.com/engine/variables/TEXTURETYPE_RGBP.md)
      - [TEXTURETYPE_SWIZZLEGGGR](https://api.playcanvas.com/engine/variables/TEXTURETYPE_SWIZZLEGGGR.md)

      Defaults to [TEXTURETYPE_DEFAULT](https://api.playcanvas.com/engine/variables/TEXTURETYPE_DEFAULT.md).
    - `options.volume` (`boolean`, optional): Specifies whether the texture is to be a 3D volume.
      Defaults to false.
    - `options.width` (`number`, optional): The width of the texture in pixels. Defaults to 4.

**Example**

```ts
// 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

### _invalid

```ts
protected _invalid: boolean = false
```

### _lockedLevel

```ts
protected _lockedLevel: number = -1
```

### _lockedMode

```ts
protected _lockedMode: number = TEXTURELOCK_NONE
```

### _numLevels

```ts
protected _numLevels: number = 0
```

### _numLevelsRequested

```ts
protected _numLevelsRequested: number | undefined
```

### _samples

```ts
protected _samples: number = 1
```

The number of MSAA samples of the texture, 1 if not multisampled.

### _storage

```ts
protected _storage: boolean = false
```

### id

```ts
protected id: number
```

### name

```ts
name: string
```

The name of the texture.

## Accessors

### addressU

```ts
get addressU(): number
set addressU(v: number)
```

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

### addressV

```ts
get addressV(): number
set addressV(v: number)
```

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

### addressW

```ts
get addressW(): number
set addressW(addressW: number)
```

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

### anisotropy

```ts
get anisotropy(): number
set anisotropy(v: number)
```

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

### array

```ts
get array(): boolean
```

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

### arrayLength

```ts
get arrayLength(): number
```

Returns the number of textures inside this texture if this is a 2D array texture or 0 otherwise.

### compareFunc

```ts
get compareFunc(): number
set compareFunc(v: number)
```

Gets the comparison function when [compareOnRead](https://api.playcanvas.com/engine/classes/Texture.md#compareonread) is enabled.

### compareOnRead

```ts
get compareOnRead(): boolean
set compareOnRead(v: boolean)
```

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

### cubemap

```ts
get cubemap(): boolean
```

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

### depth

```ts
get depth(): number
```

The number of depth slices in a 3D texture.

### flipY

```ts
get flipY(): boolean
set flipY(flipY: boolean)
```

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

### format

```ts
get format(): number
```

The pixel format of the texture. Can be:

- [PIXELFORMAT_R8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_R8.md)
- [PIXELFORMAT_RG8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RG8.md)
- [PIXELFORMAT_RGB565](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB565.md)
- [PIXELFORMAT_RGBA5551](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA5551.md)
- [PIXELFORMAT_RGBA4](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA4.md)
- [PIXELFORMAT_RGB8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB8.md)
- [PIXELFORMAT_RGBA8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA8.md)
- [PIXELFORMAT_DXT1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DXT1.md)
- [PIXELFORMAT_DXT3](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DXT3.md)
- [PIXELFORMAT_DXT5](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DXT5.md)
- [PIXELFORMAT_RGB16F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB16F.md)
- [PIXELFORMAT_RGBA16F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA16F.md)
- [PIXELFORMAT_RGB32F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGB32F.md)
- [PIXELFORMAT_RGBA32F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_RGBA32F.md)
- [PIXELFORMAT_ETC1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_ETC1.md)
- [PIXELFORMAT_PVRTC_2BPP_RGB_1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_PVRTC_2BPP_RGB_1.md)
- [PIXELFORMAT_PVRTC_2BPP_RGBA_1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_PVRTC_2BPP_RGBA_1.md)
- [PIXELFORMAT_PVRTC_4BPP_RGB_1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_PVRTC_4BPP_RGB_1.md)
- [PIXELFORMAT_PVRTC_4BPP_RGBA_1](https://api.playcanvas.com/engine/variables/PIXELFORMAT_PVRTC_4BPP_RGBA_1.md)
- [PIXELFORMAT_111110F](https://api.playcanvas.com/engine/variables/PIXELFORMAT_111110F.md)
- [PIXELFORMAT_ASTC_4x4](https://api.playcanvas.com/engine/variables/PIXELFORMAT_ASTC_4x4.md)
- [PIXELFORMAT_ATC_RGB](https://api.playcanvas.com/engine/variables/PIXELFORMAT_ATC_RGB.md)
- [PIXELFORMAT_ATC_RGBA](https://api.playcanvas.com/engine/variables/PIXELFORMAT_ATC_RGBA.md)

### height

```ts
get height(): number
```

The height of the texture in pixels.

### magFilter

```ts
get magFilter(): number
set magFilter(v: number)
```

Gets the magnification filter to be applied to the texture.

### minFilter

```ts
get minFilter(): number
set minFilter(v: number)
```

Gets the minification filter to be applied to the texture.

### mipmaps

```ts
get mipmaps(): boolean
set mipmaps(v: boolean)
```

Gets whether the texture should generate/upload mipmaps.

### numLevels

```ts
get numLevels(): number
```

Gets the number of mip levels.

### pot

```ts
get pot(): boolean
```

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

### samples

```ts
get samples(): number
```

The number of MSAA samples of the texture, 1 if the texture is not multisampled. Specified
via the `samples` constructor option (WebGPU only). A multisampled texture can only be
rendered into, and its individual samples read in a shader using `textureLoad`.

### srgb

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

### storage

```ts
get storage(): boolean
```

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

### volume

```ts
get volume(): boolean
```

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

### width

```ts
get width(): number
```

The width of the texture in pixels.

## Methods

### copy

```ts
copy(source: Texture, options?: object): boolean
```

Copies a region of a source texture into this texture. Both textures must have the same
pixel format. The copied region sizes must match (no scaling), and must lie within the
chosen mip levels of both textures. Multisampled textures can be copied to other
multisampled textures with the same sample count (WebGPU only), but only as a full-texture
copy - no offsets or partial regions, and no copies between different sample counts (use a
resolve instead).

**Parameters**

- `source` ([`Texture`](https://api.playcanvas.com/engine/classes/Texture.md)): The source texture to copy from.
- `options` (`object`, optional, default `{}`): Optional arguments.
    - `options.destMipLevel` (`number`, optional): The destination mip level to copy to. Defaults to 0.
    - `options.destX` (`number`, optional): The left edge of the destination region. Defaults to 0.
    - `options.destY` (`number`, optional): The top edge of the destination region. Defaults to 0.
    - `options.face` (`number`, optional): The cubemap face or array layer to copy (applies to both
      source and destination). Defaults to 0.
    - `options.height` (`number`, optional): The height of the copied region. Defaults to the full
      height of the source mip level (minus sourceY).
    - `options.sourceMipLevel` (`number`, optional): The source mip level to copy from. Defaults to 0.
    - `options.sourceRenderTarget` ([`RenderTarget`](https://api.playcanvas.com/engine/classes/RenderTarget.md), optional): A render target wrapping the source
      texture as its color buffer, at the matching face / mip level. Provide as an optimization to
      avoid allocating a temporary one when copying with high frequency (per frame). Note that this
      is only utilized on the WebGL platform, and ignored on WebGPU.
    - `options.sourceX` (`number`, optional): The left edge of the source region. Defaults to 0.
    - `options.sourceY` (`number`, optional): The top edge of the source region. Defaults to 0.
    - `options.width` (`number`, optional): The width of the copied region. Defaults to the full width
      of the source mip level (minus sourceX).

**Returns** `boolean`: True if the copy was successful, false otherwise.

### destroy

```ts
destroy(): void
```

Frees resources associated with this texture.

### getSource

```ts
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`, optional, default `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.

### getView

```ts
getView(baseMipLevel?: number, mipLevelCount?: number, baseArrayLayer?: number, arrayLayerCount?: number): TextureView
```

Creates a TextureView for this texture, specifying a subset of mip levels and array layers.
TextureViews can be used with compute shaders to access specific portions of a texture.

Note: TextureView is only supported on WebGPU. On WebGL, the full texture is always bound.

**Parameters**

- `baseMipLevel` (`number`, optional, default `0`): The first mip level accessible to the view. Defaults to 0.
- `mipLevelCount` (`number`, optional, default `1`): The number of mip levels accessible to the view. Defaults
  to 1.
- `baseArrayLayer` (`number`, optional, default `0`): The first array layer accessible to the view. Defaults to
  0.
- `arrayLayerCount` (`number`, optional, default `1`): The number of array layers accessible to the view.
  Defaults to 1.

**Returns** [`TextureView`](https://api.playcanvas.com/engine/classes/TextureView.md): A new TextureView for this texture.

**Example**

```ts
// Create a view for mip level 1
const mip1View = texture.getView(1);

// Use with compute shader
compute.setParameter('outputTexture', mip1View);
```

### lock

```ts
lock(options?: object): 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` (`object`, optional, default `{}`): Optional options object. Valid properties are as follows:
    - `options.face` (`number`, optional): If the texture is a cubemap, this is the index of the face
      to lock.
    - `options.level` (`number`, optional): The mip level to lock with 0 being the top level. Defaults
      to 0.
    - `options.mode` (`number`, optional): The lock mode. Can be:
      - [TEXTURELOCK_READ](https://api.playcanvas.com/engine/variables/TEXTURELOCK_READ.md)
      - [TEXTURELOCK_WRITE](https://api.playcanvas.com/engine/variables/TEXTURELOCK_WRITE.md)
      Defaults to [TEXTURELOCK_WRITE](https://api.playcanvas.com/engine/variables/TEXTURELOCK_WRITE.md).

**Returns** `Uint8Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Float32Array<ArrayBufferLike>`: A typed array containing the pixel data of
the locked mip level.

### read

```ts
read(x: number, y: number, width: number, height: number, options?: object): Promise<Uint8Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Float32Array<ArrayBufferLike>>
```

Download the textures data from the graphics memory to the local memory.

**Parameters**

- `x` (`number`): The left edge of the rectangle.
- `y` (`number`): The top edge of the rectangle.
- `width` (`number`): The width of the rectangle.
- `height` (`number`): The height of the rectangle.
- `options` (`object`, optional, default `{}`): Object for passing optional arguments.
    - `options.data` (`Uint8Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Float32Array<ArrayBufferLike>`, optional): The data buffer to
      write the pixel data to. If not provided, a new buffer will be created. The type of the buffer
      must match the texture's format.
    - `options.face` (`number`, optional): The face to download. Defaults to 0.
    - `options.frequent` (`boolean`, optional): Set this when the read is one of many, issued every
      frame or every few frames. Such a read is given the treatment which costs it a frame of
      latency and keeps it from stalling the frame it is issued in, which is the trade a one-off
      read would not want. Only utilized on the WebGL platform, where a readback has a blocking
      step; ignored on WebGPU, whose readback does not block. Defaults to false.
    - `options.immediate` (`boolean`, optional): If true, the read operation will be executed as soon as
      possible. This has a performance impact, so it should be used only when necessary. Defaults
      to false.
    - `options.mipLevel` (`number`, optional): The mip level to download. Defaults to 0.
    - `options.renderTarget` ([`RenderTarget`](https://api.playcanvas.com/engine/classes/RenderTarget.md), optional): The render target using the texture as a color
      buffer. Provide as an optimization to avoid creating a new render target. Important especially
      when this function is called with high frequency (per frame). Note that this is only utilized
      on the WebGL platform, and ignored on WebGPU.

**Returns** `Promise<Uint8Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Float32Array<ArrayBufferLike>>`: A promise that resolves
with the pixel data of the texture.

### setSource

```ts
setSource(source: HTMLElement | HTMLCanvasElement | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement[] | HTMLImageElement[] | HTMLVideoElement[] | HTMLElement[], mipLevel?: number): void
```

Set the pixel data of the texture from a canvas, image, video, or HTML DOM element. If the
texture is a cubemap, the supplied source must be an array of 6 canvases, images or videos.

Note: using an HTML element (e.g. `<div>`) as a source requires
[GraphicsDevice#supportsHtmlTextures](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#supportshtmltextures) to be true.

**Parameters**

- `source` (`HTMLElement | HTMLCanvasElement | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement[] | HTMLImageElement[] | HTMLVideoElement[] | HTMLElement[]`): A
  canvas, image, video, or HTML element, or an array of 6 canvas, image, video, or HTML
  elements.
- `mipLevel` (`number`, optional, default `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.

### unlock

```ts
unlock(): void
```

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

### upload

```ts
upload(): void
```

Forces a reupload of the texture's pixel data to graphics memory. Ordinarily, this function
is called internally by [setSource](https://api.playcanvas.com/engine/classes/Texture.md#setsource) and [unlock](https://api.playcanvas.com/engine/classes/Texture.md#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.