《游戏引擎实现原理》8.1 向量代数与 TypedArray 布局

// file: src/core/vec3.ts
// tier: L1
// verify: npx vitest run src/core/vec3.test.ts
//
// helio 内核：三维向量。两种存储视角并存——
// 标量元组 Vec3（易读、每次运算分配）与 Float32Array 上的连续布局（零分配、可批处理）。

/** 可读的向量表示：三元素只读元组。 */
export type Vec3 = readonly [number, number, number];

export const VEC3_ZERO: Vec3 = [0, 0, 0];
export const VEC3_ONE: Vec3 = [1, 1, 1];
export const VEC3_X: Vec3 = [1, 0, 0];
export const VEC3_Y: Vec3 = [0, 1, 0];
export const VEC3_Z: Vec3 = [0, 0, 1];

export function add(a: Vec3, b: Vec3): Vec3 {
  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
}

export function sub(a: Vec3, b: Vec3): Vec3 {
  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
}

export function scale(a: Vec3, s: number): Vec3 {
  return [a[0] * s, a[1] * s, a[2] * s];
}

export function dot(a: Vec3, b: Vec3): number {
  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
}

export function cross(a: Vec3, b: Vec3): Vec3 {
  return [
    a[1] * b[2] - a[2] * b[1],
    a[2] * b[0] - a[0] * b[2],
    a[0] * b[1] - a[1] * b[0],
  ];
}

export function length(a: Vec3): number {
  return Math.hypot(a[0], a[1], a[2]);
}

export function normalize(a: Vec3): Vec3 {
  const len = length(a);
  if (len === 0) return VEC3_ZERO;
  return [a[0] / len, a[1] / len, a[2] / len];
}

/** 把 a + b 写进 out[o..o+2]，不分配任何对象。 */
export function addInto(out: Float32Array, o: number, a: Vec3, b: Vec3): void {
  out[o] = a[0] + b[0];
  out[o + 1] = a[1] + b[1];
  out[o + 2] = a[2] + b[2];
}

/**
 * AoS（interleaved）：一个 Float32Array 里每 3 个 float 存一个向量，
 * 第 i 个向量的 x / y / z 分别落在下标 3i / 3i+1 / 3i+2。
 */
export class Vec3Store {
  readonly data: Float32Array;
  #count = 0;

  constructor(capacity: number) {
    this.data = new Float32Array(capacity * 3);
  }

  get count(): number {
    return this.#count;
  }

  push(v: Vec3): number {
    const i = this.#count++;
    const o = i * 3;
    this.data[o] = v[0];
    this.data[o + 1] = v[1];
    this.data[o + 2] = v[2];
    return i;
  }

  get(i: number): Vec3 {
    const o = i * 3;
    return [this.data[o]!, this.data[o + 1]!, this.data[o + 2]!];
  }

  /** 一次连续扫描算出所有向量的长度平方和——零分配。 */
  sumLengthSquared(): number {
    let sum = 0;
    const d = this.data;
    const end = this.#count * 3;
    for (let o = 0; o < end; o += 3) {
      sum += d[o]! * d[o]! + d[o + 1]! * d[o + 1]! + d[o + 2]! * d[o + 2]!;
    }
    return sum;
  }
}

/**
 * SoA：x / y / z 各占一条 Float32Array。
 * 只更新 x 分量的批量算法只碰 xs 一条数组，另外两条完全不进缓存。
 */
export class Vec3SoA {
  readonly xs: Float32Array;
  readonly ys: Float32Array;
  readonly zs: Float32Array;
  #count = 0;

  constructor(capacity: number) {
    this.xs = new Float32Array(capacity);
    this.ys = new Float32Array(capacity);
    this.zs = new Float32Array(capacity);
  }

  get count(): number {
    return this.#count;
  }

  push(v: Vec3): number {
    const i = this.#count++;
    this.xs[i] = v[0];
    this.ys[i] = v[1];
    this.zs[i] = v[2];
    return i;
  }

  get(i: number): Vec3 {
    return [this.xs[i]!, this.ys[i]!, this.zs[i]!];
  }

  sumLengthSquared(): number {
    let sum = 0;
    for (let i = 0; i < this.#count; i++) {
      sum += this.xs[i]! * this.xs[i]! + this.ys[i]! * this.ys[i]! + this.zs[i]! * this.zs[i]!;
    }
    return sum;
  }
}

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

import { describe, expect, it } from 'vitest';
import { Vec3SoA, Vec3Store, add, cross, dot, normalize, type Vec3 } from './vec3.ts';

const SAMPLES: Vec3[] = [
  [1, 0, 0],
  [0, 2, 0],
  [0, 0, 3],
  [1, 1, 1],
];

describe('vec3 标量运算', () => {
  it('点积与叉积', () => {
    expect(dot([1, 2, 3], [4, 5, 6])).toBe(32);
    expect(cross([1, 0, 0], [0, 1, 0])).toEqual([0, 0, 1]);
  });

  it('加法与归一化', () => {
    expect(add([1, 2, 3], [4, 5, 6])).toEqual([5, 7, 9]);
    const n = normalize([0, 0, 5]);
    expect(n[2]).toBeCloseTo(1, 6);
  });
});

describe('AoS / SoA 两种布局给出相同结果', () => {
  it('AoS 的 sumLengthSquared 为 17', () => {
    const s = new Vec3Store(SAMPLES.length);
    for (const v of SAMPLES) s.push(v);
    expect(s.sumLengthSquared()).toBe(17);
  });

  it('SoA 的 sumLengthSquared 同样为 17', () => {
    const s = new Vec3SoA(SAMPLES.length);
    for (const v of SAMPLES) s.push(v);
    expect(s.sumLengthSquared()).toBe(17);
  });

  it('两种布局总字节数相同', () => {
    const aos = new Vec3Store(4);
    const soa = new Vec3SoA(4);
    expect(aos.data.byteLength).toBe(48);
    expect(soa.xs.byteLength + soa.ys.byteLength + soa.zs.byteLength).toBe(48);
  });

  it('随机存取下标一致', () => {
    const aos = new Vec3Store(SAMPLES.length);
    const soa = new Vec3SoA(SAMPLES.length);
    for (const v of SAMPLES) {
      aos.push(v);
      soa.push(v);
    }
    expect(aos.get(3)).toEqual(soa.get(3));
  });
});