@forgeax/engine-render 0.1.20 → 0.1.23

package/src/targets/owner.ts

@@ -0,0 +1,214 @@
+import type { RenderError } from '../errors/render';
+import { RenderTargetOperationFailedError, RenderTargetStateInvalidError } from '../errors/render';
+import type { RenderResult } from '../render-contract';
+import type { RenderTarget, RenderTargetDescriptor } from './contracts';
+
+export type RenderTargetOwnerState =
+  | 'uninitialized'
+  | 'candidate'
+  | 'active'
+  | 'rebuilding'
+  | 'destroyed';
+
+export interface RenderTargetPhysicalCandidate {
+  readonly generation: number;
+  readonly descriptor: RenderTargetDescriptor;
+}
+
+export interface RenderTargetOwnerInspection {
+  readonly token: RenderTarget;
+  readonly state: RenderTargetOwnerState;
+  readonly generation: number;
+  readonly descriptor: RenderTargetDescriptor;
+  readonly candidate?: RenderTargetPhysicalCandidate;
+}
+
+export interface RenderTargetOwnerOptions {
+  readonly rendererId: symbol;
+  readonly initialGeneration: number;
+}
+
+export interface RenderTargetOwner {
+  create(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
+  stage(
+    target: RenderTarget,
+    descriptor?: RenderTargetDescriptor,
+  ): RenderResult<RenderTargetPhysicalCandidate, RenderError>;
+  promote(target: RenderTarget, generation: number): RenderResult<void, RenderError>;
+  rejectCandidate(
+    target: RenderTarget,
+    generation: number,
+    stage: 'allocation' | 'compile' | 'write' | 'submit',
+  ): RenderResult<void, RenderError>;
+  beginRecovery(target: RenderTarget, generation: number): RenderResult<void, RenderError>;
+  finishRecovery(target: RenderTarget): RenderResult<void, RenderError>;
+  retire(target: RenderTarget, generation: number): RenderResult<void, RenderError>;
+  destroy(target: RenderTarget): RenderResult<void, RenderError>;
+  inspect(target: RenderTarget): RenderResult<RenderTargetOwnerInspection, RenderError>;
+}
+
+interface TargetState {
+  readonly target: RenderTarget;
+  readonly rendererId: symbol;
+  state: RenderTargetOwnerState;
+  generation: number;
+  descriptor: RenderTargetDescriptor;
+  candidate: RenderTargetPhysicalCandidate | undefined;
+  retiredGenerations: Set<number>;
+}
+
+function frozenDescriptor(descriptor: RenderTargetDescriptor): RenderTargetDescriptor {
+  return Object.freeze({ ...descriptor });
+}
+
+function invalid(
+  operation: 'inspect' | 'resize' | 'source' | 'readback' | 'destroy',
+  reason: 'foreign-renderer' | 'destroyed' | 'uninitialized' | 'generation-mismatch',
+  state: RenderTargetOwnerState,
+  generation: number,
+): RenderResult<never, RenderError> {
+  return {
+    ok: false,
+    error: new RenderTargetStateInvalidError({ operation, reason, state, generation }),
+  };
+}
+
+function token(): RenderTarget {
+  return Object.freeze({}) as RenderTarget;
+}
+
+export function createRenderTargetOwner(options: RenderTargetOwnerOptions): RenderTargetOwner {
+  const targets = new WeakMap<object, TargetState>();
+  const requireTarget = (
+    target: RenderTarget,
+    operation: 'inspect' | 'resize' | 'source' | 'readback' | 'destroy',
+  ): RenderResult<TargetState, RenderError> => {
+    const state = targets.get(target as object);
+    if (state === undefined) return invalid(operation, 'foreign-renderer', 'destroyed', 0);
+    if (state.rendererId !== options.rendererId) {
+      return invalid(operation, 'foreign-renderer', state.state, state.generation);
+    }
+    if (state.state === 'destroyed') {
+      return invalid(operation, 'destroyed', state.state, state.generation);
+    }
+    return { ok: true, value: state };
+  };
+
+  return {
+    create(descriptor) {
+      const target = token();
+      targets.set(target as object, {
+        target,
+        rendererId: options.rendererId,
+        state: 'uninitialized',
+        generation: 0,
+        descriptor: frozenDescriptor(descriptor),
+        candidate: undefined,
+        retiredGenerations: new Set(),
+      });
+      return { ok: true, value: target };
+    },
+    stage(target, descriptor) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.state === 'rebuilding') {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      const candidate = Object.freeze({
+        generation: state.state === 'uninitialized' ? options.initialGeneration : state.generation,
+        descriptor: frozenDescriptor(descriptor ?? state.descriptor),
+      });
+      state.candidate = candidate;
+      state.state = 'candidate';
+      return { ok: true, value: candidate };
+    },
+    promote(target, generation) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.candidate?.generation !== generation) {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      state.descriptor = state.candidate.descriptor;
+      state.generation = generation;
+      state.candidate = undefined;
+      state.state = 'active';
+      return { ok: true, value: undefined };
+    },
+    rejectCandidate(target, generation, stage) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.candidate?.generation !== generation) {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      state.candidate = undefined;
+      state.state = state.generation === 0 ? 'uninitialized' : 'active';
+      return {
+        ok: false,
+        error: new RenderTargetOperationFailedError({
+          operation: 'resize',
+          stage,
+          generation,
+          cause: new Error(`candidate ${generation} failed during ${stage}`),
+          recovery: state.generation === 0 ? 'retry' : 'retain-last-known-good',
+        }),
+      };
+    },
+    beginRecovery(target, generation) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.state !== 'active' || generation <= state.generation) {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      state.generation = generation;
+      state.candidate = undefined;
+      state.state = 'rebuilding';
+      return { ok: true, value: undefined };
+    },
+    finishRecovery(target) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.state !== 'rebuilding') {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      state.state = 'uninitialized';
+      return { ok: true, value: undefined };
+    },
+    retire(target, generation) {
+      const found = requireTarget(target, 'destroy');
+      if (!found.ok) return found;
+      found.value.retiredGenerations.add(generation);
+      return { ok: true, value: undefined };
+    },
+    destroy(target) {
+      const state = targets.get(target as object);
+      if (state === undefined) return invalid('destroy', 'foreign-renderer', 'destroyed', 0);
+      if (state.rendererId !== options.rendererId) {
+        return invalid('destroy', 'foreign-renderer', state.state, state.generation);
+      }
+      if (state.state === 'destroyed') return { ok: true, value: undefined };
+      state.candidate = undefined;
+      state.state = 'destroyed';
+      return { ok: true, value: undefined };
+    },
+    inspect(target) {
+      const found = requireTarget(target, 'inspect');
+      if (!found.ok) return found;
+      const state = found.value;
+      return {
+        ok: true,
+        value: Object.freeze({
+          token: state.target,
+          state: state.state,
+          generation: state.generation,
+          descriptor: state.descriptor,
+          ...(state.candidate === undefined ? {} : { candidate: state.candidate }),
+        }),
+      };
+    },
+  };
+}

package/src/targets/physical.ts

@@ -0,0 +1,18 @@
+import type { Texture, TextureView } from '@forgeax/engine-rhi';
+import type { RenderTargetDescriptor } from './contracts';
+
+/** Renderer-private physical storage for one logical target generation. */
+export interface RenderTargetPhysical {
+  readonly generation: number;
+  readonly descriptor: RenderTargetDescriptor;
+  readonly texture: Texture;
+  readonly view: TextureView;
+  readonly mipViews: readonly TextureView[];
+  readonly colorTextures: readonly Texture[];
+  readonly faceViews: readonly TextureView[];
+  readonly depthTextures: readonly Texture[];
+  readonly depthViews: readonly TextureView[];
+  readonly resolveTexture?: Texture;
+  readonly resolveView: TextureView;
+  readonly resolveFaceViews: readonly TextureView[];
+}

package/src/targets/readback.ts

@@ -0,0 +1,153 @@
+import type { RenderError } from '../errors/render';
+import { RenderTargetOperationFailedError, RenderTargetStateInvalidError } from '../errors/render';
+import type { RenderResult } from '../render-contract';
+import type { RenderTarget } from './contracts';
+
+export interface RenderTargetReadbackReceipt {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+}
+
+export interface RenderTargetReadbackTicketInput {
+  readonly frameId?: number;
+  deviceGeneration: number;
+  readonly mipLevel: number;
+  readonly face?: number;
+  readonly width: number;
+  readonly height: number;
+  readonly bytesPerPixel: number;
+}
+
+export interface RenderTargetReadbackTicket {
+  readonly target: RenderTarget;
+  frameId: number | undefined;
+  deviceGeneration: number;
+  readonly mipLevel: number;
+  readonly face?: number;
+  readonly width: number;
+  readonly height: number;
+  readonly bytesPerRow: number;
+  readonly byteLength: number;
+  consumed: boolean;
+}
+
+export interface RenderTargetReadbackResult {
+  readonly bytes: Uint8Array;
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly mipLevel: number;
+  readonly face?: number;
+}
+
+function invalidTicket(
+  ticket: RenderTargetReadbackTicket,
+  reason: 'uninitialized' | 'generation-mismatch' | 'destroyed',
+): RenderResult<never, RenderError> {
+  return {
+    ok: false,
+    error: new RenderTargetStateInvalidError({
+      operation: 'readback',
+      reason,
+      state: reason === 'destroyed' ? 'destroyed' : 'active',
+      generation: ticket.deviceGeneration,
+    }),
+  };
+}
+
+export function bindRenderTargetReadbackTicket(
+  ticket: RenderTargetReadbackTicket,
+  receipt: RenderTargetReadbackReceipt,
+): RenderResult<void, RenderError> {
+  if (ticket.consumed) return invalidTicket(ticket, 'destroyed');
+  if (ticket.frameId !== undefined) {
+    return invalidTicket(ticket, 'generation-mismatch');
+  }
+  ticket.frameId = receipt.frameId;
+  ticket.deviceGeneration = receipt.deviceGeneration;
+  return { ok: true, value: undefined };
+}
+
+export function createRenderTargetReadbackTicket(
+  target: RenderTarget,
+  input: RenderTargetReadbackTicketInput,
+): RenderResult<RenderTargetReadbackTicket, RenderError> {
+  if (
+    (input.frameId !== undefined && (!Number.isInteger(input.frameId) || input.frameId < 0)) ||
+    !Number.isInteger(input.deviceGeneration) ||
+    input.deviceGeneration < 0 ||
+    !Number.isInteger(input.mipLevel) ||
+    input.mipLevel < 0 ||
+    !Number.isInteger(input.width) ||
+    input.width < 1 ||
+    !Number.isInteger(input.height) ||
+    input.height < 1 ||
+    !Number.isInteger(input.bytesPerPixel) ||
+    input.bytesPerPixel < 1
+  ) {
+    return {
+      ok: false,
+      error: new RenderTargetOperationFailedError({
+        operation: 'readback',
+        stage: 'copy',
+        generation: input.deviceGeneration,
+        cause: new Error('readback dimensions and identity must be non-negative integers'),
+        recovery: 'retry',
+      }),
+    };
+  }
+  const unalignedRowBytes = input.width * input.bytesPerPixel;
+  const bytesPerRow = Math.ceil(unalignedRowBytes / 256) * 256;
+  return {
+    ok: true,
+    value: {
+      target,
+      frameId: input.frameId,
+      deviceGeneration: input.deviceGeneration,
+      mipLevel: input.mipLevel,
+      ...(input.face === undefined ? {} : { face: input.face }),
+      width: input.width,
+      height: input.height,
+      bytesPerRow,
+      byteLength: bytesPerRow * input.height,
+      consumed: false,
+    },
+  };
+}
+
+export function completeRenderTargetReadback(
+  ticket: RenderTargetReadbackTicket,
+  receipt: RenderTargetReadbackReceipt,
+  bytes: Uint8Array,
+): RenderResult<RenderTargetReadbackResult, RenderError> {
+  if (ticket.consumed) return invalidTicket(ticket, 'destroyed');
+  if (
+    ticket.frameId === undefined ||
+    receipt.frameId !== ticket.frameId ||
+    receipt.deviceGeneration !== ticket.deviceGeneration
+  ) {
+    return invalidTicket(ticket, 'generation-mismatch');
+  }
+  if (bytes.byteLength !== ticket.byteLength) {
+    return {
+      ok: false,
+      error: new RenderTargetOperationFailedError({
+        operation: 'readback',
+        stage: 'copy',
+        generation: ticket.deviceGeneration,
+        cause: new Error(`expected ${ticket.byteLength} bytes, received ${bytes.byteLength}`),
+        recovery: 'retry',
+      }),
+    };
+  }
+  ticket.consumed = true;
+  return {
+    ok: true,
+    value: {
+      bytes,
+      frameId: ticket.frameId,
+      deviceGeneration: ticket.deviceGeneration,
+      mipLevel: ticket.mipLevel,
+      ...(ticket.face === undefined ? {} : { face: ticket.face }),
+    },
+  };
+}

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,

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/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;
@@ -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`: