《游戏引擎实现原理》3.3 三缓冲与资源生命周期

// file: src/render/resource/uniform-ring.ts
// tier: L1
// verify: npx vitest run src/render/resource/uniform-ring.test.ts
//
// helio 资源层：环形分配的三缓冲 uniform 池。
// GPU 可能还在读帧 N 的 uniform，而 CPU 已在写帧 N+1。环形池给每帧
// 一份独立槽位，并在「复用仍在飞的槽位」时直接报错，把覆盖在飞资源
// 这个竞态从线上黑屏变成一条确定性的异常。

export class UniformRingError extends Error {}

export class UniformRing {
  readonly capacity: number;
  readonly slotFloats: number;
  readonly #store: Float32Array;
  readonly #slotFrame: number[];
  readonly #inflight = new Set<number>();

  constructor(capacity: number, slotFloats: number) {
    if (capacity < 2) throw new UniformRingError('三缓冲至少需要 2 份槽位');
    if (slotFloats < 1) throw new UniformRingError('slotFloats 至少为 1');
    this.capacity = capacity;
    this.slotFloats = slotFloats;
    this.#store = new Float32Array(capacity * slotFloats);
    this.#slotFrame = new Array<number>(capacity).fill(-1);
  }

  /** 取帧 frame 的槽位；若该槽位仍被在飞帧占用则报错。 */
  acquire(frame: number): number {
    const slot = frame % this.capacity;
    const occupant = this.#slotFrame[slot];
    if (occupant !== -1 && this.#inflight.has(occupant)) {
      throw new UniformRingError(
        `槽位 ${slot} 仍被在飞帧 ${occupant} 占用，帧 ${frame} 若写入会覆盖它`,
      );
    }
    this.#slotFrame[slot] = frame;
    return slot;
  }

  /** 写入该槽位。写入前必须先 acquire，且槽位属于 frame。 */
  write(frame: number, values: readonly number[]): void {
    const slot = frame % this.capacity;
    if (this.#slotFrame[slot] !== frame) {
      throw new UniformRingError(`帧 ${frame} 尚未 acquire 槽位 ${slot}`);
    }
    if (values.length !== this.slotFloats) {
      throw new UniformRingError(`期望 ${this.slotFloats} 个 float，实得 ${values.length}`);
    }
    this.#store.set(values, slot * this.slotFloats);
  }

  /** 读回某帧的槽位内容（拷贝），用于断言。 */
  read(frame: number): Float32Array {
    const slot = frame % this.capacity;
    const base = slot * this.slotFloats;
    return this.#store.slice(base, base + this.slotFloats);
  }

  markSubmitted(frame: number): void {
    this.#inflight.add(frame);
  }

  markRetired(frame: number): void {
    if (!this.#inflight.delete(frame)) {
      throw new UniformRingError(`帧 ${frame} 不在飞，无法退役`);
    }
  }

  get inFlight(): number {
    return this.#inflight.size;
  }
}

// file: src/render/resource/uniform-ring.test.ts
// tier: L1
// verify: npx vitest run src/render/resource/uniform-ring.test.ts
import { describe, expect, it } from 'vitest';
import { UniformRing, UniformRingError } from './uniform-ring.ts';

describe('UniformRing', () => {
  it('三份槽位让连续三帧互不覆盖', () => {
    const ring = new UniformRing(3, 2);
    for (let f = 0; f < 3; f++) {
      ring.acquire(f);
      ring.write(f, [f, f * 10]);
      ring.markSubmitted(f);
    }
    expect(Array.from(ring.read(0))).toEqual([0, 0]);
    expect(Array.from(ring.read(1))).toEqual([1, 10]);
    expect(Array.from(ring.read(2))).toEqual([2, 20]);
    expect(ring.inFlight).toBe(3);
  });

  it('两份槽位不够：第 3 帧会覆盖仍在飞的第 1 帧', () => {
    const ring = new UniformRing(2, 1);
    ring.acquire(0); ring.write(0, [100]); ring.markSubmitted(0);
    ring.acquire(1); ring.write(1, [200]); ring.markSubmitted(1);
    // 帧 2 想复用槽位 0，但帧 0 仍在飞。
    expect(() => ring.acquire(2)).toThrow(/仍被在飞帧 0 占用/);
  });

  it('退役后可安全复用，且不影响其它在飞槽位', () => {
    const ring = new UniformRing(3, 1);
    ring.acquire(0); ring.write(0, [1]); ring.markSubmitted(0);
    ring.acquire(1); ring.write(1, [2]); ring.markSubmitted(1);
    ring.acquire(2); ring.write(2, [3]); ring.markSubmitted(2);
    ring.markRetired(0); // 帧 0 的 GPU 读完，槽位 0 可复用
    const slot = ring.acquire(3); // frame 3 % 3 == 0
    expect(slot).toBe(0);
    ring.write(3, [99]);
    expect(Array.from(ring.read(3))).toEqual([99]);
    // 帧 1、2 的数据未被动过。
    expect(Array.from(ring.read(1))).toEqual([2]);
    expect(Array.from(ring.read(2))).toEqual([3]);
  });

  it('未 acquire 就写入会报错', () => {
    const ring = new UniformRing(3, 1);
    expect(() => ring.write(0, [1])).toThrow(UniformRingError);
  });

  it('写入长度不符会报错', () => {
    const ring = new UniformRing(3, 4);
    ring.acquire(0);
    expect(() => ring.write(0, [1, 2])).toThrow(/期望 4 个 float/);
  });

  it('退役未在飞的帧会报错', () => {
    const ring = new UniformRing(3, 1);
    expect(() => ring.markRetired(7)).toThrow(/不在飞/);
  });
});

// file: src/render/resource/uniform-ring-demo.ts
// tier: L1
// verify: node src/render/resource/uniform-ring-demo.ts
//
// 把 UniformRing 接进一个模拟帧循环：每帧先按 fence 退役最老的帧，
// 再 acquire + write 本帧槽位。用来演示「容量必须 >= 在飞帧数」。

import { UniformRing } from './uniform-ring.ts';

export interface FrameStep {
  readonly frame: number;
  readonly slot: number;
  readonly retired: number | null;
}

/**
 * 模拟 frames 帧：GPU 比 CPU 慢 lag 帧。
 * 每帧开始时，若帧 f-lag 已完成就退役它；然后 acquire 本帧槽位并写入。
 */
export function simulateRing(capacity: number, frames: number, lag: number): FrameStep[] {
  const ring = new UniformRing(capacity, 4);
  const steps: FrameStep[] = [];
  for (let f = 0; f < frames; f++) {
    const done = f - lag;
    let retired: number | null = null;
    if (done >= 0) {
      ring.markRetired(done);
      retired = done;
    }
    const slot = ring.acquire(f);
    ring.write(f, [f, f + 1, f + 2, f + 3]);
    ring.markSubmitted(f);
    steps.push({ frame: f, slot, retired });
  }
  return steps;
}

/** 跑一个场景并打印结果；容量不足时打印抛出的异常信息。 */
function report(capacity: number, lag: number): void {
  try {
    const steps = simulateRing(capacity, 6, lag);
    const slots = steps.map((s) => s.slot).join(',');
    const retired = steps.map((s) => (s.retired === null ? '-' : s.retired)).join(',');
    console.log(`capacity=${capacity} lag=${lag}: OK  slots=[${slots}]  retired=[${retired}]`);
  } catch (e) {
    console.log(`capacity=${capacity} lag=${lag}: THROW ${(e as Error).message}`);
  }
}

report(3, 2); // 三份槽位，GPU 落后 2 帧 —— 够用
report(2, 3); // 两份槽位，GPU 落后 3 帧 —— 槽位不够，报错

capacity=3 lag=2: OK  slots=[0,1,2,0,1,2]  retired=[-,-,0,1,2,3]
capacity=2 lag=3: THROW 槽位 0 仍被在飞帧 0 占用，帧 2 若写入会覆盖它