playcanvas
Version:
Open-source WebGL/WebGPU 3D engine for the web
512 lines (511 loc) • 17.9 kB
TypeScript
/**
* @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js'
* @import { Texture } from '../../platform/graphics/texture.js'
*/
/**
* Parameters for the GSplat system.
*
* @category Graphics
*/
export class GSplatParams {
/**
* Creates a new GSplatParams instance.
*
* @param {GraphicsDevice} device - The graphics device.
*/
constructor(device: GraphicsDevice);
/**
* @type {ShaderMaterial}
* @private
*/
private _material;
/**
* Format descriptor for work buffer streams.
*
* @type {GSplatFormat}
* @private
*/
private _format;
/**
* @type {GraphicsDevice}
* @private
*/
private _device;
/**
* @type {string}
* @private
*/
private _dataFormat;
/**
* @param {string} dataFormat - The data format constant.
* @returns {GSplatFormat} The created format.
* @private
*/
private _createFormat;
/**
* Enables radial sorting based on distance from camera (for cubemap rendering). When false,
* uses directional sorting along camera forward vector. Defaults to false.
*
* Note: Radial sorting helps reduce sorting artifacts when the camera rotates (looks around),
* while linear sorting is better at minimizing artifacts when the camera translates (moves).
*/
radialSorting: boolean;
/**
* @type {number}
* @private
*/
private _renderer;
/**
* @type {number}
* @private
*/
private _currentRenderer;
/**
* Sets the rendering pipeline used for gaussian splatting. Can be:
*
* - {@link GSPLAT_RENDERER_AUTO}: Automatically selects the best pipeline for the platform.
* - {@link GSPLAT_RENDERER_RASTER_CPU_SORT}: Rasterization with CPU-side sorting.
* - {@link GSPLAT_RENDERER_COMPUTE}: Full compute pipeline (WebGPU only, experimental).
* - {@link GSPLAT_RENDERER_RASTER_GPU_SORT}: Rasterization with GPU-side sorting (WebGPU only,
* experimental).
*
* Defaults to {@link GSPLAT_RENDERER_AUTO}. Modes requiring WebGPU fall back to
* {@link GSPLAT_RENDERER_RASTER_CPU_SORT} on WebGL devices. The resolved mode actually used
* can be queried via {@link currentRenderer}.
*
* @type {number}
*/
set renderer(value: number);
/**
* Gets the requested rendering pipeline for gaussian splatting. This may differ from
* {@link currentRenderer} when a WebGPU mode falls back on a WebGL device.
*
* @type {number}
*/
get renderer(): number;
/**
* The current rendering pipeline in effect after platform-based fallback resolution. When
* {@link renderer} is set to a mode requiring WebGPU on a WebGL device, this returns the
* fallback mode actually being used.
*
* @type {number}
*/
get currentRenderer(): number;
/**
* Internal dirty flag to trigger update of gsplat managers when some params change.
*
* @ignore
*/
dirty: boolean;
/**
* @type {number}
* @private
*/
private _debug;
/**
* Sets the debug rendering mode for Gaussian splats. Can be:
*
* - {@link GSPLAT_DEBUG_NONE}: Normal rendering (default).
* - {@link GSPLAT_DEBUG_LOD}: Colorize splats by their selected LOD level.
* - {@link GSPLAT_DEBUG_SH_UPDATE}: Random color per SH update pass to visualize update
* frequency.
* - {@link GSPLAT_DEBUG_HEATMAP}: Heatmap visualization of average splats processed per
* pixel in each tile. Only supported with {@link GSPLAT_RENDERER_COMPUTE}.
* - {@link GSPLAT_DEBUG_AABBS}: Draw world-space AABBs for each GSplat, colorized by LOD.
* - {@link GSPLAT_DEBUG_NODE_AABBS}: Draw world-space AABBs for each octree node of
* streamed GSplats, colorized by the currently selected LOD.
*
* Only one debug mode can be active at a time. Defaults to {@link GSPLAT_DEBUG_NONE}.
*
* @type {number}
*/
set debug(value: number);
/**
* Gets the debug rendering mode for Gaussian splats.
*
* @type {number}
*/
get debug(): number;
/**
* @type {boolean}
* @deprecated Use {@link debug} with {@link GSPLAT_DEBUG_LOD} instead.
* @ignore
*/
set colorizeLod(value: boolean);
/**
* @type {boolean}
* @deprecated Use {@link debug} with {@link GSPLAT_DEBUG_LOD} instead.
* @ignore
*/
get colorizeLod(): boolean;
/**
* @type {boolean}
* @deprecated Use {@link debug} with {@link GSPLAT_DEBUG_AABBS} instead.
* @ignore
*/
set debugAabbs(value: boolean);
/**
* @type {boolean}
* @deprecated Use {@link debug} with {@link GSPLAT_DEBUG_AABBS} instead.
* @ignore
*/
get debugAabbs(): boolean;
/**
* @type {boolean}
* @deprecated Use {@link debug} with {@link GSPLAT_DEBUG_NODE_AABBS} instead.
* @ignore
*/
set debugNodeAabbs(value: boolean);
/**
* @type {boolean}
* @deprecated Use {@link debug} with {@link GSPLAT_DEBUG_NODE_AABBS} instead.
* @ignore
*/
get debugNodeAabbs(): boolean;
/** @private */
private _enableIds;
/**
* Enables or disables per-component ID storage in the work buffer. When enabled, each GSplat
* component gets a unique ID written to the work buffer. This ID is used by the picking
* system to identify which component was picked, but is also available to custom shaders for
* effects like highlighting, animation, or any per-component differentiation.
*
* @type {boolean}
*/
set enableIds(value: boolean);
/**
* Gets the ID storage enabled state.
*
* @type {boolean}
*/
get enableIds(): boolean;
/**
* Distance threshold in world units to trigger LOD updates for camera and gsplat instances.
* Defaults to 1.
*/
lodUpdateDistance: number;
/**
* Angle threshold in degrees to trigger LOD updates based on camera rotation. Set to 0 to
* disable rotation-based updates. Defaults to 0.
*/
lodUpdateAngle: number;
/** @private */
private _lodBehindPenalty;
/**
* Multiplier applied to effective distance for nodes behind the camera when determining LOD.
* Value 1 means no penalty; higher values drop LOD faster for nodes behind the camera.
*
* Note: when using a penalty > 1, it often makes sense to set a positive
* {@link lodUpdateAngle} so LOD is re-evaluated on camera rotation, not just translation.
*
* @type {number}
*/
set lodBehindPenalty(value: number);
/**
* Gets behind-camera LOD penalty multiplier.
*
* @type {number}
*/
get lodBehindPenalty(): number;
/** @private */
private _lodRangeMin;
/**
* Minimum allowed LOD index (inclusive). Defaults to 0.
*
* @type {number}
*/
set lodRangeMin(value: number);
/**
* Gets minimum allowed LOD index (inclusive).
*
* @type {number}
*/
get lodRangeMin(): number;
/** @private */
private _lodRangeMax;
/**
* Maximum allowed LOD index (inclusive). Defaults to 10.
*
* @type {number}
*/
set lodRangeMax(value: number);
/**
* Gets maximum allowed LOD index (inclusive).
*
* @type {number}
*/
get lodRangeMax(): number;
/** @private */
private _lodUnderfillLimit;
/**
* Maximum number of LOD levels allowed below the optimal level when the optimal data is not
* resident in memory. The system may temporarily use a coarser LOD within this limit until the
* optimal LOD is available. Defaults to 0, which disables fallback (always load optimal).
* Higher values allow faster loading by using lower-quality data.
*
* @type {number}
*/
set lodUnderfillLimit(value: number);
/**
* Gets the maximum allowed underfill LOD range.
*
* @type {number}
*/
get lodUnderfillLimit(): number;
/** @private */
private _splatBudget;
/**
* Target number of splats across all GSplats in the scene. When set > 0,
* the system adjusts LOD levels globally to stay within this budget.
* Set to 0 to disable budget enforcement and use LOD distances only (default).
*
* @type {number}
*/
set splatBudget(value: number);
/**
* Gets the target number of splats across all GSplats in the scene.
*
* @type {number}
*/
get splatBudget(): number;
/**
* @type {import('../../platform/graphics/texture.js').Texture|null}
* @private
*/
private _colorRamp;
/**
* Gradient texture for elevation-based coloring in overdraw visualization mode.
* When set, enables overdraw mode with additive blending. When null, uses normal rendering.
* Texture should be (width x 1) size. World Y coordinate (0-20 range) maps to texture U coordinate.
* Defaults to null.
*
* @type {Texture|null}
*/
set colorRamp(value: import("../../platform/graphics/texture.js").Texture | null);
/**
* Gets the color ramp texture for overdraw visualization.
*
* @type {import('../../platform/graphics/texture.js').Texture|null}
*/
get colorRamp(): import("../../platform/graphics/texture.js").Texture | null;
/**
* Intensity multiplier for overdraw visualization mode. Value of 1 uses alpha of 1/32,
* allowing approximately 32 overdraws to reach full brightness with additive blending.
* Higher values increase brightness per splat. Defaults to 1.
*/
colorRampIntensity: number;
/**
* Whether to apply scene fog to Gaussian splats. When false, splats ignore fog settings
* even if the scene or camera has fog configured. Defaults to true.
*/
useFog: boolean;
/** @deprecated Use {@link debug} with {@link GSPLAT_DEBUG_SH_UPDATE} instead. */
set colorizeColorUpdate(value: boolean);
/**
* @deprecated Use {@link debug} with {@link GSPLAT_DEBUG_SH_UPDATE} instead.
* @returns {boolean} Whether SH update colorization is enabled.
*/
get colorizeColorUpdate(): boolean;
/**
* Viewing angle threshold in degrees for triggering spherical harmonics color updates.
* When the camera translates enough to change the viewing angle to an octree node or
* splat by this amount, its SH colors are re-evaluated. Distant nodes naturally update
* less frequently since they require more camera movement to reach the angle threshold.
* Set to 0 to update every frame where camera moves. Defaults to 10.
*/
colorUpdateAngle: number;
/** @ignore */
set colorUpdateDistance(value: number);
/** @ignore */
get colorUpdateDistance(): number;
/** @ignore */
set colorUpdateDistanceLodScale(value: number);
/** @ignore */
get colorUpdateDistanceLodScale(): number;
/** @ignore */
set colorUpdateAngleLodScale(value: number);
/** @ignore */
get colorUpdateAngleLodScale(): number;
/**
* Sets the alpha threshold for shadow, pick, and prepass rendering (not the main forward
* splat pass). Higher values create more aggressive clipping, while lower values preserve more
* translucent splats. Defaults to 0.3.
*
* @type {number}
*/
set alphaClip(value: number);
/**
* Gets the alpha threshold for shadow, pick, and prepass rendering.
*
* @type {number}
*/
get alphaClip(): number;
/**
* Sets the alpha threshold below which splats are culled or clipped in the **forward** splat
* rendering pass. Does not apply to shadow, pick, or prepass — use {@link GSplatParams#alphaClip}
* for those. Higher values improve performance by culling more low-opacity splats; lower values
* preserve more translucent splats. Defaults to 1 / 255.
*
* @type {number}
*/
set alphaClipForward(value: number);
/**
* Gets the forward-pass alpha threshold.
*
* @type {number}
*/
get alphaClipForward(): number;
/**
* Sets the minimum screen-space pixel size below which splats are discarded. Defaults to 2.
*
* @type {number}
*/
set minPixelSize(value: number);
/**
* Gets the minimum pixel size threshold.
*
* @type {number}
*/
get minPixelSize(): number;
/**
* Sets the minimum visual contribution threshold for the {@link GSPLAT_RENDERER_COMPUTE} renderer.
* Splats whose total screen contribution (opacity * projected area) falls below this value are
* discarded. Higher values cull more aggressively, improving performance at the cost of quality.
* Set to 0 to disable contribution culling. Defaults to 3.
*
* @type {number}
*/
set minContribution(value: number);
/**
* Gets the minimum contribution threshold.
*
* @type {number}
*/
get minContribution(): number;
/**
* Enables anti-aliasing compensation for Gaussian splats. Defaults to false.
*
* This option is intended for splat data that was generated with anti-aliasing
* enabled during training/export. It improves visual stability and reduces
* flickering for very small or distant splats.
*
* If the source splats were generated without anti-aliasing, enabling this
* option may slightly soften the image or alter opacity.
*
* @type {boolean}
*/
set antiAlias(value: boolean);
/**
* Gets whether anti-aliasing compensation is enabled.
*
* @type {boolean}
*/
get antiAlias(): boolean;
/**
* Enables 2D Gaussian Splatting mode. Defaults to false.
*
* Renders splats as oriented 2D surface elements instead of volumetric 3D Gaussians.
* This provides a more surface-accurate appearance but requires splat data that
* was generated for 2D Gaussian Splatting.
*
* Enabling this with standard 3D splat data may produce incorrect results.
*
* @type {boolean}
*/
set twoDimensional(value: boolean);
/**
* Gets whether 2D Gaussian Splatting mode is enabled.
*
* @type {boolean}
*/
get twoDimensional(): boolean;
/** @private */
private _fisheye;
/**
* Controls the fisheye projection strength for Gaussian splats. The value is in the
* range [0, 1]:
*
* - 0: Standard rectilinear (perspective) projection.
* - (0, 1]: Increasing barrel distortion, producing a wider field of view with a
* "little planet" effect at higher values.
*
* Enabling fisheye for the first time has a small one-off cost as new shaders are
* compiled. Subsequent switches between 0 and non-zero are instantaneous.
*
* Only supported with perspective cameras. Has no effect with orthographic projection.
*
* Note: This only affects Gaussian splat rendering. Other objects in the scene (meshes,
* sprites, etc.) continue to use the standard camera projection and are not distorted.
*
* For best results, enable {@link radialSorting} when using fisheye projection
* to avoid sorting artifacts caused by the wide field of view.
*
* Defaults to 0.
*
* @type {number}
*/
set fisheye(value: number);
/**
* Gets the fisheye projection strength.
*
* @type {number}
*/
get fisheye(): number;
/**
* Number of update ticks before unloading unused streamed resources. When a streamed resource's
* reference count reaches zero, it enters a cooldown period before being unloaded. This allows
* recently used data to remain in memory for quick reuse if needed again soon. Set to 0 to
* unload immediately when unused. Defaults to 100.
*/
cooldownTicks: number;
/**
* Work buffer data format. Controls the precision and bandwidth of the intermediate work buffer
* used during GSplat rendering. Can be set to {@link GSPLATDATA_COMPACT} (20 bytes/splat)
* or {@link GSPLATDATA_LARGE} (32 bytes/splat). Defaults to {@link GSPLATDATA_COMPACT}.
*
* @type {string}
*/
set dataFormat(value: string);
/**
* Gets the work buffer data format.
*
* @type {string}
*/
get dataFormat(): string;
/**
* A material template that can be customized by the user. Any defines, parameters, or shader
* chunks set on this material will be automatically applied to all GSplat components. After
* making changes, call {@link Material#update} to for the changes to be applied on the next
* frame.
*
* @type {ShaderMaterial}
* @example
* // Set a custom parameter on all GSplat materials
* app.scene.gsplat.material.setParameter('myCustomParam', 1.0);
* app.scene.gsplat.material.update();
*/
get material(): ShaderMaterial;
/**
* Format descriptor for work buffer streams. Describes the textures used by the work buffer
* for intermediate storage during rendering. Users can add extra streams via
* {@link GSplatFormat#addExtraStreams} for custom per-splat data.
*
* @type {GSplatFormat}
* @example
* // Add a custom stream to store per-splat component IDs
* app.scene.gsplat.format.addExtraStreams([{
* name: 'splatId',
* format: pc.PIXELFORMAT_R32U
* }]);
*/
get format(): GSplatFormat;
/**
* Called at the end of the frame to clear dirty flags.
*
* @ignore
*/
frameEnd(): void;
}
import { ShaderMaterial } from '../materials/shader-material.js';
import { GSplatFormat } from '../gsplat/gsplat-format.js';
import type { GraphicsDevice } from '../../platform/graphics/graphics-device.js';