@realsee/five-webgpu 1.0.0-alpha.1

package/five/model/tile3d/trajectory-node.d.ts

@@ -0,0 +1,15 @@
+import * as THREE from 'three/webgpu';
+import type { Camera } from '../../core/camera';
+import type { ModelScene } from '../model-scene';
+import type { ParameterValue } from '../parameter';
+import type { Trajectory } from './trajectory';
+import type { Tile3D } from './index';
+export declare class TrajectoryNode extends THREE.Object3D {
+    name: string;
+    contentObject: THREE.Object3D;
+    private disposers;
+    constructor(name: string, contentObject: THREE.Object3D, disposer?: () => void);
+    update(renderer: THREE.WebGPURenderer, camera: Camera, modelScene: ModelScene, tile3d: Tile3D, trajectory: Trajectory, parameterValue: ParameterValue): boolean;
+    dispose(): void;
+    clone(): this;
+}

package/five/model/tile3d/trajectory.d.ts

@@ -0,0 +1,30 @@
+import * as THREE from 'three/webgpu';
+import type { TrajectoryHeader } from './header';
+import type { TrajectoryNode } from './trajectory-node';
+import type { Tileset } from './tileset';
+export type TrajectoryContentData = {
+    byteLength: number;
+    memoryUsage: number;
+    uri: string;
+    object: TrajectoryNode;
+    positionArray: ArrayLike<number>;
+    timeArray: ArrayLike<number>;
+};
+export declare class Trajectory {
+    id: string;
+    name: string;
+    tileset: Tileset;
+    transform: THREE.Matrix4;
+    visible: boolean;
+    content: {
+        uri: string;
+        data?: TrajectoryContentData;
+        loadState: 'LOADING' | 'UNLOADED' | 'READY' | 'FAILED';
+        loadProgress: number;
+        loadStateUpdateTime: number;
+        loadfailRetryDelay: number;
+        byteLength: number;
+        memoryUsage: number;
+    };
+    constructor(id: string, header: TrajectoryHeader, tileset: Tileset);
+}

package/five/model/tile3d/types.d.ts

@@ -0,0 +1,33 @@
+import * as THREE from 'three/webgpu';
+import type { CullingVolume } from '../../utils/volume';
+export type TileRequestOrder = 'SCREEN_SPACE_ERROR' | 'SCREEN_LEVEL_VERTICAL' | 'SCREEN_VERTICAL';
+export type FrameState = {
+    frameNumber: number;
+    time: number;
+    camera: {
+        type: "PerspectiveCamera" | "OrthographicCamera";
+        position: THREE.Vector3;
+        direction: THREE.Vector3;
+        up: THREE.Vector3;
+        projectionMatrix: THREE.Matrix4;
+        visible: boolean;
+        refine: boolean;
+    };
+    height: number;
+    pixelRatio: number;
+    cullingVolume: CullingVolume;
+    sseDenominator: number;
+    minLevelOfDetail: number;
+    maxLevelOfDetail: number;
+    minGeometricError: number;
+    maxGeometricError: number;
+    skipLevelOfDetail: boolean;
+    mostDetail: boolean;
+    loadSiblings: boolean;
+    cameraCulling: boolean;
+    maxRequests: number;
+    requestOrder: TileRequestOrder;
+    maxScreenSpaceError: number;
+    memoryAdjustedScreenSpaceError: boolean;
+    maxMemoryUsage: number;
+};

package/five/model/view-layer.d.ts

@@ -0,0 +1,20 @@
+import { Tile3D } from './tile3d';
+import { WorkModel } from "../work";
+import { TextureOptions } from "../types/imageOptions";
+import { Fetcher } from "../utils/ajax";
+export interface ViewLayer extends Tile3D {
+}
+export interface ViewLayerInit {
+    tilesetUrl: string;
+    name: string;
+    type: "point_cloud" | "mesh" | "gaussian_splatting";
+    upAxis: string;
+    light: boolean;
+    fetcher: Fetcher;
+}
+export declare function loadViewLayer(init: ViewLayerInit): Promise<ViewLayer>;
+export declare function loadViewLayers(workModel: WorkModel, options: {
+    fetcher: Fetcher;
+    light: boolean;
+    textureOptions?: TextureOptions;
+}): Promise<ViewLayer[]>;

package/five/renderer/compute-renderers/pointcloud-compute-renderer.d.ts

@@ -0,0 +1,154 @@
+import * as THREE from 'three/webgpu';
+import type { PBMPointCloud } from '../../model/objects/pbmPointCloud';
+/**
+ * 基于 Compute Shader 的点云渲染器
+ *
+ * 渲染管线：清除 framebuffer → 计算着色器计算点云 → 全屏四边形显示。
+ * 从调用方接收 GPUDevice（不自行请求 adapter/device）。
+ */
+export declare class PointCloudComputeRenderer {
+    private device;
+    private format;
+    private width;
+    private height;
+    private pointBuffer;
+    private colorBuffer;
+    private normalBuffer;
+    private framebuffer;
+    private frameUniformBuffer;
+    private displayParamsBuffer;
+    private clearPipeline;
+    private rasterizePipeline;
+    private fullscreenQuadPipeline;
+    private clearBindGroup;
+    private rasterizeBindGroup;
+    private displayBindGroup;
+    private pointCount;
+    private static readonly FRAME_UNIFORM_SIZE;
+    private static readonly TILE_UNIFORM_SIZE;
+    private static readonly OFFSET_VIEW_PROJ;
+    private static readonly OFFSET_SCREEN_WIDTH;
+    private static readonly OFFSET_SCREEN_HEIGHT;
+    private static readonly OFFSET_POINT_SIZE_MODE;
+    /** pointAttenPack: mix(-proj[2][3]), scale(2/proj[1][1]), pad, pad */
+    private static readonly OFFSET_POINT_ATTEN_PACK;
+    /** viewZRow: viewMatrix 第三行，用于 mvPosition.z */
+    private static readonly OFFSET_VIEW_Z_ROW;
+    private static readonly OFFSET_POINT_SCALE;
+    private static readonly OFFSET_POINT_MIN_PIXEL;
+    private static readonly OFFSET_POINT_MAX_PIXEL;
+    private static readonly OFFSET_PIXEL_RATIO;
+    private static readonly OFFSET_RESOLUTION_Y;
+    private static readonly OFFSET_POINT_PIXEL_HARD_MAX;
+    private static readonly OFFSET_POINT_SHAPE;
+    /** 与 rasterize.wgsl FrameUniforms 连续布局一致（无 per-tile model/bbox） */
+    private static readonly OFFSET_CAMERA_WORLD;
+    private static readonly OFFSET_CAMERA_FORWARD;
+    private static readonly OFFSET_CONSTANT_COLOR;
+    private static readonly OFFSET_COLOR_GAIN;
+    private static readonly OFFSET_STYLE_PACK;
+    private static readonly OFFSET_FLOOR_PACK;
+    private static readonly OFFSET_CLIP0_INV;
+    private static readonly OFFSET_CLIP0_META;
+    private static readonly OFFSET_CLIP1_INV;
+    private static readonly OFFSET_CLIP1_META;
+    private static readonly OFFSET_TILE_MODEL;
+    private static readonly OFFSET_TILE_BBOX_MIN;
+    private static readonly OFFSET_TILE_BBOX_MAX;
+    private static readonly OFFSET_TILE_PACK;
+    private readonly frameUniformScratch;
+    private readonly tileUniformScratch;
+    private readonly pointSizeUniformState;
+    private placeholderGradientTexture;
+    private placeholderGradientView;
+    private gradientSampler;
+    private fullscreenQuadPipelineAdditive;
+    private ready;
+    /** 同一 compute pass 内避免对 rasterize 管线重复 setPipeline（多 tile 连续 dispatch 时略减开销） */
+    private lastBoundComputePipeline;
+    /**
+     * tile 级 GPU 资源缓存：用强引用 Map 而非 WeakMap，配合 PBMPointCloud.dispose
+     * 派发的 'dispose' 事件主动销毁 buffer，确保 tile 卸载后内存立即归还。
+     */
+    private pointCloudCache;
+    private rasterizeBindGroupCache;
+    private tileUniformBufferCache;
+    /** key = PBMPointCloud；value = 注册到 THREE.EventDispatcher 上的 'dispose' 监听器，用于反注册。 */
+    private tileDisposeListeners;
+    private packedColorScratch;
+    /** GPU 法线 Int8×4 打包 scratch，跨 tile 复用（与 packedColorScratch 同策略）。 */
+    private packedNormalScratch;
+    private readonly tmpVec3a;
+    private readonly tmpVec3b;
+    private readonly tmpVec3c;
+    private readonly tmpVec3d;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    /**
+     * 上传点云数据到 GPU 缓冲区。
+     * 位置按 xyz 紧凑存储（12 字节/点），颜色预打包为 RGB565（4 字节/点）。
+     */
+    setPointCloud(cacheKey: object, positions: Float32Array, colors: Float32Array | Uint8Array, count: number, versions?: {
+        positionsVersion: number;
+        colorsVersion: number;
+    }, rasterResources?: {
+        gradientView: GPUTextureView;
+    }): void;
+    /**
+     * 每帧调用一次：写入共享 frame uniform（viewProj、屏幕、点大小、相机、材质、裁切）。
+     */
+    beginPointCloudFrame(camera: THREE.Camera, representativePc: PBMPointCloud, scratchM4: THREE.Matrix4): void;
+    /** 每 tile 单次 writeBuffer：model、bbox、pointCount、flags。 */
+    writeTileUniform(pc: PBMPointCloud, pointCount: number): void;
+    /** 写入点大小相关参数。 */
+    setPointSizeParams(params: {
+        sizeMode: 'FIXED' | 'ATTENUATION';
+        pointShape: 'SQUARE' | 'CIRCLE';
+        pointScale: number;
+        pointMinPixel: number;
+        pointMaxPixel: number;
+        pixelRatio: number;
+        resolutionY: number;
+        maxDisplayBoost?: number;
+    }): void;
+    /** 占位渐变纹理 view（无梯度图或纹理未上 GPU 时使用）。 */
+    getPlaceholderGradientView(): GPUTextureView;
+    private static tileFlags;
+    /** 与 five vertex.glsl 中 ATTENUATION 分支一致，避免透视/正交 matrixLerp 时 clip.w 失真。 */
+    private writePointAttenuationUniforms;
+    private writeFrameUniformsDataView;
+    private writeTileUniformsDataView;
+    /**
+     * 调整 framebuffer 大小并更新屏幕尺寸 uniform。
+     * 销毁旧 framebuffer，创建新的，并重建 bind groups。
+     */
+    resize(width: number, height: number): void;
+    /** 写入 clear：可并入同一 compute pass，与其它 rasterize dispatch 一起提交。 */
+    encodeFramebufferClear(computePass: GPUComputePassEncoder): void;
+    /** 按当前 bindGroup / pointCount 追加一次 rasterize dispatch（需先 setPointCloud + writeTileUniform）。 */
+    encodeRasterize(computePass: GPUComputePassEncoder): void;
+    encodeFramebufferDisplay(renderPass: GPURenderPassEncoder, options?: {
+        additive?: boolean;
+    }): void;
+    /** 单帧：clear + 多次 rasterize + display，一次 queue.submit（Potree 等多块场景同款思路）。 */
+    submitMergedPointCloudFrame(colorTextureView: GPUTextureView, depthTextureView: GPUTextureView, rasterizeSteps: (computePass: GPUComputePassEncoder) => void, options?: {
+        clear?: boolean;
+        display?: boolean;
+        displayAdditive?: boolean;
+    }): void;
+    /** 销毁所有 GPU 缓冲区。 */
+    dispose(): void;
+    /**
+     * 在 tile 第一次进入 compute 渲染管线时，挂一个 'dispose' 监听到 PBMPointCloud 上。
+     * PBMPointCloud.dispose() 由 tile 调度链路统一调用，无需 tile3d 侧做任何改动。
+     */
+    private registerTileDisposer;
+    /** 释放一个 tile 占用的所有 GPU 资源（per-tile buffers / tile uniform / bind group / 监听）。 */
+    private releaseTileResources;
+    /**
+     * 重建所有引用 framebuffer 和点云数据缓冲区的 bind groups。
+     * 当 framebuffer 和点云数据都可用时，设置 ready = true。
+     */
+    private recreateBindGroups;
+    private ensureTileUniformBuffer;
+    private bindRasterizeGroup;
+}

package/five/renderer/compute-renderers/rgb565.d.ts

@@ -0,0 +1,45 @@
+/**
+ * RGB565 color encoding/decoding utilities for compute shader point cloud rendering.
+ *
+ * RGB565 format: 16 bits total — Red 5 bits (15-11), Green 6 bits (10-5), Blue 5 bits (4-0).
+ * Used in the framebuffer encoding where each pixel is a u32: high 16 bits = depth, low 16 bits = RGB565.
+ */
+/**
+ * Pack normalized RGB [0,1] into a 16-bit RGB565 value.
+ * @param r - Red channel, normalized [0, 1]
+ * @param g - Green channel, normalized [0, 1]
+ * @param b - Blue channel, normalized [0, 1]
+ * @returns RGB565 packed as a u16 number
+ */
+export declare function packRGB565(r: number, g: number, b: number): number;
+/**
+ * Decode an RGB565 packed u16 back to normalized RGB [0,1].
+ * @param packed - RGB565 encoded value
+ * @returns Object with r, g, b channels normalized to [0, 1]
+ */
+export declare function decodeRGB565(packed: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Encode depth [0,1] and RGB [0,1] into a single u32.
+ * High 16 bits = depth quantized to u16, low 16 bits = RGB565 color.
+ * @param depth - Depth value, normalized [0, 1]
+ * @param r - Red channel, normalized [0, 1]
+ * @param g - Green channel, normalized [0, 1]
+ * @param b - Blue channel, normalized [0, 1]
+ * @returns u32 encoded value
+ */
+export declare function encodeDepthColor(depth: number, r: number, g: number, b: number): number;
+/**
+ * Decode a u32 encoded with encodeDepthColor back to depth + RGB.
+ * @param encoded - u32 value encoded by encodeDepthColor
+ * @returns Object with depth and r, g, b channels normalized to [0, 1]
+ */
+export declare function decodeDepthColor(encoded: number): {
+    depth: number;
+    r: number;
+    g: number;
+    b: number;
+};

package/five/renderer/compute-renderers/shaders/clear.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/shaders/fullscreenQuad.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/shaders/rasterize.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/five-renderer.d.ts

@@ -0,0 +1,33 @@
+import * as THREE from 'three/webgpu';
+import { type Scene } from '../core/scene';
+import { type Camera } from '../core/camera';
+import { type OutputTextureDataType } from '../core/internalWebGPURenderer';
+import { type ModelScene } from '../model';
+import { EffectComposer } from './postprocessing/composer';
+export declare class FiveRenderer {
+    renderMode: string;
+    composer: EffectComposer;
+    composerVersion: string;
+    outputType: OutputTextureDataType;
+    private sceneRenders;
+    private computeRenderer;
+    private useComputePointCloud;
+    private compositeRenderTarget;
+    private lastWidth;
+    private lastHeight;
+    private readonly gpuTextureViewCache;
+    constructor(options: {
+        outputType?: OutputTextureDataType;
+    });
+    render(renderer: THREE.WebGPURenderer, scene: Scene, modelScene: ModelScene, camera: Camera, sceneUpdated: boolean): boolean;
+    /** 将场景（点云 compute pass + three 场景）合成到 `compositeRenderTarget`。 */
+    private renderSceneToComposite;
+    /**
+     * WebGPU 路径：Compute Shader 光栅化点云 → 再渲染 three 场景叠加。
+     * 点云本身是 Mesh，需在 three 渲染阶段临时隐藏，避免被 NodeMaterial 重复绘制。
+     */
+    private renderPointCloudCompute;
+    dispose(): void;
+    private getCompositeTargetViews;
+    private getCachedGpuTextureView;
+}

package/five/renderer/index.d.ts

@@ -0,0 +1,3 @@
+export { EffectComposer, FivePass, type Pass, AdaptiveLuminancePass, EyeDomeLightingPass, FlowingLight2DPass, type FlowingLight2DPassLine, FlowingLight3DPass, type FlowingLight3DPassLine, GaussianBlurPass, FlowingFireworks3DPass, type FlowingFireworks3DPassLine, } from './postprocessing';
+export { FullScreenQuad } from './tools/full-screen-quad';
+export { FiveRenderer } from './five-renderer';

package/five/renderer/postprocessing/composer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @author alteredq / http://alteredqualia.com/
+ * WebGPU 版本，基于 three.js 的 EffectComposer 设计。
+ */
+import * as THREE from 'three/webgpu';
+import { type Pass } from './passes/pass';
+import { type OutputTextureDataType } from '../../core/internalWebGPURenderer';
+import { Clock } from '../../utils/clock';
+/**
+ * EffectComposer（WebGPU）
+ *
+ * 用于管理后处理 pass 的渲染流程。使用两个 RenderTarget 做 ping-pong，
+ * 与 three.js 的 Pass（RenderPass 写入 readBuffer）保持兼容。
+ */
+export declare class EffectComposer {
+    outputType: OutputTextureDataType;
+    renderTarget1: THREE.RenderTarget;
+    renderTarget2: THREE.RenderTarget;
+    writeBuffer: THREE.RenderTarget;
+    readBuffer: THREE.RenderTarget;
+    passes: Pass[];
+    normalMaterial: THREE.MeshNormalMaterial;
+    clock: Clock;
+    renderToScreen: boolean;
+    status: {
+        endabledPassNumber: number;
+        needsColorGBuffer: boolean;
+        needsDepthGBuffer: boolean;
+        needsNormalGBuffer: boolean;
+        version: string;
+    };
+    /** G-Buffer 纹理集合，由 FiveRenderer 注入。 */
+    gbuffer: Map<'depth' | 'normal' | 'color', THREE.Texture>;
+    constructor(options: {
+        outputType?: OutputTextureDataType;
+    });
+    swapBuffers(): void;
+    addPass(pass: Pass): void;
+    insertPass(pass: Pass, index: number): void;
+    removePass(pass: Pass): void;
+    render(renderer: THREE.WebGPURenderer): boolean;
+    setSize(width: number, height: number): void;
+    updateStatus(): void;
+    dispose(): void;
+}

package/five/renderer/postprocessing/index.d.ts

@@ -0,0 +1,8 @@
+export { EffectComposer } from './composer';
+export { type Pass, FivePass } from './passes/pass';
+export { AdaptiveLuminancePass } from './passes/adaptive-luminance-pass';
+export { EyeDomeLightingPass } from './passes/eye-dome-lighting-pass';
+export { GaussianBlurPass } from './passes/gaussian-blur-pass';
+export { FlowingLight2DPass, type FlowingLight2DPassLine } from './passes/flowing-light-2d-pass';
+export { FlowingLight3DPass, type FlowingLight3DPassLine } from './passes/flowing-light-3d-pass';
+export { FlowingFireworks3DPass, type FlowingFireworks3DPassLine } from './passes/flowing-fireworks-3d-pass';

package/five/renderer/postprocessing/passes/adaptive-luminance-pass.d.ts

@@ -0,0 +1,27 @@
+import * as THREE from 'three/webgpu';
+import { FivePass } from './pass';
+/**
+ * AdaptiveLuminancePass（WebGPU / TSL）
+ *
+ * 统计画面亮度直方图并平滑地把亮度通道映射到目标区间，实现自适应曝光/对比拉伸。
+ *
+ * 说明：WebGPU 不支持同步回读，这里使用 `readRenderTargetPixelsAsync` 做异步回读。
+ * 直方图统计存在约 1 帧延迟，min/max 每帧向目标值平滑步进，视觉上无感。
+ */
+export declare class AdaptiveLuminancePass extends FivePass {
+    maxMinValue: number;
+    minMaxValue: number;
+    valueStep: number;
+    sampleTestScale: number;
+    private histogram;
+    private minValue;
+    private maxValue;
+    private targetMin;
+    private targetMax;
+    private readbackPending;
+    private luminanceSampleTarget?;
+    constructor();
+    render(renderer: THREE.WebGPURenderer, writeBuffer: THREE.RenderTarget, readBuffer: THREE.RenderTarget, deltaTime?: number, maskActive?: boolean): void;
+    clearBuffer(): void;
+    dispose(): void;
+}

package/five/renderer/postprocessing/passes/eye-dome-lighting-pass.d.ts

@@ -0,0 +1,31 @@
+import * as THREE from 'three/webgpu';
+import { FivePass } from './pass';
+import { type Camera } from '../../../core/camera';
+/**
+ * EyeDomeLightingPass（WebGPU / TSL）
+ *
+ * 基于深度的边缘增强（EDL），常用于点云可视化，突出深度不连续处的轮廓。
+ * 依赖 G-Buffer 的 depth 纹理。
+ */
+export declare class EyeDomeLightingPass extends FivePass {
+    strength: number;
+    radius: number;
+    neighbours: number;
+    private camera;
+    private fsQuad;
+    private material;
+    private uStrength;
+    private uRadius;
+    private uResolution;
+    private uCameraNear;
+    private uCameraFar;
+    private uPerspToOrtho;
+    private depthMap;
+    private colorMap;
+    private uFlipY;
+    private builtNeighbours;
+    constructor(camera: Camera);
+    private buildMaterial;
+    render(renderer: THREE.WebGPURenderer, writeBuffer: THREE.RenderTarget, readBuffer: THREE.RenderTarget, deltaTime?: number, maskActive?: boolean): void;
+    dispose(): void;
+}

package/five/renderer/postprocessing/passes/flowing-fireworks-3d-pass.d.ts

@@ -0,0 +1,71 @@
+import * as THREE from 'three/webgpu';
+import { FivePass } from './pass';
+import { type Camera } from '../../../core/camera';
+export type FlowingFireworks3DPassLine = {
+    id?: string;
+    points: THREE.Vector3[];
+    totalLength: number;
+    color: THREE.Color;
+    opacity?: number;
+    tailLengthRatio?: number;
+    duration?: number;
+    startTime?: number;
+    particleCount?: number;
+    emissionRate?: number;
+    spread?: number;
+    particleSize?: number;
+    particleLife?: number;
+    gravity?: THREE.Vector3;
+    leadRatio?: number;
+};
+/**
+ * FlowingFireworks3DPass（WebGPU / TSL）
+ *
+ * 与 FlowingLight3DPass 配套：在每条流光线条的「尾部位置」持续喷射向四周发散的
+ * 烟花状粒子。WebGPU 下点图元固定 1px，这里改用实例化四边形（billboard）绘制粒子，
+ * 运动积分与尺寸/淡出在 GPU 上完成，发射逻辑在 CPU 上完成，功能对齐 WebGL 版本。
+ */
+export declare class FlowingFireworks3DPass extends FivePass {
+    private camera;
+    private mesh;
+    private material;
+    private uTime;
+    private lines;
+    private blocks;
+    private geometry;
+    private arrPosition;
+    private arrVelocity;
+    private arrAccel;
+    private arrColor;
+    private arrParams;
+    private particleScene;
+    private orthoCamera;
+    private particleRenderTarget;
+    private blendMaterial;
+    private blendQuad;
+    private _tmpTail;
+    private uUniformTime;
+    private uResolution;
+    private uProj;
+    private uView;
+    private uBase;
+    private uParticle;
+    private uFlipBase;
+    private uFlipParticle;
+    constructor(camera: Camera);
+    private createParticleMaterial;
+    private createBlendMaterial;
+    setLines(lines: FlowingFireworks3DPassLine[]): void;
+    addLine(...lines: FlowingFireworks3DPassLine[]): string[];
+    removeLine(...ids: string[]): number;
+    setLine(params: {
+        id: string;
+    } & Partial<Omit<FlowingFireworks3DPassLine, 'id'>>): void;
+    private _rebuild;
+    private _samplePointAtLength;
+    private _emitParticle;
+    private _emit;
+    render(renderer: THREE.WebGPURenderer, writeBuffer: THREE.RenderTarget, readBuffer: THREE.RenderTarget, deltaTime?: number, maskActive?: boolean): void;
+    private _disposeParticles;
+    dispose(): void;
+}

package/five/renderer/postprocessing/passes/flowing-light-2d-pass.d.ts

@@ -0,0 +1,26 @@
+import * as THREE from 'three/webgpu';
+import { FlowingLight3DPass } from './flowing-light-3d-pass';
+import { type Camera } from '../../../core/camera';
+export type FlowingLight2DPassLine = {
+    id?: string;
+    points: THREE.Vector2[];
+    totalLength: number;
+    color: THREE.Color;
+    opacity?: number;
+    duration?: number;
+    lineWidth?: number;
+    tailLengthRatio?: number;
+    startTime?: number;
+};
+/**
+ * FlowingLight2DPass（WebGPU / TSL）
+ *
+ * 在 3D 流光基础上增加 2D 分支：当线段两端 z 为标记值时，
+ * 直接使用归一化屏幕坐标（[0,1]，y 向下）绘制，用于 HUD/贴屏流光。
+ */
+export declare class FlowingLight2DPass extends FlowingLight3DPass<FlowingLight2DPassLine> {
+    constructor(camera: Camera);
+    /** 将 2D 归一化坐标点转为内部 vec3（z = MARKER_Z） */
+    protected toInternalPoints(points: THREE.Vector2[]): THREE.Vector3[];
+    protected createLineMaterial(): THREE.NodeMaterial;
+}

package/five/renderer/postprocessing/passes/flowing-light-3d-pass.d.ts

@@ -0,0 +1,75 @@
+import * as THREE from 'three/webgpu';
+import { FivePass } from './pass';
+import { FullScreenQuad } from '../../tools/full-screen-quad';
+import { type Camera } from '../../../core/camera';
+export type FlowingLight3DPassLine = {
+    id?: string;
+    points: THREE.Vector3[];
+    totalLength: number;
+    color: THREE.Color;
+    opacity?: number;
+    duration?: number;
+    lineWidth?: number;
+    tailLengthRatio?: number;
+    startTime?: number;
+};
+/** 流光线条的通用输入形状（2D/3D 共用），points 元素类型由子类细化 */
+export type FlowingLightLineInput = {
+    id?: string;
+    points: any[];
+    totalLength: number;
+    color: THREE.Color;
+    opacity?: number;
+    duration?: number;
+    lineWidth?: number;
+    tailLengthRatio?: number;
+    startTime?: number;
+};
+/**
+ * FlowingLight3DPass（WebGPU / TSL）
+ *
+ * 使用实例化四边形在屏幕空间绘制 3D 流光线段，随时间沿路径流动，
+ * 通过加法混合叠加到 readBuffer 上。功能对齐 WebGL 版本。
+ *
+ * 泛型 `L` 表示外部输入的线条类型（默认与内部存储一致）；
+ * 子类（如 2D）可指定不同的 `points` 类型并通过 `toInternalPoints` 转换。
+ */
+export declare class FlowingLight3DPass<L extends FlowingLightLineInput = FlowingLight3DPassLine> extends FivePass {
+    protected camera: Camera;
+    protected mesh: THREE.Mesh | null;
+    protected material: THREE.NodeMaterial;
+    protected uTime: number;
+    protected lines: FlowingLight3DPassLine[];
+    protected lineScene: THREE.Scene;
+    protected orthoCamera: THREE.OrthographicCamera;
+    protected lineRenderTarget: THREE.RenderTarget;
+    protected blendMaterial: THREE.NodeMaterial;
+    protected blendQuad: FullScreenQuad;
+    protected uUniformTime: THREE.UniformNode<"float", number>;
+    protected uResolution: THREE.UniformNode<"vec2", THREE.Vector2>;
+    protected uProj: THREE.UniformNode<"mat4", THREE.Matrix4>;
+    protected uView: THREE.UniformNode<"mat4", THREE.Matrix4>;
+    private uBase;
+    private uLine;
+    private uFlipBase;
+    private uFlipLine;
+    constructor(camera: Camera);
+    protected createLineMaterial(): THREE.NodeMaterial;
+    protected createBlendMaterial(): THREE.NodeMaterial;
+    /** 将外部 points 转为内部 Vector3[]（默认恒等，子类可覆盖，如 2D 注入标记 z） */
+    protected toInternalPoints(points: L['points']): THREE.Vector3[];
+    /** 将外部线条转为内部线条（Vector3 points） */
+    protected toInternalLine(line: L): FlowingLight3DPassLine;
+    setLines(lines: L[]): void;
+    addLine(...lines: L[]): string[];
+    removeLine(...ids: string[]): number;
+    setLine(params: {
+        id: string;
+    } & Partial<Omit<L, 'id'>>): void;
+    protected _updateLineAttributes(lineIndex: number, newLine: FlowingLight3DPassLine, oldLine: FlowingLight3DPassLine): void;
+    protected _buildGeometryFromLines(): THREE.InstancedBufferGeometry | null;
+    protected _rebuildMesh(): void;
+    render(renderer: THREE.WebGPURenderer, writeBuffer: THREE.RenderTarget, readBuffer: THREE.RenderTarget, deltaTime?: number, maskActive?: boolean): void;
+    protected _disposeMesh(): void;
+    dispose(): void;
+}

package/five/renderer/postprocessing/passes/gaussian-blur-pass.d.ts

@@ -0,0 +1,22 @@
+import * as THREE from 'three/webgpu';
+import { FivePass } from './pass';
+import { type Camera } from '../../../core/camera';
+/**
+ * GaussianBlurPass（WebGPU / TSL）
+ *
+ * 对 readBuffer 做各向同性高斯模糊。半径与 sigma 可运行时调整。
+ */
+export declare class GaussianBlurPass extends FivePass {
+    private camera;
+    private fsQuad;
+    material: THREE.NodeMaterial;
+    private uResolution;
+    private uRadius;
+    private uSigma;
+    private colorMap;
+    constructor(camera: Camera);
+    render(renderer: THREE.WebGPURenderer, writeBuffer: THREE.RenderTarget, readBuffer: THREE.RenderTarget, deltaTime?: number, maskActive?: boolean): void;
+    setRadius(radius: number): void;
+    setSigma(sigma: number): void;
+    dispose(): void;
+}