# SceneDepthReader

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/framework/graphics/scene-depth-reader.js#L59

Reads the scene depth of a camera back to the CPU.

A sample is the distance from the camera to the surface at that point, in world units, measured
along the camera's view direction.

Reads are asynchronous and land a frame or two later. Any number of them may be in flight at once, so
a read can be issued every frame without waiting for the previous one to finish.

Note that something has to be rendering the depth for there to be anything to read: an effect which
consumes it, or [CameraComponent#requestSceneDepthMap](https://api.playcanvas.com/engine/classes/CameraComponent.md#requestscenedepthmap).

```javascript
const reader = new SceneDepthReader(camera.camera);
const rect = new Vec4(0.45, 0.45, 0.1, 0.1);

app.on('update', () => {
    reader.read(rect, 8, 8)?.then((samples) => {
        const hit = samples.filter(Number.isFinite);
        console.log(hit.length ? Math.min(...hit) : 'nothing in view');
    });
});
```

## Constructors

### constructor

```ts
new SceneDepthReader(camera: CameraComponent)
```

**Parameters**

- `camera` ([`CameraComponent`](https://api.playcanvas.com/engine/classes/CameraComponent.md)): The camera whose depth is read.

## Methods

### destroy

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

Frees the resources the reader owns and stops reading for this camera. Reads which have not been
rendered yet report their region as empty, and one already in flight does the same once it
completes, rather than writing samples read through resources this has let go of.

### read

```ts
read(rect: Vec4, width: number, height: number, target?: Float32Array<ArrayBufferLike>): Promise<Float32Array<ArrayBufferLike>> | null
```

Requests the depth of a region of the view, as `width * height` samples in row major order. The
region is point sampled rather than averaged - one sample per cell, taken at its centre - so
asking for more samples than the region resolves to repeats them.

Samples where nothing was rendered read as `Infinity`, as do the few which land within a hair of
the far clip, that being the depth an empty pixel reports.

Note that on a device which stores the scene depth at a lower precision - see
[GSplatParams#sceneDepthWrite](https://api.playcanvas.com/engine/classes/GSplatParams.md#scenedepthwrite) - a far clip beyond about 16384 leaves an empty pixel
reporting a large distance rather than `Infinity`, as the two stop being far enough apart to
tell one from the other.

**Parameters**

- `rect` ([`Vec4`](https://api.playcanvas.com/engine/classes/Vec4.md)): The region of the view to sample, normalized, with its origin in the bottom
  left as [CameraComponent#rect](https://api.playcanvas.com/engine/classes/CameraComponent.md#rect).
- `width` (`number`): The number of samples across the region. Not pixels.
- `height` (`number`): The number of samples down the region.
- `target` (`Float32Array<ArrayBufferLike>`, optional): An array to fill, at least `width * height` long. One is
  allocated when not given. It is filled when the returned promise resolves, so an array must not
  be shared between reads which overlap in time.

**Returns** `Promise<Float32Array<ArrayBufferLike>> | null`: The samples, in world units, or null when the camera is
disabled or is not rendering a scene depth, leaving nothing to read.