Documentation
    Preparing search index...

    Interface PickingService

    §71's "gpu"/"pixel" tier: an offscreen id pass plus an asynchronous single-texel read-back (RFC 0005).

    import { registerPickingPipeline } from "@fourjs/render-webgl";

    registerPickingPipeline();                       // once, at setup
    const picking = renderer.createPickingService!();
    // per frame that wants pixel picking (opt-in — the pass costs a frame):
    picking.update(scene, view);
    // in a pointer handler:
    const { nodeId } = await picking.pick({ viewport: view, ndcX, ndcY });

    WebGL 2's plain readPixels is a synchronous stall; the non-stalling paths (PIXEL_PACK_BUFFER + fence on WebGL 2, mapAsync on WebGPU) are both asynchronous. A capability tier may change quality or availability; it must never change an API's shape (§62) — so pick returns a Promise even on a backend that could answer synchronously, and the result carries the PickResult.frame it came from.

    update is a second render pass proportional to the render list (§86 gains a row). Nothing runs it for you: an application calls it only on frames it intends to pick against — typically the frame under the pointer event — and a scene that never picks never pays.

    An id pass is a read-back of rendered content — the classic cross-origin texture hazard. This engine's TextureSource carries raw texels (no origin-tainted handles), so the browser's own canvas-tainting rules are the enforcement tier here: a backend surface that could ever hold tainted content will throw on read-back, and the service reports that failure rather than masking it.

    interface PickingService {
        disposed: boolean;
        dispose(): void;
        pick(request: PickRequest): Promise<PickResult>;
        update(root: Node, view: Viewport): void;
    }

    Implemented by

    Index
    disposed
    dispose pick update
    disposed: boolean

    Whether PickingService.dispose has run.

    • Releases the service's GPU resources — its render target and id program (§83). Idempotent and terminal: update and pick refuse afterwards.

      Returns void

    • Reads back one texel of the last PickingService.update's id buffer and resolves it to a node id. Asynchronous, always — see the interface documentation.

      Refused (§85/§89, as a rejection carrying a FourError): a disposed service, a pick before any successful update, ndcX/ndcY outside [-1, 1] or non-finite, a viewport other than the one the last update drew, and — CONTEXT_LOST — a context lost (or lost-and-restored) since the id buffer was drawn, because a stale undefined would be indistinguishable from "nothing there".

      Parameters

      Returns Promise<PickResult>

    • Renders the id pass for root/view into the service's own target.

      Draws the resolved world transforms (§7) — the caller must have run resolveWorldTransforms for the frame, exactly as Renderer.render's non-interpolated path requires. Deliberately never the §43 interpolated pose: a picking pass wants exactly the simulation state (renderer.ts records this as the interpolation contract's own example).

      §85 refusals (thrown from here, the call that can see the mistake): a disposed service, a view whose resolved rectangle has zero area, a candidate count the encoding cannot express. §61 skips (never thrown): a lost context, a target or program the driver refused — the pass is skipped, and the next PickingService.pick reports that there is no id buffer to read.

      Parameters

      Returns void

    Settings
    Member Visibility

    On This Page
    The contract is asynchronous on every backend, foreverCost, and why the pass is opt-in per frame§96
    Properties
    Methods