# TextureRenderer

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/extras/renderers/texture-renderer.js#L113

Displays textures for a single frame, for debugging. Call [draw](https://api.playcanvas.com/engine/classes/TextureRenderer.md#draw) or [sceneDepth](https://api.playcanvas.com/engine/classes/TextureRenderer.md#scenedepth)
during update or prerender on every frame the preview should be visible. Positions specify
the top-left corner in normalized camera-viewport coordinates: (0, 0) is top-left and (1, 1)
is bottom-right. Width and height are fractions of the viewport; a rectangle of (0, 0, 1, 1)
fills it. Signed sizes can flip a preview, and rectangles can extend outside the viewport.

Supports 2D color textures in normalized, floating-point and device-supported compressed
formats. Linear and sRGB color, and RGBM, RGBE and RGBP encoded HDR color, are detected
automatically with the default [channels](https://api.playcanvas.com/engine/classes/TextureRenderer.md#channels) selection, and single-channel formats such as
[PIXELFORMAT_R8](https://api.playcanvas.com/engine/variables/PIXELFORMAT_R8.md) display their channel as grayscale. Other selections display stored
channel values, including alpha, as opaque previews.

Depth textures using [PIXELFORMAT_DEPTH](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DEPTH.md), [PIXELFORMAT_DEPTH16](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DEPTH16.md) or
[PIXELFORMAT_DEPTHSTENCIL](https://api.playcanvas.com/engine/variables/PIXELFORMAT_DEPTHSTENCIL.md) are displayed as raw grayscale values. Use [sceneDepth](https://api.playcanvas.com/engine/classes/TextureRenderer.md#scenedepth)
to display the rendering camera's scene depth, linearized and normalized by its far clip
distance. The camera must have scene depth capture enabled.

Cube, volume, array, integer and multisampled textures are not supported. On WebGL2, raw depth
textures must have comparison sampling disabled, and both raw depth and non-filterable float
textures require nearest minification and magnification filters. WebGPU supports these textures
regardless of their filtering and comparison sampler settings.

Resources are released automatically when the application is destroyed, or earlier by calling
[destroy](https://api.playcanvas.com/engine/classes/TextureRenderer.md#destroy). Supplied textures are never destroyed by this helper.

Previews produce fully opaque pixels but are drawn as alpha-blended instances, so they render in
layers that only draw their transparent sub-layer, such as the default UI layer, which is also
where they escape a camera frame's post-processing. They do not write or test depth and do not
cast shadows. Ordering against other transparent geometry follows the destination layer's
transparent sort mode.

Every camera rendering the destination layer draws the previews, including cameras rendering
into a texture. Set [camera](https://api.playcanvas.com/engine/classes/TextureRenderer.md#camera) to limit them to a single camera, typically the one rendering
to the screen. A render pass whose target has the previewed texture among its attachments never
draws that preview: sampling a texture while rendering into it is undefined on WebGL and an
error on WebGPU. Both rules are applied as each layer is rendered, against the target the pass
really renders into, so they hold for camera frames and custom render passes and do not depend
on frustum culling.

**Example**

```ts
const textures = new TextureRenderer(app);
app.on('update', () => {
    textures.draw(texture, 0.7, 0.7, 0.25, 0.25);
});
```

**Example**

```ts
// camera is an entity with a camera component.
camera.camera.requestSceneDepthMap(true);
const textures = new TextureRenderer(app);
app.on('update', () => {
    textures.sceneDepth(0.7, 0.7, 0.25, 0.25);
});
```

## Constructors

### constructor

```ts
new TextureRenderer(app: AppBase)
```

Creates a debug texture renderer.

**Parameters**

- `app` ([`AppBase`](https://api.playcanvas.com/engine/classes/AppBase.md)): The application to render into and bind resource lifetime to.

## Properties

### camera

```ts
camera: CameraComponent | null = null
```

The only camera that draws the previews, or null to let every camera rendering the
destination layer draw them. Defaults to null.

### layer

```ts
layer: Layer | null = null
```

The layer used by subsequent draw calls, or null to use the application's default debug
drawing layer (normally Immediate). Defaults to null.

## Accessors

### channels

```ts
set channels(value: string)
```

Channels displayed by subsequent [draw](https://api.playcanvas.com/engine/classes/TextureRenderer.md#draw) calls. Must be exactly three characters from
'r', 'g', 'b' and 'a'. Defaults to 'rgb', which displays automatically decoded color, or the
stored channel as grayscale for single-channel formats. Other selections display stored
channel values without color decoding: for example, 'rrr' displays
red as grayscale, 'aaa' displays alpha, and 'bgr' swaps red and blue. Values from 0 to 1 map
directly from black to white. Output is always opaque. Ignored for depth textures and
[sceneDepth](https://api.playcanvas.com/engine/classes/TextureRenderer.md#scenedepth). Invalid values leave the previous selection unchanged.

**Example**

```ts
textures.channels = 'aaa';
textures.draw(texture, 0, 0, 0.25, 0.25);
```

## Methods

### destroy

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

Removes all previews and releases the renderer's resources. Does not destroy supplied
textures. Safe to call repeatedly; subsequent draw calls are ignored.

### draw

```ts
draw(texture: Texture, x: number, y: number, width: number, height: number): void
```

Displays a 2D color or depth texture for this frame. Color encoding and supported filtering
are detected automatically when [channels](https://api.playcanvas.com/engine/classes/TextureRenderer.md#channels) is 'rgb'. Other selections display stored
channel values. Raw depth is shown as grayscale without
projection-dependent linearization; use [sceneDepth](https://api.playcanvas.com/engine/classes/TextureRenderer.md#scenedepth) for camera depth. Texture row 0
is displayed at the top. For rendered textures, use [RENDERTARGET_ORIGIN_TOP](https://api.playcanvas.com/engine/variables/RENDERTARGET_ORIGIN_TOP.md) on their
render target for consistent orientation across backends.

Cube, volume, array, integer and multisampled textures are not supported. On WebGL2,
depth textures must have comparison sampling disabled. Raw depth and non-filterable float
textures must use nearest minification and magnification filters on WebGL2. WebGPU samples
these textures independently of their filtering and comparison sampler settings.

**Parameters**

- `texture` ([`Texture`](https://api.playcanvas.com/engine/classes/Texture.md)): The caller-owned texture to display.
- `x` (`number`): Left edge as a fraction of the camera viewport width.
- `y` (`number`): Top edge as a fraction of the camera viewport height.
- `width` (`number`): Width as a fraction of the camera viewport width.
- `height` (`number`): Height as a fraction of the camera viewport height.

### sceneDepth

```ts
sceneDepth(x: number, y: number, width: number, height: number): void
```

Displays the rendering camera's scene depth for this frame, linearized and normalized by
its far clip distance. The camera must already supply a scene depth map, for example using
[CameraComponent#requestSceneDepthMap](https://api.playcanvas.com/engine/classes/CameraComponent.md#requestscenedepthmap), and this layer must render after depth capture.

**Parameters**

- `x` (`number`): Left edge as a fraction of the camera viewport width.
- `y` (`number`): Top edge as a fraction of the camera viewport height.
- `width` (`number`): Width as a fraction of the camera viewport width.
- `height` (`number`): Height as a fraction of the camera viewport height.