@navaramap/three-csm 0.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 MapLibre contributors
+
+This project is dual-licensed under either of
+
+- Apache License, Version 2.0 (see LICENSE-APACHE)
+- MIT license (see LICENSE-MIT)
+
+at your option.

package/README.md

@@ -0,0 +1,5 @@
+# @navaramap/three-csm
+
+This is a library to extend Three.js to enable Cascaded Shadow Map(CSM).
+
+Research & development by https://github.com/takram-design-engineering.

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+import { Camera } from 'three';
+import { Color } from 'three';
+import { ColorRepresentation } from 'three';
+import { DirectionalLight } from 'three';
+import { Group } from 'three';
+import { Material } from 'three';
+import { Matrix4 } from 'three';
+import { Object3D } from 'three';
+import { OrthographicCamera } from 'three';
+import { PerspectiveCamera } from 'three';
+import { Vector2 } from 'three';
+import { Vector3 } from 'three';
+
+export declare class CascadedDirectionalLights extends Object3D {
+    readonly mainLight: DirectionalLight;
+    readonly cascadedLights: DirectionalLight[];
+    direction: Vector3;
+    constructor(color?: ColorRepresentation, intensity?: number);
+    setCount(value: number): this;
+    dispose(): void;
+    copy(source: this, _recursive?: boolean): this;
+}
+
+export declare class CascadedShadowMaps {
+    readonly mainCamera: PerspectiveCamera | OrthographicCamera;
+    needsUpdateFrusta: boolean;
+    readonly directionalLights: CascadedDirectionalLights;
+    readonly materialStates: MaterialStates;
+    readonly mainFrustum: FrustumCorners;
+    readonly cascadedFrusta: FrustumCorners[];
+    readonly splits: number[];
+    readonly cascades: Vector2[];
+    private _far;
+    private _mode;
+    private _lambda;
+    private _margin;
+    private _fade;
+    private _disableLastCascadeCutoff;
+    constructor(mainCamera: PerspectiveCamera | OrthographicCamera, params?: CascadedShadowMapsOptions);
+    dispose(): void;
+    setupMaterial<T extends Material>(material: T): T;
+    rollbackMaterial<T extends Material>(material: T): T;
+    setupMaterials<T extends readonly Material[]>(materials: T): () => void;
+    private updateCascades;
+    private getFrustumRadius;
+    private updateShadowBounds;
+    updateFrusta(): void;
+    update(): void;
+    get cascadeCount(): number;
+    set cascadeCount(value: number);
+    get mapSize(): number;
+    set mapSize(value: number);
+    get far(): number;
+    set far(value: number);
+    get mode(): FrustumSplitMode;
+    set mode(value: FrustumSplitMode);
+    get lambda(): number;
+    set lambda(value: number);
+    get margin(): number;
+    set margin(value: number);
+    get fade(): boolean;
+    set fade(value: boolean);
+    get disableLastCascadeCutoff(): boolean;
+    set disableLastCascadeCutoff(value: boolean);
+    get intensity(): number;
+    set intensity(value: number);
+    get shadowIntensity(): number;
+    set shadowIntensity(value: number);
+    get color(): Color;
+    set color(value: Color);
+    get bias(): number;
+    set bias(value: number);
+    get normalBias(): number;
+    set normalBias(value: number);
+    get radius(): number;
+    set radius(value: number);
+    get blurSamples(): number;
+    set blurSamples(value: number);
+}
+
+export declare type CascadedShadowMapsOptions = {
+    /**
+     * Number of shadow cascades. More cascades provide better shadow quality
+     * distribution but require more GPU resources.
+     * @default 4
+     */
+    cascadeCount?: number;
+    /**
+     * Resolution of shadow maps (one per cascade). Higher values provide better
+     * shadow quality but require more GPU memory.
+     * @default 2048
+     */
+    mapSize?: number;
+    /**
+     * Frustum far plane distance. Shadows will not be visible farther than this
+     * distance from the camera.
+     * @default 5000
+     */
+    far?: number;
+    /**
+     * Defines the split scheme for the camera frustum:
+     * - "uniform": Linear split distribution
+     * - "logarithmic": Logarithmic split distribution (better for large scenes)
+     * - "practical": Hybrid approach balancing quality and performance (recommended)
+     * @default "practical"
+     */
+    mode?: FrustumSplitMode;
+    /**
+     * Lambda parameter for "practical" split mode. Controls the blend between
+     * uniform (0.0) and logarithmic (1.0) split schemes.
+     * @default 0.5
+     */
+    lambda?: number;
+    /**
+     * Defines how far the shadow camera is positioned behind the cascade frustum.
+     * Larger values help prevent shadow clipping but may reduce precision.
+     * @default 200
+     */
+    margin?: number;
+    /**
+     * Enables smooth transitions between shadow cascades to reduce visible seams.
+     * @default true
+     */
+    fade?: boolean;
+    /**
+     * Disables cutting off the last cascade at the far plane, providing better
+     * shadow coverage for distant objects.
+     * @default false
+     */
+    disableLastCascadeCutoff?: boolean;
+};
+
+export declare const cascadedShadowMapsOptionsDefaults: {
+    cascadeCount: number;
+    mapSize: number;
+    far: number;
+    mode: "practical";
+    lambda: number;
+    margin: number;
+    fade: true;
+    disableLastCascadeCutoff: false;
+};
+
+export declare class CSMHelper extends Group {
+    private readonly csm;
+    displayFrustum: boolean;
+    displayPlanes: boolean;
+    displayShadowBounds: boolean;
+    private frustumLines;
+    private cascadeLines;
+    private cascadePlanes;
+    private shadowLines;
+    constructor(csm: CascadedShadowMaps);
+    updateVisibility(): void;
+    update(): void;
+}
+
+declare class FrustumCorners {
+    readonly near: Vector3[];
+    readonly far: Vector3[];
+    constructor();
+    constructor(camera: Camera, far: number);
+    clone(): FrustumCorners;
+    copy(other: FrustumCorners): this;
+    setFromCamera(camera: Camera & {
+        isOrthographicCamera?: boolean;
+    }, far: number): this;
+    split(clipDepths: readonly number[], result?: FrustumCorners[]): FrustumCorners[];
+    applyMatrix4(matrix: Matrix4): this;
+}
+
+export declare type FrustumSplitFunction = (length: number, near: number, far: number, lambda?: number, result?: number[]) => number[];
+
+export declare type FrustumSplitFunctions = {
+    uniform: FrustumSplitFunction;
+    logarithmic: FrustumSplitFunction;
+    practical: FrustumSplitFunction;
+};
+
+export declare const frustumSplitFunctions: FrustumSplitFunctions;
+
+export declare type FrustumSplitMode = keyof FrustumSplitFunctions;
+
+declare class MaterialStates {
+    private readonly map;
+    setup<T extends Material>(material: T, csm: CascadedShadowMaps): T;
+    update(csm: CascadedShadowMaps): void;
+    rollback<T extends Material>(material: T): T;
+    private rollbackToState;
+    dispose(): void;
+}
+
+export declare function overrideFragmentShaderForCSM(fragmentShader: string): string;
+
+export declare function splitFrustum(mode: FrustumSplitMode, count: number, near: number, far: number, lambda?: number, result?: number[]): number[];
+
+export { }