playcanvas
Version:
Open-source WebGL/WebGPU 3D engine for the web
312 lines (311 loc) • 12.3 kB
TypeScript
export type GSplatStreamDescriptor = {
/**
* - The name of the stream (used as texture uniform name).
*/
name: string;
/**
* - The pixel format of the texture (e.g. PIXELFORMAT_RGBA32F).
* When used as an extra stream for work buffers or as a destination stream for
* GSplatProcessor, the format must be renderable as these textures are used as render
* targets. Ensure the format is renderable on all target devices. See {@link Texture} for
* details on renderable formats and device capabilities.
*/
format: number;
/**
* - Storage type: GSPLAT_STREAM_RESOURCE (default, shared across
* instances) or GSPLAT_STREAM_INSTANCE (per-component instance). Note: Work buffer formats
* (accessed via `app.scene.gsplat.format`) do not support GSPLAT_STREAM_INSTANCE.
*/
storage?: number;
};
/**
* Gsplat resources store per-splat data (positions, colors, rotations, scales, spherical
* harmonics) in GPU textures. This class describes those texture streams and generates the
* shader code needed to access them.
*
* Each stream defines a texture with a name and pixel format. The class automatically generates
* shader declarations (uniforms/samplers) and load functions (e.g. `loadColor()`) for each
* stream. A read shader can be provided to define how splat attributes are extracted from
* these textures.
*
* Users can add extra streams via {@link addExtraStreams} for custom per-splat data. These
* can be per-resource (shared across instances) or per-instance (unique to each gsplat
* component).
*
* For loaded gsplat resources, base streams are automatically configured based on the loaded
* data format. For {@link GSplatContainer}, users define both base and extra streams to
* specify the complete data layout.
*
* @category Graphics
*/
export class GSplatFormat {
/**
* Creates a default format using 32F/16F textures, simple to use for CPU data population.
* This format can be rendered to by {@link GSplatProcessor} when supported. Check
* {@link GraphicsDevice#textureFloatRenderable} (for RGBA32F) and
* {@link GraphicsDevice#textureHalfFloatRenderable} (for RGBA16F).
*
* The format stores:
* - `dataColor` (RGBA16F): color.rgba as half floats
* - `dataCenter` (RGBA32F): center.xyz as floats (w unused)
* - `dataScale` (RGBA16F): scale.xyz as half floats (w unused)
* - `dataRotation` (RGBA16F): rotation.xyzw as half floats (w stored directly, not derived)
*
* @param {GraphicsDevice} device - The graphics device.
* @returns {GSplatFormat} The default format.
*/
static createDefaultFormat(device: GraphicsDevice): GSplatFormat;
/**
* Creates a simple format with uniform-scale splats and no rotation.
* Streams:
* - `dataCenter` (RGBA32F): center.xyz + uniform size in w
* - `dataColor` (RGBA16F): color.rgba as half floats
*
* @param {GraphicsDevice} device - The graphics device.
* @returns {GSplatFormat} The simple format.
*/
static createSimpleFormat(device: GraphicsDevice): GSplatFormat;
/**
* Creates a new GSplatFormat instance.
*
* @param {GraphicsDevice} device - The graphics device.
* @param {GSplatStreamDescriptor[]} streams - Array of stream descriptors.
* @param {object} options - Format options.
* @param {string} [options.readGLSL] - GLSL code defining getCenter(), getColor(),
* getRotation(), getScale() functions. Can include additional declarations at module scope.
* Required for WebGL.
* @param {string} [options.readWGSL] - WGSL code defining getCenter(), getColor(),
* getRotation(), getScale() functions. Can include additional declarations at module scope.
* Required for WebGPU.
*/
constructor(device: GraphicsDevice, streams: GSplatStreamDescriptor[], options: {
readGLSL?: string;
readWGSL?: string;
});
/**
* @type {GraphicsDevice}
* @private
*/
private _device;
/**
* Array of stream descriptors.
*
* @type {GSplatStreamDescriptor[]}
* @readonly
*/
readonly streams: GSplatStreamDescriptor[];
/**
* User-provided code for reading splat data (GLSL or WGSL based on device).
* Must define getCenter(), getColor(), getRotation(), getScale() functions.
*
* @type {string}
* @private
*/
private _read;
/**
* When true, allows extra streams to be removed via {@link removeExtraStreams}.
* Only work buffer formats (returned by {@link GSplatParams#format}) should set this.
*
* @ignore
*/
allowStreamRemoval: boolean;
/**
* Work buffer data layout identifier (one of GSPLATDATA_*), or null for resource formats.
* Set by {@link GSplatParams} when creating a work buffer format. Identifies how transform
* data is encoded, so consumers (e.g. the work-buffer-sourced spherical harmonics update)
* can select the matching decode without inspecting individual stream pixel formats.
*
* @type {string|null}
* @ignore
*/
dataFormat: string | null;
/**
* Extra streams added via addExtraStreams(). For resource formats, streams can only be
* added, never removed. For work buffer formats (where {@link allowStreamRemoval} is true),
* streams can also be removed via {@link removeExtraStreams}.
*
* @type {GSplatStreamDescriptor[]}
* @private
*/
private _extraStreams;
/**
* Set of all stream names (base + extra) for fast duplicate checking.
*
* @type {Set<string>}
* @private
*/
private _streamNames;
/**
* Version counter that increments when extra streams change.
*
* @private
*/
private _extraStreamsVersion;
/**
* Cached hash value.
*
* @type {number|undefined}
* @private
*/
private _hash;
/**
* Cached resource streams array.
*
* @type {GSplatStreamDescriptor[]|null}
* @private
*/
private _resourceStreams;
/**
* Cached instance streams array.
*
* @type {GSplatStreamDescriptor[]|null}
* @private
*/
private _instanceStreams;
/**
* Returns a hash of this format's configuration. Used for shader caching.
* Computed from raw inputs to avoid generating shader code just for the hash.
*
* @type {number}
* @ignore
*/
get hash(): number;
/**
* Returns the version counter. Increments when extra streams change.
*
* @type {number}
* @ignore
*/
get extraStreamsVersion(): number;
/**
* Gets the extra streams array. Streams can only be added via {@link addExtraStreams},
* not removed. Do not modify the returned array directly.
*
* @type {GSplatStreamDescriptor[]}
*/
get extraStreams(): GSplatStreamDescriptor[];
/**
* Returns all resource-level streams (base streams + extra streams where instance !== true).
* Used by GSplatStreams for resource texture management.
*
* @type {GSplatStreamDescriptor[]}
* @ignore
*/
get resourceStreams(): GSplatStreamDescriptor[];
/**
* Returns all instance-level streams (extra streams with GSPLAT_STREAM_INSTANCE storage).
* Used by GSplatStreams for per-component-instance texture management.
*
* @type {GSplatStreamDescriptor[]}
* @ignore
*/
get instanceStreams(): GSplatStreamDescriptor[];
/**
* Adds additional texture streams for custom gsplat data. Each stream defines a texture
* that can store extra information, accessible in shaders via generated load functions.
* Streams with `storage: GSPLAT_STREAM_INSTANCE` are created per gsplat component instance,
* while others are shared across all instances of the same resource.
*
* Note: Streams cannot be removed once added currently.
*
* @param {GSplatStreamDescriptor[]} streams - Array of stream descriptors to add.
*/
addExtraStreams(streams: GSplatStreamDescriptor[]): void;
/**
* Removes extra streams by name. Only supported on work buffer formats
* (returned by {@link GSplatParams#format}). Removing streams from resource
* formats is not supported.
*
* @param {string[]} names - Array of stream names to remove.
* @ignore
*/
removeExtraStreams(names: string[]): void;
/**
* Generates input declarations (texture uniforms + load functions).
*
* @param {string[]} [streamNames] - Optional array of stream names to filter. If not provided,
* generates declarations for all streams.
* @returns {string} Shader code for declarations.
* @ignore
*/
getInputDeclarations(streamNames?: string[]): string;
/**
* Returns the read code.
*
* @returns {string} Shader code for reading splat data.
* @ignore
*/
getReadCode(): string;
/**
* Generates compute shader input declarations with explicit binding annotations.
* Format texture bindings are placed at indices starting from startBinding.
*
* @param {number} startBinding - The first @group(0) @binding() index for format textures.
* @param {string[]} [streamNames] - Optional array of stream names to filter.
* @returns {string} WGSL code for compute shader declarations.
* @ignore
*/
getComputeInputDeclarations(startBinding: number, streamNames?: string[]): string;
/**
* Returns an array of BindTextureFormat entries for the format's streams, suitable for
* appending to a compute shader's BindGroupFormat. Sample types are derived from pixel formats.
*
* @param {string[]} [streamNames] - Optional array of stream names to filter.
* @returns {BindTextureFormat[]} Array of bind texture format entries.
* @ignore
*/
getComputeBindFormats(streamNames?: string[]): BindTextureFormat[];
/**
* Sets the write code for encoding splat data into the work buffer. The appropriate code
* for the current backend (GLSL or WGSL) is stored.
*
* @param {string} writeGLSL - GLSL code for writing/encoding splat data.
* @param {string} writeWGSL - WGSL code for writing/encoding splat data.
* @ignore
*/
setWriteCode(writeGLSL: string, writeWGSL: string): void;
_write: string;
/**
* Returns the write code for encoding splat data into the work buffer.
*
* @returns {string|undefined} Shader code for writing splat data, or undefined if not set.
* @ignore
*/
getWriteCode(): string | undefined;
/**
* Generates output declarations (write functions) for MRT output streams.
* Used by GSplatProcessor to generate output functions for dstStreams.
* Each stream maps to an MRT slot (pcFragColor0, pcFragColor1, etc. in GLSL or
* processOutput.color, processOutput.color1, etc. in WGSL).
*
* @param {GSplatStreamDescriptor[]} outputStreams - Stream descriptors for output.
* @returns {string} Shader code for output write functions.
* @ignore
*/
getOutputDeclarations(outputStreams: GSplatStreamDescriptor[]): string;
/**
* Generates no-op stub functions for streams that aren't render targets.
* Used in color-only mode so user modifier code compiles but writes are ignored.
*
* @param {GSplatStreamDescriptor[]} streams - Stream descriptors to generate stubs for.
* @returns {string} Shader code for no-op write functions.
* @ignore
*/
getOutputStubs(streams: GSplatStreamDescriptor[]): string;
/**
* Returns a stream descriptor by name.
*
* @param {string} name - The name of the stream to find.
* @returns {GSplatStreamDescriptor|undefined} The stream descriptor, or undefined if not found.
* @ignore
*/
getStream(name: string): GSplatStreamDescriptor | undefined;
/**
* Invalidates all cached values when streams change.
*
* @private
*/
private _invalidateCaches;
}
import { BindTextureFormat } from '../../platform/graphics/bind-group-format.js';
import type { GraphicsDevice } from '../../platform/graphics/graphics-device.js';