threepipe/lib/plugins/rendering/CascadedShadowsPlugin.d.ts

A modern 3D viewer framework built on top of three.js, written in TypeScript, designed to make creating high-quality, modular, and extensible 3D experiences on the web simple and enjoyable.

import { AViewerPluginSync, ThreeViewer } from '../../viewer';
import { UiObjectConfig } from 'uiconfig.js';
import { MaterialExtension } from '../../materials';
import { DirectionalLight, Matrix4, Object3D, Vector2, Vector3 } from 'three';
import { ICamera, IObject3D } from '../../core';
/**
 * Configuration data for CSM (Cascaded Shadow Maps) light parameters
 */
export interface CSMLightData {
    /** Number of shadow cascades. Default: 3 */
    cascades?: number;
    /** Shadow map resolution for each cascade. Default: 2048 */
    shadowMapSize?: number;
    /** Shadow bias to prevent shadow acne. If undefined, uses light's existing bias */
    shadowBias?: number | undefined;
    /** Near plane distance for shadow camera. If undefined, uses light's existing near */
    lightNear?: number | undefined;
    /** Far plane distance for shadow camera. If undefined, uses light's existing far */
    lightFar?: number | undefined;
    /** Margin around the frustum bounds for shadow calculation. Default: 200 */
    lightMargin?: number;
}
/**
 * Cascaded Shadow Maps (CSM) plugin for high-quality directional light shadows across large scenes.
 *
 * This plugin implements cascaded shadow mapping to provide better shadow quality across
 * different distances from the camera by splitting the view frustum into multiple cascades,
 * each with its own shadow map at an appropriate resolution.
 *
 * Features:
 * - Multiple cascade splitting modes: uniform, logarithmic, practical, and custom
 * - Automatic light attachment to first directional light found
 * - Configurable shadow parameters per light
 * - Material extension for proper shadow sampling
 * - Optional fade between cascades
 *
 * Original three-csm implementation - https://github.com/StrandedKitty/three-csm
 * @example
 * ```typescript
 * const viewer = new ThreeViewer({
 *     plugins: [new CascadedShadowsPlugin()]
 * })
 *
 * const light = new DirectionalLight2(0xffffff, 1.5)
 * viewer.scene.addObject(light)
 *
 * const csmPlugin = viewer.getPlugin(CascadedShadowsPlugin)!
 * csmPlugin.setLightParams({
 *     cascades: 4,
 *     shadowMapSize: 1024,
 *     lightMargin: 100
 * }, light)
 * ```
 */
export declare class CascadedShadowsPlugin extends AViewerPluginSync {
    static readonly PluginType = "CascadedShadowsPlugin";
    /** Enable/disable the cascaded shadow maps plugin */
    enabled: boolean;
    /** Current camera used for frustum calculations */
    camera?: ICamera;
    /** Parent object containing all CSM lights */
    parent: Object3D;
    /**
     * Total cascades
     */
    /** Maximum far distance for shadow calculation */
    maxFar: number;
    /** Cascade splitting mode: uniform, logarithmic, practical, or custom */
    mode: 'uniform' | 'logarithmic' | 'practical' | 'custom';
    /**
     * Automatically attach to first found directional light in the scene that casts shadow, if none is attached yet.
     * Call {@link refreshAttachedLight} to manually trigger light search.
     */
    attachToFirstLight: boolean;
    /** Enable fade between cascades for smoother transitions */
    fade: boolean;
    /** The main directional light that CSM will be applied to */
    light?: DirectionalLight & IObject3D;
    /** Custom callback for defining cascade splits when mode is 'custom' */
    customSplitsCallback?: (amount: number, near: number, far: number, breaks: number[]) => void;
    /** Main camera frustum for cascade calculation */
    mainFrustum: CSMFrustum;
    /** Individual frustums for each cascade */
    frustums: CSMFrustum[];
    /** Cascade break points in normalized depth [0-1] */
    breaks: number[];
    /** Extended break data for shader uniforms */
    extendedBreaks: (Vector3 | Vector2)[];
    /** Generated directional lights for each cascade */
    lights: DirectionalLight[];
    constructor(enabled?: boolean);
    private _lightRef;
    private _lightUpdate;
    /**
     * Configure shadow parameters for a specific light
     * @param params - CSM light configuration parameters
     * @param light - Target light (uses attached light if not specified)
     */
    setLightParams(params: CSMLightData, light?: DirectionalLight & IObject3D): void;
    refreshLights: (e?: any) => void;
    private _mainCameraChange;
    private _cameraUpdated;
    private _mainCameraUpdate;
    cameraNeedsUpdate: () => void;
    private _needsUpdate;
    private _lastEnabled;
    setDirty: () => void;
    protected _viewerListeners: {
        preRender: () => void;
    };
    onAdded(viewer: ThreeViewer): void;
    onRemove(viewer: ThreeViewer): void;
    protected _initCascades(breaks: number[]): CSMFrustum[];
    protected _updateShadowBounds(): void;
    protected _getBreaks(cascades: number): number[];
    /**
     * Uniform split function for shadow cascades
     */
    private _uniformSplit;
    /**
     * Logarithmic split function for shadow cascades
     */
    private _logarithmicSplit;
    /**
     * Practical split function for shadow cascades
     */
    private _practicalSplit;
    private _lastCenters;
    update(): boolean;
    private _lightAutoAttached;
    /**
     * Finds and attaches to the first directional light in the scene that casts shadows
     */
    refreshAttachedLight: () => void;
    private _sversion;
    protected _updateFrustums: () => void;
    /**
     * Total cascades
     */
    get cascades(): number;
    materialExtension: MaterialExtension;
    uiConfig: UiObjectConfig;
    injectInclude(): void;
    private readonly _lightDirection;
    private readonly _cameraToLightMatrix;
    private readonly _lightSpaceFrustum;
    private readonly _center;
    private readonly _bbox;
    private readonly _uniformArray;
    private readonly _logArray;
    private readonly _lightOrientationMatrix;
    private readonly _lightOrientationMatrixInverse;
    private readonly _up;
}
export interface FrustumParams {
    projectionMatrix?: Matrix4;
    maxFar?: number;
}
export interface FrustumVertices {
    far: Vector3[];
    near: Vector3[];
}
export declare class CSMFrustum {
    private _inverseProjectionMatrix;
    vertices: FrustumVertices;
    constructor(data?: FrustumParams);
    setFromProjectionMatrix(projectionMatrix: Matrix4, maxFar: number): FrustumVertices;
    split(breaks: number[], target: CSMFrustum[]): void;
    toSpace(cameraMatrix: Matrix4, target: CSMFrustum): void;
}
//# sourceMappingURL=../../src/plugins/rendering/CascadedShadowsPlugin.d.ts.map