@realsee/five-webgpu 1.0.0-alpha.12 → 1.0.0-alpha.14

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

@@ -1,5 +1,25 @@
 import * as THREE from 'three/webgpu';
+import { type BinnedStage } from './binned/binned-pipelines';
+import { type ExtraBufferKind } from './transparency-buffers';
+import type { TileCategory } from './transparency-math';
 import type { PBMPointCloud } from '../../model/objects/pbmPointCloud';
+/** 透明阶段可用性：true = 本帧该阶段的缓冲、流水线与绑定组均已就绪 */
+export interface TransparentStageAvailability {
+    blend: boolean;
+    additive: boolean;
+}
+/** 每块计算步骤回调：由上层逐块 setPointCloud → writeTileUniform → encodeRasterizeStage */
+export type PointCloudComputeSteps = (computePass: GPUComputePassEncoder) => void;
+/** 一个半透明组：组透明度 a（层合成的混合常量）与组内各块的计算步骤 */
+export interface BlendGroupSteps {
+    alpha: number;
+    steps: PointCloudComputeSteps;
+}
+/** submitTransparentStages 的结果：实际编码的半透明组数、叠加是否编码 */
+export interface TransparentStagesResult {
+    blendGroups: number;
+    additive: boolean;
+}
 /**
  * 基于 Compute Shader 的点云渲染器
  *
@@ -32,12 +52,10 @@ export declare class PointCloudComputeRenderer {
     private placeholderGradientTexture;
     private placeholderGradientView;
     private gradientSampler;
-    private fullscreenQuadPipelineAdditive;
     private ready;
     private binnedCore;
     /** 本帧 viewProj，用于计算 tile mvp */
     private readonly frameViewProj;
-    private readonly tileMvpScratch;
     /**
      * tile 级 GPU 资源缓存：用强引用 Map 而非 WeakMap，配合 PBMPointCloud.dispose
      * 派发的 'dispose' 事件主动销毁 buffer，确保 tile 卸载后内存立即归还。
@@ -50,10 +68,20 @@ export declare class PointCloudComputeRenderer {
     private packedColorScratch;
     /** GPU 法线 Int8×4 打包 scratch，跨 tile 复用（与 packedColorScratch 同策略）。 */
     private packedNormalScratch;
-    private readonly tmpVec3a;
-    private readonly tmpVec3b;
     private readonly tmpVec3c;
     private readonly tmpVec3d;
+    /** 当前 setPointCloud 所选块的缓存键（用于透明块绑定组懒创建） */
+    private currentTileKey;
+    /** 额外缓冲（叠加平面 / 透明层）；构造时不分配任何 GPU 内存，按需 ensure */
+    private readonly transparency;
+    /** 合成管线：首次需要时创建；创建失败记为 Error，之后不再重试 */
+    private compositePipelines;
+    /** 合成绑定组，按 TransparencyBuffers.revision 缓存（颜色格式随实例固定） */
+    private compositeBindGroups;
+    /** 透明层清空绑定组（clear.wgsl 布局 + 透明层 + 帧参数），按额外缓冲 revision 缓存 */
+    private layerClearBindGroup;
+    /** 本帧已 prepareStage 成功的透明阶段；每帧由 prepareTransparentStages 重置，透明阶段提交后清空 */
+    private readonly stageReady;
     constructor(device: GPUDevice, format: GPUTextureFormat);
     /**
      * 上传点云数据到 GPU 缓冲区。
@@ -68,11 +96,14 @@ export declare class PointCloudComputeRenderer {
     /** 每帧编码 tile 之前调用：按本帧总点数准备分桶资源 */
     prepareFrame(totalPointCount: number): void;
     /**
-     * 每帧调用一次：写入共享 frame uniform（viewProj、屏幕、点大小、相机、材质、裁切）。
+     * 每帧调用一次：写入帧级量（viewProj、屏幕、点大小、相机、尺寸分类、桶容量）。
+     * 块级样式参数（材质、楼层、裁剪体等）不在此写入，见 writeTileUniform。
+     */
+    beginPointCloudFrame(camera: THREE.Camera, scratchM4: THREE.Matrix4): void;
+    /**
+     * 每块单次 writeBuffer：几何、块级样式、裁剪体、类别与点透明度 a。
      */
-    beginPointCloudFrame(camera: THREE.Camera, representativePc: PBMPointCloud, scratchM4: THREE.Matrix4): void;
-    /** 每 tile 单次 writeBuffer：model、bbox、pointCount、flags。 */
-    writeTileUniform(pc: PBMPointCloud, pointCount: number): void;
+    writeTileUniform(pc: PBMPointCloud, pointCount: number, category: TileCategory, alpha: number): void;
     /** 写入点大小相关参数。 */
     setPointSizeParams(params: {
         sizeMode: 'FIXED' | 'ATTENUATION';
@@ -86,13 +117,12 @@ export declare class PointCloudComputeRenderer {
     }): void;
     /** 占位渐变纹理 view（无梯度图或纹理未上 GPU 时使用）。 */
     getPlaceholderGradientView(): GPUTextureView;
-    private static tileFlags;
     /** 与 five vertex.glsl 中 ATTENUATION 分支一致，避免透视/正交 matrixLerp 时 clip.w 失真。 */
     private writePointAttenuationUniforms;
+    /** 只写帧级量（同一帧所有块共用）；块级样式参数由 writeTileUniform 按块写入。 */
     private writeFrameUniformsDataView;
     /** 写入尺寸分类阈值与桶容量 */
     private writeRasterUniforms;
-    private writeTileUniformsDataView;
     /**
      * 调整 framebuffer 大小并更新屏幕尺寸 uniform。
      * 销毁旧 framebuffer，创建新的，并重建 bind groups。
@@ -100,16 +130,71 @@ export declare class PointCloudComputeRenderer {
     resize(width: number, height: number): void;
     /** 写入 clear：可并入同一 compute pass，与其它 rasterize dispatch 一起提交。 */
     encodeFramebufferClear(computePass: GPUComputePassEncoder): void;
-    /** 为当前 tile 追加一次分类 dispatch（需先 setPointCloud + writeTileUniform）。 */
+    /** 为当前 tile 追加一次不透明分类 dispatch（需先 setPointCloud + writeTileUniform）；即 encodeRasterizeStage(pass, 'opaque')。 */
     encodeRasterize(computePass: GPUComputePassEncoder): void;
-    encodeFramebufferDisplay(renderPass: GPURenderPassEncoder, options?: {
-        additive?: boolean;
+    /**
+     * 为当前 setPointCloud 所选块追加一次指定阶段的分类 dispatch（需先 writeTileUniform）。
+     * 不透明用含 framebuffer 的块绑定组；透明阶段用透明块绑定组（懒创建），且本帧须已准备该阶段。
+     * 未编码（未就绪、点数为 0、阶段未准备、绑定组创建失败）时返回 false。
+     */
+    encodeRasterizeStage(computePass: GPUComputePassEncoder, stage: BinnedStage): boolean;
+    /** 惰性创建 / 调整某类额外缓冲；本帧就绪返回 true（失败不抛异常）。 */
+    ensureTransparencyBuffers(kind: ExtraBufferKind): boolean;
+    /** 释放叠加平面（所有点云块的 useAddBlend 都为假时由上层调用；不存在时为空操作）。 */
+    releaseAdditiveBuffers(): void;
+    /** 释放透明层缓冲（'blend' → 'opaque' 后由上层调用；不存在时为空操作）。 */
+    releaseBlendBuffers(): void;
+    /**
+     * 每帧调用一次（在 prepareFrame 之后、编码不透明阶段之前）：重置每帧尝试标记，
+     * 对本帧需要的透明阶段创建缓冲、准备流水线与绑定组，返回各阶段是否可用。
+     * 透明层只在 needBlend（mode = 'blend' 且本帧有混合半透明块）时创建；叠加平面只在 needAdditive 时创建。
+     * 上层据此重新分类：blend=false 时半透明块按不透明绘制，additive=false 时跳过叠加块。
+     * @param depthView 合成渲染目标的深度视图，层写入时读取；为 null 时混合半透明不可用
+     */
+    prepareTransparentStages(needBlend: boolean, needAdditive: boolean, depthView: GPUTextureView | null): TransparentStageAvailability;
+    /**
+     * 单个透明阶段准备：binned 流水线 + 平面绑定组 + 合成管线与合成绑定组均可用才算成功；
+     * 混合半透明还需要透明层清空绑定组。
+     */
+    private prepareStage;
+    /** 透明层清空绑定组：clear.wgsl 的布局 + {0: 透明层, 1: 帧参数}，按额外缓冲 revision 缓存。 */
+    private getLayerClearBindGroup;
+    /** 清透明层：组计算通道内的第一个调度，写 0xFFFFFFFF（只清 W × H 个像素）。 */
+    private encodeLayerClear;
+    /** 惰性创建合成管线；失败时记录一次错误并返回 null。 */
+    private getCompositePipelines;
+    /**
+     * 合成绑定组（group0 = 叠加平面 / 透明层 + displayParams{width,height}），按额外缓冲 revision 缓存。
+     */
+    private getCompositeBindGroup;
+    /** 当前块的透明块绑定组（binding 1..7）；与不透明块绑定组同条目缓存、同失效。 */
+    private ensureTransparentTileBindGroup;
+    encodeFramebufferDisplay(renderPass: GPURenderPassEncoder): void;
+    /** 等同 submitOpaqueStage。 */
+    submitMergedPointCloudFrame(colorTextureView: GPUTextureView, depthTextureView: GPUTextureView, rasterizeSteps: PointCloudComputeSteps, options?: {
+        clear?: boolean;
+        display?: boolean;
     }): void;
-    /** 单帧：clear + 各 tile 分类 + 协作光栅 + display，一次 queue.submit。 */
-    submitMergedPointCloudFrame(colorTextureView: GPUTextureView, depthTextureView: GPUTextureView, rasterizeSteps: (computePass: GPUComputePassEncoder) => void, options?: {
+    /**
+     * 透明阶段（单个编码器、一次 queue.submit），须在 three 不透明段之后调用：
+     * - 对每个半透明组 g（`groups` 已按远 → 近排序）：清计数器 → 计算通道（清透明层调度 → g.steps 中各块
+     *   blend 分类 → args + coop）→ 层合成渲染通道（setBlendConstant(g.alpha)、draw(3)）；
+     * - [additiveSteps] clearBuffer(叠加平面，整个缓冲 = 三段) + 清计数器 → 叠加计算通道 → 叠加合成通道。
+     * 合成通道只挂颜色附件。某阶段本帧未准备成功时跳过该阶段，不抛异常；
+     * 未先调用 prepareTransparentStages 时会在此处补做准备。
+     * 返回实际编码的半透明组数与叠加是否编码；提交后清空本帧阶段就绪标记。
+     */
+    submitTransparentStages(colorTextureView: GPUTextureView, depthTextureView: GPUTextureView | null, groups: readonly BlendGroupSteps[], additiveSteps: PointCloudComputeSteps | null): TransparentStagesResult;
+    /** 合成渲染通道：只挂颜色附件（不挂深度），全屏三角形。 */
+    private encodeComposite;
+    private resetStageReady;
+    /**
+     * 不透明阶段：清计数器 → 计算通道（清像素缓冲 + 各块不透明分类 + 协作光栅）→ 显示通道（颜色 + 深度），一次 queue.submit。
+     * 非拆分帧与拆分帧都走此方法。
+     */
+    submitOpaqueStage(colorTextureView: GPUTextureView, depthTextureView: GPUTextureView, rasterizeSteps: PointCloudComputeSteps, options?: {
         clear?: boolean;
         display?: boolean;
-        displayAdditive?: boolean;
     }): void;
     /** 销毁所有 GPU 缓冲区。 */
     dispose(): void;

package/five/renderer/compute-renderers/shaders/composite-blend.d.ts

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

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

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

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

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

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

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

package/five/renderer/compute-renderers/shaders/lib/write-additive.d.ts

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

package/five/renderer/compute-renderers/shaders/lib/write-blend.d.ts

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

package/five/renderer/compute-renderers/shaders/lib/write-opaque.d.ts

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

package/five/renderer/compute-renderers/tile-uniform-writer.d.ts

@@ -0,0 +1,70 @@
+import type { TileCategory } from './transparency-math';
+/** 列主序 4×4 矩阵（与 `THREE.Matrix4.elements` 相同） */
+export interface Mat4Like {
+    readonly elements: ArrayLike<number>;
+}
+export interface Vec3Like {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** 裁剪体参数，与 `PBMClipperParameter` 结构兼容 */
+export interface TileClipperInput {
+    readonly clippingBoxMatrix: Mat4Like;
+    readonly floorIndex?: number;
+}
+/** 写入一个块的块参数所需的全部输入 */
+export interface TileUniformInput {
+    readonly modelMatrix: Mat4Like;
+    readonly bboxMin: Vec3Like;
+    readonly bboxMax: Vec3Like;
+    /** 亮度系数，写入 bboxMax.w */
+    readonly brightness: number;
+    readonly pointCount: number;
+    readonly hasNormals: boolean;
+    readonly category: TileCategory;
+    /** 点透明度 a（CPU 64 位算好，写入时舍入为 f32） */
+    readonly alpha: number;
+    readonly floorIndex: number;
+    readonly shownFloorIndex: number;
+    readonly opacity: number;
+    readonly modelAlpha: number;
+    /** 'OPACITY' 写 1，其余写 0 */
+    readonly floorStyle: string;
+    /** 空数组表示不裁剪：两个裁剪体 Meta.w 写 0 */
+    readonly clippers: readonly TileClipperInput[];
+    /** 'ALTITUDE' 写 1，'CONSTANT' 写 2，其余写 0 */
+    readonly colorStyle: string;
+    readonly useAddBlend: boolean;
+    readonly constantColor: Vec3Like;
+    readonly colorSaturation: number;
+    readonly colorBrightness: number;
+    readonly outlineGain: number;
+    readonly distanceGain: number;
+    /** 'HIDDEN' 写 1，'DARK' 写 2，其余写 0 */
+    readonly pointBack: string;
+}
+export declare function encodeColorStyle(colorStyle: string): number;
+export declare function encodeFloorStyle(floorStyle: string): number;
+export declare function encodePointBack(pointBack: string): number;
+/** tilePack.y：bit0 有法线、bit3 useAddBlend */
+export declare function encodeTileFlags(hasNormals: boolean, useAddBlend: boolean): number;
+/** out = a × b（列主序），与 three `Matrix4.multiplyMatrices` 计算步骤相同 */
+export declare function multiplyMat4(a: ArrayLike<number>, b: ArrayLike<number>, out: Float64Array): Float64Array;
+/**
+ * out = m⁻¹（列主序），与 three `Matrix4.invert` 计算步骤相同；
+ * 行列式为 0 时 out 为全 0 矩阵（three 的行为）。
+ */
+export declare function invertMat4(m: ArrayLike<number>, out: Float64Array): Float64Array;
+/**
+ * 把一个块的块参数写入 `dv[byteOffset, byteOffset + TILE.size)`（416 B）。
+ *
+ * 该范围内每个字节都被写入（含填充位写 0），因此输出只由 `tile` 与 `viewProj` 决定，
+ * 与 DataView 原有内容无关。
+ *
+ * @param dv - 目标 DataView，长度至少 byteOffset + TILE.size
+ * @param tile - 本块参数
+ * @param viewProj - 本帧相机 projectionMatrix × matrixWorldInverse，用于 mvp = viewProj × modelMatrix
+ * @param byteOffset - 写入起点，默认 0
+ */
+export declare function writeTileUniformsDataView(dv: DataView, tile: TileUniformInput, viewProj: Mat4Like, byteOffset?: number): void;

package/five/renderer/compute-renderers/transparency-buffers.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 半透明点云额外缓冲，两类各自独立：
+ *
+ * - 叠加平面（'additive'）：一个缓冲内分 R、G、B 三段，每段 W × H 个 u32，合计 12 B/px；
+ *   usage = STORAGE | COPY_DST（每帧叠加阶段前 encoder.clearBuffer 清零）。
+ * - 透明层（'layer'）：一个 u32 缓冲，4 B/px；usage = STORAGE（用 clear.wgsl 计算管线清空）。
+ *
+ * 规则：
+ * - 只在本帧确实需要某类时调用 ensure，所以从未用到的类不分配；未创建的类不因画布尺寸变化而创建。
+ * - 尺寸不符时同帧销毁旧缓冲再建新缓冲。
+ * - 创建失败：limits 预检失败 / 同步异常当帧判失败；错误作用域异步报告失败时销毁该缓冲、置空、
+ *   revision++，下一个需要它的帧重试。每帧每类最多尝试 1 次、最多 1 条 console.error。
+ *
+ * 不在模块顶层引用全局 GPUBufferUsage（无 WebGPU 的环境中不存在），改用与之相同的数值常量。
+ */
+/** GPUBufferUsage.STORAGE */
+export declare const BUFFER_USAGE_STORAGE = 128;
+/** GPUBufferUsage.COPY_DST */
+export declare const BUFFER_USAGE_COPY_DST = 8;
+export type ExtraBufferKind = 'additive' | 'layer';
+/** 各类缓冲每像素字节数 */
+export declare const EXTRA_BUFFER_BYTES_PER_PIXEL: Readonly<Record<ExtraBufferKind, number>>;
+/** 各类缓冲 usage */
+export declare const EXTRA_BUFFER_USAGE: Readonly<Record<ExtraBufferKind, number>>;
+/** 透明阶段可能用到的额外缓冲（未创建时为 null） */
+export interface ExtraBuffers {
+    additive: GPUBuffer | null;
+    layer: GPUBuffer | null;
+}
+export declare class TransparencyBuffers {
+    /** 缓冲对象发生任何变化（创建 / 销毁）时递增，供绑定组缓存失效 */
+    revision: number;
+    private readonly device;
+    private readonly slots;
+    private disposed;
+    constructor(device: GPUDevice);
+    /** 叠加平面（12 × W × H 字节） */
+    get additive(): GPUBuffer | null;
+    /** 透明层缓冲（4 × W × H 字节） */
+    get layer(): GPUBuffer | null;
+    /** 每帧开始调用：重置每帧每类的尝试 / 日志标记 */
+    beginFrame(): void;
+    /**
+     * 惰性创建 / 调整尺寸。本帧该类缓冲就绪（尺寸 = 当前宽高）返回 true，否则 false。
+     */
+    ensure(kind: ExtraBufferKind, width: number, height: number): boolean;
+    /** 释放某类缓冲（不存在时为空操作） */
+    release(kind: ExtraBufferKind): void;
+    /** 释放全部缓冲；之后 ensure 恒返回 false */
+    dispose(): void;
+    private destroySlot;
+    private watchAsyncFailure;
+    /**
+     * 异步报告失败：若该缓冲仍由槽持有则销毁并置空，下一个需要它的帧重试。
+     * 不再持有的缓冲已在尺寸变化 / 释放 / dispose 时销毁过，不重复 destroy。
+     */
+    private onAsyncFailure;
+    private reportError;
+}

package/five/renderer/compute-renderers/transparency-math.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 计算着色器点云透明相关的纯函数与常量。
+ *
+ * CPU 端每块每帧计算点透明度 a，写入块参数 `tile.alphaPack`。
+ * WGSL 侧的透明常量也由 `TRANSPARENCY_CONSTANTS` 生成，保证 CPU 与 GPU 同源。
+ */
+/** 每块绘制类别，与 `tilePack.z` 的取值一致。 */
+export declare const TILE_CATEGORY: {
+    /** 不透明绘制（atomicMin 写像素缓冲） */
+    readonly OPAQUE: 0;
+    /** 叠加模式（原子加写叠加缓冲） */
+    readonly ADDITIVE: 1;
+    /** 混合半透明（普通混合，写透明层缓冲后逐组合成） */
+    readonly BLEND: 2;
+};
+export type TileCategory = (typeof TILE_CATEGORY)[keyof typeof TILE_CATEGORY];
+export declare const TRANSPARENCY_CONSTANTS: {
+    /** 点透明度 a 小于该值时剔除 */
+    readonly ALPHA_CULL_THRESHOLD: 0.0001;
+    /** 非选中楼层且 floorStyle = 'OPACITY' 时楼层透明度的基数 */
+    readonly FLOOR_OPACITY_BASE: 0.2;
+    /** 选中楼层判断阈值，与 cull.wgsl 一致：shownFloor < −0.01 表示显示全部楼层 */
+    readonly SHOWN_FLOOR_ALL_THRESHOLD: -0.01;
+    /** 选中楼层判断阈值，与 cull.wgsl 一致：|floorIndex − shownFloor| < 0.99 视为相等 */
+    readonly FLOOR_EQUAL_EPSILON: 0.99;
+    readonly additive: {
+        /** 叠加缩放系数：每通道贡献 = round(K · a · c)；K 为 2 的幂，K · a 与 ÷ K 在 f32 中无舍入 */
+        readonly K: 4096;
+        /** rgba16float 的最大有限值；合成时加数先限制到该值 */
+        readonly HALF_FLOAT_MAX: 65504;
+    };
+    readonly layer: {
+        /** "无点"值，与 clear.wgsl 写入的值相同 */
+        readonly EMPTY: 4294967295;
+        /** 层写入的深度比较统一换算到 24 位整数 */
+        readonly DEPTH_U24_MAX: 16777215;
+    };
+};
+/** clamp(x, lo, hi)；x 为 NaN 时返回 lo。 */
+export declare function clamp(x: number, lo: number, hi: number): number;
+/** 计算点透明度所需的块级参数。 */
+export interface FloorOpacityInput {
+    floorIndex: number;
+    shownFloorIndex: number;
+    /** 'OPACITY' 时非选中楼层半透明，其余值不影响透明度 */
+    floorStyle: string;
+}
+/**
+ * 点云块是否属于选中楼层。
+ * 选中楼层号 < 0（显示全部楼层），或块楼层号等于选中楼层号时为真。
+ * 判断阈值与 cull.wgsl 的 `is_current_floor` 相同，楼层号为整数时等价于精确比较。
+ */
+export declare function isSelectedFloor(floorIndex: number, shownFloorIndex: number): boolean;
+/**
+ * 楼层透明度（64 位计算）。
+ * 非选中楼层且 floorStyle = 'OPACITY' 时为 clamp(0.2 × min(1 + 相机朝向y, 1), 0, 1)，其余为 1。
+ */
+export declare function floorOpacity(tile: FloorOpacityInput, cameraForwardY: number): number;
+/**
+ * 点透明度 a = clamp(opacity × 楼层透明度 × modelAlpha, 0, 1)，64 位计算。
+ * 写入块参数时由 Float32 存储舍入为 f32。
+ */
+export declare function pointAlpha(opacity: number, floorOpacityValue: number, modelAlpha: number): number;
+/** 点透明度是否低于剔除阈值。 */
+export declare function isAlphaCulled(a: number): boolean;
+/**
+ * 由 `TRANSPARENCY_CONSTANTS` 生成 WGSL 常量声明（叠加、透明层与共用常量），
+ * 供写像素变体与合成着色器拼接。
+ */
+export declare function transparencyWgslConstants(): string;

package/five/renderer/compute-renderers/transparency-settings.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 计算着色器点云的半透明设置项：半透明处理方式。
+ *
+ * 本文件不依赖 GPU，只负责取值校验与状态标记：
+ * - 非法值保持原值，不抛错，每次非法设置输出一条 `console.warn`；
+ * - 值确实改变时置 `needsRender = true`，由上层同步到 `Five.needsRender`；
+ * - 'blend' → 'opaque' 时置 `pendingBlendRelease = true`，由下一次 `renderPointCloudCompute`
+ *   开头释放透明层缓冲后清零。
+ */
+/** 半透明处理方式：'blend' 为普通混合，'opaque' 为按不透明绘制。 */
+export type PointCloudTransparencyMode = 'blend' | 'opaque';
+/** 半透明处理方式默认值。 */
+export declare const DEFAULT_POINT_CLOUD_TRANSPARENCY_MODE: PointCloudTransparencyMode;
+/** 是否为合法的半透明处理方式。 */
+export declare function isPointCloudTransparencyMode(v: unknown): v is PointCloudTransparencyMode;
+export declare class TransparencySettings {
+    /** 设置项发生改变、需要重绘时为 true；由使用方读取后清零。 */
+    needsRender: boolean;
+    /** 由 'blend' 切到 'opaque' 后为 true，表示需要在下一帧开头释放透明层缓冲。 */
+    pendingBlendRelease: boolean;
+    private _mode;
+    get mode(): PointCloudTransparencyMode;
+    set mode(value: PointCloudTransparencyMode);
+}

package/five/renderer/compute-renderers/uniform-layout.d.ts

@@ -8,8 +8,17 @@ interface StructLayout<F extends FieldTable> {
     readonly size: number;
     readonly wgsl: string;
 }
-export declare const FRAME: StructLayout<readonly [readonly ["viewProj", "mat4x4<f32>"], readonly ["screenInfo", "vec4<u32>"], readonly ["pointAttenPack", "vec4<f32>"], readonly ["viewZRow", "vec4<f32>"], readonly ["sizeInfo0", "vec4<f32>"], readonly ["sizeInfo1", "vec4<u32>"], readonly ["cameraWorld", "vec4<f32>"], readonly ["cameraForward", "vec4<f32>"], readonly ["constantColor", "vec4<f32>"], readonly ["colorGain", "vec4<f32>"], readonly ["stylePack", "vec4<u32>"], readonly ["floorPack", "vec4<f32>"], readonly ["clip0Inv", "mat4x4<f32>"], readonly ["clip0Meta", "vec4<f32>"], readonly ["clip1Inv", "mat4x4<f32>"], readonly ["clip1Meta", "vec4<f32>"], readonly ["rasterParams", "vec4<f32>"], readonly ["binnedInfo", "vec4<u32>"]]>;
-export declare const TILE: StructLayout<readonly [readonly ["modelMatrix", "mat4x4<f32>"], readonly ["bboxMin", "vec4<f32>"], readonly ["bboxMax", "vec4<f32>"], readonly ["tilePack", "vec4<u32>"], readonly ["mvp", "mat4x4<f32>"]]>;
+/** 帧级量：只放同一帧所有块共用的参数，块级样式参数见 TILE */
+export declare const FRAME: StructLayout<readonly [readonly ["viewProj", "mat4x4<f32>"], readonly ["screenInfo", "vec4<u32>"], readonly ["pointAttenPack", "vec4<f32>"], readonly ["viewZRow", "vec4<f32>"], readonly ["sizeInfo0", "vec4<f32>"], readonly ["sizeInfo1", "vec4<u32>"], readonly ["cameraWorld", "vec4<f32>"], readonly ["cameraForward", "vec4<f32>"], readonly ["rasterParams", "vec4<f32>"], readonly ["binnedInfo", "vec4<u32>"]]>;
+/** 块级量：每块一次 writeBuffer，块之间互不影响 */
+export declare const TILE: StructLayout<readonly [readonly ["modelMatrix", "mat4x4<f32>"], readonly ["bboxMin", "vec4<f32>"], readonly ["bboxMax", "vec4<f32>"], readonly ["tilePack", "vec4<u32>"], readonly ["mvp", "mat4x4<f32>"], readonly ["constantColor", "vec4<f32>"], readonly ["colorGain", "vec4<f32>"], readonly ["stylePack", "vec4<u32>"], readonly ["floorPack", "vec4<f32>"], readonly ["alphaPack", "vec4<f32>"], readonly ["clip0Inv", "mat4x4<f32>"], readonly ["clip0Meta", "vec4<f32>"], readonly ["clip1Inv", "mat4x4<f32>"], readonly ["clip1Meta", "vec4<f32>"]]>;
+/** tilePack.y（flags）位定义 */
+export declare const TILE_FLAG_HAS_NORMAL: number;
+export declare const TILE_FLAG_ADD_BLEND: number;
+/** tilePack.z（category）取值 */
+export declare const TILE_CATEGORY_OPAQUE = 0;
+export declare const TILE_CATEGORY_ADDITIVE = 1;
+export declare const TILE_CATEGORY_BLEND = 2;
 export declare const BUCKET_ENTRY_BYTES = 16;
 export declare const SUB_BLOCK_ENTRY_BYTES = 8;
 export declare const SUB_BLOCK_SIZE = 8;

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

@@ -3,26 +3,40 @@ import { type Scene } from '../core/scene';
 import { type Camera } from '../core/camera';
 import { type OutputTextureDataType } from '../core/internalWebGPURenderer';
 import { type ModelScene } from '../model';
+import { type PointCloudTransparencyMode } from './compute-renderers/transparency-settings';
 import { EffectComposer } from './postprocessing/composer';
+export type { PointCloudTransparencyMode };
 export declare class FiveRenderer {
     renderMode: string;
     composer: EffectComposer;
     composerVersion: string;
     outputType: OutputTextureDataType;
     private sceneRenders;
-    private computeRenderer;
+    private pointcloudComputeRenderer;
     private useComputePointCloud;
     private compositeRenderTarget;
     private lastWidth;
     private lastHeight;
     private readonly gpuTextureViewCache;
+    /** 含模板的深度纹理需要单独的 depth-only 视图才能绑定为 texture_depth_2d */
+    private readonly depthOnlyViewCache;
+    /** 只存值与标记，不触碰 GPU，WebGL 后端下同样可安全读写 */
+    private readonly transparencySettings;
+    /**
+     * 计算着色器点云的半透明处理方式：'blend' | 'opaque'，默认 'blend'。
+     * 非法值保持原值并输出警告；值改变时置 needsRender。
+     */
+    get pointCloudTransparencyMode(): PointCloudTransparencyMode;
+    set pointCloudTransparencyMode(value: PointCloudTransparencyMode);
+    /** 设置项改变后为 true，由 Five 在同步状态阶段读取并清零。 */
+    get needsRender(): boolean;
+    set needsRender(value: boolean);
     constructor(options: {
         outputType?: OutputTextureDataType;
     });
     render(renderer: THREE.WebGPURenderer, scene: Scene, modelScene: ModelScene, camera: Camera, sceneUpdated: boolean): boolean;
-    /** 将场景（点云 compute pass + three 场景）合成到 `compositeRenderTarget`。 */
     private renderSceneToComposite;
-    /** 按相机到点云世界包围盒的距离由近到远排序 */
+    /** 按相机到点云世界包围盒的距离由近到远排序（缺失包围盒的块排在最后） */
     private sortByDistance;
     /**
      * WebGPU 路径：Compute Shader 光栅化点云 → 再渲染 three 场景叠加。
@@ -30,6 +44,17 @@ export declare class FiveRenderer {
      */
     private renderPointCloudCompute;
     dispose(): void;
+    /**
+     * 合成渲染目标的原生视图。
+     * - depthView：默认视图，作为不透明显示通道的深度附件；
+     * - layerDepthView：层写入以 texture_depth_2d 读取的视图。
+     *
+     * three WebGPU 后端下 `new THREE.DepthTexture(w, h)` 映射为 `depth24plus`（无模板），usage 含 TEXTURE_BINDING，
+     * 可直接绑定为 texture_depth_2d。若将来改为带模板的格式，默认视图（aspect = 'all'）不能这样绑定，
+     * 因此改用单独缓存的 `aspect: 'depth-only'` 视图；无模板时与 depthView 为同一视图。
+     */
     private getCompositeTargetViews;
     private getCachedGpuTextureView;
+    private getLayerDepthView;
+    private getCachedView;
 }

package/five/renderer/index.d.ts

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

package/five/renderer/postprocessing/passes/pass.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/29
- * Version: 1.0.0-alpha.12
+ * Generated: 2026/11/3
+ * Version: 1.0.0-alpha.14
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/const e=require("../../tools/full-screen-quad.js");var t=class{constructor(e){this.enabled=!0,this.needsSwap=!0,this.clear=!1,this.renderToScreen=!0,this.dependencies=e==null?[]:e}setSize(e,t){}render(e,t,n,r,i){}dispose(){}};t.FullScreenQuad=e.FullScreenQuad,exports.FivePass=t;
+*/const require_full_screen_quad=require("../../tools/full-screen-quad.js");var FivePass=class{constructor(dependencies){this.enabled=!0,this.needsSwap=!0,this.clear=!1,this.renderToScreen=!0,this.dependencies=dependencies==null?[]:dependencies}setSize(width,height){}render(renderer,writeBuffer,readBuffer,deltaTime,maskActive){}dispose(){}};FivePass.FullScreenQuad=require_full_screen_quad.FullScreenQuad,exports.FivePass=FivePass;

package/five/renderer/postprocessing/passes/pass.mjs

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/29
- * Version: 1.0.0-alpha.12
+ * Generated: 2026/11/3
+ * Version: 1.0.0-alpha.14
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/import{FullScreenQuad as e}from"../../tools/full-screen-quad.mjs";var t=class{constructor(e){this.enabled=!0,this.needsSwap=!0,this.clear=!1,this.renderToScreen=!0,this.dependencies=e==null?[]:e}setSize(e,t){}render(e,t,n,r,i){}dispose(){}};t.FullScreenQuad=e;export{t as FivePass};
+*/import{FullScreenQuad}from"../../tools/full-screen-quad.mjs";var FivePass=class{constructor(dependencies){this.enabled=!0,this.needsSwap=!0,this.clear=!1,this.renderToScreen=!0,this.dependencies=dependencies==null?[]:dependencies}setSize(width,height){}render(renderer,writeBuffer,readBuffer,deltaTime,maskActive){}dispose(){}};FivePass.FullScreenQuad=FullScreenQuad;export{FivePass};

package/five/renderer/tools/full-screen-quad.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/29
- * Version: 1.0.0-alpha.12
+ * Generated: 2026/11/3
+ * Version: 1.0.0-alpha.14
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/const e=require("../../../_virtual/_rolldown/runtime.js");let t=require("three/webgpu");t=e.__toESM(t,1);var n=class e{constructor(n){this._scene=new t.Scene,this._mesh=new t.Mesh(e.geometry,n),this._mesh.frustumCulled=!1,this._scene.add(this._mesh)}get material(){return this._mesh.material}set material(e){this._mesh.material=e}dispose(){this._mesh.geometry.dispose()}render(t){t.render(this._scene,e.camera)}};n.camera=new t.OrthographicCamera(-1,1,1,-1,0,1),n.geometry=(()=>{let e=new t.PlaneGeometry(2,2,1,1);for(let t=1;t<e.attributes.uv.array.length;t+=2)e.attributes.uv.array[t]=1-e.attributes.uv.array[t];return e})(),exports.FullScreenQuad=n;
+*/const require_runtime=require("../../../_virtual/_rolldown/runtime.js");let three_webgpu=require("three/webgpu");three_webgpu=require_runtime.__toESM(three_webgpu,1);var FullScreenQuad=class FullScreenQuad{constructor(material){this._scene=new three_webgpu.Scene,this._mesh=new three_webgpu.Mesh(FullScreenQuad.geometry,material),this._mesh.frustumCulled=!1,this._scene.add(this._mesh)}get material(){return this._mesh.material}set material(value){this._mesh.material=value}dispose(){this._mesh.geometry.dispose()}render(renderer){renderer.render(this._scene,FullScreenQuad.camera)}};FullScreenQuad.camera=new three_webgpu.OrthographicCamera(-1,1,1,-1,0,1),FullScreenQuad.geometry=(()=>{let ge=new three_webgpu.PlaneGeometry(2,2,1,1);for(let i=1;i<ge.attributes.uv.array.length;i+=2)ge.attributes.uv.array[i]=1-ge.attributes.uv.array[i];return ge})(),exports.FullScreenQuad=FullScreenQuad;

package/five/renderer/tools/full-screen-quad.mjs

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/29
- * Version: 1.0.0-alpha.12
+ * Generated: 2026/11/3
+ * Version: 1.0.0-alpha.14
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/import*as e from"three/webgpu";var t=class t{constructor(n){this._scene=new e.Scene,this._mesh=new e.Mesh(t.geometry,n),this._mesh.frustumCulled=!1,this._scene.add(this._mesh)}get material(){return this._mesh.material}set material(e){this._mesh.material=e}dispose(){this._mesh.geometry.dispose()}render(e){e.render(this._scene,t.camera)}};t.camera=new e.OrthographicCamera(-1,1,1,-1,0,1),t.geometry=(()=>{let t=new e.PlaneGeometry(2,2,1,1);for(let e=1;e<t.attributes.uv.array.length;e+=2)t.attributes.uv.array[e]=1-t.attributes.uv.array[e];return t})();export{t as FullScreenQuad};
+*/import*as THREE from"three/webgpu";var FullScreenQuad=class FullScreenQuad{constructor(material){this._scene=new THREE.Scene,this._mesh=new THREE.Mesh(FullScreenQuad.geometry,material),this._mesh.frustumCulled=!1,this._scene.add(this._mesh)}get material(){return this._mesh.material}set material(value){this._mesh.material=value}dispose(){this._mesh.geometry.dispose()}render(renderer){renderer.render(this._scene,FullScreenQuad.camera)}};FullScreenQuad.camera=new THREE.OrthographicCamera(-1,1,1,-1,0,1),FullScreenQuad.geometry=(()=>{let ge=new THREE.PlaneGeometry(2,2,1,1);for(let i=1;i<ge.attributes.uv.array.length;i+=2)ge.attributes.uv.array[i]=1-ge.attributes.uv.array[i];return ge})();export{FullScreenQuad};