Engine API Reference - v2.24.0-beta.28
    Preparing search index...

    Class ComputePass

    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. Compute shaders are only supported on WebGPU, see GraphicsDevice#supportsCompute. On other devices the pass executes without dispatching anything.

    Add the pass to the CameraComponent#beforePasses or the CameraComponent#afterPasses of a camera, to dispatch it before or after the camera renders, or to the FramePass#beforePasses or FramePass#afterPasses of another pass. It can also be rendered on its own, with FramePass#render. Set its FramePass#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.

    Each compute instance is dispatched with the dispatch size and parameters set on it, typically set before the frame renders, or in FramePass#onBefore. Use onBefore also to prepare the buffers the shaders write, for example to clear them, and FramePass#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.

    When the frame renders multiple XR views, ComputePass#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.

    // 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();

    Hierarchy (View Summary)

    Index
    constructor
    afterPasses beforePasses computes device executeEnabled onAfter onBefore
    enabled name xrViewIndex
    after before destroy execute frameUpdate onDisable onEnable render
    afterPasses: FramePass[] = []

    Frame passes which need to be executed after this pass. This pass does not own them, and does not destroy them: whoever adds a pass to the list destroys it.

    beforePasses: FramePass[] = []

    Frame passes which need to be executed before this pass. The engine does not change this list, so the passes in it execute every frame this pass executes. This pass does not own them, and does not destroy them: whoever adds a pass to the list destroys it.

    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.

    device: GraphicsDevice

    The graphics device.

    executeEnabled: boolean = true

    True if the frame pass is enabled and execute function will be called. Note that before and after functions are called regardless of this flag. Set it before the frame renders, at the latest in frameUpdate, as the frame graph decides which passes to merge from it.

    onAfter: ((pass: FramePass) => void) | null = null

    Called when the pass renders, right after it executes: for a render pass once its GPU render pass has ended, and after FramePass#after. The results the pass writes can be read back here, as a read records its copy when it is requested, and so right after the pass. Reads should not be immediate, as that submits the work of the frame recorded so far. Like after, it is called even if FramePass#executeEnabled is false, but not when the pass is disabled. A render pass with this callback is not merged with the pass after it into a single GPU render pass, so the callback runs outside of one.

    onBefore: ((pass: FramePass) => void) | null = null

    Called when the pass renders, right before it executes: after FramePass#before, and for a render pass before its GPU render pass starts. Work recorded here, such as setting the parameters of the pass, or clearing a buffer it writes to, executes right before the pass. Like before, it is called even if FramePass#executeEnabled is false, but not when the pass is disabled. A render pass with this callback is not merged with the pass before it into a single GPU render pass, so the callback runs outside of one.

    • get enabled(): boolean

      Gets whether the frame pass is enabled.

      Returns boolean

    • set enabled(value: boolean): void

      Sets whether the frame pass is enabled. A disabled pass is skipped when the frame is built, together with its FramePass#beforePasses and FramePass#afterPasses, and its frameUpdate is not called. To skip only the execution of the pass, while still updating it and its before and after passes, use FramePass#executeEnabled instead. Change it before the frame is built: the frameUpdate of a pass, or of its before-passes, cannot disable the pass itself. Defaults to true.

      Parameters

      • value: boolean

      Returns void

    • get name(): string

      Gets the name of the pass.

      Returns string

    • set name(value: string): void

      Sets the name of the pass, which identifies it in debug output, GPU profiling and graphics debuggers. Defaults to the name of its class, which minified builds can shorten, so set it explicitly for a readable name.

      Parameters

      • value: string

      Returns void

    • get xrViewIndex(): number

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

      Returns number

    • set xrViewIndex(value: number): void

      Sets the index of the XR view the pass executes in, when the frame renders multiple XR views and the pass executes with the passes rendering them, such as in the before passes of a camera. It executes at its position in that view, after what the view renders before it, such as its depth prepass. Use -1 to execute it once before all the views, and so before what they render. When the frame does not render multiple XR views, or the pass executes outside of them, such as in the after passes of a camera, it executes when the index is -1 or 0. Defaults to 0.

      Parameters

      • value: number

      Returns void

    Settings
    Member Visibility

    On This Page
    Adding the pass to a frameThe dispatchXR views
    Constructors
    Properties
    Accessors
    Methods