@forgeax/engine-render 0.1.2

package/src/gpu-scene.ts

@@ -0,0 +1,855 @@
+import type { Buffer, Result, RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-rhi';
+import {
+  GPU_SCENE_LAYOUTS,
+  GPU_SCENE_PRIMITIVE_FLAGS,
+  type GpuSceneTableLayout,
+  gpuSceneFieldOffset,
+  type SceneFactRevisionDomain,
+} from './gpu-scene-schema';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_STORAGE,
+} from './gpu-usage';
+import type {
+  RenderSceneApplyResult,
+  RenderSceneProjection,
+  RenderSceneProjectionSlot,
+  RenderSceneSubmissionDelta,
+  SpatialIndexInspection,
+} from './render-scene-projection';
+import type { RenderableTemporalSnapshot } from './render-system-extract';
+
+const PRIMITIVE = GPU_SCENE_LAYOUTS.primitive;
+const INSTANCE = GPU_SCENE_LAYOUTS.instance;
+const TRANSFORM = GPU_SCENE_LAYOUTS.transform;
+const DRAW_TEMPLATE = GPU_SCENE_LAYOUTS.drawTemplate;
+const MATERIAL = GPU_SCENE_LAYOUTS.material;
+const PRIMITIVE_ACTIVE = GPU_SCENE_PRIMITIVE_FLAGS.active;
+const PRIMITIVE_HAS_BOUNDS = GPU_SCENE_PRIMITIVE_FLAGS.hasBounds;
+const PRIMITIVE_GPU_DRIVEN = GPU_SCENE_PRIMITIVE_FLAGS.gpuDriven;
+const PRIMITIVE_STATIC = GPU_SCENE_PRIMITIVE_FLAGS.static;
+const PRIMITIVE_DYNAMIC = GPU_SCENE_PRIMITIVE_FLAGS.dynamic;
+const PRIMITIVE_CASTER_ELIGIBLE = GPU_SCENE_PRIMITIVE_FLAGS.casterEligible;
+const PRIMITIVE_CASTER_INELIGIBLE = GPU_SCENE_PRIMITIVE_FLAGS.casterIneligible;
+const PRIMITIVE_CASTER_UNKNOWN = GPU_SCENE_PRIMITIVE_FLAGS.casterUnknown;
+const ALL_SCENE_FACT_DOMAINS: readonly SceneFactRevisionDomain[] = [
+  'transform',
+  'geometry',
+  'material',
+  'eligibility',
+  'space',
+  'batch',
+  'resource',
+];
+const IDENTITY_MATRIX = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+interface GpuSceneBuffers {
+  readonly primitive: Buffer;
+  readonly instance: Buffer;
+  readonly transform: Buffer;
+  readonly drawTemplate: Buffer;
+  readonly material: Buffer;
+}
+
+interface PrimitiveAllocation {
+  readonly instanceStart: number;
+  readonly instanceCount: number;
+  readonly transformStart: number;
+  readonly drawStart: number;
+  readonly drawCount: number;
+  readonly materialStart: number;
+  readonly materialCount: number;
+}
+
+class StableRangeAllocator {
+  private next = 0;
+  private readonly free: Array<{ start: number; count: number }> = [];
+
+  allocate(count: number): number {
+    const freeIndex = this.free.findIndex((range) => range.count >= count);
+    if (freeIndex >= 0) {
+      const range = this.free[freeIndex];
+      if (range === undefined) throw new RangeError('free range disappeared');
+      const start = range.start;
+      if (range.count === count) this.free.splice(freeIndex, 1);
+      else this.free[freeIndex] = { start: range.start + count, count: range.count - count };
+      return start;
+    }
+    const start = this.next;
+    this.next += count;
+    return start;
+  }
+
+  release(start: number, count: number): void {
+    if (count <= 0) return;
+    this.free.push({ start, count });
+    this.free.sort((left, right) => left.start - right.start);
+    for (let index = this.free.length - 1; index > 0; index -= 1) {
+      const current = this.free[index];
+      const previous = this.free[index - 1];
+      if (
+        current === undefined ||
+        previous === undefined ||
+        previous.start + previous.count !== current.start
+      ) {
+        continue;
+      }
+      this.free[index - 1] = { start: previous.start, count: previous.count + current.count };
+      this.free.splice(index, 1);
+    }
+  }
+
+  requiredCapacity(): number {
+    return this.next;
+  }
+
+  reset(): void {
+    this.next = 0;
+    this.free.length = 0;
+  }
+}
+
+type GpuSceneTableName = keyof GpuSceneBuffers;
+
+const TABLE_LAYOUTS = {
+  primitive: PRIMITIVE,
+  instance: INSTANCE,
+  transform: TRANSFORM,
+  drawTemplate: DRAW_TEMPLATE,
+  material: MATERIAL,
+} as const satisfies Readonly<Record<GpuSceneTableName, GpuSceneTableLayout>>;
+
+const TABLE_NAMES = Object.keys(TABLE_LAYOUTS) as readonly GpuSceneTableName[];
+
+export interface GpuSceneTableInspection {
+  readonly capacity: number;
+  readonly bytes: number;
+}
+
+export interface GpuSceneInspection {
+  readonly capacity: number;
+  readonly tables: Readonly<Record<GpuSceneTableName, GpuSceneTableInspection>>;
+  readonly uploadRanges: number;
+  readonly uploadBytes: number;
+  readonly capacityGrows: number;
+  readonly fullRebuilds: number;
+  readonly clearedSlots: number;
+  readonly noChangeFrames: number;
+  /** Mirrored CPU broadphase evidence; RenderSceneProjection remains the owner. */
+  readonly spatialIndex: SpatialIndexInspection | undefined;
+}
+
+export interface GpuSceneSyncResult {
+  readonly ranges: number;
+  readonly bytes: number;
+  readonly grew: boolean;
+  readonly cleared: number;
+}
+
+export type GpuSceneAvailability =
+  | { readonly status: 'available'; readonly scene: GpuScene }
+  | { readonly status: 'unavailable'; readonly reason: 'storage-buffer-unavailable' };
+
+function createBuffers(device: RhiDevice, capacity: number): Result<GpuSceneBuffers, RhiError> {
+  const usage = GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_COPY_SRC;
+  const created: Partial<Record<GpuSceneTableName, Buffer>> = {};
+  for (const name of TABLE_NAMES) {
+    const result = device.createBuffer({
+      label: `gpu-scene-${name}-table`,
+      size: capacity * TABLE_LAYOUTS[name].stride,
+      usage,
+      mappedAtCreation: false,
+    });
+    if (!result.ok) {
+      for (const buffer of Object.values(created)) device.destroyBuffer(buffer);
+      return result;
+    }
+    created[name] = result.value;
+  }
+  return ok(created as unknown as GpuSceneBuffers);
+}
+
+function writeMat4(view: DataView, byteOffset: number, value: Float32Array): void {
+  for (let lane = 0; lane < 16; lane += 1) {
+    view.setFloat32(byteOffset + lane * 4, value[lane] ?? 0, true);
+  }
+}
+
+function writeVec4(view: DataView, byteOffset: number, values: readonly number[]): void {
+  for (let lane = 0; lane < 4; lane += 1) {
+    view.setFloat32(byteOffset + lane * 4, values[lane] ?? 0, true);
+  }
+}
+
+function offset(layout: GpuSceneTableLayout, field: string): number {
+  return gpuSceneFieldOffset(layout, field);
+}
+
+function stableU32(value: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+function coalesceSlots(
+  slots: readonly number[],
+): readonly { readonly start: number; readonly end: number }[] {
+  const ordered = [...new Set(slots)].sort((a, b) => a - b);
+  const ranges: Array<{ start: number; end: number }> = [];
+  for (const slot of ordered) {
+    const previous = ranges.at(-1);
+    if (previous !== undefined && previous.end === slot) {
+      previous.end = slot + 1;
+    } else {
+      ranges.push({ start: slot, end: slot + 1 });
+    }
+  }
+  return ranges;
+}
+
+/** Persistent GPU tables derived only from renderer projection slots. */
+export class GpuScene {
+  private tableBytes: Record<GpuSceneTableName, ArrayBuffer>;
+  private buffers: GpuSceneBuffers;
+  private uploadRanges = 0;
+  private uploadBytes = 0;
+  private capacityGrows = 0;
+  private fullRebuilds = 0;
+  private clearedSlots = 0;
+  private noChangeFrames = 0;
+  private readonly allocations = new Map<number, PrimitiveAllocation>();
+  private readonly instances = new StableRangeAllocator();
+  private readonly transforms = new StableRangeAllocator();
+  private readonly draws = new StableRangeAllocator();
+  private readonly materials = new StableRangeAllocator();
+  private readonly pendingSubmittedSlots = new Set<number>();
+  private spatialIndex: SpatialIndexInspection | undefined;
+
+  private constructor(
+    private readonly device: RhiDevice,
+    private capacity: number,
+    buffers: GpuSceneBuffers,
+  ) {
+    this.buffers = buffers;
+    this.tableBytes = this.allocateCpuTables(capacity);
+  }
+
+  static create(device: RhiDevice, initialCapacity = 256): Result<GpuSceneAvailability, RhiError> {
+    if (!device.caps.storageBuffer) {
+      return ok({ status: 'unavailable', reason: 'storage-buffer-unavailable' });
+    }
+    const requestedCapacity = Number.isFinite(initialCapacity)
+      ? Math.max(1, Math.ceil(initialCapacity))
+      : 256;
+    const capacity = 2 ** Math.ceil(Math.log2(requestedCapacity));
+    const buffers = createBuffers(device, capacity);
+    if (!buffers.ok) return err(buffers.error);
+    return ok({ status: 'available', scene: new GpuScene(device, capacity, buffers.value) });
+  }
+
+  get primitiveBuffer(): Buffer {
+    return this.buffers.primitive;
+  }
+
+  get instanceBuffer(): Buffer {
+    return this.buffers.instance;
+  }
+
+  get transformBuffer(): Buffer {
+    return this.buffers.transform;
+  }
+
+  get drawTemplateBuffer(): Buffer {
+    return this.buffers.drawTemplate;
+  }
+
+  get materialBuffer(): Buffer {
+    return this.buffers.material;
+  }
+
+  sync(
+    projection: RenderSceneProjection,
+    delta: RenderSceneApplyResult,
+  ): Result<GpuSceneSyncResult, RhiError> {
+    if (delta.spatialIndex !== undefined) this.spatialIndex = delta.spatialIndex.inspection;
+    const factDeltaBySlot = new Map(
+      delta.factDeltas.map((factDelta) => [factDelta.slot, factDelta]),
+    );
+    const writes = [
+      ...delta.createdSlots.map((record) => ({
+        record,
+        resetPrevious: true,
+        dirtyDomains: ALL_SCENE_FACT_DOMAINS,
+      })),
+      ...delta.updatedSlots.flatMap((record) => {
+        const factDelta = factDeltaBySlot.get(record.slot);
+        // An old caller may construct a delta without factDeltas. Preserve its
+        // previous full-write behavior for compatibility; projection deltas
+        // always carry the fine-grained entry.
+        if (factDelta === undefined) {
+          return [{ record, resetPrevious: false, dirtyDomains: ALL_SCENE_FACT_DOMAINS }];
+        }
+        if (factDelta.changedDomains.length === 0) return [];
+        return [{ record, resetPrevious: false, dirtyDomains: factDelta.changedDomains }];
+      }),
+      ...delta.recreatedSlots.map((record) => ({
+        record,
+        resetPrevious: true,
+        dirtyDomains: ALL_SCENE_FACT_DOMAINS,
+      })),
+    ];
+    const changedSlots = [
+      ...writes.map(({ record }) => record.slot),
+      ...delta.removedSlots.map((r) => r.slot),
+    ];
+    if (changedSlots.length === 0 && this.pendingSubmittedSlots.size === 0) {
+      this.noChangeFrames += 1;
+      return ok({ ranges: 0, bytes: 0, grew: false, cleared: 0 });
+    }
+    const writesByTable: Record<GpuSceneTableName, number[]> = {
+      primitive: [],
+      instance: [],
+      transform: [],
+      drawTemplate: [],
+      material: [],
+    };
+    for (const { record } of writes) this.ensureAllocation(record, writesByTable);
+    const changedSlotSet = new Set(changedSlots);
+    const submittedOnly = [...this.pendingSubmittedSlots].flatMap((slot) => {
+      if (changedSlotSet.has(slot)) return [];
+      const record = projection.slotByIndex(slot);
+      return record === undefined ? [] : [record];
+    });
+    const requiredCapacity = Math.max(
+      Math.max(...changedSlots) + 1,
+      this.instances.requiredCapacity(),
+      this.transforms.requiredCapacity(),
+      this.draws.requiredCapacity(),
+      this.materials.requiredCapacity(),
+    );
+    const grew = requiredCapacity > this.capacity;
+    if (grew) {
+      const grown = this.grow(requiredCapacity);
+      if (!grown.ok) return grown;
+    }
+
+    for (const write of writes) {
+      const temporal = projection.temporalSnapshotBySlot(write.record.slot);
+      if (temporal !== undefined) {
+        this.writeSlot(write.record, temporal, writesByTable, write.dirtyDomains);
+      }
+    }
+    for (const record of submittedOnly) {
+      const temporal = projection.temporalSnapshotBySlot(record.slot);
+      if (temporal !== undefined) this.writePreviousTransforms(record, temporal, writesByTable);
+    }
+    this.pendingSubmittedSlots.clear();
+    for (const record of delta.removedSlots) this.clearSlot(record.slot, writesByTable);
+    const uploaded = this.uploadRows(writesByTable);
+    if (!uploaded.ok) return uploaded;
+    this.clearedSlots += delta.removedSlots.length;
+    return ok({
+      ranges: uploaded.value.ranges,
+      bytes: uploaded.value.bytes,
+      grew,
+      cleared: delta.removedSlots.length,
+    });
+  }
+
+  rebuild(projection: RenderSceneProjection): Result<GpuSceneSyncResult, RhiError> {
+    const slots = projection.slotsSnapshot();
+    this.spatialIndex = projection.inspect().spatialIndex;
+    this.allocations.clear();
+    this.instances.reset();
+    this.transforms.reset();
+    this.draws.reset();
+    this.materials.reset();
+    const writesByTable: Record<GpuSceneTableName, number[]> = {
+      primitive: [],
+      instance: [],
+      transform: [],
+      drawTemplate: [],
+      material: [],
+    };
+    for (const slot of slots) this.ensureAllocation(slot, writesByTable);
+    const highestSlot = slots.reduce((maximum, slot) => Math.max(maximum, slot.slot), -1);
+    const requiredCapacity = Math.max(
+      highestSlot + 1,
+      this.instances.requiredCapacity(),
+      this.transforms.requiredCapacity(),
+      this.draws.requiredCapacity(),
+      this.materials.requiredCapacity(),
+    );
+    let grew = false;
+    if (requiredCapacity > this.capacity) {
+      const grown = this.grow(requiredCapacity);
+      if (!grown.ok) return grown;
+      grew = true;
+    }
+    for (const bytes of Object.values(this.tableBytes)) new Uint8Array(bytes).fill(0);
+    for (const slot of slots) {
+      const temporal = projection.temporalSnapshotBySlot(slot.slot);
+      if (temporal !== undefined) {
+        this.writeSlot(slot, temporal, writesByTable, ALL_SCENE_FACT_DOMAINS);
+      }
+    }
+    let bytes = 0;
+    for (const name of TABLE_NAMES) {
+      const table = this.tableBytes[name];
+      const write = this.device.queue.writeBuffer(this.buffers[name], 0, new Uint8Array(table));
+      if (!write.ok) return write;
+      bytes += table.byteLength;
+    }
+    this.uploadRanges += TABLE_NAMES.length;
+    this.uploadBytes += bytes;
+    this.fullRebuilds += 1;
+    this.pendingSubmittedSlots.clear();
+    return ok({ ranges: TABLE_NAMES.length, bytes, grew, cleared: 0 });
+  }
+
+  inspect(): GpuSceneInspection {
+    return {
+      capacity: this.capacity,
+      tables: Object.fromEntries(
+        TABLE_NAMES.map((name) => [
+          name,
+          { capacity: this.capacity, bytes: this.tableBytes[name].byteLength },
+        ]),
+      ) as unknown as Readonly<Record<GpuSceneTableName, GpuSceneTableInspection>>,
+      uploadRanges: this.uploadRanges,
+      uploadBytes: this.uploadBytes,
+      capacityGrows: this.capacityGrows,
+      fullRebuilds: this.fullRebuilds,
+      clearedSlots: this.clearedSlots,
+      noChangeFrames: this.noChangeFrames,
+      spatialIndex: this.spatialIndex,
+    };
+  }
+
+  dispose(): void {
+    for (const buffer of Object.values(this.buffers)) this.device.destroyBuffer(buffer);
+  }
+
+  stageSubmitted(delta: RenderSceneSubmissionDelta): void {
+    for (const slot of delta.slots) this.pendingSubmittedSlots.add(slot);
+  }
+
+  private writeSlot(
+    record: RenderSceneProjectionSlot,
+    temporal: RenderableTemporalSnapshot,
+    writes: Record<GpuSceneTableName, number[]>,
+    dirtyDomains: readonly SceneFactRevisionDomain[],
+  ): void {
+    const allocation = this.allocations.get(record.slot);
+    if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
+    const dirty = new Set(dirtyDomains);
+    const writePrimitive =
+      dirty.has('geometry') ||
+      dirty.has('eligibility') ||
+      dirty.has('batch') ||
+      dirty.has('resource');
+    const writeInstances = dirty.has('geometry');
+    const writeLocalTransforms = dirty.has('geometry');
+    const writeTransforms = dirty.has('geometry') || dirty.has('transform') || dirty.has('space');
+    const writeDrawTemplates = dirty.has('geometry') || dirty.has('batch');
+    const writeMaterials = dirty.has('geometry') || dirty.has('material') || dirty.has('resource');
+    const primitiveOffset = record.slot * PRIMITIVE.stride;
+    const primitive = new DataView(this.tableBytes.primitive);
+    if (writePrimitive) {
+      const bounds =
+        record.fact.bounds.status === 'present' ? record.fact.bounds.localAabb : undefined;
+      let flags = PRIMITIVE_ACTIVE;
+      if (record.fact.bounds.status === 'present') flags |= PRIMITIVE_HAS_BOUNDS;
+      if (record.snapshot.gpuDrivenDraws !== undefined) flags |= PRIMITIVE_GPU_DRIVEN;
+      if (record.fact.mobility === 'static') flags |= PRIMITIVE_STATIC;
+      if (record.fact.mobility === 'dynamic') flags |= PRIMITIVE_DYNAMIC;
+      if (record.fact.casterEligibility === 'eligible') flags |= PRIMITIVE_CASTER_ELIGIBLE;
+      if (record.fact.casterEligibility === 'ineligible') flags |= PRIMITIVE_CASTER_INELIGIBLE;
+      if (record.fact.casterEligibility === 'unknown') flags |= PRIMITIVE_CASTER_UNKNOWN;
+      primitive.setUint32(
+        primitiveOffset + offset(PRIMITIVE, 'generation'),
+        record.generation,
+        true,
+      );
+      primitive.setUint32(primitiveOffset + offset(PRIMITIVE, 'flags'), flags, true);
+      primitive.setUint32(
+        primitiveOffset + offset(PRIMITIVE, 'transformIndex'),
+        allocation.transformStart,
+        true,
+      );
+      primitive.setUint32(
+        primitiveOffset + offset(PRIMITIVE, 'materialIndex'),
+        allocation.materialStart,
+        true,
+      );
+      primitive.setUint32(
+        primitiveOffset + offset(PRIMITIVE, 'drawTemplateIndex'),
+        allocation.drawStart,
+        true,
+      );
+      primitive.setUint32(
+        primitiveOffset + offset(PRIMITIVE, 'instanceStart'),
+        allocation.instanceStart,
+        true,
+      );
+      primitive.setUint32(
+        primitiveOffset + offset(PRIMITIVE, 'instanceCount'),
+        allocation.instanceCount,
+        true,
+      );
+      primitive.setUint32(
+        primitiveOffset + offset(PRIMITIVE, 'assetHandle'),
+        record.snapshot.assetHandle,
+        true,
+      );
+      writeVec4(primitive, primitiveOffset + offset(PRIMITIVE, 'localBoundsMin'), [
+        bounds?.[0] ?? 0,
+        bounds?.[1] ?? 0,
+        bounds?.[2] ?? 0,
+        0,
+      ]);
+      writeVec4(primitive, primitiveOffset + offset(PRIMITIVE, 'localBoundsMax'), [
+        bounds?.[3] ?? 0,
+        bounds?.[4] ?? 0,
+        bounds?.[5] ?? 0,
+        0,
+      ]);
+      writes.primitive.push(record.slot);
+    }
+
+    const instance = new DataView(this.tableBytes.instance);
+    const transform = new DataView(this.tableBytes.transform);
+    if (writeInstances || writeLocalTransforms) {
+      for (let ordinal = 0; ordinal < allocation.instanceCount; ordinal += 1) {
+        const instanceIndex = allocation.instanceStart + ordinal;
+        const instanceOffset = instanceIndex * INSTANCE.stride;
+        const transformIndex = allocation.transformStart + 1 + ordinal;
+        if (writeInstances) {
+          instance.setUint32(
+            instanceOffset + offset(INSTANCE, 'primitiveIndex'),
+            record.slot,
+            true,
+          );
+          instance.setUint32(
+            instanceOffset + offset(INSTANCE, 'transformIndex'),
+            transformIndex,
+            true,
+          );
+          instance.setUint32(instanceOffset + offset(INSTANCE, 'customDataStart'), 0, true);
+          instance.setUint32(instanceOffset + offset(INSTANCE, 'flags'), PRIMITIVE_ACTIVE, true);
+          writes.instance.push(instanceIndex);
+        }
+        if (writeLocalTransforms) {
+          const local = record.snapshot.instances?.transforms.subarray(
+            ordinal * 16,
+            ordinal * 16 + 16,
+          );
+          const localWorld = local?.length === 16 ? local : IDENTITY_MATRIX;
+          const localOffset = transformIndex * TRANSFORM.stride;
+          const localCurrentOffset = localOffset + offset(TRANSFORM, 'currentWorld');
+          const localPreviousOffset = localOffset + offset(TRANSFORM, 'previousWorld');
+          writeMat4(transform, localCurrentOffset, localWorld);
+          const previousLocal = temporal.previousInstances?.transforms.subarray(
+            ordinal * 16,
+            ordinal * 16 + 16,
+          );
+          writeMat4(
+            transform,
+            localPreviousOffset,
+            previousLocal?.length === 16 ? previousLocal : localWorld,
+          );
+          writes.transform.push(transformIndex);
+        }
+      }
+    }
+
+    if (writeTransforms) {
+      const transformOffset = allocation.transformStart * TRANSFORM.stride;
+      const currentOffset = transformOffset + offset(TRANSFORM, 'currentWorld');
+      const previousOffset = transformOffset + offset(TRANSFORM, 'previousWorld');
+      writeMat4(transform, currentOffset, record.snapshot.transform.world);
+      writeMat4(transform, previousOffset, temporal.previousTransform.world);
+      writes.transform.push(allocation.transformStart);
+    }
+
+    const draw = new DataView(this.tableBytes.drawTemplate);
+    const drawSnapshots = record.snapshot.gpuDrivenDraws ?? [];
+    if (writeDrawTemplates) {
+      for (let ordinal = 0; ordinal < allocation.drawCount; ordinal += 1) {
+        const drawIndex = allocation.drawStart + ordinal;
+        const drawOffset = drawIndex * DRAW_TEMPLATE.stride;
+        const drawSnapshot = drawSnapshots[ordinal];
+        draw.setUint32(
+          drawOffset + offset(DRAW_TEMPLATE, 'pipelineClass'),
+          drawSnapshot === undefined ? 0 : stableU32(drawSnapshot.pipelineClass),
+          true,
+        );
+        draw.setUint32(
+          drawOffset + offset(DRAW_TEMPLATE, 'materialIndex'),
+          allocation.materialStart + (drawSnapshot?.materialSlot ?? 0),
+          true,
+        );
+        draw.setUint32(
+          drawOffset + offset(DRAW_TEMPLATE, 'firstIndex'),
+          drawSnapshot?.first ?? 0,
+          true,
+        );
+        draw.setUint32(
+          drawOffset + offset(DRAW_TEMPLATE, 'indexCount'),
+          drawSnapshot?.count ?? 0,
+          true,
+        );
+        draw.setInt32(
+          drawOffset + offset(DRAW_TEMPLATE, 'baseVertex'),
+          drawSnapshot?.baseVertex ?? 0,
+          true,
+        );
+        draw.setUint32(drawOffset + offset(DRAW_TEMPLATE, 'firstInstance'), 0, true);
+        draw.setUint32(drawOffset + offset(DRAW_TEMPLATE, 'passFlags'), 0, true);
+        draw.setUint32(drawOffset + offset(DRAW_TEMPLATE, 'reserved'), 0, true);
+        writes.drawTemplate.push(drawIndex);
+      }
+    }
+
+    const material = new DataView(this.tableBytes.material);
+    if (writeMaterials) {
+      for (let ordinal = 0; ordinal < allocation.materialCount; ordinal += 1) {
+        const materialIndex = allocation.materialStart + ordinal;
+        const materialOffset = materialIndex * MATERIAL.stride;
+        const snapshot = record.snapshot.materials[ordinal] ?? record.snapshot.material;
+        writeVec4(material, materialOffset + offset(MATERIAL, 'params0'), [
+          snapshot.baseColor?.[0] ?? 0,
+          snapshot.baseColor?.[1] ?? 0,
+          snapshot.baseColor?.[2] ?? 0,
+          1,
+        ]);
+        writeVec4(material, materialOffset + offset(MATERIAL, 'params1'), [
+          snapshot.metallic ?? 0,
+          snapshot.roughness ?? 1,
+          snapshot.clearcoat ?? 0,
+          snapshot.clearcoatRoughness ?? 0,
+        ]);
+        writeVec4(material, materialOffset + offset(MATERIAL, 'params2'), [
+          snapshot.emissive?.[0] ?? 0,
+          snapshot.emissive?.[1] ?? 0,
+          snapshot.emissive?.[2] ?? 0,
+          snapshot.emissiveIntensity ?? 0,
+        ]);
+        writeVec4(material, materialOffset + offset(MATERIAL, 'params3'), [
+          snapshot.normalScale ?? 1,
+          snapshot.occlusionStrength ?? 1,
+          0,
+          0,
+        ]);
+        material.setUint32(
+          materialOffset + offset(MATERIAL, 'resource0'),
+          snapshot.baseColorTexture ?? 0,
+          true,
+        );
+        material.setUint32(
+          materialOffset + offset(MATERIAL, 'resource1'),
+          snapshot.metallicRoughnessTexture ?? 0,
+          true,
+        );
+        material.setUint32(
+          materialOffset + offset(MATERIAL, 'resource2'),
+          snapshot.normalTexture ?? 0,
+          true,
+        );
+        material.setUint32(
+          materialOffset + offset(MATERIAL, 'resource3'),
+          snapshot.emissiveTexture ?? 0,
+          true,
+        );
+        writes.material.push(materialIndex);
+      }
+    }
+  }
+
+  private writePreviousTransforms(
+    record: RenderSceneProjectionSlot,
+    temporal: RenderableTemporalSnapshot,
+    writes: Record<GpuSceneTableName, number[]>,
+  ): void {
+    const allocation = this.allocations.get(record.slot);
+    if (allocation === undefined) return;
+    const transform = new DataView(this.tableBytes.transform);
+    const rootOffset =
+      allocation.transformStart * TRANSFORM.stride + offset(TRANSFORM, 'previousWorld');
+    writeMat4(transform, rootOffset, temporal.previousTransform.world);
+    writes.transform.push(allocation.transformStart);
+    for (let ordinal = 0; ordinal < allocation.instanceCount; ordinal += 1) {
+      const transformIndex = allocation.transformStart + 1 + ordinal;
+      const previous = temporal.previousInstances?.transforms.subarray(
+        ordinal * 16,
+        ordinal * 16 + 16,
+      );
+      const current = record.snapshot.instances?.transforms.subarray(
+        ordinal * 16,
+        ordinal * 16 + 16,
+      );
+      const value = previous?.length === 16 ? previous : current;
+      if (value?.length !== 16) continue;
+      writeMat4(
+        transform,
+        transformIndex * TRANSFORM.stride + offset(TRANSFORM, 'previousWorld'),
+        value,
+      );
+      writes.transform.push(transformIndex);
+    }
+  }
+
+  private clearSlot(slot: number, writes: Record<GpuSceneTableName, number[]>): void {
+    for (const name of ['primitive'] as const) {
+      const layout = TABLE_LAYOUTS[name];
+      new Uint8Array(this.tableBytes[name], slot * layout.stride, layout.stride).fill(0);
+      writes[name].push(slot);
+    }
+    const allocation = this.allocations.get(slot);
+    if (allocation === undefined) return;
+    this.clearAllocation(allocation, writes);
+    this.allocations.delete(slot);
+  }
+
+  private uploadRows(
+    rows: Readonly<Record<GpuSceneTableName, readonly number[]>>,
+  ): Result<{ readonly ranges: number; readonly bytes: number }, RhiError> {
+    let rangeCount = 0;
+    let bytes = 0;
+    for (const name of TABLE_NAMES) {
+      const ranges = coalesceSlots(rows[name]);
+      rangeCount += ranges.length;
+      for (const range of ranges) {
+        const layout = TABLE_LAYOUTS[name];
+        const tableOffset = range.start * layout.stride;
+        const tableSize = (range.end - range.start) * layout.stride;
+        const write = this.device.queue.writeBuffer(
+          this.buffers[name],
+          tableOffset,
+          new Uint8Array(this.tableBytes[name], tableOffset, tableSize),
+        );
+        if (!write.ok) return write;
+        bytes += tableSize;
+      }
+    }
+    this.uploadRanges += rangeCount;
+    this.uploadBytes += bytes;
+    return ok({ ranges: rangeCount, bytes });
+  }
+
+  private ensureAllocation(
+    record: RenderSceneProjectionSlot,
+    writes: Record<GpuSceneTableName, number[]>,
+  ): void {
+    const instanceCount = Math.max(1, record.snapshot.instances?.instanceCount ?? 1);
+    const drawCount = Math.max(1, record.snapshot.gpuDrivenDraws?.length ?? 0);
+    const materialCount = Math.max(1, record.snapshot.materials.length);
+    const existing = this.allocations.get(record.slot);
+    if (
+      existing?.instanceCount === instanceCount &&
+      existing.drawCount === drawCount &&
+      existing.materialCount === materialCount
+    ) {
+      return;
+    }
+    if (existing !== undefined) this.clearAllocation(existing, writes);
+    const allocation = {
+      instanceStart: this.instances.allocate(instanceCount),
+      instanceCount,
+      transformStart: this.transforms.allocate(instanceCount + 1),
+      drawStart: this.draws.allocate(drawCount),
+      drawCount,
+      materialStart: this.materials.allocate(materialCount),
+      materialCount,
+    };
+    this.allocations.set(record.slot, allocation);
+  }
+
+  private clearAllocation(
+    allocation: PrimitiveAllocation,
+    writes: Record<GpuSceneTableName, number[]>,
+  ): void {
+    for (let ordinal = 0; ordinal < allocation.instanceCount; ordinal += 1) {
+      const instanceIndex = allocation.instanceStart + ordinal;
+      new Uint8Array(
+        this.tableBytes.instance,
+        instanceIndex * INSTANCE.stride,
+        INSTANCE.stride,
+      ).fill(0);
+      writes.instance.push(instanceIndex);
+    }
+    for (let ordinal = 0; ordinal <= allocation.instanceCount; ordinal += 1) {
+      const transformIndex = allocation.transformStart + ordinal;
+      new Uint8Array(
+        this.tableBytes.transform,
+        transformIndex * TRANSFORM.stride,
+        TRANSFORM.stride,
+      ).fill(0);
+      writes.transform.push(transformIndex);
+    }
+    for (let ordinal = 0; ordinal < allocation.drawCount; ordinal += 1) {
+      const drawIndex = allocation.drawStart + ordinal;
+      new Uint8Array(
+        this.tableBytes.drawTemplate,
+        drawIndex * DRAW_TEMPLATE.stride,
+        DRAW_TEMPLATE.stride,
+      ).fill(0);
+      writes.drawTemplate.push(drawIndex);
+    }
+    for (let ordinal = 0; ordinal < allocation.materialCount; ordinal += 1) {
+      const materialIndex = allocation.materialStart + ordinal;
+      new Uint8Array(
+        this.tableBytes.material,
+        materialIndex * MATERIAL.stride,
+        MATERIAL.stride,
+      ).fill(0);
+      writes.material.push(materialIndex);
+    }
+    this.instances.release(allocation.instanceStart, allocation.instanceCount);
+    this.transforms.release(allocation.transformStart, allocation.instanceCount + 1);
+    this.draws.release(allocation.drawStart, allocation.drawCount);
+    this.materials.release(allocation.materialStart, allocation.materialCount);
+  }
+
+  private grow(requiredCapacity: number): Result<void, RhiError> {
+    let nextCapacity = this.capacity;
+    while (nextCapacity < requiredCapacity) nextCapacity *= 2;
+    const nextBuffers = createBuffers(this.device, nextCapacity);
+    if (!nextBuffers.ok) return err(nextBuffers.error);
+    const nextTables = this.allocateCpuTables(nextCapacity);
+    for (const name of TABLE_NAMES) {
+      new Uint8Array(nextTables[name]).set(new Uint8Array(this.tableBytes[name]));
+      const write = this.device.queue.writeBuffer(
+        nextBuffers.value[name],
+        0,
+        new Uint8Array(nextTables[name]),
+      );
+      if (!write.ok) {
+        for (const buffer of Object.values(nextBuffers.value)) this.device.destroyBuffer(buffer);
+        return write;
+      }
+    }
+    for (const buffer of Object.values(this.buffers)) this.device.destroyBuffer(buffer);
+    this.buffers = nextBuffers.value;
+    this.tableBytes = nextTables;
+    this.capacity = nextCapacity;
+    this.capacityGrows += 1;
+    this.uploadRanges += TABLE_NAMES.length;
+    this.uploadBytes += Object.values(nextTables).reduce(
+      (total, bytes) => total + bytes.byteLength,
+      0,
+    );
+    return ok(undefined);
+  }
+
+  private allocateCpuTables(capacity: number): Record<GpuSceneTableName, ArrayBuffer> {
+    return Object.fromEntries(
+      TABLE_NAMES.map((name) => [name, new ArrayBuffer(capacity * TABLE_LAYOUTS[name].stride)]),
+    ) as unknown as Record<GpuSceneTableName, ArrayBuffer>;
+  }
+}