@forgeax/engine-render 0.1.21 → 0.1.24

package/src/temporal/frame-coordinator.ts

@@ -70,6 +70,32 @@ export interface TemporalFrameReceipt<T = unknown> {
   readonly historyDirection: 'a-to-b' | 'b-to-a';
 }
 
+export type ReflectionFallbackTemporalReset =
+  | { readonly reset: false }
+  | { readonly reset: true; readonly reason: 'reflection-fallback-generation' };
+
+/** Maps committed producer generations into the existing temporal reset seam. */
+export function resolveReflectionFallbackTemporalReset(
+  previousGeneration: number | undefined,
+  nextGeneration: number | undefined,
+): ReflectionFallbackTemporalReset {
+  if (previousGeneration === undefined || nextGeneration === undefined) return { reset: false };
+  return previousGeneration === nextGeneration
+    ? { reset: false }
+    : { reset: true, reason: 'reflection-fallback-generation' };
+}
+
+/**
+ * Keeps SSR admission on the existing producer-generation reset seam. The
+ * admission path never allocates or resolves temporal history itself.
+ */
+export function resolveSsrAdmissionTemporalReset(
+  previousGeneration: number | undefined,
+  nextGeneration: number | undefined,
+): ReflectionFallbackTemporalReset {
+  return resolveReflectionFallbackTemporalReset(previousGeneration, nextGeneration);
+}
+
 function failure(code: TemporalFrameErrorCode, hint: string): TemporalFrameError {
   return {
     code,
@@ -176,7 +202,10 @@ export class TemporalFrameCoordinator<T = unknown> {
     }
     this.historyDirection = candidate.history.direction === 'a-to-b' ? 'b-to-a' : 'a-to-b';
     const historyAttempt = this.historyAttempts.get(candidate);
-    historyAttempt?.commit();
+    historyAttempt?.commit({
+      deviceGeneration: this.historyStore.inspect().deviceGeneration,
+      completed: true,
+    });
     this.coverage = classifySceneDataCoverage({
       contributors: candidate.contributors,
       requiredContributorIds: candidate.requiredContributorIds,

package/src/temporal/frame.ts

@@ -44,6 +44,8 @@ export interface TemporalFrameTransaction {
   stage(input: TemporalFrameInput): void;
   commit(submit: TemporalSubmitResult): Result<TemporalFrame, TemporalFrameSubmitError>;
   snapshot(): TemporalFrame;
+  /** Drop accepted/staged history after a producer or device generation cut. */
+  reset(reason?: Extract<TemporalResetReason, 'signature-change' | 'device-recovery'>): void;
 }
 
 function copyInput(input: TemporalFrameInput): TemporalFrameInput {
@@ -82,6 +84,7 @@ export function createTemporalFrameTransaction(options: {
   let accepted: TemporalFrame | undefined;
   let staged: TemporalFrameInput | undefined;
   let historyEpoch = 0;
+  let pendingResetReason: Exclude<TemporalResetReason, 'none' | 'queue-submit-failed'> | undefined;
 
   return {
     stage(input) {
@@ -96,7 +99,7 @@ export function createTemporalFrameTransaction(options: {
         return err(new TemporalFrameSubmitError('queue-submit-failed'));
       }
 
-      const resetReason = submit.resetReason ?? staged.resetReason ?? 'none';
+      const resetReason = submit.resetReason ?? staged.resetReason ?? pendingResetReason ?? 'none';
       const shouldReset = resetReason !== 'none';
       if (shouldReset) historyEpoch += 1;
       const next: TemporalFrame = {
@@ -117,6 +120,7 @@ export function createTemporalFrameTransaction(options: {
       };
       accepted = next;
       staged = undefined;
+      pendingResetReason = undefined;
       return ok(copyFrame(next));
     },
     snapshot() {
@@ -124,5 +128,14 @@ export function createTemporalFrameTransaction(options: {
         throw new Error('TemporalFrame snapshot is unavailable before commit');
       return copyFrame(accepted);
     },
+    reset(reason = 'signature-change') {
+      accepted = undefined;
+      staged = undefined;
+      historyEpoch += 1;
+      // The reason is carried into the next accepted frame while clearing the
+      // committed frame prevents stale motion vectors from crossing the
+      // producer/device boundary.
+      pendingResetReason = reason;
+    },
   };
 }

package/src/temporal/taa-history-store.ts

@@ -6,6 +6,11 @@ export type TaaHistoryResetReason =
   | 'device-generation';
 
 export interface TaaHistoryInspection {
+  readonly token: number;
+  readonly deviceGeneration: number;
+  readonly content: 'uninitialized' | 'active';
+  readonly fallback: 'neutral-texture';
+  readonly requestVersion: number;
   readonly generation: number;
   readonly seed: number;
   readonly attempt: 'none' | 'active' | 'committed' | 'aborted';
@@ -13,15 +18,26 @@ export interface TaaHistoryInspection {
   readonly resetReason: TaaHistoryResetReason | undefined;
 }
 
+export interface TaaHistoryReceipt {
+  readonly deviceGeneration: number;
+  readonly completed: boolean;
+}
+
 export interface TaaHistoryAttempt {
   readonly generation: number;
   readonly seed: number;
-  commit(): void;
+  commit(receipt?: TaaHistoryReceipt): void;
   abort(): void;
 }
 
+let nextHistoryToken = 1;
+
 /** TAA-only history owner. No global registry or backend handle crosses this boundary. */
 export class TaaHistoryStore {
+  private readonly token = nextHistoryToken++;
+  private deviceGeneration = 0;
+  private content: TaaHistoryInspection['content'] = 'uninitialized';
+  private requestVersion = 0;
   private generation = 0;
   private seed = 0;
   private valid = false;
@@ -36,11 +52,21 @@ export class TaaHistoryStore {
     return {
       generation,
       seed,
-      commit: () => {
+      commit: (receipt) => {
         if (state !== 'active') return;
+        if (
+          receipt !== undefined &&
+          (!receipt.completed || receipt.deviceGeneration !== this.deviceGeneration)
+        ) {
+          state = 'aborted';
+          this.attempt = 'aborted';
+          return;
+        }
         state = 'committed';
         this.attempt = 'committed';
         this.valid = true;
+        this.content = 'active';
+        this.requestVersion += 1;
         this.generation += 1;
         this.seed += 1;
         this.resetReason = reason;
@@ -55,6 +81,7 @@ export class TaaHistoryStore {
 
   seedHistory(reason: TaaHistoryResetReason = 'first-frame'): void {
     this.valid = false;
+    this.content = 'uninitialized';
     this.resetReason = reason;
     this.attempt = 'none';
   }
@@ -63,12 +90,29 @@ export class TaaHistoryStore {
     this.generation = 0;
     this.seed = 0;
     this.valid = false;
+    this.content = 'uninitialized';
     this.attempt = 'none';
     this.resetReason = reason;
   }
 
+  recoverForGeneration(deviceGeneration: number): void {
+    if (!Number.isSafeInteger(deviceGeneration) || deviceGeneration < 0) {
+      throw new RangeError('deviceGeneration must be a non-negative safe integer.');
+    }
+    this.deviceGeneration = deviceGeneration;
+    this.valid = false;
+    this.content = 'uninitialized';
+    this.attempt = 'none';
+    this.resetReason = 'device-generation';
+  }
+
   inspect(): TaaHistoryInspection {
     return {
+      token: this.token,
+      deviceGeneration: this.deviceGeneration,
+      content: this.content,
+      fallback: 'neutral-texture',
+      requestVersion: this.requestVersion,
       generation: this.generation,
       seed: this.seed,
       attempt: this.attempt,

package/src/temporal/temporal-view.ts

@@ -89,8 +89,8 @@ function cameraProjection(camera: CameraSnapshot): Float32Array {
       projection,
       camera.orthoLeft,
       camera.orthoRight,
-      camera.orthoBottom,
       camera.orthoTop,
+      camera.orthoBottom,
       camera.near,
       camera.far,
     );

package/src/temporal/transaction.ts

@@ -10,6 +10,15 @@ export interface TemporalFrameCandidate {
   readonly history: TemporalHistory;
 }
 
+export interface TemporalGenerationFence {
+  readonly capturedGeneration: number;
+  readonly currentGeneration: () => number;
+}
+
+export function temporalGenerationIsCurrent(fence: TemporalGenerationFence): boolean {
+  return fence.currentGeneration() === fence.capturedGeneration;
+}
+
 export function stageTemporalFrame(
   candidate: TemporalFrameCandidate,
 ): RendererFrameTransaction<TemporalFrameCandidate> {

package/src/temporal/view.ts

@@ -38,6 +38,8 @@ export interface TemporalViewInput {
   readonly historyValid?: boolean;
   readonly currentUnjitteredViewProjection?: ArrayLike<number> | undefined;
   readonly previousUnjitteredViewProjection?: ArrayLike<number> | undefined;
+  readonly currentCameraPosition?: readonly [number, number, number] | undefined;
+  readonly previousCameraPosition?: readonly [number, number, number] | undefined;
   readonly resetReason?: TemporalResetReason | undefined;
 }
 
@@ -55,6 +57,8 @@ interface TemporalViewSnapshot {
   readonly historyValid: boolean;
   readonly currentUnjitteredViewProjection: ArrayLike<number> | undefined;
   readonly previousUnjitteredViewProjection: ArrayLike<number> | undefined;
+  readonly currentCameraPosition: readonly [number, number, number] | undefined;
+  readonly previousCameraPosition: readonly [number, number, number] | undefined;
   readonly resetReason: TemporalResetReason | undefined;
 }
 
@@ -70,6 +74,9 @@ export interface TemporalView {
   /** Unjittered matrices are supplied by the renderer projection owner. */
   readonly currentUnjitteredViewProjection: ArrayLike<number> | undefined;
   readonly previousUnjitteredViewProjection: ArrayLike<number> | undefined;
+  /** Camera origins follow the same accepted-submit boundary as the matrices. */
+  readonly currentCameraPosition: readonly [number, number, number] | undefined;
+  readonly previousCameraPosition: readonly [number, number, number] | undefined;
   readonly currentProjection: 'jittered' | 'unjittered';
   readonly previousProjection: 'unjittered';
   readonly historyRequired: boolean;
@@ -112,6 +119,8 @@ export function createTemporalView(input: TemporalViewInput): TemporalView {
     historyValid: input.historyValid ?? false,
     currentUnjitteredViewProjection: input.currentUnjitteredViewProjection,
     previousUnjitteredViewProjection: input.previousUnjitteredViewProjection,
+    currentCameraPosition: input.currentCameraPosition,
+    previousCameraPosition: input.previousCameraPosition,
     resetReason: input.resetReason,
   });
   const taa = input.antialias === 'taa';
@@ -135,6 +144,8 @@ export function createTemporalView(input: TemporalViewInput): TemporalView {
     temporalFrameIndex: frameIndex,
     currentUnjitteredViewProjection: input.currentUnjitteredViewProjection,
     previousUnjitteredViewProjection: input.previousUnjitteredViewProjection,
+    currentCameraPosition: input.currentCameraPosition,
+    previousCameraPosition: input.previousCameraPosition,
     currentProjection: taa ? 'jittered' : 'unjittered',
     previousProjection: 'unjittered',
     historyRequired: taa,

package/src/tilemap-chunk-extract-system.ts

@@ -57,7 +57,7 @@ import {
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { decodeTileBits } from '@forgeax/engine-graphics-extras';
 import { type box3, frustum, mat4 } from '@forgeax/engine-math';
-import { ChildOf, Children, Transform } from '@forgeax/engine-scene';
+import { ChildOf, Children, GlobalTransform, Transform } from '@forgeax/engine-scene';
 import {
   type Handle,
   type MaterialAsset,
@@ -874,13 +874,13 @@ function bucketTileLayer(
  * cull paths use byte-identical planes (charter P4 consistent abstraction).
  */
 function buildCameraFrustumPlanes(world: World): frustum.Frustum | null {
-  const query = world.query({ with: [Camera, Transform] }).unwrap();
+  const query = world.query({ with: [Camera, Transform, GlobalTransform] }).unwrap();
   let result: frustum.Frustum | null = null;
   for (const row of query) {
     const camEntity = row.entity;
 
     const camRes = world.get(camEntity, Camera);
-    const trRes = world.get(camEntity, Transform);
+    const trRes = world.get(camEntity, GlobalTransform);
     if (!camRes.ok || !trRes.ok) continue;
 
     const cam = camRes.value;
@@ -895,8 +895,8 @@ function buildCameraFrustumPlanes(world: World): frustum.Frustum | null {
         proj as Parameters<typeof mat4.orthographic>[0],
         cam.left,
         cam.right,
-        cam.bottom,
         cam.top,
+        cam.bottom,
         near,
         far,
       );
@@ -1081,7 +1081,7 @@ function evictDeadPerCellStreamingCaches(work: readonly LayerWork[], world: Worl
 /**
  * Walk every TileLayer ChildOf-ing a Tilemap, extract its non-zero cells
  * into derived render entities. A Renderer attaches this system to FrameEnd;
- * World's final publication then resolves newly-created Transform.world values before the
+ * World's final publication then resolves newly-created GlobalTransform.world values before the
  * read-only render walk begins.
  *
  * Two paths based on `TileLayer.sortScope`:

package/src/transmission/__tests__/standard-transmission.dawn.test.ts

@@ -29,6 +29,7 @@ const BUFFER_USAGE_MAP_READ = 0x0001;
 const BUFFER_USAGE_COPY_DST = 0x0008;
 const GPU_MAP_MODE_READ = 0x0001;
 const TEST_REACTIVE = 0;
+const LIGHTWEIGHT_DAWN = process.env.FORGEAX_DAWN_LIGHTWEIGHT === '1';
 
 const ENGINE_MANIFEST = await (async () => {
   const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
@@ -377,8 +378,8 @@ describe('Standard transmission Dawn ROI', () => {
   }, 120_000);
 
   it('keeps IOR, thickness, and roughness monotonic in a finite linear ROI', async () => {
-    const cases = await Promise.all([
-      renderCase({
+    const fullCases = [
+      {
         name: 'ior-low',
         transmission: 1,
         ior: 1.1,
@@ -386,8 +387,8 @@ describe('Standard transmission Dawn ROI', () => {
         roughness: 0.1,
         attenuationColor: [0.8, 0.8, 0.8],
         attenuationDistance: 4,
-      }),
-      renderCase({
+      },
+      {
         name: 'ior-high',
         transmission: 1,
         ior: 2.2,
@@ -395,8 +396,8 @@ describe('Standard transmission Dawn ROI', () => {
         roughness: 0.1,
         attenuationColor: [0.8, 0.8, 0.8],
         attenuationDistance: 4,
-      }),
-      renderCase({
+      },
+      {
         name: 'thick',
         transmission: 1,
         ior: 1.5,
@@ -404,8 +405,8 @@ describe('Standard transmission Dawn ROI', () => {
         roughness: 0.1,
         attenuationColor: [0.1, 0.1, 0.1],
         attenuationDistance: 1,
-      }),
-      renderCase({
+      },
+      {
         name: 'rough',
         transmission: 1,
         ior: 1.5,
@@ -413,12 +414,18 @@ describe('Standard transmission Dawn ROI', () => {
         roughness: 0.9,
         attenuationColor: [0.8, 0.8, 0.8],
         attenuationDistance: 4,
-      }),
-    ]);
+      },
+    ] as const;
+    // Browser parity still exercises every transmission fixture. The PR
+    // Dawn lane keeps the low/high IOR and roughness boundaries, while the
+    // full local/nightly lane retains the thickness case as well.
+    const selectedCases = LIGHTWEIGHT_DAWN ? [fullCases[0], fullCases[1], fullCases[3]] : fullCases;
+    const cases = await Promise.all(selectedCases.map((testCase) => renderCase(testCase)));
     for (const result of cases) expect(result.pixel.every(Number.isFinite)).toBe(true);
     expect(cases[1]?.pixel).not.toEqual(cases[0]?.pixel);
-    expect(cases[2]?.pixel).not.toEqual(cases[0]?.pixel);
-    expect(luma(cases[3]?.pixel ?? [0, 0, 0, 0])).toBeLessThanOrEqual(
+    if (!LIGHTWEIGHT_DAWN) expect(cases[2]?.pixel).not.toEqual(cases[0]?.pixel);
+    const rough = LIGHTWEIGHT_DAWN ? cases[2] : cases[3];
+    expect(luma(rough?.pixel ?? [0, 0, 0, 0])).toBeLessThanOrEqual(
       luma(cases[0]?.pixel ?? [0, 0, 0, 0]) + 2,
     );
   }, 120_000);

package/src/typed-render-graph-primitives.ts

@@ -34,6 +34,7 @@ import {
 } from './render-graph-primitives';
 import type { RenderPipelineFrame, RenderPipelineGpuDrivenProjection } from './render-pipeline';
 import { createRenderPipelineTarget, type RenderPipelineTarget } from './render-pipeline';
+import type { OcclusionFrameProjection } from './scene/visibility/occlusion-runtime';
 import {
   getTemporalBindGroupResources,
   getTemporalGpuState,
@@ -136,6 +137,7 @@ export interface TypedScenePassOptions {
   readonly transmissionBackdrop?: GraphTextureView | undefined;
   readonly extraAccesses?: readonly GraphAccess[] | undefined;
   readonly gpuDriven?: RenderPipelineGpuDrivenProjection | undefined;
+  readonly occlusion?: OcclusionFrameProjection | undefined;
 }
 
 export function addTypedScenePass(
@@ -187,6 +189,7 @@ export function addTypedScenePass(
       stencilLoadOp: options.depthLoadOp ?? 'clear',
       stencilStoreOp: 'store',
     },
+    occlusionQuerySet: options.occlusion?.querySet,
     encode: ({ pass, frame, resources }) => {
       const colorViews = colorTargets.map((target) => resolvedView(resources, target.view));
       const depthView = resolvedView(resources, options.depth.view);
@@ -228,13 +231,23 @@ export function addTypedScenePass(
       if (groups.viewBindGroup !== null) {
         options.gpuDriven?.encode(groups.viewBindGroup, pass, resources);
       }
+      // The context carries the frame's primary occlusion projection for
+      // pipeline construction, but only the pass that owns that projection
+      // may begin its query. Forwarding it to deferred/temporal scene passes
+      // leaves their descriptors without an occlusionQuerySet and makes Dawn
+      // reject beginOcclusionQuery in those passes.
+      const activeOcclusion = options.occlusion;
       encodeMainPass(
         {
           ...internal,
+          ...(activeOcclusion === undefined ? {} : { occlusion: activeOcclusion }),
           geometryColorView: colorViews[0] ?? null,
           geometryDepthView: depthView,
           geometryColorResolveView: resolveView,
           transparentColorFormat: colorTargets[0]?.format as GPUTextureFormat,
+          ...(colorTargets[1]?.format === 'rgba16float'
+            ? { reflectionFallbackColorFormat: 'rgba16float' as const }
+            : {}),
           msaaActive: colorTargets[0]?.sampleCount === 4,
           viewBindGroup: groups.viewBindGroup,
           meshBindGroup: groups.meshBindGroup,
@@ -256,6 +269,10 @@ export function addTypedScenePass(
             : { transmissionBackdropView: transmissionBackdrop }),
         },
       );
+      if (activeOcclusion !== undefined) {
+        const proxyResult = activeOcclusion.encodeProxyBounds(pass);
+        if (!proxyResult.ok) throw proxyResult.error;
+      }
     },
   });
 }
@@ -291,6 +308,37 @@ export function addTypedFrameObservationPass(
   });
 }
 
+/** Publish the same-frame fallback MRT as a detached, copy-readable source. */
+export function addReflectionFallbackObservationPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  target: RenderPipelineTarget,
+): Result<void, RenderGraphError> {
+  return graph.addCopyPass('reflection-fallback-observation', {
+    accesses: [{ resource: target.view, usage: 'copy-src' }],
+    encode: ({ frame, resources }) => {
+      const internal = frame as _InternalRenderPipelineContext;
+      const texture = resources.texture(target.texture);
+      if (!texture.ok) throw texture.error;
+      internal.frameState.reflectionFallbackObservationSource = {
+        texture: texture.value,
+        descriptor: {
+          texture: texture.value,
+          format: target.format,
+          size: { width: frame.targetW, height: frame.targetH },
+          usage:
+            GPU_TEXTURE_USAGE_COPY_SRC |
+            GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+            GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+          sample: target.sampleCount,
+        },
+        frameId: internal.frameState.frameNumber,
+        pipelineId: 'forgeax::standard',
+        backendId: internal.runtime.device.caps.backendKind,
+      };
+    },
+  });
+}
+
 export interface TypedBloomTargets {
   readonly scene: RenderPipelineTarget;
   readonly composited: RenderPipelineTarget;