《游戏引擎实现原理》8.2 矩阵、行/列主序与左/右手坐标系

// file: src/core/mat4.ts
// tier: L1
// verify: npx vitest run src/core/mat4.test.ts
//
// helio 内核：4x4 矩阵。存储采用 WebGPU / WGSL 的约定——列主序（column-major），
// 即逻辑上第 c 列第 r 行落在 data[c * 4 + r]。这个约定和「把 16 个数按行读」的
// 直觉相反，是本文件最容易出错的地方。

/** 列主序 4x4 矩阵：长度 16 的 Float32Array。 */
export type Mat4 = Float32Array;

export function identity(): Mat4 {
  const m = new Float32Array(16);
  m[0] = 1;
  m[5] = 1;
  m[10] = 1;
  m[15] = 1;
  return m;
}

export function fromTranslation(tx: number, ty: number, tz: number): Mat4 {
  const m = identity();
  m[12] = tx;
  m[13] = ty;
  m[14] = tz;
  return m;
}

export function fromScale(sx: number, sy: number, sz: number): Mat4 {
  const m = new Float32Array(16);
  m[0] = sx;
  m[5] = sy;
  m[10] = sz;
  m[15] = 1;
  return m;
}

/** out = a * b（列主序，作用于列向量：先应用 b，再应用 a）。out 不能与 a / b 同一块。 */
export function multiply(out: Mat4, a: Mat4, b: Mat4): Mat4 {
  for (let c = 0; c < 4; c++) {
    const b0 = b[c * 4 + 0]!;
    const b1 = b[c * 4 + 1]!;
    const b2 = b[c * 4 + 2]!;
    const b3 = b[c * 4 + 3]!;
    out[c * 4 + 0] = a[0]! * b0 + a[4]! * b1 + a[8]! * b2 + a[12]! * b3;
    out[c * 4 + 1] = a[1]! * b0 + a[5]! * b1 + a[9]! * b2 + a[13]! * b3;
    out[c * 4 + 2] = a[2]! * b0 + a[6]! * b1 + a[10]! * b2 + a[14]! * b3;
    out[c * 4 + 3] = a[3]! * b0 + a[7]! * b1 + a[11]! * b2 + a[15]! * b3;
  }
  return out;
}

/** 用列主序矩阵变换一个点：结果 = 各列按 x / y / z / 1 加权求和。 */
export function transformPoint(m: Mat4, x: number, y: number, z: number): [number, number, number] {
  return [
    m[0]! * x + m[4]! * y + m[8]! * z + m[12]!,
    m[1]! * x + m[5]! * y + m[9]! * z + m[13]!,
    m[2]! * x + m[6]! * y + m[10]! * z + m[14]!,
  ];
}

/** 转置：把「列主序解释」与「行主序解释」互换。 */
export function transpose(m: Mat4): Mat4 {
  const t = new Float32Array(16);
  for (let c = 0; c < 4; c++) {
    for (let r = 0; r < 4; r++) {
      t[c * 4 + r] = m[r * 4 + c]!;
    }
  }
  return t;
}

/** 把 16 个数按「第 0 行、第 1 行……」的顺序列出（行主序读法），用于和存储顺序对照。 */
export function toRowMajorNumbers(m: Mat4): number[] {
  const out: number[] = [];
  for (let r = 0; r < 4; r++) {
    for (let c = 0; c < 4; c++) {
      out.push(m[c * 4 + r]!);
    }
  }
  return out;
}

// file: src/core/mat4.test.ts
// tier: L1
// verify: npx vitest run src/core/mat4.test.ts

import { describe, expect, it } from 'vitest';
import {
  fromScale,
  fromTranslation,
  identity,
  multiply,
  toRowMajorNumbers,
  transformPoint,
  transpose,
} from './mat4.ts';

describe('列主序矩阵', () => {
  it('单位阵不动点', () => {
    expect(transformPoint(identity(), 3, 4, 5)).toEqual([3, 4, 5]);
  });

  it('平移矩阵作用在点上', () => {
    expect(transformPoint(fromTranslation(10, 20, 30), 1, 2, 3)).toEqual([11, 22, 33]);
  });

  it('复合顺序：先缩放后平移', () => {
    const m = multiply(identity(), fromTranslation(10, 20, 30), fromScale(2, 3, 4));
    expect(transformPoint(m, 1, 1, 1)).toEqual([12, 23, 34]);
  });

  it('交换顺序结果不同', () => {
    const ts = multiply(identity(), fromTranslation(10, 20, 30), fromScale(2, 3, 4));
    const st = multiply(identity(), fromScale(2, 3, 4), fromTranslation(10, 20, 30));
    expect(transformPoint(ts, 1, 1, 1)).toEqual([12, 23, 34]);
    expect(transformPoint(st, 1, 1, 1)).toEqual([22, 63, 124]);
  });

  it('转置陷阱：同一组数字两种解释给出不同点', () => {
    const m = multiply(identity(), fromTranslation(10, 20, 30), fromScale(2, 3, 4));
    const asColumn = transformPoint(m, 1, 1, 1); // 列主序解释：正确
    const asRow = transformPoint(transpose(m), 1, 1, 1); // 行主序解释：错误
    expect(asColumn).toEqual([12, 23, 34]);
    expect(asRow).not.toEqual(asColumn);
  });

  it('行主序读法与列主序存储的排列差异', () => {
    const m = multiply(identity(), fromTranslation(10, 20, 30), fromScale(2, 3, 4));
    expect([...m]).toEqual([2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 4, 0, 10, 20, 30, 1]);
    expect(toRowMajorNumbers(m)).toEqual([2, 0, 0, 10, 0, 3, 0, 20, 0, 0, 4, 30, 0, 0, 0, 1]);
  });
});