@realsee/five-webgpu 1.0.0-alpha.4 → 1.0.0-alpha.6

package/five/model/objects/pbmGaussianSplattingRenderMesh.d.ts

@@ -1,9 +1,9 @@
 import * as THREE from 'three/webgpu';
 import { PBMGaussianSplattingNodeMaterial } from '../materials/pbmGaussianSplattingNodeMaterial';
 /**
- * 3DGS 渲染 Mesh（WebGPU / TSL 版，纯 CPU 数据准备）
+ * 3DGS 渲染 Mesh（WebGPU / TSL 版）
  *
- * 主循环用四个协作者准备数据（**无任何 compute shader**）：
+ * 主循环用四个协作者准备数据：
  *   - `SplatAssembler`：per-object region 增量 diff + **CPU 拼装** 大数据纹理
  *     （把各对象 packedData 紧凑拷进 CPU 缓冲，写 transformIndex/layerIndex 到 texel1.w；
  *     经 THREE.DataTexture 上传供主材质采样）
@@ -15,11 +15,14 @@ import { PBMGaussianSplattingNodeMaterial } from '../materials/pbmGaussianSplatt
  * 索引顺序 ≡ `SHStore` 写入顺序。四个协作者都从**同一有序 `objects` 数组、同一顺序**同步，
  * 因此不会产生 transformIndex / SH 错位；`onBeforeRender` 中另加防御性一致性断言兜底。
  *
- * 排序：把 `SplatAssembler.extractSortInputs()`（世界坐标 + transformIndex）与
- * `TransformStore.transforms`（20 float/对象）喂给 Sort_Worker，回传的 `depthIndex`
- * 保存为 `orderData`。每帧（order 或布局变化时）在 **CPU 端** 用「旧布局→当前布局」段表
- * 把 orderData remap 到当前布局，紧凑写入 `splatIndex` 实例属性，材质用 `splatIndex` 取点驱动
- * instanced draw（tile 增删布局变化时保持排序与大纹理映射一致、不闪烁）。
+ * 排序：本类**不再自己排序**。排序、绘制索引来源与绘制实例数一律经 `GSplatPipeline` 抽象基类
+ * 消费（Requirement 10.2）：
+ *   - `RASTER_CPU_SORT`（`CpuSortPipeline`）：wasm worker 排序 + Reorder_CPU，索引来自
+ *     `splatIndex` 实例属性；
+ *   - `RASTER_GPU_SORT`（`GpuSortPipeline`）：GPU radix sort，索引来自 R32UI Order_Texture。
+ * 「本帧是否需要排序」由 `SortThrottle` 判定（相机小平移 / 小角度 / min-interval 门），
+ * 与管线实现无关，两条路径的节流行为完全一致。管线按 `pipelineMode` 解析结果整体切换，
+ * 本类不引用 Sort_Worker、排序模块或任何 WebGPU 资源。
  *
  * 大数据纹理：
  *   - `SplatAssembler` 在对象集合变化时在 **CPU** 端把各对象 packedData 紧凑拼进一张
@@ -36,100 +39,61 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
     private transformStore;
     private layerRegistry;
     private shStore;
-    private sortWorker;
+    /**
+     * 当前生效的排序管线。由 `syncPipelineMode` 按 Current_Pipeline_Mode 创建 / 重建，
+     * 尚未创建（首帧之前）时为 null。
+     */
+    private pipeline;
+    /** 排序节流器：判定本 Render_Frame 是否需要调用 `pipeline.requestSort`。 */
+    private throttle;
+    /** Requested_Pipeline_Mode（外部经 `pipelineMode` 写入，下一帧生效）。 */
+    private _requestedPipelineMode;
+    /**
+     * Current_Pipeline_Mode（`resolvePipelineMode` 的解析结果，永不为 `AUTO`）。
+     * 初值取 CPU 排序：管线未创建前对外报告最保守的取值。
+     */
+    private _activePipelineMode;
+    /**
+     * 创建当前 `pipeline` 时所用的渲染器。渲染器只能从 `onBeforeRender` 拿到，因此管线在首帧
+     * 才创建；若本 Mesh 被挂到另一个渲染器上（renderer 身份变化），管线持有的 device 资源不再
+     * 有效，需连同模式一起重建。
+     */
+    private _pipelineRenderer;
+    /**
+     * 传给管线的每帧参数。**跨帧复用同一个对象**（Requirement 10.7），每帧填字段后传入，
+     * 不在渲染循环里新建。`camera` 由每帧填充，构造时无值。
+     */
+    private _frameParams;
     /**
      * 大纹理待组装标记：tile 集合变化（rebuildScene）时置 true；onBeforeRender 中即调用
      * `assembler.assemble()`（CPU 拼装 + DataTexture 上传）并清除。相机移动帧不置位（不重组装）。
      */
     private assemblePending;
-    /** splatIndex 实例属性的当前容量（点数）；不足时按 2 的幂扩容。 */
-    private splatIndexCapacity;
-    /** 单调递增的排序请求代；每代记录其所基于的布局快照，回传时按代取回（防异步错配）。 */
-    private sortGeneration;
-    /** 当前排序输入是否已上传给 worker（场景/transform 变化时置 false 触发重传）。 */
-    private sortDataUploaded;
-    /** 排序输入（布局 / transform）自上次上传后是否已变化——脏则强制重排并重传。 */
-    private sortInputsDirty;
     private forceClipperUniformRefresh;
+    private usedSHDegree;
+    constructor();
     /**
-     * Sort_Worker 是否已进入不可恢复的失败态（WASM 加载失败）。一旦置位，Render_Mesh
-     * 持续降级为空绘制（instanceCount=0），不再尝试消费排序结果（Requirement 18.1）。
-     */
-    private sortWorkerFailed;
-    /** 当前 order 长度（= 最近一次排序回传的 depthIndex 长度 = 该次排序时 vertexCount）。 */
-    private orderCount;
-    /**
-     * 最近一次排序回传的 depthIndex 副本（基于 orderBaseSnapshot 布局的全局点索引 P 的排列）。
-     * 作为 CPU reorder 的输入源：`applyReorderCPU` 用「orderBaseSnapshot → 当前布局」段表把它
-     * remap 到当前布局，紧凑写入 splatIndex 实例属性，从而在 tile 增删（布局变化）时保持排序与
-     * 大纹理映射一致、不闪烁。
+     * Requested_Pipeline_Mode（`GSPLAT_PIPELINE_*`）。写入后在**下一帧**由
+     * `syncPipelineMode` 解析并按需重建管线，便于开发期在同场景下对比两条管线
+     * （Requirement 13.2）。
      */
-    private orderData;
-    /** order 内容变化（新排序回传）→ 需重跑 CPU reorder。 */
-    private orderDirty;
-    /** 布局变化（LOD 增删 / 场景重建）→ 需以新布局（新段表）重跑 CPU reorder。 */
-    private layoutDirty;
-    /** 当前存活实例数（= 最近一次 applyReorderCPU 写入 splatIndex 的点数）。 */
-    private aliveCount;
-    /** 当前 order 所基于的布局快照（= 该次排序发起时的布局）。 */
-    private orderBaseSnapshot;
-    /** generation → 该次排序发起时的布局快照。 */
-    private snapshotByGen;
-    private prevSortCameraMatrix;
+    get pipelineMode(): number;
+    set pipelineMode(value: number);
+    /** 实际生效的 Current_Pipeline_Mode（解析后的结果，永不为 `AUTO`）。 */
+    get currentPipelineMode(): number;
     /** 平移增量阈值（世界单位）：超过才重排。 */
-    sortCameraDistance: number;
+    get sortCameraDistance(): number;
+    set sortCameraDistance(value: number);
     /** 姿态相似度阈值（|quat 点积|）：低于才重排（0.99 ≈ 约 16° 内不重排）。 */
-    sortCameraCoorient: number;
+    get sortCameraCoorient(): number;
+    set sortCameraCoorient(value: number);
     /** 最小重排间隔（ms）：即使脏也不超过此频率，0=不限。 */
-    sortMinIntervalMs: number;
-    private sortLastTime;
-    private _scratchViewProj;
-    private usedSHDegree;
-    constructor();
+    get sortMinIntervalMs(): number;
+    set sortMinIntervalMs(value: number);
     private createGeometry;
-    /**
-     * 确保 splatIndex 实例属性容量 >= requiredCount；不足时按 2 的幂扩容（保留旧内容）。
-     * 返回当前（可能是新建的）属性。
-     */
-    private ensureSplatIndexCapacity;
     private createMaterial;
     private createDefaultLayerClipperRanges;
     private createDefaultClipperMatrices;
-    /**
-     * 应用排序结果：
-     *   1. 保存 depthIndex 副本到 `orderData`（作为 CPU reorder 的输入源；实际 remap 在
-     *      onBeforeRender 中由 applyReorderCPU 完成，此处不写 splatIndex）。
-     *   2. 置 orderDirty（新排序回传 → 需重跑 CPU reorder）。
-     *   3. 按 generation 取回该次排序真正基于的布局快照，作为 reorder 基准，并清理更旧快照
-     *      （worker 结果按 generation 单调返回，更旧快照不会再用到）。
-     * 保证：每次回传的 depthIndex 恒为「该代排序时 totalPoints」的一个排列，点数守恒。
-     */
-    private applyDepthIndex;
-    /** 捕获当前布局：assembler.regions 的 {object, start, count}（顺序即全局点区间顺序）。 */
-    private snapshotLayout;
-    /**
-     * 用「排序时旧布局 → 当前布局」构造 reorder 段表：
-     *   - 存活对象：{ oldStart, oldEnd, delta = 当前 start - 旧 start, removed: false }
-     *   - 被删对象：{ oldStart, oldEnd, delta: 0, removed: true }
-     * 段按 oldStart 升序（base 已按 start 升序）、区间不重叠；相邻同类段（同 removed 且
-     * removed 或 delta 相同、且首尾相接）合并以压低段数（供 applyReorderCPU 二分查找）。
-     */
-    private buildSegments;
-    /**
-     * 二分查找覆盖全局点索引 P 的段（段按 oldStart 升序、区间 [oldStart,oldEnd) 连续无重叠）。
-     * 找不到（P 越界，理论上不会发生）返回 null。
-     */
-    private findSegment;
-    /**
-     * CPU reorder：把最近一次排序回传的 depthIndex（orderData，基于 orderBaseSnapshot 旧布局的
-     * 全局点索引 P 的排列）用「旧布局 → 当前布局」段表 remap 到当前布局，紧凑写入 splatIndex 实例属性：
-     *   - 存活对象点 P → 写入 P + delta；
-     *   - 被删对象点（removed）→ 跳过（不写，实例数不计）。
-     * 从而在 tile 增删（布局变化）时保持排序顺序与大纹理映射一致、不闪烁（等价 five 的 ReorderPass）。
-     * 结果实例数写入 `geometry.instanceCount`（= 存活点数 n）。material.numPoints 设为当前布局总点数
-     * 作 shader 端 P>=numPoints 的保护性剔除（正常情况下存活区都 < numPoints）。
-     */
-    private applyReorderCPU;
     private collectObjects;
     private isSceneNeedsRebuild;
     private getClipperHash;
@@ -142,8 +106,8 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
     /**
      * 场景变化时按**同一有序 objects**依次同步四个协作者，保证布局三一致：
      * layerRegistry / transformStore 先行（assembler 的 resolveIndices 依赖二者的 indexOf/layerIndexOf），
-     * 再 assembler.sync（增量 diff + 连续 start 偏移，不触碰 GPU）→ shStore.sync；大纹理 GPU 组装
-     * 延迟到 onBeforeRender 中 device 就绪时的 assembler.assemble(device)。
+     * 再 assembler.sync（增量 diff + 连续 start 偏移，不触碰 GPU）→ shStore.sync；大纹理组装
+     * 延迟到 onBeforeRender 中的 assembler.assemble()。
      */
     private rebuildScene;
     /**
@@ -151,21 +115,23 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
      * 四者由 rebuildScene 从同一 objects 同序同步，正常情况下恒成立；不成立即视为错误状态并告警。
      */
     private assertLayoutConsistency;
-    /**
-     * 把排序输入喂给 Sort_Worker：位置 + transformIndex 来自 assembler.extractSortInputs()，
-     * 变换矩阵来自 transformStore.transforms（20 float/对象，与 sort.cpp `_sort` 步长一致）。
-     * 每次上传 ++generation，回传时据此丢弃过期结果。
-     */
-    private postSortData;
-    /**
-     * 是否需要重排：
-     *   - 排序输入脏（布局 / transform 变化）或尚未上传过 → 强制重排；
-     *   - 否则比较相机相对「上次排序时快照」的平移 / 姿态增量，均小于阈值则跳过（小角度节流）。
-     */
-    private shouldSort;
-    private requestSort;
     /** 把 store 产出的纹理与 SH 阶数同步到材质。 */
     private syncMaterialTextures;
+    /**
+     * 每帧一次的 Pipeline_Mode 检查与管线切换（Requirement 8.2）。
+     *
+     * 之所以每帧检查而非首帧一次性初始化：`pipelineMode` 的运行时修改要在下一帧生效
+     * （Requirement 8.6 / 13.2），且 `totalPoints` 增长导致 limits 越界、或 GPU 管线运行期失效
+     * （compute pipeline 创建失败 / device lost，经 `unusable` 汇聚）时都要能自动降级。
+     * 所有降级情形统一归结为「`resolvePipelineMode` 返回 `RASTER_CPU_SORT`」后由本方法完成切换
+     * （Requirement 15.4），因此不存在第二条降级代码路径。
+     *
+     * 模式未变且管线已就绪时只做一次整数比较即返回，开销可忽略（Requirement 8.10）。
+     *
+     * @param renderer 本帧渲染器（由 `onBeforeRender` 传入，是取 `GPUDevice` 的唯一入口）
+     * @param totalPoints 当前布局的 Total_Points，用于按实际规模检查 limits
+     */
+    private syncPipelineMode;
     onBeforeRender: (renderer: any, scene: THREE.Scene, camera: THREE.Camera, ..._rest: any[]) => void;
     dispose(): void;
 }

package/five/model/parameter.d.ts

@@ -1,5 +1,5 @@
 import * as THREE from 'three/webgpu';
-import { type PBMPanoPicture, type PBMPanoDepth, type PBMRefinedScreen, type PBMTransition, type PBMFloorStyle, type PBMRoofStyle, type PBMColorStyle, type PBMClipperParameter, type PBMPanoFilter, type PBMPointShape, type PBMPointSize, type PBMPointBack } from './materials/pbmMaterial';
+import { type PBMPanoPicture, type PBMPanoDepth, type PBMRefinedScreen, type PBMTransition, type PBMFloorStyle, type PBMRoofStyle, type PBMColorStyle, type PBMClipperParameter, type PBMPanoFilter, type PBMPointShape, type PBMPointSize, type PBMPointBack, type PBMCustomNode } from './materials/pbmMaterial';
 import type { TileRequestOrder } from './tile3d/types';
 import type { Camera } from '../core/camera';
 export interface ParameterMaterialValue {
@@ -80,6 +80,13 @@ export interface ParameterMaterialValue {
     /** 3dgs球谐阶数*/
     gaussianSplattingSHDegree: number;
     maxDisplayBoost: number;
+    /** 自定义节点列表（TSL Node 级别的材质扩展） */
+    customNodes: readonly PBMCustomNode[];
+    /**
+     * 自定义节点 uniform 的脏计数器（内部维护，无需手动设置）。
+     * 任一 customNode emit('update') 时自动递增，用于触发材质刷新。
+     */
+    customNodesVersion: number;
 }
 export interface ParameterTilesetValue {
     /** 模型显示最小细化层级 */
@@ -132,6 +139,11 @@ export declare class Parameter {
     resolveValue<K extends keyof ParameterValue>(name: K, ...values: Partial<ParameterValue>[]): ParameterValue[K];
     resolveValue(...baseValues: Partial<ParameterValue>[]): ResolvedParameterValue;
     private assignValue;
+    /**
+     * 递增 customNodesVersion 并 bump 参数版本，促使模型重新下发参数、
+     * 令 NodeMaterialObserver 检测到 customNodesVersion 变化而刷新（上传 customNode 的 uniform）。
+     */
+    private bumpCustomNodesVersion;
     set<T extends keyof ParameterValue>(name: T, value: ParameterValue[T]): this;
     set(values: Partial<ParameterValue>): this;
     reset(...names: (keyof ParameterValue)[]): this;

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

@@ -73,6 +73,8 @@ export declare class Tile3D extends THREE.Object3D {
     loadContent(tile: Tile): Promise<void>;
     unloadContent(tile: Tile): Promise<void>;
     loadAllTilesets(): Promise<void>;
+    loadTrajectory(trajectory: Trajectory): Promise<void>;
+    unloadTrajectory(trajectory: Trajectory): Promise<void>;
     intersectRaycaster(raycaster: THREE.Raycaster, target?: Intersection[]): Intersection[];
     update(renderer: THREE.WebGPURenderer, camera: Camera, modelScene: ModelScene, model: Model): boolean;
     dispose(): void;

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

@@ -12,6 +12,11 @@ export interface TilesetOptions {
     onTileLoad: (tile: Tile) => any;
     onTileUnload: (tile: Tile) => any;
     onTileError: (tile: Tile, error: Error) => any;
+    trajectoryLoader: (trajectory: Trajectory) => Promise<void>;
+    trajectoryUnloader: (trajectory: Trajectory) => Promise<void>;
+    onTrajectoryLoad: (trajectory: Trajectory) => any;
+    onTrajectoryUnload: (trajectory: Trajectory) => any;
+    onTrajectoryError: (trajectory: Trajectory, error: Error) => any;
 }
 export declare class Tileset {
     asset: {

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

@@ -0,0 +1,53 @@
+import * as THREE from 'three/webgpu';
+import type { Trajectory } from './trajectory';
+import { Fetcher } from '../../utils/ajax';
+/**
+ * 轨迹的两套自定义着色器原为 GLSL `ShaderMaterial`，WebGPURenderer 只支持 NodeMaterial
+ * （其它材质类型会被退化成空白 NodeMaterial），这里按 GLSL 逐层翻译为 TSL：
+ *
+ * 管道 TRAJECTOR_PIPE：
+ *   vertex:   `vUv = uv;` + `transformed += normalize(objectNormal) * displacementScalar`
+ *   fragment: `if (mod(abs(vUv.x * totalLength + dashOffset), dashSize.x + dashSize.y) > dashSize.x) discard;`
+ *             `vec4 diffuseColor = vec4(mix(diffuse, diffuse2, vUv.x), opacity);`
+ * 圆球 TRAJECTOR_SPHERE：
+ *   vertex:   `transformed += normalize(objectNormal) * displacementScalar`
+ *   fragment: `vec4 diffuseColor = vec4(diffuse, opacity);`
+ *
+ * 说明：
+ * - 原 shader 里的 `<tonemapping_fragment>` / `<colorspace_fragment>` 由渲染器的 Output 通道统一处理
+ *   （WebGPURenderer 把 tone mapping 与输出色彩空间放到独立的输出 pass），<fog_fragment> /
+ *   `<premultiplied_alpha_fragment>` 对应 NodeMaterial 的 `fog` / `premultipliedAlpha` 属性（默认 fog 生效）。
+ * - 颜色不再调用 `convertSRGBToLinear()`：r152+ 的 `new THREE.Color(hex)` 已经按 sRGB 解释并转到线性工作空间，
+ *   再转换一次会变暗。
+ * - `uniform()` 生成的 uniform 节点保留 `.value` 读写，所以材质上挂的 `uniforms` 与 GLSL 版本用法一致
+ *   （见 trajectory-node.ts 的 dashOffset 动画）。
+ */
+declare function createPipeUniforms(): {
+    diffuse: THREE.UniformNode<"color", THREE.Color>;
+    diffuse2: THREE.UniformNode<"color", THREE.Color>;
+    opacity: THREE.UniformNode<"float", number>;
+    displacementScalar: THREE.UniformNode<"float", number>;
+    totalLength: THREE.UniformNode<"float", number>;
+    dashSize: THREE.UniformNode<"vec2", THREE.Vector2>;
+    dashOffset: THREE.UniformNode<"float", number>;
+};
+declare function createSphereUniforms(): {
+    diffuse: THREE.UniformNode<"color", THREE.Color>;
+    opacity: THREE.UniformNode<"float", number>;
+    displacementScalar: THREE.UniformNode<"float", number>;
+};
+export type TrajectoryPipeUniforms = ReturnType<typeof createPipeUniforms>;
+export type TrajectorySphereUniforms = ReturnType<typeof createSphereUniforms>;
+export type TrajectoryPipeMaterial = THREE.NodeMaterial & {
+    uniforms: TrajectoryPipeUniforms;
+};
+export type TrajectorySphereMaterial = THREE.NodeMaterial & {
+    uniforms: TrajectorySphereUniforms;
+};
+export declare function loadTrajectory<T extends Trajectory>(trajectory: T, options: {
+    fetcher: Fetcher;
+    search?: string;
+    renderer?: THREE.WebGPURenderer;
+}): Promise<T>;
+export declare function unloadTrajectory(trajectory: Trajectory): void;
+export {};

package/five/texture/loader.d.ts

@@ -27,6 +27,12 @@ export declare class TextureLoader {
             options?: ImageURLOptions;
         };
         format?: THREE.PixelFormat;
+        /**
+         * 色彩空间
+         * @description 缺省为 `SRGBColorSpace`（颜色贴图）。非颜色数据（如 gainmap）应显式传 `NoColorSpace`，
+         * 否则会被当成 sRGB 解码（WebGPU 下会创建 `rgba8unorm-srgb` 做硬件解码）。
+         */
+        colorSpace?: THREE.ColorSpace;
         minFilter?: THREE.TextureFilter;
         magFilter?: THREE.TextureFilter;
         generateMipmaps?: boolean;

package/five/types/cube.d.ts

@@ -1,2 +1 @@
 export type CubeFace = 'right' | 'left' | 'up' | 'down' | 'front' | 'back';
-export type GainMapFace = 'gainmap_right' | 'gainmap_left' | 'gainmap_up' | 'gainmap_down' | 'gainmap_front' | 'gainmap_back';

package/five/utils/detector.d.ts

@@ -1,8 +1,18 @@
 declare const userAgent: string;
+declare const isHdrHighDynamicRange: () => boolean;
 /**
  * 是否可以使用 webgl
  */
 declare const canWebGL: boolean;
+/**
+ * 是否可以使用 webgpu
+ * @description
+ * 初始值基于 `navigator.gpu` 是否存在做同步判断，随后通过 `navigator.gpu.requestAdapter()`
+ * 异步校正（部分设备/浏览器声明了 `navigator.gpu` 但实际无可用 adapter）。
+ * 因此该值在页面刚加载的极短时间内可能还未完成校正，如需强一致的判断请使用 `canWebGPUAsync`。
+ */
+declare let canWebGPU: boolean;
+declare const canWebGPUAsync: Promise<boolean>;
 /**
  * 是否可以 pushState
  */
@@ -11,4 +21,4 @@ declare const canPushState: boolean;
  * 是否是通过手机访问
  */
 declare const isMobile: boolean;
-export { userAgent, canWebGL, canPushState, isMobile, };
+export { userAgent, isHdrHighDynamicRange, canWebGL, canWebGPU, canWebGPUAsync, canPushState, isMobile, };

package/five/utils/error.d.ts

@@ -0,0 +1 @@
+export declare function toError(error: any): Error;

package/five/utils/event.d.ts

@@ -12,7 +12,10 @@ export interface BaseEvent {
     type: string;
     timeStamp: number;
     preventDefault(): void;
-    defaultPrevented: boolean;
+    readonly defaultPrevented: boolean;
+}
+export interface BaseExtendableEvent extends BaseEvent {
+    waitUntil(f: Promise<any>): void;
 }
 export interface IntersectEvent extends BaseEvent {
     object: THREE.Object3D;
@@ -29,6 +32,17 @@ export interface PanoEvent extends StateEvent {
     options: MovePanoOptions;
     error: Error | null;
 }
+/** 全景图准备事件 */
+export interface PanoPrepareEvent extends BaseExtendableEvent {
+    /** 切换时选项 */
+    options: MovePanoOptions;
+    /** 切换前模态 */
+    prevMode: Mode;
+    /** 切换前的全景图 */
+    prevPano: Pano;
+    /** 全景图 */
+    pano: Pano;
+}
 export interface PanoTextureEvent extends BaseEvent {
     pano: Pano;
     progress: number;
@@ -157,3 +171,5 @@ export interface NetworkResourceEvent extends BaseEvent {
     detail: string;
 }
 export declare function createEvent<T extends BaseEvent = BaseEvent>(type: string, eventArgs: Omit<T, keyof BaseEvent>): T;
+export declare function createExtendableEvent<T extends BaseExtendableEvent = BaseExtendableEvent>(type: string, eventArgs: Omit<T, keyof BaseExtendableEvent>): T;
+export declare function waitForExtendableEvent(event: BaseExtendableEvent): Promise<void>;

package/five/utils/gainmap-data.d.ts

@@ -0,0 +1,23 @@
+export interface GainmapCfgData {
+    /** gainmap 最大亮度增益 */
+    maxContentBoost: number;
+    /** gainmap 最小亮度增益（通常为 1） */
+    minContentBoost: number;
+    /** 显示器 HDR 容量下限（通常为 1） */
+    hdrCapacityMin: number;
+    /** 显示器 HDR 容量上限 */
+    hdrCapacityMax: number;
+    /** gainmap gamma 值 */
+    gamma: number;
+    /** SDR 偏移，缺省 1/64（UltraHDR 规范） */
+    offsetSdr: number;
+    /** HDR 偏移，缺省 1/64（UltraHDR 规范） */
+    offsetHdr: number;
+}
+/**
+ * `GainmapCfgData` 的默认值（UltraHDR 规范默认值）
+ *
+ * offset 取规范默认 1/64：编码/解码 offset 必须一致，数据里显式提供时以数据为准
+ */
+export declare const DEFAULT_GAINMAP_CFG_DATA: Readonly<GainmapCfgData>;
+export declare function parseGainmapCfgData(input: unknown): GainmapCfgData;

package/five/work/index.d.ts

@@ -1,4 +1,4 @@
-export { parseWork, type ParseOptions, Work, type WorkCubeImage, type WorkImage, type WorkInitial, type WorkModel, type WorkModelLayer, type WorkObserver, type WorkTile, type WorkVideo, } from './work';
+export { parseWork, type ParseOptions, Work, type WorkCubeHdrGainmapImage, type WorkCubeImage, type WorkImage, type WorkInitial, type WorkModel, type WorkModelLayer, type WorkObserver, type WorkTile, type WorkVideo, } from './work';
 export { type WorkInitialJson, type WorkJson, type WorkModelJson, type WorkModelLayerJson, type WorkObserverJson, type WorkPanoramaJson, type WorkPanoramasJson, } from './workJsonType';
 export { workToJson, } from './workJson';
 export { type LoosePanoWork, type LooseWork, type LooseWorkInitial, type LooseWorkModel, type LooseWorkObserver, type LooseWorkPanorama, type LooseWorkVideo, type LooseWorkWithExtrinsics, } from './looseWorkType';

package/five/work/looseWorkType.d.ts

@@ -20,7 +20,8 @@ export interface LooseWorkPanorama {
     size_list?: number[];
     derived_id?: number;
     derived_id_str?: string;
-    hdr_config?: string;
+    hdr?: boolean;
+    gainmap_cfg?: string;
     gainmap_right?: string;
     gainmap_left?: string;
     gainmap_up?: string;

package/five/work/work.d.ts

@@ -2,7 +2,7 @@ import * as THREE from "three/webgpu";
 import type { Mode } from "../application/mode";
 import type { TilesetHeader } from "../model/tile3d/header";
 import type { LooseWork, LoosePanoWork } from "./looseWorkType";
-import { CubeFace, GainMapFace } from "../types/cube";
+import { CubeFace } from "../types/cube";
 import type { PanoId } from "../utils/pano";
 /** 全景视频贴片 */
 export interface WorkVideo {
@@ -14,9 +14,18 @@ export interface WorkVideo {
     /** 视频源长宽尺寸 */
     size: THREE.Vector2;
 }
-export interface WorkCubeImage extends Record<CubeFace | GainMapFace, string> {
+/** HDR gainmap 六视图 */
+export interface WorkCubeHdrGainmapImage extends Record<CubeFace, string> {
+    /** HDR 配置数据地址 */
+    cfg: string;
+}
+export interface WorkCubeImage extends Record<CubeFace, string> {
     work: Work;
-    hdrConfig?: string;
+    /**
+     * HDR gainmap 六视图 + 配置
+     * @description 该点位无 HDR 数据时不存在该字段
+     */
+    gainmap?: WorkCubeHdrGainmapImage;
 }
 export interface WorkTile extends WorkCubeImage {
     /** 层级 */
@@ -183,13 +192,17 @@ export interface Work {
     observers: readonly WorkObserver[];
 }
 export declare class Work {
-    jsonp: boolean;
+    observerBox: THREE.Box3;
+    readonly jsonp: boolean;
+    readonly shortPath: boolean;
+    readonly disableGainmap: boolean;
+    /**
+     * @deprecated 标准数据不混合 panoHDR 数据。而是直接包含 hdr 标识
+     */
     panoHDR?: {
         baseURL: string;
         manifest: any;
     };
-    shortPath: boolean;
-    observerBox: THREE.Box3;
     /**
      * 控制参数
      * @deprecated 通过 work.transform 替换
@@ -231,7 +244,17 @@ export type ParseOptions = {
     shortPath?: boolean;
     /** 资源使用 jsonp 方式发布 */
     jsonp?: boolean;
-    /** 全景 HDR */
+    /**
+     * 不解析 HDR gainmap 数据，点位按「无 HDR」处理
+     * @description 显式 `gainmap_*` 字段、`hdr` 标识推导、`panoHDR` 注入的 gainmap 都会被跳过，
+     * 因此 `images.gainmap` / `tile.gainmap` 不存在；此时即使 `useHDR` 打开也按 SDR 渲染。
+     * 注意：`work.toJSON()` 的 `hdr` 标记由 gainmap 是否存在推导，会一并变为 false。
+     */
+    disableGainmap?: boolean;
+    /**
+     * 全景 HDR
+     * @deprecated 标准数据不混合 panoHDR 数据。而是直接包含 hdr 标识
+     */
     panoHDR?: {
         baseURL: string;
         manifest: any;

package/five/work/workJsonType.d.ts

@@ -58,13 +58,14 @@ export interface WorkPanoramaJson {
     loadable?: boolean;
     derived_id?: number;
     derived_id_str?: string;
-    size_list: number[];
     up: string;
     down: string;
     right: string;
     left: string;
     front: string;
     back: string;
+    size_list: number[];
+    hdr?: boolean;
     video?: {
         source: string;
         matrix: number[];

package/gltf-loader/gltf-object.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from "three/webgpu";
+/**
+ * GLTF 对象
+ */
+declare class GLTFObject extends THREE.Group {
+    needsRender: boolean;
+    /**
+     * mixer 为对应当前对象的动画混合器
+     * @description
+     * 通过 `gltf.animations` 可以获取动画帧。
+     * 通过 `gltf.scene.mixer.clipAction(gltf.animations[0]).play()` 即可播放动画。
+     */
+    mixer: THREE.AnimationMixer;
+    constructor(rootObject?: THREE.Object3D);
+    clone(): this;
+}
+export { GLTFObject };

package/gltf-loader/index.d.ts

@@ -0,0 +1,45 @@
+import * as THREE from "three/webgpu";
+import type { LoadResultType } from "@realsee/five-webgpu";
+import { GLTFObject } from "./gltf-object";
+/**
+ * GLTFLoader 返回数据
+ * @description
+ * 一般情况下，gltf.scene 为模型对象，直接通过 `five.scene.add(gltf.scene)` 即可添加到场景
+ * Five 的模型单位 1 为 1米，载入的模型单位标准不一，请自行 scale。
+ * 如果涉及模型内置动画，GLTF 已经帮你封装了，通过 `gltf.animations` 可以获取动画帧。gltf.scene.mixer 为对应的 动画混合器。
+ * 通过 `gltf.scene.mixer.clipAction(gltf.animations[0]).play()` 即可播放动画。
+ *
+ * 数据由 `@realsee/five-webgpu` 的 `loadGltf` 提供，字段与 `LoadResultType` 保持一致。
+ * 注意 `loadGltf` 以 `{ modelUpAxis: 'Y', upAxis: 'Y' }` 加载，模型保持 glTF 原始的 Y-up 朝向，不会自动旋转到 Five 的 Z-up 坐标系。
+ */
+interface GLTF extends LoadResultType<GLTFObject> {
+    /** 场景列表，本实现中固定为 `[ scene ]` */
+    scenes: GLTFObject[];
+    /** `loadGltf` 不提供相机信息，该字段仅为兼容旧 API 保留，运行时为 `undefined` */
+    cameras?: THREE.Camera[];
+}
+/**
+ * GLTF 模型加载器
+ * @description
+ * 实现基于 `@realsee/five-webgpu` 的 `loadGltf`，因此不再接受 LoadingManager 参数，也不再提供 parse 方法。
+ *
+ * @example
+ * ```
+ * const gltfLoader = new GLTFLoader();
+ * gltfLoader.load("https://vr-public.realsee-cdn.cn/release/static/image/release/five/demo/gltf/plants/scene.gltf", ({ scene }) => {
+ *   five.scene.add(scene);
+ * });
+ * ```
+ */
+declare class GLTFLoader {
+    static get version(): string;
+    /**
+     * 加载模型
+     * @param url - 模型 URL
+     * @param onLoad - 加载完成回调
+     * @param onProgress - 加载进度回调
+     * @param onError - 加载错误回调
+     */
+    load(url: string, onLoad: (gltf: GLTF) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: ErrorEvent) => void): void;
+}
+export { GLTFObject, GLTFLoader, GLTF };