《游戏引擎实现原理》3.2 队列提交、帧同步与 fence

// file: src/render/frame/frame-sync.ts
// tier: L1
// verify: npx vitest run src/render/frame/frame-sync.test.ts
//
// helio 渲染帧循环：GPU 与 CPU 的同步点。
// FrameRing 记录「哪些帧还在 GPU 上飞」，容量 = 最大在飞帧数；
// 用确定性时间线模拟「每帧 await」与「流水线」两种策略的吞吐差异。

export interface FrameCosts {
  readonly cpuRecordMs: number;
  readonly gpuMs: number;
}

export interface FrameTiming {
  readonly frame: number;
  readonly cpuStart: number;
  readonly cpuEnd: number;
  readonly gpuStart: number;
  readonly gpuEnd: number;
}

export class FrameSyncError extends Error {}

/**
 * 在飞帧的环形登记表。容量 = 允许同时「已提交但未完成」的帧数。
 * acquire 返回可复用的槽位；若所有槽位都在飞，抛错——这正对应
 * 真实循环里「必须等 onSubmittedWorkDone 才能继续录制」的时刻。
 */
export class FrameRing {
  readonly #capacity: number;
  readonly #slotFrame: number[];
  #nextFrame = 0;

  constructor(capacity: number) {
    if (capacity < 1) throw new FrameSyncError('capacity 至少为 1');
    this.#capacity = capacity;
    this.#slotFrame = new Array<number>(capacity).fill(-1);
  }

  /** 申请一个新帧的槽位；满员则抛错（调用方应在此处等待）。 */
  acquire(): number {
    const slot = this.#nextFrame % this.#capacity;
    const occupant = this.#slotFrame[slot];
    if (occupant !== -1) {
      throw new FrameSyncError(`槽位 ${slot} 仍被帧 ${occupant} 占用，需等待 onSubmittedWorkDone`);
    }
    const frame = this.#nextFrame;
    this.#slotFrame[slot] = frame;
    this.#nextFrame += 1;
    return slot;
  }

  /** 该帧的工作已提交到队列，进入「在飞」。 */
  markSubmitted(frame: number): void {
    const slot = frame % this.#capacity;
    if (this.#slotFrame[slot] !== frame) {
      throw new FrameSyncError(`帧 ${frame} 未占用槽位 ${slot}`);
    }
  }

  /** onSubmittedWorkDone 触发：该帧的 GPU 工作完成，槽位可复用。 */
  markRetired(frame: number): void {
    const slot = frame % this.#capacity;
    if (this.#slotFrame[slot] !== frame) {
      throw new FrameSyncError(`帧 ${frame} 不在槽位 ${slot} 上，无法回收`);
    }
    this.#slotFrame[slot] = -1;
  }

  get inFlight(): number {
    return this.#slotFrame.filter((f) => f !== -1).length;
  }
}

/**
 * 策略 A：每帧 await onSubmittedWorkDone。CPU 录完一帧后阻塞，
 * 等 GPU 跑完才录下一帧，CPU 与 GPU 完全串行。
 */
export function simulateSerial(costs: FrameCosts, frames: number): FrameTiming[] {
  const out: FrameTiming[] = [];
  let clock = 0;
  for (let f = 0; f < frames; f++) {
    const cpuStart = clock;
    const cpuEnd = cpuStart + costs.cpuRecordMs;
    const gpuStart = cpuEnd;
    const gpuEnd = gpuStart + costs.gpuMs;
    out.push({ frame: f, cpuStart, cpuEnd, gpuStart, gpuEnd });
    clock = gpuEnd;
  }
  return out;
}

/**
 * 策略 B：最多 maxInFlight 帧在飞，不逐帧 await。CPU 录下一帧的同时
 * GPU 仍在跑上一帧，两级流水线重叠。
 */
export function simulatePipelined(
  costs: FrameCosts,
  frames: number,
  maxInFlight: number,
): FrameTiming[] {
  if (maxInFlight < 2) throw new FrameSyncError('流水线需要 maxInFlight >= 2');
  const out: FrameTiming[] = [];
  let cpuFree = 0;
  let gpuFree = 0;
  for (let f = 0; f < frames; f++) {
    // CPU 是单线程资源：上一帧录完才能录这一帧；若在飞帧数达到上限，
    // 还要等最老的帧在 GPU 上退役（f - maxInFlight 的 gpuEnd）。
    const gate = f >= maxInFlight ? out[f - maxInFlight].gpuEnd : 0;
    const cpuStart = Math.max(cpuFree, gate);
    const cpuEnd = cpuStart + costs.cpuRecordMs;
    const gpuStart = Math.max(cpuEnd, gpuFree);
    const gpuEnd = gpuStart + costs.gpuMs;
    out.push({ frame: f, cpuStart, cpuEnd, gpuStart, gpuEnd });
    cpuFree = cpuEnd;
    gpuFree = gpuEnd;
  }
  return out;
}

/** 整条时间线的墙钟耗时（最后一帧 GPU 结束时刻）。 */
export function wallClock(timings: readonly FrameTiming[]): number {
  return timings.length === 0 ? 0 : timings[timings.length - 1].gpuEnd;
}

// file: src/render/frame/frame-sync.test.ts
// tier: L1
// verify: npx vitest run src/render/frame/frame-sync.test.ts
import { describe, expect, it } from 'vitest';
import {
  FrameRing,
  FrameSyncError,
  simulatePipelined,
  simulateSerial,
  wallClock,
} from './frame-sync.ts';

describe('FrameRing', () => {
  it('容量内可连续 acquire', () => {
    const ring = new FrameRing(3);
    expect(ring.acquire()).toBe(0);
    expect(ring.acquire()).toBe(1);
    expect(ring.acquire()).toBe(2);
    expect(ring.inFlight).toBe(3);
  });

  it('满员时 acquire 抛错（这就是同步点）', () => {
    const ring = new FrameRing(2);
    ring.acquire();
    ring.acquire();
    expect(() => ring.acquire()).toThrow(/需等待 onSubmittedWorkDone/);
  });

  it('退役后槽位可复用', () => {
    const ring = new FrameRing(2);
    ring.acquire(); // frame 0 -> slot 0
    ring.acquire(); // frame 1 -> slot 1
    ring.markRetired(0);
    expect(ring.inFlight).toBe(1);
    expect(ring.acquire()).toBe(0); // frame 2 复用 slot 0
    expect(ring.inFlight).toBe(2);
  });

  it('回收未占用的帧会报错', () => {
    const ring = new FrameRing(2);
    expect(() => ring.markRetired(5)).toThrow(FrameSyncError);
  });

  it('容量必须为正', () => {
    expect(() => new FrameRing(0)).toThrow(/至少为 1/);
  });
});

describe('同步策略吞吐对比', () => {
  const costs = { cpuRecordMs: 2, gpuMs: 8 };

  it('每帧 await 时 CPU 与 GPU 完全串行', () => {
    const t = simulateSerial(costs, 5);
    expect(wallClock(t)).toBe(5 * (2 + 8)); // 50
    // 相邻帧不重叠：下一帧 cpuStart 等于上一帧 gpuEnd。
    expect(t[1].cpuStart).toBe(t[0].gpuEnd);
  });

  it('流水线把 CPU 录制藏进 GPU 执行', () => {
    const t = simulatePipelined(costs, 5, 3);
    // 理想两级流水线：首帧满额 (cpu+gpu)，其后每帧只加 gpu。
    expect(wallClock(t)).toBe(2 + 8 + 4 * 8); // 42
    expect(wallClock(t)).toBeLessThan(wallClock(simulateSerial(costs, 5)));
    // 帧 1 的 GPU 起点不早于帧 0 的 GPU 终点（GPU 串行）。
    expect(t[1].gpuStart).toBeGreaterThanOrEqual(t[0].gpuEnd);
  });

  it('在飞上限小于 2 时流水线不成立', () => {
    expect(() => simulatePipelined(costs, 3, 1)).toThrow(/maxInFlight >= 2/);
  });
});