《游戏引擎实现原理》3.3 蒙皮集成与性能基准

// file: src/subsys/anim/skinning.ts
// tier: L1
// verify: npx vitest run src/subsys/anim/skinning.test.ts
//
// helio 子系统卷 3.3：CPU 线性混合蒙皮（LBS）参考实现。每个顶点携带 4 组
// 「关节下标 + 权重」，变形位置 = Σ wⱼ · (skinⱼ · p)。这份 CPU 版既是最小 glTF
// 骨骼模型的正确性基准，也是 3.3 性能对照里的「慢的那一侧」。

import { type Mat4 } from '../../core/mat4.ts';
import {
  computeGlobalMatrices,
  defaultLocalPose,
  invertRigid,
  type Joint,
  type LocalPose,
  type Skeleton,
} from './skeleton.ts';

export interface SkinnedMesh {
  readonly positions: Float32Array;
  readonly joints: Uint16Array;
  readonly weights: Float32Array;
  readonly vertexCount: number;
}

/**
 * CPU 线性混合蒙皮：把每个顶点按 4 组关节权重加权求和。
 * out 与 mesh.positions 同长；返回 out。零权重跳过，是这里唯一的优化。
 */
export function skinVerticesCPU(
  mesh: SkinnedMesh,
  skinMatrices: readonly Mat4[],
  out: Float32Array = new Float32Array(mesh.positions.length),
): Float32Array {
  const { positions, joints, weights, vertexCount } = mesh;
  for (let v = 0; v < vertexCount; v++) {
    const x = positions[v * 3]!;
    const y = positions[v * 3 + 1]!;
    const z = positions[v * 3 + 2]!;
    let px = 0;
    let py = 0;
    let pz = 0;
    for (let k = 0; k < 4; k++) {
      const w = weights[v * 4 + k]!;
      if (w === 0) continue;
      const m = skinMatrices[joints[v * 4 + k]!]!;
      px += w * (m[0]! * x + m[4]! * y + m[8]! * z + m[12]!);
      py += w * (m[1]! * x + m[5]! * y + m[9]! * z + m[13]!);
      pz += w * (m[2]! * x + m[6]! * y + m[10]! * z + m[14]!);
    }
    out[v * 3] = px;
    out[v * 3 + 1] = py;
    out[v * 3 + 2] = pz;
  }
  return out;
}

/** 静态网格变换：每个顶点只乘一个模型矩阵。这是蒙皮对照里的「快的那一侧」。 */
export function transformPositions(
  positions: Float32Array,
  m: Mat4,
  out: Float32Array = new Float32Array(positions.length),
): Float32Array {
  const n = positions.length / 3;
  for (let v = 0; v < n; v++) {
    const x = positions[v * 3]!;
    const y = positions[v * 3 + 1]!;
    const z = positions[v * 3 + 2]!;
    out[v * 3] = m[0]! * x + m[4]! * y + m[8]! * z + m[12]!;
    out[v * 3 + 1] = m[1]! * x + m[5]! * y + m[9]! * z + m[13]!;
    out[v * 3 + 2] = m[2]! * x + m[6]! * y + m[10]! * z + m[14]!;
  }
  return out;
}

/**
 * 造一条沿 +Y 的关节链：第 j 个关节相对父关节平移 (0, segLen, 0)。
 * 返回骨骼与绑定姿态（绑定姿态即局部平移本身，无旋转、单位缩放）。
 */
export function buildChainSkeleton(jointCount: number, segLen: number): { skeleton: Skeleton; bindPose: LocalPose } {
  const bindPose = defaultLocalPose(jointCount);
  for (let j = 0; j < jointCount; j++) {
    bindPose.translation[j * 3 + 1] = j === 0 ? 0 : segLen;
  }
  // 先用占位 inverseBind 建骨架，再用绑定姿态的全局矩阵求逆填回
  const joints: Joint[] = [];
  for (let j = 0; j < jointCount; j++) {
    joints.push({ name: `j${j}`, parent: j === 0 ? -1 : j - 1, inverseBind: new Float32Array(16) });
  }
  const bindGlobals = computeGlobalMatrices({ joints }, bindPose);
  for (let j = 0; j < jointCount; j++) {
    joints[j] = { name: `j${j}`, parent: j === 0 ? -1 : j - 1, inverseBind: invertRigid(bindGlobals[j]!) };
  }
  return { skeleton: { joints }, bindPose };
}

/**
 * 沿关节链生成一条竖直窄带网格：顶点均匀分布在 [0, chainLength]，
 * 每个顶点把权重摊给最近的上下两个关节（线性混合）。
 * 这是最小可蒙皮模型——弯曲任一关节，窄带对应段随之弯折。
 */
export function buildStripMesh(jointCount: number, segLen: number, verts: number): SkinnedMesh {
  const chainLen = (jointCount - 1) * segLen;
  const positions = new Float32Array(verts * 3);
  const joints = new Uint16Array(verts * 4);
  const weights = new Float32Array(verts * 4);
  for (let v = 0; v < verts; v++) {
    const u = verts === 1 ? 0 : v / (verts - 1);
    const y = u * chainLen;
    positions[v * 3] = 0;
    positions[v * 3 + 1] = y;
    positions[v * 3 + 2] = 0;
    const f = segLen > 0 ? y / segLen : 0;
    const j0 = Math.min(jointCount - 1, Math.max(0, Math.floor(f)));
    const j1 = Math.min(jointCount - 1, j0 + 1);
    const frac = j0 === j1 ? 0 : Math.min(1, Math.max(0, f - j0));
    joints[v * 4] = j0;
    joints[v * 4 + 1] = j1;
    weights[v * 4] = 1 - frac;
    weights[v * 4 + 1] = frac;
  }
  return { positions, joints, weights, vertexCount: verts };
}

// file: shaders/skinning.wgsl
// tier: L2
// verify: node tools/run-l2-ch3.mjs src/subsys/anim/skinning-l2.ts
// helio 子系统卷 3.3：GPU 蒙皮。同一段 LBS 数学（skin_one）被两条路径复用——
// compute 路径把全部顶点算进 storage buffer 供精确回读，渲染路径在顶点着色器里
// 直接蒙皮后光栅化。skin_mats 是每帧由 CPU 算好的 skin[i] = global[i]·invBind[i]。

struct SkinU { count: u32, _pad0: u32, _pad1: u32, _pad2: u32 };
struct ViewU { scale: f32, offset_y: f32, half_width: f32, _pad: f32 };

@group(0) @binding(0) var<storage, read> skin_mats: array<mat4x4<f32>>;
// 注意：WGSL 里 array<vec3<f32>> 的元素步长是 16 字节（对齐到 16），不是 12。
// 为免踩坑，位置统一用 vec4 承载，w 分量留空。
@group(0) @binding(1) var<storage, read> src_pos: array<vec4<f32>>;
@group(0) @binding(2) var<storage, read> src_joints: array<vec4<u32>>;
@group(0) @binding(3) var<storage, read> src_weights: array<vec4<f32>>;
@group(0) @binding(4) var<storage, read_write> dst_pos: array<vec4<f32>>;
@group(0) @binding(5) var<uniform> su: SkinU;
@group(0) @binding(6) var<uniform> view: ViewU;

// 线性混合蒙皮：Σ wⱼ · (skinⱼ · p)。4 组影响权重由导入器保证归一。
fn skin_one(p: vec3<f32>, j: vec4<u32>, w: vec4<f32>) -> vec3<f32> {
  var acc = vec3<f32>(0.0);
  acc += w.x * (skin_mats[j.x] * vec4<f32>(p, 1.0)).xyz;
  acc += w.y * (skin_mats[j.y] * vec4<f32>(p, 1.0)).xyz;
  acc += w.z * (skin_mats[j.z] * vec4<f32>(p, 1.0)).xyz;
  acc += w.w * (skin_mats[j.w] * vec4<f32>(p, 1.0)).xyz;
  return acc;
}

@compute @workgroup_size(64)
fn skin_compute(@builtin(global_invocation_id) gid: vec3<u32>) {
  let i = gid.x;
  if (i >= su.count) { return; }
  dst_pos[i] = vec4<f32>(skin_one(src_pos[i].xyz, src_joints[i], src_weights[i]), 0.0);
}

// 渲染路径：顶点属性直接带 pos / joints / weights，顶点着色器里蒙皮后投影到 NDC。
struct VOut { @builtin(position) pos: vec4<f32>, @location(0) tint: f32 };
@vertex
fn vs_skin(
  @location(0) p: vec3<f32>,
  @location(1) j: vec4<u32>,
  @location(2) w: vec4<f32>,
) -> VOut {
  let sp = skin_one(p, j, w);
  var o: VOut;
  o.pos = vec4<f32>(sp.x / view.half_width, sp.y * view.scale + view.offset_y, 0.0, 1.0);
  o.tint = f32(j.x) / 8.0;
  return o;
}

@fragment
fn fs_skin(in: VOut) -> @location(0) vec4<f32> {
  return vec4<f32>(in.tint, 1.0 - in.tint, 0.5, 1.0);
}

PASS  wgsl 0 error  0
PASS  GPU 蒙皮与 CPU LBS 一致  4.77e-7
PASS  绑定姿态下 GPU 蒙皮复现原顶点  4.77e-7
PASS  弯关节后 GPU 仍与 CPU 一致  4.77e-7
PASS  弯关节确实改变了顶点位置  2.598
PASS  渲染路径画出几何（绑定姿态有覆盖）  768
PASS  弯关节后渲染画面改变  1629

档位        中位数(ms)   每顶点(ns)   相对静态
静态变换     0.85         4.3          1.0×
蒙皮 1 影响  2.36         11.8         2.8×
蒙皮 4 影响  5.37         26.9         6.3×

关节数    调色板构建(ms)   调色板字节
16        0.010            1024
64        0.015            4096
256       0.058            16384