@realsee/five-webgpu 1.0.0-alpha.3 → 1.0.0-alpha.5

package/five/model/index.d.ts

@@ -5,7 +5,7 @@ export { PBMGaussianSplattingObject as PBMGSObject, } from "./objects/pbmGaussia
 export { PBMPointCloud, type PointCloudData, } from "./objects/pbmPointCloud";
 export { PBMGaussianSplattingRenderMesh, } from "./objects/pbmGaussianSplattingRenderMesh";
 export { PBMGaussianSplattingNodeMaterial, } from "./materials/pbmGaussianSplattingNodeMaterial";
-export { PBMUpdateable, PBMPanoFilter, type IPBMMaterial, type PBMPanoFilterValue, type PBMAlphaMode, type PBMClipperParameter, type PBMColorStyle, type PBMFloorStyle, type PBMPanoPicture, type PBMHDRConfig, type PBMPanoDepth, type PBMPointBack, type PBMPointCloudShaderType, type PBMPointShape, type PBMPointSize, type PBMRefinedScreen, type PBMTransition, } from "./materials/pbmMaterial";
+export { PBMUpdateable, PBMPanoFilter, PBMCustomNode, customNodesCacheKey, type IPBMMaterial, type PBMPanoFilterValue, type PBMAlphaMode, type PBMClipperParameter, type PBMColorStyle, type PBMFloorStyle, type PBMRoofStyle, type PBMPanoPicture, type PBMHDRConfig, type PBMPanoDepth, type PBMPointBack, type PBMPointCloudShaderType, type PBMPointShape, type PBMPointSize, type PBMRefinedScreen, type PBMTransition, type PBMCustomNodeSlots, type PBMCustomNodeTargetType, type PBMCustomNodeOptions, type PBMCustomNodeContext, type PBMCustomNodePanoContext, } from "./materials/pbmMaterial";
 export { type PBMMeshMaterial, PBMMeshBasicMaterial, PBMMeshPhongMaterial, PBMMeshPhysicalMaterial, PBMMeshPanoOnlyMaterial } from './materials/pbmMeshMaterial';
 export { registerPBMMaterials, } from './materials/pbmMaterialRegister';
 export { PBMMeshBasicNodeMaterial, } from './materials/nodes/pbmMeshBasicNodeMaterial';

package/five/model/materials/nodes/pbmMeshBasicNodeMaterial.d.ts

@@ -9,6 +9,8 @@ export declare class PBMMeshBasicNodeMaterial extends THREE.MeshBasicNodeMateria
     static get type(): string;
     readonly isPBMMeshBasicNodeMaterial = true;
     constructor(parameters?: THREE.MeshBasicNodeMaterialParameters);
+    customProgramCacheKey(): string;
+    setupVertex(builder: THREE.NodeBuilder): THREE.Node;
     setup(builder: THREE.NodeBuilder): void;
     setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
 }

package/five/model/materials/nodes/pbmMeshPanoOnlyNodeMaterial.d.ts

@@ -9,6 +9,8 @@ export declare class PBMMeshPanoOnlyNodeMaterial extends THREE.MeshBasicNodeMate
     static get type(): string;
     readonly isPBMPanoOnlyNodeMaterial = true;
     constructor(parameters?: THREE.MeshBasicNodeMaterialParameters);
+    customProgramCacheKey(): string;
+    setupVertex(builder: THREE.NodeBuilder): THREE.Node;
     setup(builder: THREE.NodeBuilder): void;
     setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
 }

package/five/model/materials/nodes/pbmMeshPhongNodeMaterial.d.ts

@@ -9,6 +9,8 @@ export declare class PBMMeshPhongNodeMaterial extends THREE.MeshPhongNodeMateria
     static get type(): string;
     readonly isPBMMeshPhongNodeMaterial = true;
     constructor(parameters?: THREE.MeshPhongNodeMaterialParameters);
+    customProgramCacheKey(): string;
+    setupVertex(builder: THREE.NodeBuilder): THREE.Node;
     setup(builder: THREE.NodeBuilder): void;
     setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
 }

package/five/model/materials/nodes/pbmMeshPhysicalNodeMaterial.d.ts

@@ -9,6 +9,8 @@ export declare class PBMMeshPhysicalNodeMaterial extends THREE.MeshPhysicalNodeM
     static get type(): string;
     readonly isPBMMeshPhysicalNodeMaterial = true;
     constructor(parameters?: THREE.MeshPhysicalNodeMaterialParameters);
+    customProgramCacheKey(): string;
+    setupVertex(builder: THREE.NodeBuilder): THREE.Node;
     setup(builder: THREE.NodeBuilder): void;
     setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
 }

package/five/model/materials/pbmMaterial.d.ts

@@ -7,6 +7,12 @@ export type PBMPointCloudShaderType = 'pointcloud';
 export type PBMAlphaMode = 'OPAQUE' | 'MASK' | 'BLEND';
 export type PBMTransition = 'BLACK' | 'SPREAD' | 'FADE';
 export type PBMFloorStyle = 'VISIBILITY' | 'OPACITY';
+/**
+ * 屋顶样式（仅在 vertexMarks 为 true、即模型带屋顶标记时生效）
+ * - AUTO: 根据相机俯仰角渐进裁切屋顶（默认，原有行为）
+ * - HIDE: 始终隐藏屋顶，与视角无关
+ */
+export type PBMRoofStyle = 'AUTO' | 'HIDE';
 export type PBMColorStyle = 'RGB' | 'ALTITUDE' | 'CONSTANT';
 export type PBMPointShape = 'SQUARE' | 'CIRCLE';
 export type PBMPointSize = 'FIXED' | 'ATTENUATION';
@@ -15,6 +21,165 @@ export declare class PBMUpdateable extends Subscribe<{
     "update": () => void;
 }> {
 }
+/** PBMCustomNode 生效的材质类型 */
+export type PBMCustomNodeTargetType = 'basic' | 'phong' | 'standard' | 'panoOnly' | 'pointcloud';
+/**
+ * 全景分支中可供自定义节点使用的节点上下文。
+ * 这些字段是稳定的 PBM API，业务方不需要直接依赖内部 defines.ts 路径。
+ */
+export interface PBMCustomNodePanoContext {
+    /** 全景点位在世界空间中的原点 */
+    origin: THREE.Node<'vec3'>;
+    /** 当前片元对应的全景采样方向 */
+    sampleDirection: THREE.Node<'vec3'>;
+    /** SDR 全景颜色 */
+    sdrColor: THREE.Node<'vec3'>;
+    /** HDR 处理后的全景颜色 */
+    hdrColor: THREE.Node<'vec3'>;
+    /** 全景深度可信度 */
+    depthTrust: THREE.Node<'float'>;
+}
+/**
+ * PBMCustomNode callback 可访问的内置 TSL 节点。
+ *
+ * 注意：这里暴露的是节点表达式，不是 CPU 侧的实时数值；它们会被编译进当前材质的 shader。
+ */
+export interface PBMCustomNodeContext {
+    /** 当前片元的世界空间位置 */
+    positionWorld: THREE.Node<'vec3'>;
+    /** 当前片元的视图空间位置 */
+    positionView: THREE.Node<'vec3'>;
+    /** 相机朝向（世界/模型渲染使用的 varying） */
+    cameraDirection: THREE.Node<'vec3'>;
+    /** 当前渲染分辨率 */
+    resolution: THREE.Node<'vec2'>;
+    /** 当前像素比 */
+    pixelRatio: THREE.Node<'float'>;
+    /** 模型/全景渲染参数 */
+    progress: THREE.Node<'float'>;
+    maxDisplayBoost: THREE.Node<'float'>;
+    modelAlpha: THREE.Node<'float'>;
+    colorAlpha: THREE.Node<'float'>;
+    brightness: THREE.Node<'float'>;
+    colorSaturation: THREE.Node<'float'>;
+    colorBrightness: THREE.Node<'float'>;
+    constantColor: THREE.Node<'vec3'>;
+    /** 楼层和屋顶状态 */
+    floorIndex: THREE.Node<'float'>;
+    shownFloorIndex: THREE.Node<'float'>;
+    isCurrentFloor: THREE.Node<'bool'>;
+    floorOpacity: THREE.Node<'float'>;
+    isRoof: THREE.Node<'bool'>;
+    isRoofCameraCut: THREE.Node<'bool'>;
+    isRoofModelAlphaCut: THREE.Node<'bool'>;
+    modelBoundingMin: THREE.Node<'vec3'>;
+    modelBoundingMax: THREE.Node<'vec3'>;
+    /** 起始/结束全景点位的采样结果 */
+    pano0: PBMCustomNodePanoContext;
+    pano1: PBMCustomNodePanoContext;
+    /** 点云相关参数 */
+    pointScale: THREE.Node<'float'>;
+    pointMinPixel: THREE.Node<'float'>;
+    pointMaxPixel: THREE.Node<'float'>;
+}
+/**
+ * 节点插槽定义
+ *
+ * 每个插槽是一个函数，接收当前管线中的节点，返回修改后的节点。
+ * 用户在函数中可自由使用 TSL API（uniform、attribute、Fn、数学运算等）。
+ */
+export interface PBMCustomNodeSlots {
+    /**
+     * 模型基础颜色修改（在全景混合之前）
+     * - Mesh 材质：在 colorMode 处理之后、pano 混合之前调用
+     * - PointCloud 材质：在实例颜色读取 + HSV 调整之后调用
+     *
+     * @param color - 当前模型颜色 (vec3, linear working space)
+     * @returns 修改后的颜色 (vec3)
+     */
+    modelColor?: (color: THREE.Node<'vec3'>, context: PBMCustomNodeContext) => THREE.Node<'vec3'>;
+    /**
+     * 全景颜色修改（在全景采样 + HDR + filter 之后，与模型混合之前）
+     * 仅在启用全景贴图时生效。
+     *
+     * @param panoColor - 当前全景采样颜色 (vec3)
+     * @returns 修改后的全景颜色 (vec3)
+     */
+    panoColor?: (panoColor: THREE.Node<'vec3'>, context: PBMCustomNodeContext) => THREE.Node<'vec3'>;
+    /**
+     * 最终输出颜色修改（在全部管线处理完成后、return 之前）
+     *
+     * @param color - 当前最终颜色 (vec4, 含 alpha)
+     * @returns 修改后的最终颜色 (vec4)
+     */
+    outputColor?: (color: THREE.Node<'vec4'>, context: PBMCustomNodeContext) => THREE.Node<'vec4'>;
+    /**
+     * 自定义 discard 逻辑（在管线 discard 判断之后额外追加）
+     * 返回的 bool 节点为 true 时丢弃该片元。
+     *
+     * @returns 是否丢弃 (bool node)
+     */
+    discard?: (context: PBMCustomNodeContext) => THREE.Node<'bool'>;
+    /**
+     * 顶点位置偏移（世界空间）
+     * 在标准顶点变换之后、投影之前应用。
+     * 注意：PointCloud 材质中此插槽作用于 instancePosition 展开后的 view 空间。
+     *
+     * @param position - 当前世界空间位置 (vec3)
+     * @returns 修改后的世界空间位置 (vec3)
+     */
+    vertexPosition?: (position: THREE.Node<'vec3'>, context: PBMCustomNodeContext) => THREE.Node<'vec3'>;
+}
+export interface PBMCustomNodeOptions {
+    /** 生效的材质类型 */
+    type: readonly PBMCustomNodeTargetType[];
+    /** 节点插槽 */
+    slots: PBMCustomNodeSlots;
+    /**
+     * 自定义标量 uniforms（可选）。
+     * 登记在这里的 uniform，写其 `.value` 时会自动触发所属材质刷新（见 watchUniforms）。
+     * 注意：uniformArray 的数据在 `.array`/元素上，`.value` setter 捕获不到，
+     * 不要放进这里；这类改动请在原地修改后显式调用 {@link PBMCustomNode.markNeedsUpdate}。
+     */
+    uniforms?: Record<string, THREE.UniformNode<any, any>>;
+}
+export declare class PBMCustomNode extends PBMUpdateable {
+    readonly id: string;
+    /** 生效的材质类型 */
+    readonly type: readonly PBMCustomNodeTargetType[];
+    /** TSL Node 插槽 */
+    readonly slots: PBMCustomNodeSlots;
+    /**
+     * 登记的标量 uniforms（仅 UniformNode）。写其 `.value` 会自动触发材质刷新。
+     * uniformArray 请勿放这里（.value setter 捕获不到），改用 markNeedsUpdate()。
+     */
+    readonly uniforms: Record<string, THREE.UniformNode<any, any>>;
+    constructor(options: PBMCustomNodeOptions);
+    /**
+     * 包装登记的 uniforms：写 `.value` 时自动 emit('update')，触发所属材质刷新
+     * （配合 Parameter 对 customNodes 的监听 + customNodesVersion 被监视属性）。
+     */
+    private watchUniforms;
+    /**
+     * 手动标记 uniform 已变化、需要把最新值刷新到所有相关材质。
+     * 用于原地修改 uniformArray / Vector 等 `.value` setter 捕获不到的场景。
+     */
+    markNeedsUpdate(): void;
+    /**
+     * 判断此 CustomNode 是否对指定材质类型生效
+     */
+    appliesTo(materialType: PBMCustomNodeTargetType): boolean;
+    /**
+     * 生成用于 customProgramCacheKey 的标识字符串
+     * 包含 id + 目标材质类型 + 启用的 slot 名称。
+     */
+    get cacheKey(): string;
+}
+/**
+ * 生成 customNodes 数组的 customProgramCacheKey 片段。
+ * 在 NodeMaterial 的 customProgramCacheKey() 中调用。
+ */
+export declare function customNodesCacheKey(customNodes: readonly PBMCustomNode[] | undefined): string;
 export interface PBMPanoFilterValue {
     saturationSaturationBias: number;
     contrastContrastBias: number;
@@ -152,6 +317,7 @@ export interface IPBMMaterial {
     floorIndex: number;
     shownFloorIndex: number;
     floorStyle: string;
+    roofStyle: PBMRoofStyle;
     brightness: number;
     colorSaturation: number;
     colorBrightness: number;
@@ -160,6 +326,15 @@ export interface IPBMMaterial {
     maxDisplayBoost: number;
     modelBoundingMin: THREE.Vector3;
     modelBoundingMax: THREE.Vector3;
+    /** 自定义节点列表（TSL Node 级别的材质扩展） */
+    customNodes: readonly PBMCustomNode[];
+    /**
+     * 自定义节点 uniform 的“脏计数器”。
+     * 被 NodeMaterialObserver 监视（见 pbmProperties）：任一 customNode 的 uniform 变化时，
+     * Parameter 会 ++ 此值，从而让 observer 判定材质需要刷新、把最新 uniform 上传到所有材质。
+     * 该值不进入 shader，仅作刷新触发用。
+     */
+    customNodesVersion: number;
 }
 export type PBMPropertyKey = keyof Omit<IPBMMaterial, 'isPBMMaterial'>;
 export declare const pbmProperties: PBMPropertyKey[];

package/five/model/materials/tsl/defines.d.ts

@@ -47,7 +47,8 @@ export declare const colorSaturation: THREE.Node<"float">;
 export declare const colorBrightness: THREE.Node<"float">;
 export declare const isCurrentFloor: THREE.VarNode<"bool">;
 export declare const isRoof: THREE.VarNode<"bool">;
-export declare const isRoofCut: THREE.VarNode<"bool">;
+export declare const isRoofCameraCut: THREE.VarNode<"bool">;
+export declare const isRoofModelAlphaCut: THREE.VarNode<"bool">;
 export declare const pano0Origin: THREE.VarNode<"vec3">;
 export declare const pano0SampleDirection: THREE.VarNode<"vec3">;
 export declare const pano1Origin: THREE.VarNode<"vec3">;

package/five/model/materials/tsl/outputBuilder.d.ts

@@ -7,8 +7,7 @@
  * 通用工具函数（rgb2hsv, hsv2rgb, resolutionUniform, pixelRatioUniform）在 utils.ts 中。
  */
 import * as THREE from 'three/webgpu';
-import type { PBMTransition, PBMColorStyle } from '../pbmMaterial';
-import { IPBMMaterial } from '../pbmMaterial';
+import type { PBMTransition, PBMColorStyle, PBMCustomNodeTargetType, IPBMMaterial } from '../pbmMaterial';
 export interface SetupPanoOutputOptions {
     useVertexMark: boolean;
     useFloorStyleVisibility: boolean;
@@ -20,7 +19,12 @@ export interface SetupPanoOutputOptions {
     colorMode: PBMColorStyle;
     transition: PBMTransition;
 }
-export declare function setupMeshOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder): void;
-export declare function setupMeshPanoOnlyOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder): void;
+export declare function setupMeshOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder, materialType: PBMCustomNodeTargetType): void;
+/**
+ * 在 NodeMaterial 已完成 morph/skinning/instance 等标准顶点处理后，
+ * 对世界空间位置应用 custom vertexPosition，再转换回裁剪空间。
+ */
+export declare function setupMeshVertex(material: THREE.NodeMaterial & IPBMMaterial, materialType: PBMCustomNodeTargetType, baseVertex: THREE.Node): THREE.Node;
+export declare function setupMeshPanoOnlyOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder, materialType: PBMCustomNodeTargetType): void;
 export declare function setupPointCloudVertex(material: THREE.NodeMaterial & THREE.Material & IPBMMaterial, builder: THREE.NodeBuilder): THREE.Node;
 export declare function setupPointCloudOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder): 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 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 {
@@ -31,6 +31,8 @@ export interface ParameterMaterialValue {
     opacity: number;
     /** 楼层样式 */
     floorStyle: PBMFloorStyle;
+    /** 屋顶样式（仅在 vertexMarks 为 true 时生效；AUTO 按视角渐切，HIDE 始终隐藏） */
+    roofStyle: PBMRoofStyle;
     /** 颜色样式 */
     colorStyle: PBMColorStyle;
     /** 模型颜色*/
@@ -78,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 {
     /** 模型显示最小细化层级 */
@@ -130,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/utils/ktx2.d.ts

@@ -22,9 +22,9 @@ export declare class KTX2 {
     setTranscoderPath(transcoderPath: string): void;
     detectSupport(renderer: THREE.WebGPURenderer): this;
     init(): Promise<void>;
-    parse(buffer: ArrayBuffer): Promise<THREE.CompressedTexture>;
-    _createTextureFrom(transcodeResult: any): Promise<THREE.CompressedTexture<THREE.CompressedTextureImageData>>;
-    _createTexture(buffers: ArrayBuffer[]): Promise<THREE.CompressedTexture<THREE.CompressedTextureImageData>>;
+    parse(buffer: ArrayBuffer): Promise<THREE.Texture>;
+    _createTextureFrom(transcodeResult: any): Promise<THREE.Texture<unknown>>;
+    _createTexture(buffers: ArrayBuffer[]): Promise<THREE.Texture<unknown>>;
     dispose(): this;
 }
 export declare const ktx2: KTX2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realsee/five-webgpu",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Realsee Renderer SDK",
   "author": "BEIKE REALSEE TECHNOLOGY (HK) LIMITED",
   "license": "SEE LICENSE IN TERMS.txt",

package/plugins/index.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/8/11
- * Version: 1.0.0-alpha.3
+ * Generated: 8/31/2026
+ * Version: 1.0.0-alpha.5
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/plugins/index.mjs

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/8/11
- * Version: 1.0.0-alpha.3
+ * Generated: 8/31/2026
+ * Version: 1.0.0-alpha.5
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/react/index.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/8/11
- * Version: 1.0.0-alpha.3
+ * Generated: 8/31/2026
+ * Version: 1.0.0-alpha.5
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/react/index.mjs

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/8/11
- * Version: 1.0.0-alpha.3
+ * Generated: 8/31/2026
+ * Version: 1.0.0-alpha.5
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/umd/five-plugins.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/8/11
- * Version: 1.0.0-alpha.3
+ * Generated: 8/31/2026
+ * Version: 1.0.0-alpha.5
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/umd/five-react.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/8/11
- * Version: 1.0.0-alpha.3
+ * Generated: 8/31/2026
+ * Version: 1.0.0-alpha.5
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021