playcanvas/build/playcanvas/src/scene/gsplat-unified/gsplat-renderer.d.ts

Open-source WebGL/WebGPU 3D engine for the web

/**
 * Per-call parameters for a renderer view (forward or pick), populated by the manager each frame
 * from the scene gsplat settings plus the view camera (and pick viewport). Reused per call to avoid
 * per-frame allocation; the renderer must not retain a reference to it.
 */
export type GSplatRenderViewParams = object;
/**
 * @import { StorageBuffer } from '../../platform/graphics/storage-buffer.js'
 * @import { ShaderMaterial } from '../materials/shader-material.js'
 * @import { Layer } from '../layer.js'
 * @import { GraphNode } from '../graph-node.js'
 * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js'
 * @import { GSplatWorkBuffer } from './gsplat-work-buffer.js'
 * @import { GSplatWorld } from './gsplat-world.js'
 * @import { GSplatWorldState } from './gsplat-world-state.js'
 * @import { GSplatVaryings } from './gsplat-varyings.js'
 * @import { MeshInstance } from '../mesh-instance.js'
 * @import { FogParams } from '../fog-params.js'
 */
/**
 * Per-call parameters for a renderer view (forward or pick), populated by the manager each frame
 * from the scene gsplat settings plus the view camera (and pick viewport). Reused per call to avoid
 * per-frame allocation; the renderer must not retain a reference to it.
 *
 * @typedef {object} GSplatRenderViewParams
 * @ignore
 * @property {GraphNode} cameraNode - The camera node for this view.
 * @property {boolean} radialSorting - Whether radial (vs linear) depth sorting is used.
 * @property {number} alphaClip - Alpha threshold for shadow/pick/prepass rendering.
 * @property {number} alphaClipForward - Alpha floor for the forward pass.
 * @property {number} minPixelSize - Minimum projected splat size.
 * @property {number} minContribution - Minimum visual contribution threshold.
 * @property {number} foveationStrength - Foveation strength.
 * @property {number} foveationCenter - Foveation center.
 * @property {boolean} antiAlias - Whether antialiasing is enabled.
 * @property {number} fisheye - Fisheye projection strength.
 * @property {ShaderMaterial} material - The scene gsplat template material.
 * @property {GSplatVaryings} varyings - User varying streams (provides the cache `words` count).
 * @property {number} [width] - Pick viewport width in pixels (picking only).
 * @property {number} [height] - Pick viewport height in pixels (picking only).
 */
/**
 * Base class for splat renderers. Holds common state shared by all renderer
 * implementations (instanced-quad, hybrid GPU-sort, etc.). Derived classes
 * implement the actual rendering strategy.
 *
 * @ignore
 */
export class GSplatRenderer {
    /**
     * @param {GraphicsDevice} device - The graphics device.
     * @param {GraphNode} node - The graph node.
     * @param {GraphNode} cameraNode - The camera node.
     * @param {Layer} layer - The layer to add mesh instances to.
     * @param {GSplatWorkBuffer} workBuffer - The work buffer containing splat data.
     */
    constructor(device: GraphicsDevice, node: GraphNode, cameraNode: GraphNode, layer: Layer, workBuffer: GSplatWorkBuffer);
    /** @type {GraphicsDevice} */
    device: GraphicsDevice;
    /** @type {GraphNode} */
    node: GraphNode;
    /** @type {GraphNode} */
    cameraNode: GraphNode;
    /** @type {Layer} */
    layer: Layer;
    /** @type {GSplatWorkBuffer} */
    workBuffer: GSplatWorkBuffer;
    /** @type {number|undefined} */
    renderMode: number | undefined;
    /**
     * Cached work buffer format version for detecting extra stream changes.
     *
     * @protected
     */
    protected _workBufferFormatVersion: number;
    /**
     * Fisheye projection helper shared by all renderer paths.
     * The manager calls update() during culling; renderers read the computed values
     * when binding uniforms.
     *
     * @type {FisheyeProjection}
     * @ignore
     */
    fisheyeProj: FisheyeProjection;
    destroy(): void;
    /**
     * Resolves the effective fisheye strength for this renderer's camera. Fisheye is not supported
     * in XR by any renderer (it overrides the per-eye perspective projection), so it is forced off
     * while an XR session is active. Warns once when a non-zero value is suppressed.
     *
     * @param {number} fisheye - Requested fisheye strength (typically `scene.gsplat.fisheye`).
     * @returns {number} The fisheye strength to use (0 while in XR, otherwise `fisheye`).
     */
    resolveFisheye(fisheye: number): number;
    /**
     * Sets the render mode for this renderer.
     *
     * @param {number} renderMode - Bitmask flags controlling render passes (GSPLAT_FORWARD, GSPLAT_SHADOW, or both).
     */
    setRenderMode(renderMode: number): void;
    /**
     * Whether this renderer runs the GPU sort/projection/cull pipeline itself (true) rather than
     * relying on the manager's CPU worker sorter (false). Drives the manager's per-frame branching.
     *
     * @type {boolean}
     */
    get usesGpuSort(): boolean;
    /**
     * Whether this renderer needs frustum-culling bounds uploaded to the work buffer (the GPU cull
     * path allocates them; the CPU path does not).
     *
     * @type {boolean}
     */
    get requiresBounds(): boolean;
    /**
     * Whether this renderer relies on the manager-owned CPU worker sorter.
     *
     * @type {boolean}
     */
    get requiresCpuSort(): boolean;
    /**
     * Returns the material used by this renderer, or null if not applicable.
     *
     * @type {ShaderMaterial|null}
     */
    get material(): ShaderMaterial | null;
    /**
     * Sets the data source providing format and texture access. The base implementation updates
     * the workBuffer and notifies derived classes of the format change. Derived classes may
     * override this to react to the source change (e.g. re-pointing materials at the new
     * work-buffer textures).
     *
     * The source object must provide:
     * - `format` — a {@link GSplatFormat} describing the texture streams and shader read code.
     * - `getTexture(name)` — a function returning a {@link Texture} for a given stream name.
     *
     * @param {object} source - The data source (typically a {@link GSplatWorkBuffer}).
     */
    setDataSource(source: object): void;
    /**
     * Called when the work buffer format has changed. Derived classes reconfigure
     * their rendering resources (materials, pipelines, bindings, etc.).
     */
    onWorkBufferFormatChanged(): void;
    /**
     * Updates the renderer with the current splat count and texture size.
     *
     * @param {number} count - The number of visible splats.
     * @param {number} textureSize - The work buffer texture size.
     */
    update(count: number, textureSize: number): void;
    /**
     * Configures the renderer to use GPU-sorted data for rendering.
     *
     * @param {number} drawSlot - The indirect draw slot index.
     * @param {StorageBuffer} sortedIds - Buffer containing sorted visible splat IDs.
     * @param {StorageBuffer} numSplatsBuffer - Buffer containing the visible splat count.
     * @param {number} textureSize - The work buffer texture size.
     */
    setGpuSortedRendering(drawSlot: number, sortedIds: StorageBuffer, numSplatsBuffer: StorageBuffer, textureSize: number): void;
    /**
     * Switches the renderer to CPU-sorted rendering mode.
     */
    setCpuSortedRendering(): void;
    /**
     * Binds the current order data (texture or storage buffer) for CPU-sorted rendering.
     */
    setOrderData(): void;
    /**
     * Per-frame update for the renderer (material syncing, parameter updates).
     *
     * @param {object} params - The gsplat parameters.
     * @param {number} [exposure] - Scene exposure value.
     * @param {FogParams} [fogParams] - Fog parameters.
     */
    frameUpdate(params: object, exposure?: number, fogParams?: FogParams): void;
    /**
     * Updates the overdraw visualization mode.
     *
     * @param {object} params - The gsplat parameters.
     */
    updateOverdrawMode(params: object): void;
    /**
     * Invalidates any cached cull/compaction upload state (e.g. after a work-buffer rebuild that
     * may have moved bounds indices). No-op for renderers without a GPU cull pipeline.
     */
    invalidateCullUpload(): void;
    /**
     * Prepares the forward view for rendering. Renderers that run their own GPU pipeline (cull +
     * projection + sort) do their per-frame work here; CPU-sort renderers rely on the manager's
     * worker instead and leave this as a no-op.
     *
     * @param {GSplatWorld} world - The world providing the work buffer, bounds, and states.
     * @param {GSplatWorldState} worldState - The render-ready world state to draw.
     * @param {GSplatRenderViewParams} params - Per-call parameters for this view.
     * @returns {boolean} True if a GPU dispatch ran this call.
     */
    prepareRenderView(world: GSplatWorld, worldState: GSplatWorldState, params: GSplatRenderViewParams): boolean;
    /**
     * Prepares a pick view and returns the configured pick mesh instance. Only meaningful for
     * renderers with a GPU pipeline; others return null.
     *
     * @param {GSplatWorld} world - The world providing the work buffer, bounds, and states.
     * @param {GSplatWorldState} worldState - The render-ready world state.
     * @param {GSplatRenderViewParams} pickParams - Per-call parameters for the pick view.
     * @returns {MeshInstance|null} The pick mesh instance, or null.
     */
    preparePickingView(world: GSplatWorld, worldState: GSplatWorldState, pickParams: GSplatRenderViewParams): MeshInstance | null;
}
import type { GraphicsDevice } from '../../platform/graphics/graphics-device.js';
import type { GraphNode } from '../graph-node.js';
import type { Layer } from '../layer.js';
import type { GSplatWorkBuffer } from './gsplat-work-buffer.js';
import { FisheyeProjection } from '../graphics/fisheye-projection.js';
import type { ShaderMaterial } from '../materials/shader-material.js';
import type { StorageBuffer } from '../../platform/graphics/storage-buffer.js';
import type { FogParams } from '../fog-params.js';
import type { GSplatWorld } from './gsplat-world.js';
import type { GSplatWorldState } from './gsplat-world-state.js';
import type { MeshInstance } from '../mesh-instance.js';