@spatialwalk/avatarkit 1.0.0-beta.76 → 1.0.0-beta.77

package/dist/index.js

@@ -1,4 +1,4 @@
-import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-ZN-iK3b8.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-CTh2onXJ.js";
 export {
   b as Avatar,
   c as AvatarController,

package/dist/renderer/webgpu/flameGPUBuffers.d.ts

@@ -0,0 +1,137 @@
+/**
+ * FLAME GPU Buffers 管理类
+ *
+ * 管理所有 FLAME 模板数据的 GPU 缓冲区
+ * - 模板数据在初始化时一次性上传 (~31MB)
+ * - 每帧参数通过 uniform buffer 更新 (460 bytes)
+ */
+/**
+ * FLAME 模板数据结构
+ */
+export interface FLAMETemplateData {
+    vTemplate: Float32Array;
+    vertexCount: number;
+    shapedirs: Float32Array;
+    shapeParamCount: number;
+    posedirs: Float32Array;
+    poseParamCount: number;
+    jRegressor: Float32Array;
+    jointCount: number;
+    lbsWeights: Float32Array;
+    parents: Int32Array;
+    faces: Uint32Array;
+    faceCount: number;
+    staticOffset: Float32Array | null;
+    staticOffsetCount: number;
+}
+/**
+ * 🚀 活跃Shape参数（零参数过滤优化）
+ */
+export interface ActiveShapeParams {
+    activeIndices: Uint32Array;
+    activeValues: Float32Array;
+    count: number;
+}
+/**
+ * FLAME 帧参数 (从动画中获取)
+ * 🚀 优化: 移除 shapeParams (静态数据，只需上传一次)
+ */
+export interface FLAMEFrameParams {
+    exprParams: Float32Array;
+    rotation: Float32Array;
+    translation: Float32Array;
+    neckPose: Float32Array;
+    jawPose: Float32Array;
+    eyesPose: Float32Array;
+    eyelid: Float32Array;
+}
+/**
+ * GPU Buffer 集合
+ */
+export interface FLAMEGPUBufferSet {
+    vTemplate: GPUBuffer;
+    shapedirs: GPUBuffer;
+    posedirs: GPUBuffer;
+    jRegressor: GPUBuffer;
+    lbsWeights: GPUBuffer;
+    parents: GPUBuffer;
+    faces: GPUBuffer;
+    staticOffset: GPUBuffer | null;
+    activeShapeIndices: GPUBuffer;
+    activeShapeValues: GPUBuffer;
+    frameParams: GPUBuffer;
+    metadata: GPUBuffer;
+}
+export declare class FLAMEGPUBuffers {
+    private device;
+    private buffers;
+    private vertexCount;
+    private faceCount;
+    private jointCount;
+    private shapeParamCount;
+    private poseParamCount;
+    private staticOffsetCount;
+    private activeShapeCount;
+    private paramDataCache;
+    /**
+     * 初始化 GPU 缓冲区并上传模板数据
+     * 🚀 优化: 需要传入 characterHandle 以获取静态 shape parameters
+     * @param activeShapeParams 活跃shape参数（零参数过滤优化，可选）
+     */
+    initialize(device: GPUDevice, templateData: FLAMETemplateData, _shapeParams: Float32Array, activeShapeParams?: ActiveShapeParams): void;
+    /**
+     * 创建 Storage Buffer 并上传数据
+     */
+    private createStorageBuffer;
+    /**
+     * 创建帧参数 Uniform Buffer
+     * 🚀 优化: 移除 shapeParams，减小 70% 大小
+     *
+     * Layout (std140):
+     * - exprParams: vec4[25]   (100 floats, padded)
+     * - rotation: vec4         (3 floats + padding)
+     * - translation: vec4      (3 floats + padding)
+     * - neckPose: vec4         (3 floats + padding)
+     * - jawPose: vec4          (3 floats + padding)
+     * - eyesPose: vec4[2]      (6 floats, split into 2 vec4)
+     * - eyelid: vec4           (2 floats + padding)
+     */
+    private createFrameParamsBuffer;
+    /**
+     * 创建元数据 Uniform Buffer
+     *
+     * Layout:
+     * - vertexCount: u32
+     * - faceCount: u32
+     * - jointCount: u32
+     * - shapeParamCount: u32
+     * - poseParamCount: u32
+     * - staticOffsetCount: u32
+     * (padding to 256 bytes for alignment)
+     */
+    private createMetadataBuffer;
+    /**
+     * 更新每帧参数
+     * 🚀 优化: 移除 shapeParams 打包，减少 70% 上传量
+     */
+    updateFrameParams(params: FLAMEFrameParams): void;
+    /**
+     * 获取所有缓冲区
+     */
+    getBuffers(): FLAMEGPUBufferSet;
+    /**
+     * 获取元数据
+     */
+    getMetadata(): {
+        vertexCount: number;
+        faceCount: number;
+        jointCount: number;
+        shapeParamCount: number;
+        poseParamCount: number;
+        staticOffsetCount: number;
+    };
+    /**
+     * 清理资源
+     */
+    destroy(): void;
+}

package/dist/renderer/webgpu/flamePipeline.d.ts

@@ -0,0 +1,71 @@
+import { FLAMEGPUBufferSet } from './flameGPUBuffers';
+/**
+ * FLAME Pipeline 输出
+ */
+export interface FLAMEPipelineOutput {
+    faceGeometries: GPUBuffer;
+    faceCount: number;
+}
+export declare class FLAMEPipeline {
+    private device;
+    private buffers;
+    private vertexCount;
+    private faceCount;
+    private jointCount;
+    private shapeBlendPipeline;
+    private poseDeformPipeline;
+    private jointRegressPipeline;
+    private fkPipeline;
+    private lbsPipeline;
+    private faceGeometryPipeline;
+    private shapeBlendParamsBindGroup;
+    private poseDeformParamsBindGroup;
+    private jointRegressMetadataBindGroup;
+    private fkParamsBindGroup;
+    private lbsMetadataBindGroup;
+    private shapeBlendBindGroup;
+    private poseDeformBindGroup;
+    private jointRegressBindGroup;
+    private fkBindGroup;
+    private lbsBindGroup;
+    private faceGeometryParamsBindGroup;
+    private faceGeometryBindGroup;
+    private vShapedBuffer;
+    private vPosedBuffer;
+    private jointsBuffer;
+    private jointTransformsBuffer;
+    private vDeformedBuffer;
+    private faceGeometriesBuffer;
+    constructor(device: GPUDevice, buffers: FLAMEGPUBufferSet, vertexCount: number, faceCount: number, jointCount: number);
+    private initialize;
+    /**
+     * 创建中间缓冲区
+     */
+    private createIntermediateBuffers;
+    /**
+     * 清零所有中间缓冲区 (避免未初始化的垃圾数据)
+     * 🔧 关键修复: LBS shader 如果某些顶点权重全为0，会跳过不写入，导致保留垃圾数据
+     */
+    private clearIntermediateBuffers;
+    /**
+     * 创建计算管线
+     */
+    private createComputePipelines;
+    /**
+     * 创建单个计算管线
+     */
+    private createPipeline;
+    /**
+     * 创建绑定组
+     */
+    private createBindGroups;
+    /**
+     * 计算一帧 FLAME (主入口)
+     * 🚀 优化: 拆分为6个独立pass，支持详细的GPU profiling
+     */
+    compute(commandEncoder: GPUCommandEncoder): FLAMEPipelineOutput;
+    /**
+     * 清理资源
+     */
+    destroy(): void;
+}

package/dist/renderer/webgpu/gpuRadixSort.d.ts

@@ -0,0 +1,47 @@
+/**
+ * GPU Radix Sort - FFX 风格实现
+ *
+ * 核心思想：不用 atomicAdd 来决定写入位置，而是通过分层 Prefix Sum 预计算
+ *
+ * 每个 Pass (处理 8-bit，共 4 个 pass):
+ *   1. Histogram: 每个 workgroup 统计局部 histogram
+ *   2. Scan: 对所有 workgroup 的 histogram 做 prefix sum
+ *   3. Scatter: 根据预计算的位置写入
+ */
+export interface GPURadixSortOptions {
+    device: GPUDevice;
+    maxSplatCount: number;
+}
+export declare class GPURadixSort {
+    private device;
+    private maxSplatCount;
+    private paddedCount;
+    private numWorkgroups;
+    private depthPipeline;
+    private histogramPipeline;
+    private scanPipeline;
+    private addBlockSumsPipeline;
+    private scatterPipeline;
+    private reversePipeline;
+    private uniformBuffer;
+    private paramsBuffer;
+    private scanParamsBuffer;
+    private keysBuffer0;
+    private keysBuffer1;
+    private valuesBuffer0;
+    private valuesBuffer1;
+    private histogramBuffer;
+    private blockSumsBuffer;
+    private blockSumsBuffer2;
+    private positionsBuffer;
+    constructor(options: GPURadixSortOptions);
+    private initialize;
+    setPositionsBuffer(buffer: GPUBuffer): void;
+    sortAsync(viewMatrix: Float32Array, splatCount: number): Promise<GPUBuffer>;
+    private runReversePass;
+    private runDepthPass;
+    private runHistogramPass;
+    private runPrefixSum;
+    private runScatterPass;
+    destroy(): void;
+}

package/dist/renderer/webgpu/transformPipeline.d.ts

@@ -0,0 +1,97 @@
+/**
+ * WebGPU Transform Pipeline
+ *
+ * 管理3DGS Transform的GPU计算:
+ * - Original Splats Buffer (一次性上传)
+ * - Face Geometry Buffer (每帧更新)
+ * - Transformed Output Buffer (GPU输出)
+ */
+export declare class TransformPipeline {
+    private device;
+    private computePipeline;
+    private bindGroup;
+    private originalSplatsBuffer;
+    private faceGeometryBuffer;
+    private transformedOutputBuffer;
+    private positionsOutputBuffer;
+    private viewMatrixBuffer;
+    private depthsOutputBuffer;
+    private splatCount;
+    private faceCount;
+    private usesExternalFaceGeometryBuffer;
+    constructor(device: GPUDevice);
+    /**
+     * 初始化Pipeline
+     */
+    initialize(): Promise<void>;
+    /**
+     * 上传Original Splats (一次性调用)
+     * @param originalSplatsData Float32Array, 每个splat 16 floats (64 bytes)
+     * @param splatCount splat数量
+     */
+    uploadOriginalSplats(originalSplatsData: Float32Array, splatCount: number): void;
+    /**
+     * 🆕 设置外部 GPU FaceGeometry Buffer（GPU FLAME 路径）
+     * @param externalBuffer 外部 GPU buffer（来自 FLAME Pipeline 的 faceGeometriesBuffer）
+     * @param faceCount face 数量
+     */
+    setFaceGeometryBufferFromGPU(externalBuffer: GPUBuffer, faceCount: number): void;
+    /**
+     * 更新Face Geometry Buffer (每帧调用) - CPU 路径
+     * @param faceGeometryData Float32Array, 每个face 8 floats (32 bytes)
+     */
+    updateFaceGeometry(faceGeometryData: Float32Array): void;
+    /**
+     * 执行Transform计算 (在给定的command encoder中)
+     * @param commandEncoder 外部command encoder (与render共享以保证顺序)
+     */
+    executeInEncoder(commandEncoder: GPUCommandEncoder): void;
+    /**
+     * 获取Transformed Output Buffer (供渲染器使用)
+     */
+    getTransformedOutputBuffer(): GPUBuffer | null;
+    /**
+     * 🚀 获取Positions Output Buffer (供排序使用)
+     */
+    getPositionsOutputBuffer(): GPUBuffer | null;
+    /**
+     * 🆕 获取Depths Output Buffer (供GPU排序使用)
+     */
+    getDepthsOutputBuffer(): GPUBuffer | null;
+    /**
+     * 🆕 更新View Matrix (每帧调用)
+     * @param viewMatrix 4x4 view matrix
+     */
+    updateViewMatrix(viewMatrix: Float32Array): void;
+    /**
+     * 获取Splat数量
+     */
+    getSplatCount(): number;
+    /**
+     * 创建Transformed Output Buffer
+     * 格式: position[3] + color[4] + covariance[6] = 13 floats = 52 bytes
+     */
+    private createTransformedOutputBuffer;
+    /**
+     * 🚀 创建Positions Output Buffer (用于排序)
+     * 格式: position[3] = 3 floats = 12 bytes per splat
+     */
+    private createPositionsOutputBuffer;
+    /**
+     * 🆕 创建View Matrix Buffer
+     */
+    private createViewMatrixBuffer;
+    /**
+     * 🆕 创建Depths Output Buffer (用于GPU排序)
+     * 格式: depth (Uint32) = 4 bytes per splat
+     */
+    private createDepthsOutputBuffer;
+    /**
+     * 创建Bind Group
+     */
+    private createBindGroup;
+    /**
+     * 清理资源
+     */
+    destroy(): void;
+}

package/dist/renderer/webgpu/webgpuRenderer.d.ts

@@ -1,4 +1,5 @@
 import { I3DGSRenderer, Transform } from '../renderer';
+import { FLAMETemplateData, FLAMEFrameParams, ActiveShapeParams } from './flameGPUBuffers';
 export declare class WebGPURenderer implements I3DGSRenderer {
     private canvas;
     private backgroundColor;
@@ -13,6 +14,13 @@ export declare class WebGPURenderer implements I3DGSRenderer {
     private splatDataBuffer;
     private storageBindGroup;
     private bindGroupNeedsUpdate;
+    private transformPipeline;
+    private useGPUTransform;
+    private flamePipeline;
+    private flameGPUBuffers;
+    private useGPUFLAME;
+    private gpuRadixSort;
+    private useGPURadixSort;
     private splatCount;
     private presentationFormat;
     private alpha;
@@ -56,10 +64,54 @@ export declare class WebGPURenderer implements I3DGSRenderer {
      * 🚀 完全消除 CPU 重排序开销
      */
     loadSplatsFromPackedData(packedData: Float32Array, pointCount: number, sortOrder?: Uint32Array): void;
+    /**
+     * 🆕 上传原始Splats数据到GPU (一次性调用，角色加载时)
+     * @param originalSplatsData Float32Array, 每个splat 16 floats (64 bytes)
+     * @param splatCount splat数量
+     */
+    loadOriginalSplats(originalSplatsData: Float32Array, splatCount: number): void;
+    /**
+     * 🆕 更新Face Geometry (每帧调用，用于GPU Transform优化)
+     * @param faceGeometryData Float32Array, 每个face 8 floats (32 bytes)
+     */
+    updateFaceGeometry(faceGeometryData: Float32Array): void;
+    /**
+     * 🆕 加载 FLAME 模板数据到 GPU (一次性调用，角色加载时)
+     * @param templateData FLAME 模板数据
+     * @param shapeParams Shape 参数 [300]
+     * @param activeShapeParams 活跃shape参数（零参数过滤优化，可选）
+     */
+    loadFLAMETemplateData(templateData: FLAMETemplateData, shapeParams: Float32Array, activeShapeParams?: ActiveShapeParams): void;
+    /**
+     * 🆕 更新 FLAME 帧参数 (每帧调用)
+     * @param frameParams FLAME 帧参数
+     */
+    updateFLAMEFrameParams(frameParams: FLAMEFrameParams): void;
+    /**
+     * 🆕 获取是否使用 GPU Transform 路径
+     */
+    getUseGPUTransform(): boolean;
+    /**
+     * 🆕 获取是否使用 GPU FLAME 路径
+     */
+    getUseGPUFLAME(): boolean;
+    /**
+     * 🆕 使用Face Geometry渲染 (GPU Transform优化路径)
+     * 数据流: Face Geometry → GPU Transform → Render
+     *
+     * 支持两种模式：
+     * 1. CPU FLAME 路径：传入 faceGeometryData（从 CPU 计算）
+     * 2. GPU FLAME 路径：传入 frameParams（在 GPU 上计算 FLAME）
+     */
+    renderWithFaceGeometry(faceGeometryDataOrFrameParams: Float32Array | FLAMEFrameParams, viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number], transform?: Transform): Promise<void>;
     /**
      * 渲染一帧
      */
     render(viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number], transform?: Transform): void;
+    /**
+     * 🆕 渲染逻辑（提取为独立方法，供Transform和传统路径共用）
+     */
+    private renderWithCommandEncoder;
     /**
      * 将 render texture 绘制到屏幕（应用 transform）
      */
@@ -72,6 +124,11 @@ export declare class WebGPURenderer implements I3DGSRenderer {
      * 更新背景颜色
      */
     updateBackgroundColor(backgroundColor: [number, number, number, number]): void;
+    /**
+     * 🔍 关键修复：从GPU读取transform后的positions，进行深度排序，更新sortIndexBuffer
+     * 这解决了第一帧GPU路径渲染异常的问题（未排序导致渲染顺序错误）
+     */
+    private updateSortIndexFromGPU;
     /**
      * 清理资源
      */

package/dist/types/index.d.ts

@@ -3,8 +3,7 @@
  */
 export declare enum Environment {
     cn = "cn",
-    intl = "intl",
-    test = "test"
+    intl = "intl"
 }
 export declare enum DrivingServiceMode {
     /** Driven by SDK directly */

package/dist/wasm/avatarCoreAdapter.d.ts

@@ -74,4 +74,53 @@ export declare class AvatarCoreAdapter {
      */
     releaseCurrentCharacter(): void;
     load3DGSData(_original3DGSPoints: any, _binding: any, _flameFaces: any): Promise<boolean>;
+    /**
+     * 🆕 GPU 路径: 计算帧并返回 Face Geometry 数据
+     */
+    computeFrameAsFaceGeometry(params?: {
+        frameIndex?: number;
+        characterId?: string;
+    }): Promise<Float32Array | null>;
+    /**
+     * 🆕 获取原始3DGS点数据 (一次性调用)
+     */
+    getOriginalSplatsData(): Promise<{
+        data: Float32Array;
+        count: number;
+    } | null>;
+    /**
+     * 🆕 获取角色 Shape 参数
+     */
+    getCharacterShapeParams(characterId?: string): Promise<{
+        params: number[];
+    } | null>;
+    /**
+     * 🆕 获取 FLAME 模板数据（用于 GPU FLAME Pipeline）
+     */
+    getFLAMETemplateData(characterId?: string): Promise<FLAMETemplateData | null>;
+}
+export interface FLAMETemplateData {
+    vTemplate: Float32Array;
+    vertexCount: number;
+    shapedirs: Float32Array;
+    shapeParamCount: number;
+    posedirs: Float32Array;
+    poseParamCount: number;
+    jRegressor: Float32Array;
+    jointCount: number;
+    lbsWeights: Float32Array;
+    parents: Int32Array;
+    faces: Uint32Array;
+    faceCount: number;
+    staticOffset: Float32Array | null;
+    staticOffsetCount: number;
+}
+export interface FLAMEIntermediateResults {
+    vShaped: Float32Array | null;
+    vPosed: Float32Array | null;
+    joints: Float32Array | null;
+    jointTransforms: Float32Array | null;
+    vDeformed: Float32Array | null;
+    vertexCount: number;
+    jointCount: number;
 }

package/dist/wasm/avatarCoreMemory.d.ts

@@ -108,6 +108,19 @@ export declare class AvatarCoreMemoryManager {
      * ⚠️ 使用 getValue 逐个读取，避免动态内存的 HEAPF32 detachment 问题
      */
     readSplatPointFlatArray(arrayPtr: number): Float32Array | null;
+    /**
+     * 🆕 读取 AvatarFaceGeometryArray 结构体数据 (WebGPU优化路径)
+     * 每个Face Geometry: center[3] + scale + quat[4] = 8 floats
+     */
+    readFaceGeometryArray(arrayPtr: number): Float32Array | null;
+    /**
+     * 🆕 读取 AvatarOriginalSplatArray 结构体数据 (WebGPU优化路径)
+     * 每个Original Splat: 15 floats + 1 int32 = 64 bytes
+     */
+    readOriginalSplatArray(arrayPtr: number): {
+        data: Float32Array;
+        count: number;
+    } | null;
     /**
      * 读取AvatarMeshData结构体数据
      */

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.76",
+  "version": "1.0.0-beta.77",
+  "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
   "author": "AvatarKit Team",
   "license": "MIT",
@@ -37,6 +38,17 @@
     "vite.js",
     "vite.d.ts"
   ],
+  "scripts": {
+    "build": "SDK_BUILD=true vite build --mode library && npm run build:vite-plugin",
+    "build:vite-plugin": "tsc vite.ts --outDir . --module esnext --target es2020 --moduleResolution bundler --esModuleInterop --skipLibCheck --declaration --declarationMap",
+    "dev": "vite build --mode library --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "cd tests && pnpm test",
+    "test:watch": "cd tests && pnpm run test:watch",
+    "test:e2e": "cd tests && pnpm run test:e2e",
+    "test:perf": "cd tests && pnpm run test:perf"
+  },
   "peerDependencies": {
     "@webgpu/types": "*",
     "vite": "^5.0.0"
@@ -54,16 +66,5 @@
     "typescript": "^5.0.0",
     "vite": "^5.0.0",
     "vite-plugin-dts": "^4.5.4"
-  },
-  "scripts": {
-    "build": "SDK_BUILD=true vite build --mode library && npm run build:vite-plugin",
-    "build:vite-plugin": "tsc vite.ts --outDir . --module esnext --target es2020 --moduleResolution bundler --esModuleInterop --skipLibCheck --declaration --declarationMap",
-    "dev": "vite build --mode library --watch",
-    "clean": "rm -rf dist",
-    "typecheck": "tsc --noEmit",
-    "test": "cd tests && pnpm test",
-    "test:watch": "cd tests && pnpm run test:watch",
-    "test:e2e": "cd tests && pnpm run test:e2e",
-    "test:perf": "cd tests && pnpm run test:perf"
   }
-}
+}