@forgeax/engine-render 0.1.24 → 0.1.26

package/src/gpu-scene.ts

@@ -225,6 +225,10 @@ export class GpuScene {
     drawTemplate: [],
     material: [],
   };
+  /** Transform rows whose previous value advances only after submit. */
+  private readonly pendingTemporalTransforms = new Set<number>();
+  /** Previous rows whose post-submit upload must be retried before the next draw. */
+  private readonly pendingTemporalUploads = new Set<number>();
 
   private constructor(
     private readonly device: RhiDevice,
@@ -273,31 +277,47 @@ export class GpuScene {
   }
 
   sync(delta: RenderSceneApplyResult): Result<GpuSceneSyncResult, RhiError> {
+    for (const transformIndex of this.pendingTemporalUploads) {
+      this.writesByTable.transform.push(transformIndex);
+    }
+    const pendingWrites = TABLE_NAMES.some((name) => this.writesByTable[name].length > 0);
     if (
       delta.createdSlots.length === 0 &&
       delta.updatedSlots.length === 0 &&
       delta.recreatedSlots.length === 0 &&
-      delta.removedSlots.length === 0
+      delta.removedSlots.length === 0 &&
+      !pendingWrites
     ) {
       this.noChangeFrames += 1;
       return ok({ ranges: 0, bytes: 0, grew: false, cleared: 0 });
     }
     const writesByTable = this.writesByTable;
-    for (const name of TABLE_NAMES) writesByTable[name].length = 0;
-    if (!this.identityUploaded) writesByTable.transform.push(0);
+    if (!this.identityUploaded && !writesByTable.transform.includes(0)) {
+      writesByTable.transform.push(0);
+    }
     let highestChangedSlot = -1;
-    for (const records of [delta.createdSlots, delta.recreatedSlots]) {
+    const contentUpdatedSlots = delta.contentUpdatedSlots ?? [];
+    const contentUpdatedSlotIds = new Set(contentUpdatedSlots.map((record) => record.slot));
+    const allocationResets = new Set<number>();
+    // RenderScene may recycle a released CPU slot for a different identity in
+    // the same delta. Clear the old GPU allocation before ensuring the new
+    // record; otherwise the later removal pass clears the newly allocated
+    // record and the next transform-only update sees no allocation.
+    for (const record of delta.removedSlots) {
+      if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
+      this.clearSlot(record.slot, writesByTable);
+    }
+    for (const records of [delta.createdSlots, contentUpdatedSlots, delta.recreatedSlots]) {
       for (const record of records) {
+        const previous = this.allocations[record.slot];
         this.ensureAllocation(record, writesByTable);
+        if (previous !== this.allocations[record.slot]) allocationResets.add(record.slot);
         if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
       }
     }
     for (const record of delta.updatedSlots) {
       if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
     }
-    for (const record of delta.removedSlots) {
-      if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
-    }
     const requiredCapacity = Math.max(
       highestChangedSlot + 1,
       this.instances.requiredCapacity(),
@@ -312,11 +332,18 @@ export class GpuScene {
     }
 
     for (const record of delta.createdSlots) this.writeSlot(record, true, writesByTable);
-    for (const record of delta.updatedSlots) this.writeRootTransform(record, false, writesByTable);
+    for (const record of contentUpdatedSlots) {
+      this.writeSlot(record, allocationResets.has(record.slot), writesByTable);
+    }
+    for (const record of delta.updatedSlots) {
+      if (contentUpdatedSlotIds.has(record.slot)) continue;
+      this.writeRootTransform(record, false, writesByTable);
+    }
     for (const record of delta.recreatedSlots) this.writeSlot(record, true, writesByTable);
-    for (const record of delta.removedSlots) this.clearSlot(record.slot, writesByTable);
     const uploaded = this.uploadRows(writesByTable);
     if (!uploaded.ok) return uploaded;
+    this.pendingTemporalUploads.clear();
+    for (const name of TABLE_NAMES) writesByTable[name].length = 0;
     this.identityUploaded = true;
     this.clearedSlots += delta.removedSlots.length;
     return ok({
@@ -329,27 +356,47 @@ export class GpuScene {
 
   /** Publish current transforms as previous only after a successful submit. */
   commitTemporalFrame(enabled = true): Result<void, RhiError> {
-    if (!enabled) return ok(undefined);
-    const nextTransform = this.tableBytes.transform.slice(0);
-    const next = new Uint8Array(nextTransform);
-    const current = this.transformBytes;
+    if (!enabled) {
+      this.pendingTemporalTransforms.clear();
+      this.pendingTemporalUploads.clear();
+      return ok(undefined);
+    }
+    if (this.pendingTemporalTransforms.size === 0) return ok(undefined);
     const currentOffset = offset(TRANSFORM, 'currentWorld');
     const previousOffset = offset(TRANSFORM, 'previousWorld');
-    for (let index = 0; index < this.capacity; index += 1) {
-      next.set(
-        current.subarray(
+    const ranges = coalesceSlots([...this.pendingTemporalTransforms]);
+    for (const range of ranges) {
+      for (let index = range.start; index < range.end; index += 1) {
+        this.pendingTemporalUploads.add(index);
+      }
+    }
+    for (const range of ranges) {
+      for (let index = range.start; index < range.end; index += 1) {
+        this.transformBytes.copyWithin(
+          index * TRANSFORM.stride + previousOffset,
           index * TRANSFORM.stride + currentOffset,
           index * TRANSFORM.stride + currentOffset + 64,
-        ),
-        index * TRANSFORM.stride + previousOffset,
+        );
+      }
+    }
+    for (const range of ranges) {
+      const firstOffset = range.start * TRANSFORM.stride;
+      const lastOffset = range.end * TRANSFORM.stride;
+      const uploaded = this.device.queue.writeBuffer(
+        this.buffers.transform,
+        firstOffset,
+        this.transformBytes.subarray(firstOffset, lastOffset),
       );
+      if (!uploaded.ok) return uploaded;
     }
-    const uploaded = this.device.queue.writeBuffer(this.buffers.transform, 0, next);
-    if (!uploaded.ok) return uploaded;
-    this.tableBytes.transform = nextTransform;
-    this.refreshTransformViews();
-    this.uploadRanges += 1;
-    this.uploadBytes += next.byteLength;
+    this.pendingTemporalTransforms.clear();
+    this.pendingTemporalUploads.clear();
+    const bytes = ranges.reduce(
+      (total, range) => total + (range.end - range.start) * TRANSFORM.stride,
+      0,
+    );
+    this.uploadRanges += ranges.length;
+    this.uploadBytes += bytes;
     return ok(undefined);
   }
 
@@ -359,6 +406,9 @@ export class GpuScene {
     this.transforms.reset(1);
     this.draws.reset();
     this.materials.reset();
+    this.pendingTemporalTransforms.clear();
+    this.pendingTemporalUploads.clear();
+    for (const name of TABLE_NAMES) this.writesByTable[name].length = 0;
     const writesByTable: Record<GpuSceneTableName, number[]> = {
       primitive: [],
       instance: [],
@@ -520,7 +570,8 @@ export class GpuScene {
         const localCurrentOffset = localOffset + offset(TRANSFORM, 'currentWorld');
         const localPreviousOffset = localOffset + offset(TRANSFORM, 'previousWorld');
         writeMat4(transform, localCurrentOffset, localWorld);
-        writeMat4(transform, localPreviousOffset, localWorld);
+        if (resetPrevious) writeMat4(transform, localPreviousOffset, localWorld);
+        else this.pendingTemporalTransforms.add(transformIndex);
         writes.transform.push(transformIndex);
       }
       writes.instance.push(instanceIndex);
@@ -631,14 +682,16 @@ export class GpuScene {
     const allocation = this.allocations[record.slot];
     if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
     const transformOffset = allocation.transformStart * TRANSFORM.stride;
-    const currentOffset = transformOffset + offset(TRANSFORM, 'currentWorld');
     const previousOffset = transformOffset + offset(TRANSFORM, 'previousWorld');
     if (resetPrevious) {
       writeMat4(this.transformView, previousOffset, record.snapshot.transform.world);
-    } else {
-      this.transformBytes.copyWithin(previousOffset, currentOffset, currentOffset + 64);
     }
-    writeMat4(this.transformView, currentOffset, record.snapshot.transform.world);
+    writeMat4(
+      this.transformView,
+      transformOffset + offset(TRANSFORM, 'currentWorld'),
+      record.snapshot.transform.world,
+    );
+    if (!resetPrevious) this.pendingTemporalTransforms.add(allocation.transformStart);
     writes.transform.push(allocation.transformStart);
   }
 
@@ -743,6 +796,8 @@ export class GpuScene {
         TRANSFORM.stride,
       ).fill(0);
       writes.transform.push(transformIndex);
+      this.pendingTemporalTransforms.delete(transformIndex);
+      this.pendingTemporalUploads.delete(transformIndex);
     }
     for (let ordinal = 0; ordinal < allocation.drawCount; ordinal += 1) {
       const drawIndex = allocation.drawStart + ordinal;

package/src/index.ts

@@ -196,6 +196,7 @@ export type {
   ReflectionProbeSelectionInspection,
   TransmissionInspection,
 } from './inspection-types';
+export type { InstanceCollectionInspection } from './instances';
 export {
   type MaterialColorInput3,
   type MaterialColorInput4,

package/src/instance-buffer-cache.ts

@@ -23,12 +23,16 @@ import type { GpuBuffer } from './gpu-resource';
  * and routes dispose through the RHI shim's destroy bookkeeping SSOT. The
  * two `uploaded*` fields are the cache invalidation fingerprint -- when the
  * archetype version bumps or the byte length changes, the record stage
- * allocates a fresh GpuBuffer and replaces the entry.
+ * allocates a fresh GpuBuffer and replaces the entry. Explicit collection
+ * entries are keyed by renderer-owned collection id at the outer map; the
+ * legacy entity key remains only for sprite/fold snapshots.
  */
 export interface InstanceBufferCacheEntry {
   readonly buffer: GpuBuffer;
   readonly uploadedByteLength: number;
   readonly uploadedArchVersion: number;
+  /** Renderer-owned collection revision uploaded into this buffer. */
+  readonly uploadedRevision?: number;
 }
 
 function destroyInstanceBufferEntries(
@@ -85,6 +89,15 @@ export function disposeInstanceBuffers(
   map.clear();
 }
 
+/** Destroy the renderer-owned buffers used by internal large-instance chunks. */
+export function disposeInstanceBufferChunks(
+  map: Map<string, InstanceBufferCacheEntry>,
+  errorRegistry?: InstanceBufferCacheErrorSink,
+): void {
+  destroyInstanceBufferEntries(map.values(), errorRegistry);
+  map.clear();
+}
+
 /** Destroy transient uniform-fallback chunks allocated for the previous frame. */
 export function disposeTransientInstanceBuffers(
   entries: InstanceBufferCacheEntry[],

package/src/instances.ts

@@ -0,0 +1,288 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { RhiErrorCode } from '@forgeax/engine-rhi';
+
+const MATRIX_STRIDE = 16;
+
+export type InstanceCollectionId = number & {
+  readonly __forgeaxInstanceCollectionId: unique symbol;
+};
+
+export interface InstanceCollectionInfo {
+  readonly collectionId: InstanceCollectionId;
+  readonly count: number;
+  readonly revision: number;
+}
+
+export interface InstanceUploadRange {
+  start: number;
+  end: number;
+}
+
+export interface InstanceCollectionSnapshot extends InstanceCollectionInfo {
+  readonly transforms: Float32Array;
+}
+
+/** The renderer-owned submission lane selected for one collection. */
+export type InstanceSubmissionLane =
+  | 'unresident'
+  | 'direct-storage'
+  | 'chunked-storage'
+  | 'direct-uniform'
+  | 'chunked-uniform'
+  | 'unavailable';
+
+/** Backend identity carried by collection residency and failure facts. */
+export type InstanceBackendKind = 'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null' | 'unknown';
+
+/** Closed record-stage failure vocabulary for collection residency. */
+export type InstanceCollectionFailureCode = RhiErrorCode | 'queue-write-buffer-failed';
+
+/** Typed producer facts retained when a collection cannot be admitted. */
+export interface InstanceCollectionFailureFacts {
+  readonly requestedBytes: number;
+  readonly supportedBytes: number | undefined;
+  readonly backend: InstanceBackendKind;
+  readonly owner: 'renderer.instances';
+  readonly cause: string;
+  readonly recovery: string;
+}
+
+/** Detached, bounded collection evidence exposed by Renderer.inspect(). */
+export interface InstanceCollectionInspection extends InstanceCollectionInfo {
+  readonly residentGeneration: number | undefined;
+  readonly lane: InstanceSubmissionLane;
+  readonly uploadRanges: readonly InstanceUploadRange[];
+  readonly uploadedBytes: number;
+  readonly requestedBytes: number;
+  readonly supportedBytes: number | undefined;
+  readonly backend: InstanceBackendKind;
+  readonly owner: 'renderer.instances';
+  readonly error:
+    | {
+        readonly code: InstanceCollectionFailureCode;
+        readonly expected: string;
+        readonly hint: string;
+        readonly detail: InstanceCollectionFailureFacts;
+      }
+    | undefined;
+}
+
+export interface InstanceResidency {
+  readonly frameNumber: number;
+  readonly residentGeneration: number | undefined;
+  readonly lane: InstanceSubmissionLane;
+  readonly uploadRanges: readonly InstanceUploadRange[];
+  readonly uploadedBytes: number;
+  readonly requestedBytes: number;
+  readonly supportedBytes: number | undefined;
+  readonly backend: InstanceBackendKind;
+  readonly error: InstanceCollectionInspection['error'];
+}
+
+function appendRange(ranges: InstanceUploadRange[], start: number, end: number): void {
+  if (start >= end) return;
+  // Updates are allowed to arrive in any order. Insert at the first range
+  // whose end reaches the new interval, then consume every range that starts
+  // before the merged end. This preserves the complete union for both
+  // adjacent and overlapping writes (for example [10, 12) then [8, 11)).
+  let index = 0;
+  while (index < ranges.length) {
+    const existing = ranges[index];
+    if (existing === undefined || existing.end >= start) break;
+    index += 1;
+  }
+  while (index < ranges.length) {
+    const existing = ranges[index];
+    if (existing === undefined || existing.start > end) break;
+    start = Math.min(start, existing.start);
+    end = Math.max(end, existing.end);
+    ranges.splice(index, 1);
+  }
+  ranges.splice(index, 0, { start, end });
+}
+
+interface CollectionRecord extends InstanceCollectionInfo {
+  readonly world: World;
+  readonly entity: number;
+  readonly transforms: Float32Array;
+}
+
+/** Rebuildable per-renderer projection. World remains the authoring authority. */
+export class InstanceProjectionStore {
+  private nextId = 1;
+  private identities = new WeakMap<World, Map<number, InstanceCollectionId>>();
+  private readonly records = new Map<InstanceCollectionId, CollectionRecord>();
+
+  project(world: World, entity: number, transforms: ArrayLike<number>): InstanceCollectionSnapshot {
+    let entities = this.identities.get(world);
+    if (entities === undefined) {
+      entities = new Map();
+      this.identities.set(world, entities);
+    }
+    let collectionId = entities.get(entity);
+    if (collectionId === undefined) {
+      collectionId = this.nextId++ as InstanceCollectionId;
+      entities.set(entity, collectionId);
+    }
+    const previous = this.records.get(collectionId);
+    const unchanged =
+      previous !== undefined &&
+      previous.transforms.length === transforms.length &&
+      previous.transforms.every((value, index) => Object.is(value, transforms[index]));
+    const record: CollectionRecord = unchanged
+      ? previous
+      : {
+          collectionId,
+          world,
+          entity,
+          transforms: new Float32Array(transforms),
+          count: transforms.length / MATRIX_STRIDE,
+          revision: (previous?.revision ?? 0) + 1,
+        };
+    this.records.set(collectionId, record);
+    // Every consumer gets a complete snapshot. Reading never acknowledges an
+    // upload; each GPU resident records its own successfully uploaded revision.
+    return { ...this.info(record), transforms: record.transforms };
+  }
+
+  retain(ids: ReadonlySet<InstanceCollectionId>): void {
+    for (const [id, record] of this.records) {
+      if (ids.has(id)) continue;
+      this.identities.get(record.world)?.delete(record.entity);
+      this.records.delete(id);
+    }
+  }
+
+  /** Release one producer-owned collection when its render identity is removed. */
+  release(world: World, entity: number): void {
+    const entities = this.identities.get(world);
+    const collectionId = entities?.get(entity);
+    if (collectionId === undefined) return;
+    entities?.delete(entity);
+    this.records.delete(collectionId);
+  }
+
+  dispose(): void {
+    this.records.clear();
+    this.identities = new WeakMap();
+  }
+
+  /**
+   * Return detached residency facts for every live collection.
+   *
+   * @internal Joins CPU projection identity with the active device residency;
+   * callers only receive immutable PODs and never GPU handles.
+   */
+  _inspections(
+    residency: ReadonlyMap<InstanceCollectionId, InstanceResidency> | undefined,
+    frameNumber: number,
+  ): readonly InstanceCollectionInspection[] {
+    return Object.freeze(
+      [...this.records.values()].map((record) =>
+        this.projectInspection(record, residency?.get(record.collectionId), frameNumber),
+      ),
+    );
+  }
+
+  private info(record: CollectionRecord): InstanceCollectionInfo {
+    return Object.freeze({
+      collectionId: record.collectionId,
+      count: record.count,
+      revision: record.revision,
+    });
+  }
+
+  private projectInspection(
+    record: CollectionRecord,
+    residency: InstanceResidency | undefined,
+    frameNumber: number,
+  ): InstanceCollectionInspection {
+    return Object.freeze({
+      ...this.info(record),
+      residentGeneration: residency?.residentGeneration,
+      lane: residency?.lane ?? 'unresident',
+      uploadRanges: Object.freeze(
+        residency?.frameNumber === frameNumber
+          ? residency.uploadRanges.map((range) => ({ ...range }))
+          : [],
+      ),
+      uploadedBytes: residency?.frameNumber === frameNumber ? residency.uploadedBytes : 0,
+      requestedBytes: residency?.requestedBytes ?? record.count * MATRIX_STRIDE * 4,
+      supportedBytes: residency?.supportedBytes,
+      backend: residency?.backend ?? 'unknown',
+      owner: 'renderer.instances',
+      error: residency?.error,
+    });
+  }
+}
+
+/** @internal Renderer record owner reports the accepted collection lane. */
+export function recordInstanceResidency(
+  residency: Map<InstanceCollectionId, InstanceResidency>,
+  input: {
+    readonly collectionId: InstanceCollectionId;
+    readonly frameNumber: number;
+    readonly residentGeneration: number;
+    readonly lane: Exclude<InstanceSubmissionLane, 'unresident' | 'unavailable'>;
+    readonly uploadRanges: readonly InstanceUploadRange[];
+    readonly uploadedBytes: number;
+    readonly requestedBytes: number;
+    readonly supportedBytes: number | undefined;
+    readonly backend: InstanceBackendKind;
+  },
+): void {
+  const previous = residency.get(input.collectionId);
+  const sameFrame =
+    previous !== undefined &&
+    previous.frameNumber === input.frameNumber &&
+    previous.error === undefined;
+  const uploadRanges = sameFrame
+    ? [...previous.uploadRanges].reduce(
+        (ranges, range) => {
+          appendRange(ranges, range.start, range.end);
+          return ranges;
+        },
+        input.uploadRanges.map((range) => ({ ...range })),
+      )
+    : input.uploadRanges.map((range) => ({ ...range }));
+  residency.set(input.collectionId, {
+    frameNumber: input.frameNumber,
+    residentGeneration: input.residentGeneration,
+    lane: input.lane,
+    uploadRanges,
+    uploadedBytes: sameFrame ? previous.uploadedBytes + input.uploadedBytes : input.uploadedBytes,
+    requestedBytes: input.requestedBytes,
+    supportedBytes: input.supportedBytes,
+    backend: input.backend,
+    error: undefined,
+  });
+}
+
+/** @internal Renderer record owner reports a typed admission failure. */
+export function recordInstanceFailure(
+  residency: Map<InstanceCollectionId, InstanceResidency>,
+  input: {
+    readonly collectionId: InstanceCollectionId;
+    readonly code: InstanceCollectionFailureCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly facts: InstanceCollectionFailureFacts;
+  },
+): void {
+  residency.set(input.collectionId, {
+    frameNumber: -1,
+    residentGeneration: undefined,
+    lane: 'unavailable',
+    uploadRanges: [],
+    uploadedBytes: 0,
+    requestedBytes: input.facts.requestedBytes,
+    supportedBytes: input.facts.supportedBytes,
+    backend: input.facts.backend,
+    error: {
+      code: input.code,
+      expected: input.expected,
+      hint: input.hint,
+      detail: { ...input.facts },
+    },
+  });
+}