diff --git a/src/SparkRenderer.ts b/src/SparkRenderer.ts index 02ebc94..18da9a0 100644 --- a/src/SparkRenderer.ts +++ b/src/SparkRenderer.ts @@ -78,62 +78,101 @@ THREE.Scene.prototype.onBeforeRender = function ( }; export type SparkRendererOptions = { - // Pass in your THREE.WebGLRenderer instance so Spark can perform work - // outside the usual render loop. Should be created with antialias: false - // (default setting) as WebGL anti-aliasing doesn't improve Gaussian Splatting - // rendering and significantly reduces performance. + /** + * Pass in your THREE.WebGLRenderer instance so Spark can perform work + * outside the usual render loop. Should be created with antialias: false + * (default setting) as WebGL anti-aliasing doesn't improve Gaussian Splatting + * rendering and significantly reduces performance. + */ renderer: THREE.WebGLRenderer; - // Pass in a THREE.Clock to synchronize time-based effects across different - // systems. Alternatively, you can set the SparkRenderer properties time and - // deltaTime directly. (default: new THREE.Clock) + /** + * Pass in a THREE.Clock to synchronize time-based effects across different + * systems. Alternatively, you can set the SparkRenderer properties time and + * deltaTime directly. (default: new THREE.Clock) + */ clock?: THREE.Clock; - // Controls whether to check and automatically update Gsplat collection after - // each frame render. (default: true) + /** + * Controls whether to check and automatically update Gsplat collection after + * each frame render. + * @default true + */ autoUpdate?: boolean; - // Controls whether to update the Gsplats before or after rendering. For WebXR - // this must be false in order to complete rendering as soon as possible. - // (default: false) + /** + * Controls whether to update the Gsplats before or after rendering. For WebXR + * this must be false in order to complete rendering as soon as possible. + * @default false + */ preUpdate?: boolean; - // Distance threshold for SparkRenderer movement triggering a Gsplat update at - // the new origin. (default: 1.0) + /** + * Distance threshold for SparkRenderer movement triggering a Gsplat update at + * the new origin. + * @default 1.0 + */ originDistance?: number; - // Maximum standard deviations from the center to render Gaussians. Values - // Math.sqrt(5)..Math.sqrt(8) produce good results and can be tweaked for - // performance. (default: Math.sqrt(8)) + /** + * Maximum standard deviations from the center to render Gaussians. Values + * Math.sqrt(5)..Math.sqrt(8) produce good results and can be tweaked for + * performance. + * @default Math.sqrt(8) + */ maxStdDev?: number; - // Enable 2D Gaussian splatting rendering ability. When this mode is enabled, - // any scale x/y/z component that is exactly 0 (minimum quantized value) results - // in the other two non-0 axis being interpreted as an oriented 2D Gaussian Splat, - // rather instead of the usual projected 3DGS Z-slice. When reading PLY files, - // scale values less than e^-30 will be interpreted as 0. (default: false) + /** + * Enable 2D Gaussian splatting rendering ability. When this mode is enabled, + * any scale x/y/z component that is exactly 0 (minimum quantized value) results + * in the other two non-0 axis being interpreted as an oriented 2D Gaussian Splat, + * rather instead of the usual projected 3DGS Z-slice. When reading PLY files, + * scale values less than e^-30 will be interpreted as 0. + * @default false + */ enable2DGS?: boolean; - // Scalar value to add to 2D splat covariance diagonal, effectively blurring + - // enlarging splats. In scenes trained without the Gsplat anti-aliasing tweak - // this value was typically 0.3, but with anti-aliasing it is 0.0 (default: 0.0) + /** + * Scalar value to add to 2D splat covariance diagonal, effectively blurring + + * enlarging splats. In scenes trained without the Gsplat anti-aliasing tweak + * this value was typically 0.3, but with anti-aliasing it is 0.0 + * @default 0.0 + */ preBlurAmount?: number; - // Scalar value to add to 2D splat covarianve diagonal, with opacity adjustment - // to correctly account for "blurring" when anti-aliasing. Typically 0.3 - // (equivalent to approx 0.5 pixel radius) in scenes trained with anti-aliasing. + /** + * Scalar value to add to 2D splat covarianve diagonal, with opacity adjustment + * to correctly account for "blurring" when anti-aliasing. Typically 0.3 + * (equivalent to approx 0.5 pixel radius) in scenes trained with anti-aliasing. + */ blurAmount?: number; - // Depth-of-field distance to focal plane + /** + * Depth-of-field distance to focal plane + */ focalDistance?: number; - // Full-width angle of aperture opening (in radians), default 0.0 to disable + /** + * Full-width angle of aperture opening (in radians), 0.0 to disable + * @default 0.0 + */ apertureAngle?: number; - // Modulate Gaussian kernel falloff. 0 means "no falloff, flat shading", - // while 1 is the normal Gaussian kernel. (default: 1.0) + /** + * Modulate Gaussian kernel falloff. 0 means "no falloff, flat shading", + * while 1 is the normal Gaussian kernel. + * @default 1.0 + */ falloff?: number; - // X/Y clipping boundary factor for Gsplat centers against view frustum. - // 1.0 clips any centers that are exactly out of bounds, while 1.4 clips - // centers that are 40% beyond the bounds. (default: 1.4) + /** + * X/Y clipping boundary factor for Gsplat centers against view frustum. + * 1.0 clips any centers that are exactly out of bounds, while 1.4 clips + * centers that are 40% beyond the bounds. + * @default 1.4 + */ clipXY?: number; - // Parameter to adjust projected splat scale calculation to match other renderers, - // similar to the same parameter in the MKellogg 3DGS renderer. Higher values will - // tend to sharpen the splats. A value 2.0 can be used to match the behavior of - // the PlayCanvas renderer. (default: 1.0) + /** + * Parameter to adjust projected splat scale calculation to match other renderers, + * similar to the same parameter in the MKellogg 3DGS renderer. Higher values will + * tend to sharpen the splats. A value 2.0 can be used to match the behavior of + * the PlayCanvas renderer. + * @default 1.0 + */ focalAdjustment?: number; - // Configures the SparkViewpointOptions for the default SparkViewpoint - // associated with this SparkRenderer. Notable option: sortRadial (sort by - // radial distance or Z-depth) + /** + * Configures the SparkViewpointOptions for the default SparkViewpoint + * associated with this SparkRenderer. Notable option: sortRadial (sort by + * radial distance or Z-depth) + */ view?: SparkViewpointOptions; }; diff --git a/src/SparkViewpoint.ts b/src/SparkViewpoint.ts index bd0da72..c2056d4 100644 --- a/src/SparkViewpoint.ts +++ b/src/SparkViewpoint.ts @@ -29,53 +29,93 @@ import { withWorker } from "./splatWorker"; import { FreeList, withinCoorientDist } from "./utils"; export type SparkViewpointOptions = { - // Controls whether to auto-update its sort order whenever the SparkRenderer - // updates the Gsplats. If you expect to render/display from this viewpoint - // most frames, set this to true. (default: false) + /** + * Controls whether to auto-update its sort order whenever the SparkRenderer + * updates the Gsplats. If you expect to render/display from this viewpoint + * most frames, set this to true. + * @default false + */ autoUpdate?: boolean; - // Set a THREE.Camera for this viewpoint to follow. (default: undefined) + /** + * Set a THREE.Camera for this viewpoint to follow. + * @default undefined + */ camera?: THREE.Camera; - // Set an explicit view-to-world transformation matrix for this viewpoint (equivalent - // to camera.matrixWorld), overrides any camera setting. (default: undefined) + /** + * Set an explicit view-to-world transformation matrix for this viewpoint (equivalent + * to camera.matrixWorld), overrides any camera setting. + * @default undefined + */ viewToWorld?: THREE.Matrix4; - // Configure viewpoint with an off-screen render target. (default: undefined) + /** + * Configure viewpoint with an off-screen render target. + * @default undefined + */ target?: { - // Width of the render target in pixels. + /** + * Width of the render target in pixels. + */ width: number; - // Height of the render target in pixels. + /** + * Height of the render target in pixels. + */ height: number; - // If you want to be able to render a scene that depends on this target's - // output (for example, a recursive viewport), set this to true to enable - // double buffering. (default: false) + /** + * If you want to be able to render a scene that depends on this target's + * output (for example, a recursive viewport), set this to true to enable + * double buffering. + * @default false + */ doubleBuffer?: boolean; - // Super-sampling factor for the render target. Values 1-4 are supported. - // Note that re-sampling back down to .width x .height is done on the CPU - // with simple averaging only when calling readTarget(). (default: 1) + /** + * Super-sampling factor for the render target. Values 1-4 are supported. + * Note that re-sampling back down to .width x .height is done on the CPU + * with simple averaging only when calling readTarget(). + * @default 1 + */ superXY?: number; }; - // Callback function that is called when the render target texture is updated. - // Receives the texture as a parameter. Use this to update a viewport with - // the latest viewpoint render each frame. (default: undefined) + /** + * Callback function that is called when the render target texture is updated. + * Receives the texture as a parameter. Use this to update a viewport with + * the latest viewpoint render each frame. + * @default undefined + */ onTextureUpdated?: (texture: THREE.Texture) => void; - // Whether to sort splats radially (geometric distance) from the viewpoint (true) - // or by Z-depth (false). Most scenes are trained with the Z-depth sort metric - // and will render more accurately at certain viewpoints. However, radial sorting - // is more stable under viewpoint rotations. (default: true) + /** + * Whether to sort splats radially (geometric distance) from the viewpoint (true) + * or by Z-depth (false). Most scenes are trained with the Z-depth sort metric + * and will render more accurately at certain viewpoints. However, radial sorting + * is more stable under viewpoint rotations. + * @default true + */ sortRadial?: boolean; - // Distance threshold for re-sorting splats. If the viewpoint moves more than - // this distance, splats will be re-sorted. (default: 0.01 units) + /** + * Distance threshold for re-sorting splats. If the viewpoint moves more than + * this distance, splats will be re-sorted. + * @default 0.01 units + */ sortDistance?: number; - // View direction dot product threshold for re-sorting splats. For - // sortRadial: true we use 0.99 while sortRadial: false uses 0.999 because it is - // more sensitive to view direction. (default: 0.99 if sortRadial else 0.999) + /** + * View direction dot product threshold for re-sorting splats. For + * sortRadial: true we use 0.99 while sortRadial: false uses 0.999 because it is + * more sensitive to view direction. + * @default 0.99 if sortRadial else 0.999 + */ sortCoorient?: boolean; - // Constant added to Z-depth to bias values into the positive range for - // sortRadial: false, but also used for culling Gsplats "well behind" - // the viewpoint origin (default: 1.0) + /** + * Constant added to Z-depth to bias values into the positive range for + * sortRadial: false, but also used for culling Gsplats "well behind" + * the viewpoint origin + * @default 1.0 + */ depthBias?: number; - // Set this to true if rendering a 360 to disable "behind the viewpoint" - // culling during sorting. This is set automatically when rendering 360 envMaps - // using the SparkRenderer.renderEnvMap() utility function. (default: false) + /** + * Set this to true if rendering a 360 to disable "behind the viewpoint" + * culling during sorting. This is set automatically when rendering 360 envMaps + * using the SparkRenderer.renderEnvMap() utility function. + * @default false + */ sort360?: boolean; };