@forgeax/engine-render 0.1.32 → 0.1.33

package/src/inspection-types.ts

@@ -92,6 +92,10 @@ export type BloomGraphStatus = 'empty' | 'valid' | 'invalid';
 export interface BloomInspection {
   readonly graphStatus: BloomGraphStatus;
   readonly enabled: boolean;
+  readonly levelCount: number;
+  readonly levelDimensions: readonly { readonly width: number; readonly height: number }[];
+  readonly downsamplePassCount: number;
+  readonly upsamplePassCount: number;
   readonly targetCount: number;
   readonly targetBytes: number;
   readonly resourceCount: number;
@@ -99,10 +103,30 @@ export interface BloomInspection {
   readonly encodeCount: number;
   readonly bindGroupCount: number;
   readonly uploadCount: number;
+  /** Descriptor-derived bytes for the active Bloom target child in the compiled graph. */
   readonly residentChildBytes: number;
   readonly generation: number;
   readonly state: 'off' | 'active' | 'retiring';
 }
+
+export const emptyBloomInspection = (): BloomInspection => ({
+  graphStatus: 'empty',
+  enabled: false,
+  levelCount: 0,
+  levelDimensions: [],
+  downsamplePassCount: 0,
+  upsamplePassCount: 0,
+  targetCount: 0,
+  targetBytes: 0,
+  resourceCount: 0,
+  passCount: 0,
+  encodeCount: 0,
+  bindGroupCount: 0,
+  uploadCount: 0,
+  residentChildBytes: 0,
+  generation: 0,
+  state: 'off',
+});
 export type { TransmissionInspection } from './transmission/inspection';
 
 export interface BatchTopologyInspection {
@@ -555,7 +579,29 @@ export interface TemporalTargetInspection {
 }
 
 /** Detached, bounded Motion Blur facts; no graph, device, target, or history handle. */
-export type MotionBlurInspectionStatus = 'off' | 'active' | 'reset' | 'invalid';
+export type MotionBlurInspectionStatus = 'off' | 'active' | 'reset' | 'limited' | 'invalid';
+export type MotionBlurInspectionLane = 'compute' | 'raster-limited';
+
+/**
+ * Submission receipt for the admitted compute lane. This is derived from the
+ * compiled graph and the resolved feature dispatches after a successful
+ * queue submit; capability intent alone never produces this receipt.
+ */
+export interface MotionBlurExecutionPass {
+  readonly name: 'motion-blur-tile-summary' | 'motion-blur';
+  readonly kind: 'compute';
+  readonly entryPoint: 'tile_summary' | 'reconstruct';
+  readonly workgroups: readonly [number, number, number];
+}
+
+export interface MotionBlurExecutionReceipt {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly program: 'motion-blur-compute';
+  readonly outputFormat: 'rgba16float';
+  readonly passes: readonly [MotionBlurExecutionPass, MotionBlurExecutionPass];
+}
 
 /** Bounded renderer-owned Depth of Field facts; no graph or GPU handles. */
 export type DepthOfFieldInspectionStatus = 'off' | 'active' | 'reset' | 'invalid' | 'unsupported';
@@ -597,13 +643,25 @@ export interface DepthOfFieldInspection {
 export interface MotionBlurInspection {
   readonly enabled: boolean;
   readonly status: MotionBlurInspectionStatus;
+  /** Capability-selected implementation lane; raster is explicitly limited. */
+  readonly lane: MotionBlurInspectionLane;
   readonly shutterAngle: number;
   readonly maxRadiusPixels: number;
   readonly sampleCount: number;
+  /** Target presentation rate used by the accepted exposure calculation. */
+  readonly targetFps: number;
+  /** Bounded tier selected from the authored sample budget. */
+  readonly effectiveSampleCount: 0 | 4 | 8 | 16;
   readonly temporalDemand: 'none' | 'scene-data-temporal-v1';
   readonly passName: 'motion-blur';
   readonly historyWrites: 0;
-  readonly lastFailure?: 'invalid-params' | 'scene-data-unavailable';
+  /** Zero when demand is disabled; compute uses one summary plus one fused pass. */
+  readonly passCount: 0 | 1 | 2;
+  readonly tapBudget: 0 | 4 | 8 | 16;
+  /** Present only when the current accepted frame executed both compute passes. */
+  readonly execution?: MotionBlurExecutionReceipt;
+  readonly resetReason?: import('./temporal/view').TemporalResetReason;
+  readonly lastFailure?: 'invalid-params' | 'scene-data-unavailable' | 'submit-failure';
 }
 
 export type RenderSceneResyncReason =

package/src/instances.ts

@@ -41,6 +41,8 @@ export function instanceUploadRangesForResident(
 
 export interface InstanceCollectionSnapshot extends InstanceCollectionInfo {
   readonly transforms: Float32Array;
+  /** Unique identity generations that travel with an instance through reorder. */
+  readonly generations: Uint32Array;
   readonly dirtyRanges: readonly InstanceDirtyRange[];
 }
 
@@ -171,6 +173,7 @@ export type InstanceCollectionResult<T> = Result<T, InstanceCollectionError>;
 interface CollectionRecord {
   readonly id: InstanceCollectionId;
   transforms: Float32Array;
+  generations: Uint32Array;
   count: number;
   capacity: number;
   revision: number;
@@ -307,6 +310,7 @@ function missing(
  */
 export class InstanceCollectionStore {
   private nextId = 1;
+  private nextInstanceGeneration = 1;
   private epochValue = 0;
   private disposed = false;
   private readonly records = new Map<InstanceCollectionId, CollectionRecord>();
@@ -330,9 +334,11 @@ export class InstanceCollectionStore {
     if (invalidPayload !== undefined) return err(invalidPayload);
     const id = this.nextId++ as InstanceCollectionId;
     const count = input.transforms.length / MATRIX_STRIDE;
+    const generations = this.allocateGenerations(count);
     const record: CollectionRecord = {
       id,
       transforms: new Float32Array(input.transforms),
+      generations,
       count,
       capacity: nextCapacity(Math.max(INITIAL_CAPACITY, count)),
       revision: 1,
@@ -348,13 +354,26 @@ export class InstanceCollectionStore {
   replace(
     id: InstanceCollectionId,
     transforms: Float32Array,
+    /** Prior identity generations in the replacement order; omitted rows are new. */
+    generations?: Uint32Array,
   ): InstanceCollectionResult<InstanceCollectionInfo> {
     const record = this.live('replace', id);
     if (!record.ok) return record;
     const invalidPayload = validateTransforms('replace', transforms, id);
     if (invalidPayload !== undefined) return err(invalidPayload);
     const count = transforms.length / MATRIX_STRIDE;
+    const generationResult =
+      generations === undefined
+        ? ok(this.allocateGenerations(count))
+        : this.validateReplacementGenerations(generations, count, id);
+    if (!generationResult.ok) return generationResult;
+    // Replacement is a topology boundary by default. A producer that keeps
+    // logical instance identity through compaction/reorder may pass the prior
+    // generation tokens in their new order; the record stage then maps the
+    // real previous transform by token instead of by draw ordinal.
+    const replacementGenerations = generationResult.value;
     record.value.transforms = new Float32Array(transforms);
+    record.value.generations = replacementGenerations;
     record.value.count = count;
     record.value.capacity = Math.max(record.value.capacity, nextCapacity(Math.max(1, count)));
     record.value.revision += 1;
@@ -402,6 +421,11 @@ export class InstanceCollectionStore {
       record.value.dirtyRanges = [];
     }
     record.value.transforms.set(input.transforms, input.start * MATRIX_STRIDE);
+    // An update changes a pose while retaining the same ordinal identity.
+    // Keep its generation stable so the record stage can pair this current
+    // transform with the last submitted transform and expose real velocity.
+    // `replace` is the explicit topology boundary that advances generations
+    // for compaction, reorder, retirement, and newly occupied ordinals.
     record.value.revision += 1;
     appendDirtyRange(record.value, input.start, input.start + span);
     this.epochValue += 1;
@@ -502,7 +526,12 @@ export class InstanceCollectionStore {
     if (!record.ok) return record;
     const value = record.value;
     value.lastSnapshotRevision = value.revision;
-    const result = this.detachedSnapshot(value);
+    const result = {
+      ...this.info(value),
+      transforms: new Float32Array(value.transforms),
+      generations: new Uint32Array(value.generations),
+      dirtyRanges: value.dirtyRanges.map((range) => ({ ...range })),
+    };
     // Keep the current ranges stable for repeated reads by entities sharing
     // this collection. The next authoring mutation starts a fresh interval
     // set once this revision has been observed.
@@ -579,6 +608,7 @@ export class InstanceCollectionStore {
     return {
       ...this.info(record),
       transforms: new Float32Array(record.transforms),
+      generations: new Uint32Array(record.generations),
       dirtyRanges: record.dirtyRanges.map((range) => ({ ...range })),
     };
   }
@@ -592,6 +622,55 @@ export class InstanceCollectionStore {
     });
   }
 
+  private allocateGenerations(count: number): Uint32Array {
+    const generations = new Uint32Array(count);
+    for (let index = 0; index < count; index += 1) {
+      generations[index] = this.nextInstanceGeneration;
+      this.nextInstanceGeneration = (this.nextInstanceGeneration + 1) >>> 0 || 1;
+    }
+    return generations;
+  }
+
+  private validateReplacementGenerations(
+    generations: Uint32Array,
+    count: number,
+    collectionId: InstanceCollectionId,
+  ): InstanceCollectionResult<Uint32Array> {
+    if (!(generations instanceof Uint32Array) || generations.length !== count) {
+      return err(
+        invalid(
+          'replace',
+          `generations is a Uint32Array with ${count} entries`,
+          generations instanceof Uint32Array ? generations.length : typeof generations,
+          collectionId,
+          { requestedBytes: generations?.byteLength ?? 0, cause: 'invalid-generation-shape' },
+        ),
+      );
+    }
+    const seen = new Set<number>();
+    for (const generation of generations) {
+      if (generation === 0 || seen.has(generation)) {
+        return err(
+          invalid(
+            'replace',
+            'generations contain unique non-zero identity tokens',
+            generation,
+            collectionId,
+            {
+              requestedBytes: generations.byteLength,
+              cause: 'invalid-generation-identity',
+            },
+          ),
+        );
+      }
+      seen.add(generation);
+      if (generation >= this.nextInstanceGeneration) {
+        this.nextInstanceGeneration = (generation + 1) >>> 0 || 1;
+      }
+    }
+    return ok(new Uint32Array(generations));
+  }
+
   private projectInspection(record: CollectionRecord): InstanceCollectionInspection {
     const residency = this.residency.get(record.id);
     return Object.freeze({