# ComputePass

Class · extends [`FramePass`](https://api.playcanvas.com/engine/classes/FramePass.md) · category: Graphics

Source: https://github.com/playcanvas/engine/blob/64089771243fe28a9b9d2b4de538b99b07c75097/src/platform/graphics/compute-pass.js#L76

A frame pass which dispatches a list of compute instances, in order, in a single compute pass.
It schedules compute work at a position in the frame, for example after a camera renders, to
process its scene depth and color maps in the same frame. To dispatch compute instances right
away instead, when called, use [GraphicsDevice#computeDispatch](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#computedispatch). Compute shaders are only
supported on WebGPU, see [GraphicsDevice#supportsCompute](https://api.playcanvas.com/engine/classes/GraphicsDevice.md#supportscompute). On other devices the pass
executes without dispatching anything.

## Adding the pass to a frame

Add the pass to the [CameraComponent#beforePasses](https://api.playcanvas.com/engine/classes/CameraComponent.md#beforepasses) or the
[CameraComponent#afterPasses](https://api.playcanvas.com/engine/classes/CameraComponent.md#afterpasses) of a camera, to dispatch it before or after the camera
renders, or to the [FramePass#beforePasses](https://api.playcanvas.com/engine/classes/FramePass.md#beforepasses) or [FramePass#afterPasses](https://api.playcanvas.com/engine/classes/FramePass.md#afterpasses) of another
pass. It can also be rendered on its own, with [FramePass#render](https://api.playcanvas.com/engine/classes/FramePass.md#render). Set its
[FramePass#name](https://api.playcanvas.com/engine/classes/FramePass.md#name), which labels the dispatch in GPU profiling. The pass does not destroy
its compute instances, and the camera does not destroy the pass: whoever creates them destroys
them.

## The dispatch

Each compute instance is dispatched with the dispatch size and parameters set on it, typically
set before the frame renders, or in [FramePass#onBefore](https://api.playcanvas.com/engine/classes/FramePass.md#onbefore). Use onBefore also to prepare the
buffers the shaders write, for example to clear them, and [FramePass#onAfter](https://api.playcanvas.com/engine/classes/FramePass.md#onafter) to read the
results back, as a read requested there is recorded right after the dispatch. The pass executes
at most once in a frame.

## XR views

When the frame renders multiple XR views, [ComputePass#xrViewIndex](https://api.playcanvas.com/engine/classes/ComputePass.md#xrviewindex) selects the view the
pass executes in. As a compute instance is dispatched at most once in a frame, dispatching for
several views needs a compute pass for each, with separate compute instances.

**Example**

```ts
// A compute shader building a histogram of what a camera renders, into a storage buffer
cameraComponent.requestSceneColorMap(true);

const compute = new Compute(device, shader, 'Histogram');
compute.setSceneColorMap(cameraComponent.sceneColorMapHandle);
compute.setParameter('bins', histogramBuffer);

const pass = new ComputePass(device, [compute]);
pass.name = 'HistogramPass';

// right before the dispatch: a thread for each texel of the color map, and an empty buffer
pass.onBefore = () => {
    const { width, height } = cameraComponent.sceneColorMapHandle;
    compute.setupDispatchThreads(width, height);
    histogramBuffer.clear();
};

// read the result back right after the dispatch
pass.onAfter = () => {
    histogramBuffer.read().then((data) => {
        // the histogram, which arrives a few frames after it was computed
    });
};

// dispatch after the camera renders, so the shader reads the scene color of the same frame
cameraComponent.afterPasses.push(pass);

// when no longer needed, remove the pass, and destroy it and the compute instance
const passes = cameraComponent.afterPasses;
passes.splice(passes.indexOf(pass), 1);
pass.destroy();
compute.destroy();
```

## Constructors

### constructor

```ts
new ComputePass(graphicsDevice: GraphicsDevice, computes?: Compute[])
```

Creates a new ComputePass instance.

**Parameters**

- `graphicsDevice` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device.
- `computes` ([`Compute`](https://api.playcanvas.com/engine/classes/Compute.md)`[]`, optional, default `[]`): The compute instances the pass dispatches. Defaults to an
  empty array.

## Properties

### computes

```ts
computes: Compute[]
```

The compute instances the pass dispatches, in order. Add instances to the array, or remove
them from it, to change them. The pass does not own them.

## Accessors

### xrViewIndex

```ts
get xrViewIndex(): number
set xrViewIndex(value: number)
```

Gets the index of the XR view the pass executes in.

## Methods

### destroy

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

Releases the pass. It empties [ComputePass#computes](https://api.playcanvas.com/engine/classes/ComputePass.md#computes), without destroying the compute
instances, which are destroyed by whoever created them.

### execute

```ts
execute(): void
```

Dispatches the compute instances in [ComputePass#computes](https://api.playcanvas.com/engine/classes/ComputePass.md#computes), in order, in a single
compute pass labeled with [FramePass#name](https://api.playcanvas.com/engine/classes/FramePass.md#name). Does nothing when there are none.

### render

```ts
render(): void
```

Renders the pass, as [FramePass#render](https://api.playcanvas.com/engine/classes/FramePass.md#render) describes. When the frame renders multiple XR
views, it executes only in the view selected by [ComputePass#xrViewIndex](https://api.playcanvas.com/engine/classes/ComputePass.md#xrviewindex), and is
skipped in the others.

## Inherited from [FramePass](https://api.playcanvas.com/engine/classes/FramePass.md)

- `afterPasses: FramePass[] = []`
- `beforePasses: FramePass[] = []`
- `device: GraphicsDevice`
- `executeEnabled: boolean = true`
- `onAfter: ((pass: FramePass) => void) | null = null`
- `onBefore: ((pass: FramePass) => void) | null = null`
- `get enabled(): boolean` · `set enabled(value: boolean)`
- `get name(): string` · `set name(value: string)`
- `after(): void`
- `before(): void`
- `frameUpdate(): void`
- `onDisable(): void`
- `onEnable(): void`
