@forgeax/engine-render 0.1.7 → 0.1.19

package/src/scene/render-scene.ts

@@ -2,9 +2,10 @@ import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { componentId } from '@forgeax/engine-ecs/internal';
 import type { RenderReadLease } from '@forgeax/engine-ecs/projection';
 import { box3, frustum, mat4 } from '@forgeax/engine-math';
-import type { RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import { type RhiDevice, RhiError } from '@forgeax/engine-rhi';
 import { ChildOf, Transform } from '@forgeax/engine-scene';
 import { Skin } from '@forgeax/engine-skinning';
+import { err, ok, type Result } from '@forgeax/engine-types';
 import {
   Camera,
   DirectionalLight,
@@ -35,9 +36,17 @@ import type { CameraSnapshot } from '../render-contract';
 import type {
   DispatchEntry,
   ExtractedFrame,
+  MaterialSnapshot,
   MaterialSnapshotCachesByWorld,
+  RenderableReactiveReason,
   RenderableSnapshot,
+  RenderableTemporalSnapshot,
 } from '../render-system-extract';
+import {
+  PersistentTransmissionDemandProjection,
+  type TransmissionDemand,
+  type TransmissionDemandOperation,
+} from '../transmission/projection';
 import type {
   RenderSceneApplyResult,
   RenderSceneBounds,
@@ -69,13 +78,63 @@ interface PendingIdentity {
   removed: boolean;
 }
 
+export interface RenderSceneSubmissionCapture {
+  readonly revision: number;
+  readonly slots: readonly {
+    readonly slot: number;
+    readonly current: RenderSceneSlot | undefined;
+  }[];
+  readonly visible: ReadonlySet<string>;
+}
+
+export interface RenderSceneSubmissionDelta {
+  readonly epoch: number;
+  readonly slots: readonly number[];
+}
+
 function identityKey(worldId: number, entityKey: number): string {
   return `${worldId}:${entityKey}`;
 }
 
+const STANDARD_TRANSMISSION_SHADER = 'forgeax::default-standard-pbr';
+
+function transmissionValue(material: MaterialSnapshot): number {
+  const value = material.paramSnapshot?.transmission;
+  return typeof value === 'number' ? value : 0;
+}
+
+function transmissionRoughness(material: MaterialSnapshot): number {
+  const value = material.paramSnapshot?.roughness;
+  return typeof value === 'number' ? value : material.roughness;
+}
+
+function transmissionDemandOperations(
+  renderables: readonly RenderableSnapshot[],
+): readonly TransmissionDemandOperation[] {
+  const operations: TransmissionDemandOperation[] = [];
+  for (const renderable of renderables) {
+    for (const [materialIndex, material] of renderable.materials.entries()) {
+      operations.push({
+        kind: 'upsert',
+        key: `${renderable.worldId}:${renderable.entityKey}:${materialIndex}`,
+        candidate: {
+          attached: true,
+          ready:
+            material.materialShaderId === STANDARD_TRANSMISSION_SHADER &&
+            material.paramSnapshot !== undefined,
+          transmission: transmissionValue(material),
+          roughness: transmissionRoughness(material),
+        },
+      });
+    }
+  }
+  return operations;
+}
+
 function ownSnapshot(snapshot: RenderableSnapshot): RenderableSnapshot {
+  const { temporal: _temporal, ...current } = snapshot;
   return {
-    ...snapshot,
+    ...current,
     transform: { ...snapshot.transform, world: new Float32Array(snapshot.transform.world) },
     ...(snapshot.localAabb === undefined
       ? {}
@@ -169,10 +228,14 @@ function worldBounds(snapshot: RenderableSnapshot): RenderSceneBounds | undefine
  */
 export class RenderScene {
   private readonly slots: Array<RenderSceneSlot | undefined> = [];
+  private readonly lastSubmittedSlots: Array<RenderSceneSlot | undefined> = [];
   private readonly generations: number[] = [];
   private readonly freeSlots: number[] = [];
   private readonly slotsByWorld = new Map<number, Map<number, number>>();
   private readonly slotsByMaterial = new Map<number, Set<number>>();
+  private readonly dirtySinceSubmitted = new Set<number>();
+  private lastSubmittedVisible = new Set<string>();
+  private submittedEpoch = 0;
   // World bounds are a pure projection of each immutable snapshot. Cache the
   // derived value by snapshot identity so repeated view queries do not redo
   // the eight-corner transform for every view in the same frame.
@@ -188,6 +251,11 @@ export class RenderScene {
   private resyncs = 0;
   private lastResyncReason: RenderSceneResyncReason | undefined;
 
+  /** Bounded current-scene facts for the Standard temporal producer. */
+  temporalContributorCount(): number {
+    return this.orderedSlots.length;
+  }
+
   apply(operations: readonly RenderSceneOperation[]): RenderSceneApplyResult {
     if (operations.length === 0) {
       this.noChangeFrames += 1;
@@ -253,19 +321,25 @@ export class RenderScene {
     for (const pending of pendingOrder) {
       if (pending.initial === undefined) {
         if (pending.current === undefined) continue;
-        createdSlots.push(this.allocate(pending.current));
+        const createdSlot = this.allocate(pending.current);
+        this.dirtySinceSubmitted.add(createdSlot.slot);
+        createdSlots.push(createdSlot);
         created += 1;
         continue;
       }
       if (pending.current === undefined) {
+        this.dirtySinceSubmitted.add(pending.initial.slot);
         this.release(pending.initial);
         removedSlots.push(pending.initial);
         removed += 1;
         continue;
       }
       if (pending.removed) {
+        this.dirtySinceSubmitted.add(pending.initial.slot);
         this.release(pending.initial);
-        recreatedSlots.push(this.allocate(pending.current));
+        const recreatedSlot = this.allocate(pending.current);
+        this.dirtySinceSubmitted.add(recreatedSlot.slot);
+        recreatedSlots.push(recreatedSlot);
         recreated += 1;
         continue;
       }
@@ -276,6 +350,7 @@ export class RenderScene {
       this.unindexMaterials(pending.initial);
       this.slots[pending.initial.slot] = updatedSlot;
       this.indexMaterials(updatedSlot);
+      this.dirtySinceSubmitted.add(updatedSlot.slot);
       updatedSlots.push(updatedSlot);
       updated += 1;
     }
@@ -316,6 +391,12 @@ export class RenderScene {
 
   /** Reconcile the current identity set while retaining slots for survivors. */
   reset(snapshots: readonly RenderableSnapshot[], countAsRebuild = true): void {
+    // A full reconciliation is a temporal cut.  Survivors may keep their
+    // stable slot, but no prior slot is valid until this frame submits.
+    this.lastSubmittedSlots.length = 0;
+    this.lastSubmittedVisible.clear();
+    this.dirtySinceSubmitted.clear();
+    this.submittedEpoch = 0;
     const desired = new Map<string, RenderableSnapshot>();
     for (const snapshot of snapshots) {
       desired.set(identityKey(snapshot.worldId, snapshot.entityKey), snapshot);
@@ -330,7 +411,8 @@ export class RenderScene {
     for (const snapshot of desired.values()) {
       const existing = this.lookup(snapshot.worldId, snapshot.entityKey);
       if (existing === undefined) {
-        this.allocate(snapshot);
+        const created = this.allocate(snapshot);
+        this.dirtySinceSubmitted.add(created.slot);
         continue;
       }
       const updated: RenderSceneSlot = {
@@ -340,6 +422,7 @@ export class RenderScene {
       this.unindexMaterials(existing);
       this.slots[existing.slot] = updated;
       this.indexMaterials(updated);
+      this.dirtySinceSubmitted.add(updated.slot);
       this.orderedSlots.push(existing.slot);
     }
 
@@ -363,6 +446,59 @@ export class RenderScene {
     return this.materialized;
   }
 
+  lastSubmittedSlotByIndex(slot: number): RenderSceneSlot | undefined {
+    return this.lastSubmittedSlots[slot];
+  }
+
+  temporalSnapshotBySlot(slot: number): RenderableTemporalSnapshot | undefined {
+    const current = this.slots[slot];
+    return current === undefined ? undefined : this.temporalSnapshot(current);
+  }
+
+  withTemporal(snapshot: RenderableSnapshot): RenderableSnapshot {
+    const slot = this.lookup(snapshot.worldId, snapshot.entityKey);
+    return slot === undefined ? snapshot : { ...snapshot, temporal: this.temporalSnapshot(slot) };
+  }
+
+  wasLastSubmittedVisible(slot: number, generation: number): boolean {
+    return this.lastSubmittedVisible.has(`${slot}:${generation}`);
+  }
+
+  captureSubmission(
+    visible: readonly Pick<RenderableSnapshot, 'worldId' | 'entityKey'>[],
+  ): RenderSceneSubmissionCapture {
+    const visibleSlots = new Set<string>();
+    for (const snapshot of visible) {
+      const slot = this.lookup(snapshot.worldId, snapshot.entityKey);
+      if (slot !== undefined) visibleSlots.add(`${slot.slot}:${slot.generation}`);
+    }
+    return {
+      revision: this.revision,
+      slots: [...this.dirtySinceSubmitted].map((slot) => ({
+        slot,
+        current: this.slots[slot],
+      })),
+      visible: visibleSlots,
+    };
+  }
+
+  commitSubmission(capture: RenderSceneSubmissionCapture): RenderSceneSubmissionDelta {
+    if (capture.revision !== this.revision) {
+      throw new RangeError('render scene changed while its temporal submission was active');
+    }
+    for (const update of capture.slots) {
+      this.lastSubmittedSlots[update.slot] = update.current;
+      this.dirtySinceSubmitted.delete(update.slot);
+    }
+    this.lastSubmittedVisible = new Set(capture.visible);
+    this.submittedEpoch += 1;
+    this.invalidateSnapshots();
+    return {
+      epoch: this.submittedEpoch,
+      slots: capture.slots.map((update) => update.slot),
+    };
+  }
+
   slotsSnapshot(): readonly RenderSceneSlot[] {
     if (this.slotSnapshot !== undefined) return this.slotSnapshot;
     const records: RenderSceneSlot[] = [];
@@ -522,6 +658,49 @@ export class RenderScene {
     }
   }
 
+  private temporalSnapshot(slot: RenderSceneSlot): RenderableTemporalSnapshot {
+    const submitted = this.lastSubmittedSlots[slot.slot];
+    const sameGeneration = submitted?.generation === slot.generation;
+    const wasVisible =
+      sameGeneration && this.lastSubmittedVisible.has(`${slot.slot}:${slot.generation}`);
+    const reasons: RenderableReactiveReason[] = [];
+    if (!sameGeneration) {
+      reasons.push(submitted === undefined ? 'new-slot' : 'generation-reuse');
+    } else if (!wasVisible) {
+      reasons.push('reentered');
+    }
+    if (
+      sameGeneration &&
+      submitted !== undefined &&
+      submitted.snapshot.assetHandle !== slot.snapshot.assetHandle
+    ) {
+      reasons.push('geometry-revision');
+    }
+    if (
+      sameGeneration &&
+      submitted !== undefined &&
+      submitted.snapshot.materials !== slot.snapshot.materials
+    ) {
+      reasons.push('material-revision');
+    }
+    const seedCurrent =
+      !sameGeneration ||
+      !wasVisible ||
+      reasons.includes('geometry-revision') ||
+      reasons.includes('material-revision');
+    const previous = seedCurrent || submitted === undefined ? slot.snapshot : submitted.snapshot;
+    return {
+      previousEpoch: seedCurrent ? undefined : this.submittedEpoch,
+      previousSource: seedCurrent ? 'current-seed' : 'last-submitted',
+      reactive: reasons.length > 0,
+      reactiveReasons: reasons,
+      previousTransform: previous.transform,
+      previousInstances: previous.instances,
+      previousSkin: previous.skin,
+      previousMorphWeights: previous.morph?.weights,
+    };
+  }
+
   private invalidateSnapshots(): void {
     this.materialized = undefined;
     this.slotSnapshot = undefined;
@@ -554,6 +733,7 @@ interface PersistentCompositionEntry {
   readonly resourceOwner: number;
   readonly projection: RenderScene;
   readonly topology: BatchTopology;
+  readonly transmissionDemand: PersistentTransmissionDemandProjection;
   readonly readCursors: number[];
   readonly leaseIdentities: readonly string[];
   catalogEpoch: number;
@@ -693,6 +873,9 @@ export class PersistentRenderScene {
   private gpuDevice: RhiDevice | undefined;
   private gpuStatus: 'inactive' | 'unsupported' | 'resident' | 'rebuild-pending' | 'error' =
     'inactive';
+  private temporalCapture:
+    | { readonly projection: RenderScene; readonly capture: RenderSceneSubmissionCapture }
+    | undefined;
   private pointsLinesInspections: readonly PointsLinesInspection[] = [];
 
   constructor(private readonly options: PersistentRenderSceneOptions = {}) {}
@@ -817,7 +1000,11 @@ export class PersistentRenderScene {
             });
             continue;
           }
+          // Camera snapshots are rebuilt from the current candidate frame and
+          // drive culling there; moving a camera must not invalidate the
+          // retained scene projection or recreate its GPU tables.
           if (
+            !world.hasComponent(entity, Camera) &&
             NON_RENDERABLE_TRANSFORM_CONSUMERS.some((component) =>
               world.hasComponent(entity, component),
             )
@@ -848,6 +1035,7 @@ export class PersistentRenderScene {
 
   invalidate(): void {
     this.composition = undefined;
+    this.temporalCapture = undefined;
     this.lastResyncReason = 'explicit-invalidate';
   }
 
@@ -864,6 +1052,7 @@ export class PersistentRenderScene {
       ? this.composition
       : undefined;
     if (detachedComposition !== undefined) this.composition = undefined;
+    if (detachedComposition !== undefined) this.temporalCapture = undefined;
     if (this.gpuOwner !== world && this.gpuOwner !== detachedComposition?.token) return;
     this.gpuScene?.dispose();
     this.gpuScene = undefined;
@@ -896,6 +1085,7 @@ export class PersistentRenderScene {
     this.gpuDevice = undefined;
     this.gpuStatus = 'inactive';
     this.composition = undefined;
+    this.temporalCapture = undefined;
     this.pointsLinesInspections = [];
   }
 
@@ -937,6 +1127,40 @@ export class PersistentRenderScene {
     };
   }
 
+  /** Publish renderer-owned previous transforms after queue submission. */
+  commitTemporalFrame(): Result<void, RhiError> {
+    const gpuCommit = this.gpuScene?.commitTemporalFrame();
+    if (gpuCommit !== undefined && !gpuCommit.ok) return gpuCommit;
+    const temporalCapture = this.temporalCapture;
+    if (temporalCapture !== undefined) {
+      try {
+        temporalCapture.projection.commitSubmission(temporalCapture.capture);
+      } catch (cause) {
+        void cause;
+        return err(
+          new RhiError({
+            code: 'internal-error',
+            expected: 'render scene remains unchanged while a submitted temporal frame commits',
+            hint: 'retry the temporal frame after the renderer-owned scene snapshot is stable',
+          }),
+        );
+      }
+      this.temporalCapture = undefined;
+    }
+    return ok(undefined);
+  }
+
+  /** Capture current CPU scene facts; commitTemporalFrame publishes them only after submit. */
+  prepareTemporalFrame(
+    visible: readonly Pick<RenderableSnapshot, 'worldId' | 'entityKey'>[],
+  ): void {
+    const projection = this.composition?.projection;
+    this.temporalCapture =
+      projection === undefined
+        ? undefined
+        : { projection, capture: projection.captureSubmission(visible) };
+  }
+
   pointsLinesSnapshots(): readonly PointsLinesRetainedSnapshot[] {
     return this.composition?.projection.pointsLinesSnapshots() ?? [];
   }
@@ -961,9 +1185,12 @@ export class PersistentRenderScene {
     leases?: readonly RenderReadLease[],
   ): ExtractedFrame {
     const candidateFrame = buildCandidateFrame();
+    this.temporalCapture = undefined;
     this.worldEntitiesScanned = candidateFrame.renderables.length;
     const projection = new RenderScene();
     projection.reset(candidateFrame.renderables);
+    const transmissionDemand = new PersistentTransmissionDemandProjection();
+    transmissionDemand.apply(transmissionDemandOperations(candidateFrame.renderables));
     const topology = new BatchTopology();
     topology.rebuild(projection.slotsSnapshot());
     const token = {};
@@ -974,6 +1201,7 @@ export class PersistentRenderScene {
       resourceOwner: owner.resourceOwner,
       projection,
       topology,
+      transmissionDemand,
       readCursors:
         leases === undefined || leases.length !== worlds.length
           ? []
@@ -991,7 +1219,20 @@ export class PersistentRenderScene {
     this.syncGpuOwner(token, projection, undefined, true);
     this.fullRebuilds += 1;
     this.lastResyncReason = 'attach';
-    return cullPersistentFrame(candidateFrame, projection.materialize());
+    const candidates = projection
+      .materialize()
+      .map((snapshot) => projection.withTemporal(snapshot));
+    return cullPersistentFrame({ ...candidateFrame, renderables: [...candidates] }, candidates);
+  }
+
+  /** Internal topology fact; the renderer does not expose demand as public API. */
+  transmissionTopologyDemand(): TransmissionDemand {
+    return (
+      this.composition?.transmissionDemand.inspect() ?? {
+        activeCount: 0,
+        needsRoughMips: false,
+      }
+    );
   }
 
   /**
@@ -1003,7 +1244,9 @@ export class PersistentRenderScene {
     buildCandidateFrame: () => ExtractedFrame,
   ): ExtractedFrame {
     const candidateFrame = buildCandidateFrame();
-    const candidates = entry.projection.materialize();
+    const candidates = entry.projection
+      .materialize()
+      .map((snapshot) => entry.projection.withTemporal(snapshot));
     return cullPersistentFrame({ ...candidateFrame, renderables: [...candidates] }, candidates);
   }
 

package/src/temporal/__tests__/taa-history-resources.unit.test.ts

@@ -0,0 +1,45 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { createTaaHistoryResources, type TaaHistoryResources } from '../taa-history-resources';
+
+async function nullDevice(): Promise<RhiDevice> {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw adapter.error;
+  const device = await adapter.value.requestDevice();
+  if (!device.ok) throw device.error;
+  return device.value;
+}
+
+describe('TAA GPU history resources', () => {
+  it('allocates two rgba16float slots with sampled/render/copy usage', async () => {
+    const device = await nullDevice();
+    const resources = createTaaHistoryResources(device, 64, 32);
+    expect(resources.ok).toBe(true);
+    if (!resources.ok) return;
+    expect(resources.value.slots).toHaveLength(2);
+    expect(resources.value.descriptor.format).toBe('rgba16float');
+    expect(resources.value.descriptor.usage).toBe(0x17);
+    resources.value.dispose();
+  });
+
+  it('swaps only on commit and preserves the previous slot on abort', async () => {
+    const device = await nullDevice();
+    const resources = createTaaHistoryResources(device, 8, 8);
+    expect(resources.ok).toBe(true);
+    if (!resources.ok) return;
+    const state: TaaHistoryResources = resources.value;
+    expect(state.previousIndex).toBe(1);
+    expect(state.valid).toBe(false);
+    state.beginFrame();
+    state.abortFrame();
+    expect(state.currentIndex).toBe(0);
+    expect(state.valid).toBe(false);
+    state.beginFrame();
+    state.commitFrame();
+    expect(state.currentIndex).toBe(1);
+    expect(state.previousIndex).toBe(0);
+    expect(state.valid).toBe(true);
+    state.dispose();
+  });
+});

package/src/temporal/coverage.ts

@@ -0,0 +1,76 @@
+import type { SceneDataLane, SceneDataSchemaId } from './scene-data';
+
+export interface SceneDataCoverage {
+  readonly schema: SceneDataSchemaId;
+  readonly lane: SceneDataLane;
+  readonly producerId: string;
+  readonly complete: boolean;
+  readonly contributorIds: readonly string[];
+  readonly exactContributorIds: readonly string[];
+  readonly reactiveContributorIds: readonly string[];
+  readonly missingContributorIds: readonly string[];
+  readonly omittedMissingContributorCount: number;
+}
+
+export interface TemporalCoverage {
+  readonly width: number;
+  readonly height: number;
+  readonly bytes: number;
+  readonly fullScreen: true;
+}
+
+export function createTemporalCoverage(width: number, height: number): TemporalCoverage {
+  if (!Number.isSafeInteger(width) || width <= 0) throw new RangeError('width must be positive.');
+  if (!Number.isSafeInteger(height) || height <= 0)
+    throw new RangeError('height must be positive.');
+  return Object.freeze({ width, height, bytes: 32 * width * height, fullScreen: true as const });
+}
+
+export type SceneDataContributorKind = 'exact' | 'reactive';
+export interface SceneDataContributor {
+  readonly id: string;
+  readonly kind: SceneDataContributorKind;
+}
+export function classifySceneDataCoverage(input: {
+  readonly contributors: readonly SceneDataContributor[];
+  readonly requiredContributorIds: readonly string[];
+}): {
+  readonly exactContributorIds: readonly string[];
+  readonly reactiveContributorIds: readonly string[];
+  readonly missingContributorIds: readonly string[];
+  readonly omittedMissingContributorCount: number;
+  readonly complete: boolean;
+} {
+  const exactContributorIds = input.contributors.filter((c) => c.kind === 'exact').map((c) => c.id);
+  const reactiveContributorIds = input.contributors
+    .filter((c) => c.kind === 'reactive')
+    .map((c) => c.id);
+  const available = new Set(input.contributors.map((c) => c.id));
+  const missing = input.requiredContributorIds.filter((id) => !available.has(id));
+  return {
+    exactContributorIds: Object.freeze(exactContributorIds),
+    reactiveContributorIds: Object.freeze(reactiveContributorIds),
+    missingContributorIds: Object.freeze(missing.slice(0, 32)),
+    omittedMissingContributorCount: Math.max(0, missing.length - 32),
+    complete: missing.length === 0,
+  };
+}
+export function scanSceneDataCoverage(input: {
+  readonly schema: SceneDataSchemaId;
+  readonly lane: SceneDataLane;
+  readonly producerId: string;
+  readonly contributorIds: readonly string[];
+  readonly requiredContributorIds: readonly string[];
+}): SceneDataCoverage {
+  const classification = classifySceneDataCoverage({
+    contributors: input.contributorIds.map((id) => ({ id, kind: 'exact' as const })),
+    requiredContributorIds: input.requiredContributorIds,
+  });
+  return Object.freeze({
+    schema: input.schema,
+    lane: input.lane,
+    producerId: input.producerId,
+    ...classification,
+    contributorIds: Object.freeze([...input.contributorIds]),
+  });
+}