@forgeax/engine-render 0.1.20 → 0.1.21

package/src/renderer.ts

@@ -0,0 +1,222 @@
+import { err, ok } from '@forgeax/engine-types';
+import type { RenderError } from './errors/render.js';
+import { FrameReceiptStaleError } from './errors/render.js';
+import type {
+  GpuPassTimingObservation,
+  GpuPassTimingReason,
+  GpuPassTimingRef,
+} from './record/gpu-pass-timing/index.js';
+import type {
+  FrameObservationRequest,
+  FrameReceipt,
+  FrameReceiptObservation,
+  RenderResult,
+} from './render-contract.js';
+
+/**
+ * Internal Render producer callback; public callers receive only frozen facts.
+ * The callback is receipt-bound and never exposes RHI handles or query state.
+ */
+export type GpuPassTimingObservationSource = () => Promise<GpuPassTimingObservation>;
+
+/**
+ * Receipt observation seam for the public `draw()` then `observe()` route.
+ * `status`, `completeness`, and `latestKnownGood` are separate projections;
+ * pass duration is not frame latency. Timing errors retain the closed code,
+ * expected, hint, and detail fields so a caller can follow producer recovery.
+ * See the bounded contract and fail-closed validator in the GPU pass timing
+ * record and benchmark modules.
+ */
+export interface GpuPassTimingObservationStore {
+  register(receipt: FrameReceipt, source?: GpuPassTimingObservationSource): void;
+  observe(
+    receipt: FrameReceipt,
+    request: FrameObservationRequest,
+  ): Promise<RenderResult<FrameReceiptObservation, RenderError>>;
+  inspect(): {
+    readonly status: GpuPassTimingObservation['status'];
+    readonly completeness: 'complete' | 'partial' | 'unavailable' | 'failed';
+    readonly latestKnownGood?: GpuPassTimingRef | undefined;
+  };
+}
+
+/**
+ * Preserve the receipt observation contract without constructing the timing
+ * retention store when GPU timing was not opted in.
+ */
+export async function observeGpuPassTimingDisabled(
+  receipt: FrameReceipt,
+  request: FrameObservationRequest,
+  currentDeviceGeneration: () => number,
+): Promise<RenderResult<FrameReceiptObservation, RenderError>> {
+  const completed = await receipt.completed;
+  if (!completed.ok) return completed;
+  if (receipt.deviceGeneration !== currentDeviceGeneration()) {
+    return err(
+      new FrameReceiptStaleError({
+        frameId: receipt.frameId,
+        receiptGeneration: receipt.deviceGeneration,
+        currentGeneration: currentDeviceGeneration(),
+      }),
+    );
+  }
+  const base = {
+    frameId: receipt.frameId,
+    deviceGeneration: receipt.deviceGeneration,
+    include: freeze([...request.include]),
+  } as const;
+  if (!request.include.includes('timings')) return ok(freeze(base));
+  return ok(freeze({ ...base, timings: notEnabled }));
+}
+
+interface ReceiptRecord {
+  readonly source: GpuPassTimingObservationSource;
+}
+
+interface ObservationStoreOptions {
+  readonly retentionFrames: number;
+  readonly currentDeviceGeneration: () => number;
+}
+
+const notEnabled: GpuPassTimingObservation = {
+  status: 'unavailable',
+  reason: {
+    code: 'gpu-timing-not-enabled',
+    expected: 'gpuPassTiming is enabled in RendererOptions',
+    hint: 'set RendererOptions.gpuPassTiming to opt into bounded timing facts',
+    detail: {},
+  },
+  capability: { timestampQuery: false, timestampPeriodNanoseconds: null },
+};
+
+function failedObservation(
+  error: GpuPassTimingReason,
+  latestKnownGood?: GpuPassTimingRef,
+): GpuPassTimingObservation {
+  return {
+    status: 'failed',
+    error,
+    ...(latestKnownGood === undefined ? {} : { latestKnownGood }),
+  };
+}
+
+function retentionExpired(): GpuPassTimingObservation {
+  return failedObservation({
+    code: 'timing-retention-expired',
+    expected: 'the requested receipt remains inside the bounded timing retention window',
+    hint: 'observe a newer receipt before the retention window expires',
+    detail: {},
+  });
+}
+
+function freeze<T>(value: T): T {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value as Record<string, unknown>)) freeze(child);
+  return value;
+}
+
+/**
+ * Keep receipt-bound observations in a bounded Render-owned retention ring.
+ * This helper does not expose RHI handles, query objects, or a timing
+ * controller; the public lifecycle remains `draw` then `observe`.
+ * Omitting `timings` from the observation request does not materialize facts.
+ */
+export function createGpuPassTimingObservationStore(
+  options: ObservationStoreOptions,
+): GpuPassTimingObservationStore {
+  const records = new Map<FrameReceipt, ReceiptRecord>();
+  const order: FrameReceipt[] = [];
+  const expired = new WeakSet<FrameReceipt>();
+  let latestKnownGood: GpuPassTimingRef | undefined;
+  let currentStatus: GpuPassTimingObservation['status'] = 'unavailable';
+  let currentCompleteness: 'complete' | 'partial' | 'unavailable' | 'failed' = 'unavailable';
+
+  const evict = (): void => {
+    while (order.length > options.retentionFrames) {
+      const old = order.shift();
+      if (old === undefined) break;
+      records.delete(old);
+      expired.add(old);
+    }
+  };
+
+  return {
+    register(receipt, source): void {
+      records.set(receipt, { source: source ?? (async () => notEnabled) });
+      order.push(receipt);
+      evict();
+    },
+    async observe(receipt, request): Promise<RenderResult<FrameReceiptObservation, RenderError>> {
+      const record = records.get(receipt);
+      if (record === undefined) {
+        if (expired.has(receipt) && request.include.includes('timings')) {
+          return ok(
+            freeze({
+              frameId: receipt.frameId,
+              deviceGeneration: receipt.deviceGeneration,
+              include: freeze([...request.include]),
+              timings: retentionExpired(),
+            }),
+          );
+        }
+        return err(
+          new FrameReceiptStaleError({
+            frameId: receipt.frameId,
+            receiptGeneration: receipt.deviceGeneration,
+            currentGeneration: options.currentDeviceGeneration(),
+          }),
+        );
+      }
+      const completed = await receipt.completed;
+      if (!completed.ok) return completed;
+      if (receipt.deviceGeneration !== options.currentDeviceGeneration()) {
+        return err(
+          new FrameReceiptStaleError({
+            frameId: receipt.frameId,
+            receiptGeneration: receipt.deviceGeneration,
+            currentGeneration: options.currentDeviceGeneration(),
+          }),
+        );
+      }
+      const base = {
+        frameId: receipt.frameId,
+        deviceGeneration: receipt.deviceGeneration,
+        include: freeze([...request.include]),
+      } as const;
+      if (!request.include.includes('timings')) return ok(freeze(base));
+      let timings: GpuPassTimingObservation;
+      try {
+        timings = await record.source();
+      } catch (cause) {
+        timings = failedObservation(
+          {
+            code: 'timestamp-readback-failed',
+            expected: 'the Render-owned timing observation completes without throwing',
+            hint: 'observe a later receipt and inspect latestKnownGood',
+            detail: { frameId: receipt.frameId },
+            cause: { message: cause instanceof Error ? cause.message : String(cause) },
+          },
+          latestKnownGood,
+        );
+      }
+      currentStatus = timings.status;
+      currentCompleteness = timings.status;
+      if (timings.status === 'complete') {
+        latestKnownGood = {
+          frameId: timings.frame.frameId,
+          deviceGeneration: timings.frame.deviceGeneration,
+          graphGeneration: timings.frame.graphGeneration,
+        };
+      }
+      return ok(freeze({ ...base, timings }));
+    },
+    inspect() {
+      return freeze({
+        status: currentStatus,
+        completeness: currentCompleteness,
+        latestKnownGood,
+      });
+    },
+  };
+}

package/src/scene/render-scene.ts

@@ -16,6 +16,7 @@ import {
   PointLight,
   PointLightShadow,
   PostProcessParams,
+  ReflectionProbe,
   SkyboxBackground,
   Skylight,
   SpotLight,
@@ -30,8 +31,14 @@ import {
 } from '../gpu-driven/batch-topology';
 import { GpuScene } from '../gpu-scene';
 import type { PersistentRenderSceneInspection } from '../inspection-types';
+import { fingerprintNumericArray, InstanceBoundsCache } from '../instances-derived-bounds';
 import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRetainedSnapshot } from '../points-lines/snapshot';
+import {
+  type ReflectionProbeFact,
+  ReflectionProbeProjection,
+  type ReflectionProbeSelectionResult,
+} from '../reflection/projection';
 import type { CameraSnapshot } from '../render-contract';
 import type {
   DispatchEntry,
@@ -220,6 +227,22 @@ function worldBounds(snapshot: RenderableSnapshot): RenderSceneBounds | undefine
   return { min, max };
 }
 
+function boundsFromArray(bounds: ArrayLike<number>): RenderSceneBounds | undefined {
+  if (bounds.length < 6) return undefined;
+  const min: [number, number, number] = [Number(bounds[0]), Number(bounds[1]), Number(bounds[2])];
+  const max: [number, number, number] = [Number(bounds[3]), Number(bounds[4]), Number(bounds[5])];
+  if (
+    !min.every(Number.isFinite) ||
+    !max.every(Number.isFinite) ||
+    min[0] > max[0] ||
+    min[1] > max[1] ||
+    min[2] > max[2]
+  ) {
+    return undefined;
+  }
+  return { min, max };
+}
+
 /**
  * The renderer's single rebuildable CPU scene authority.
  *
@@ -241,6 +264,7 @@ export class RenderScene {
   // derived value by snapshot identity so repeated view queries do not redo
   // the eight-corner transform for every view in the same frame.
   private readonly worldBoundsCache = new WeakMap<RenderableSnapshot, RenderSceneBounds | null>();
+  private readonly instanceBoundsCache = new InstanceBoundsCache();
   private orderedSlots: number[] = [];
   private materialized: readonly RenderableSnapshot[] | undefined;
   private slotSnapshot: readonly RenderSceneSlot[] | undefined;
@@ -552,11 +576,7 @@ export class RenderScene {
       const record = this.slots[slot];
       if (record === undefined) continue;
       const snapshot = record.snapshot;
-      let candidate = this.worldBoundsCache.get(snapshot);
-      if (candidate === undefined && !this.worldBoundsCache.has(snapshot)) {
-        candidate = worldBounds(snapshot) ?? null;
-        this.worldBoundsCache.set(snapshot, candidate);
-      }
+      const candidate = this.cullingWorldBounds(snapshot);
       if (candidate === null || candidate === undefined) continue;
       if (intersects(candidate, bounds)) records.push(record);
     }
@@ -629,6 +649,7 @@ export class RenderScene {
 
   private release(record: RenderSceneSlot): void {
     this.slots[record.slot] = undefined;
+    this.instanceBoundsCache.invalidate(record.entityKey, record.worldId);
     this.unindexMaterials(record);
     const entities = this.slotsByWorld.get(record.worldId);
     entities?.delete(record.entityKey);
@@ -706,6 +727,41 @@ export class RenderScene {
     this.materialized = undefined;
     this.slotSnapshot = undefined;
   }
+
+  /**
+   * Return the CPU culling projection for one retained snapshot. Instances
+   * use a renderer-derived union, while the GPU scene keeps the mesh-local
+   * bounds for its independent per-instance visibility pass. Unknown or
+   * empty instance facts deliberately return undefined (conservative no-cull).
+   */
+  cullingWorldBounds(snapshot: RenderableSnapshot): RenderSceneBounds | undefined {
+    let candidate = this.worldBoundsCache.get(snapshot);
+    if (candidate !== undefined || this.worldBoundsCache.has(snapshot)) {
+      return candidate ?? undefined;
+    }
+    if (snapshot.instances !== undefined) {
+      const instanceCount = snapshot.instances.instanceCount;
+      if (instanceCount === 0 || snapshot.localAabb === undefined) {
+        this.worldBoundsCache.set(snapshot, null);
+        return undefined;
+      }
+      const derived = this.instanceBoundsCache.get({
+        worldId: snapshot.worldId,
+        entityKey: snapshot.entityKey,
+        meshGeneration: fingerprintNumericArray(snapshot.localAabb) ^ (snapshot.assetHandle >>> 0),
+        transformGeneration: fingerprintNumericArray(snapshot.transform.world),
+        matrixGeneration: snapshot.instances.archVersion,
+        meshAabb: snapshot.localAabb,
+        entityWorld: snapshot.transform.world,
+        transforms: snapshot.instances.transforms,
+      });
+      candidate = boundsFromArray(derived ?? []);
+    } else {
+      candidate = worldBounds(snapshot);
+    }
+    this.worldBoundsCache.set(snapshot, candidate ?? null);
+    return candidate;
+  }
 }
 
 function readTransformWorld(world: World, entity: EntityHandle): Float32Array | undefined {
@@ -762,6 +818,7 @@ const RENDER_RELEVANT_COMPONENT_IDS = new Set([
   componentId(Skylight),
   componentId(SkyboxBackground),
   componentId(PostProcessParams),
+  componentId(ReflectionProbe),
   componentId(VolumetricFog),
 ]);
 
@@ -810,6 +867,7 @@ function cameraFrusta(cameras: readonly CameraSnapshot[]): readonly Float32Array
 function cullPersistentFrame(
   frame: ExtractedFrame,
   candidates: readonly RenderableSnapshot[],
+  boundsOf: (snapshot: RenderableSnapshot) => RenderSceneBounds | undefined = worldBounds,
 ): ExtractedFrame {
   const planes = cameraFrusta(frame.cameras);
   const visible: RenderableSnapshot[] = [];
@@ -822,10 +880,16 @@ function cullPersistentFrame(
     const candidate = candidates[index];
     if (candidate === undefined) continue;
     let isVisible = true;
-    if (candidate.localAabb !== undefined) {
+    const candidateBounds = boundsOf(candidate);
+    if (candidateBounds !== undefined) {
       total += 1;
       const worldAabb = box3.create();
-      box3.transformBox3(worldAabb, candidate.localAabb, candidate.transform.world);
+      worldAabb[0] = candidateBounds.min[0] ?? 0;
+      worldAabb[1] = candidateBounds.min[1] ?? 0;
+      worldAabb[2] = candidateBounds.min[2] ?? 0;
+      worldAabb[3] = candidateBounds.max[0] ?? 0;
+      worldAabb[4] = candidateBounds.max[1] ?? 0;
+      worldAabb[5] = candidateBounds.max[2] ?? 0;
       isVisible = planes.length === 0;
       for (const cameraPlanes of planes) {
         if (
@@ -879,6 +943,7 @@ export class PersistentRenderScene {
     | { readonly projection: RenderScene; readonly capture: RenderSceneSubmissionCapture }
     | undefined;
   private pointsLinesInspections: readonly PointsLinesInspection[] = [];
+  private readonly reflectionProbes = new ReflectionProbeProjection();
 
   constructor(private readonly options: PersistentRenderSceneOptions = {}) {}
 
@@ -887,6 +952,37 @@ export class PersistentRenderScene {
     return this.materialSnapshotCaches;
   }
 
+  /** Project probe facts and per-primitive selection into the persistent scene owner. */
+  projectReflectionProbes(probes: readonly ReflectionProbeFact[]): void {
+    const projection = this.composition?.projection;
+    if (projection === undefined) return;
+    const primitives = projection
+      .slotsSnapshot()
+      .map((slot) => {
+        const resolved = worldBounds(slot.snapshot);
+        if (resolved === undefined || resolved === null) return undefined;
+        return {
+          worldId: slot.worldId,
+          entityKey: slot.entityKey,
+          center: [
+            (resolved.min[0] + resolved.max[0]) / 2,
+            (resolved.min[1] + resolved.max[1]) / 2,
+            (resolved.min[2] + resolved.max[2]) / 2,
+          ] as [number, number, number],
+        };
+      })
+      .filter((primitive): primitive is NonNullable<typeof primitive> => primitive !== undefined);
+    this.reflectionProbes.update(probes, primitives);
+  }
+
+  reflectionProbeSelection(worldId: number, entityKey: number): ReflectionProbeSelectionResult {
+    return this.reflectionProbes.selection(worldId, entityKey);
+  }
+
+  reflectionProbeProjection(): ReturnType<ReflectionProbeProjection['snapshot']> {
+    return this.reflectionProbes.snapshot();
+  }
+
   extractComposition(
     worlds: readonly World[],
     owner: { readonly cameraOwner: number; readonly resourceOwner: number },
@@ -1195,6 +1291,7 @@ export class PersistentRenderScene {
     transmissionDemand.apply(transmissionDemandOperations(candidateFrame.renderables));
     const topology = new BatchTopology();
     topology.rebuild(projection.slotsSnapshot());
+    this.projectReflectionProbes(candidateFrame.reflectionProbes ?? []);
     const token = {};
     const entry: PersistentCompositionEntry = {
       token,
@@ -1224,7 +1321,11 @@ export class PersistentRenderScene {
     const candidates = projection
       .materialize()
       .map((snapshot) => projection.withTemporal(snapshot));
-    return cullPersistentFrame({ ...candidateFrame, renderables: [...candidates] }, candidates);
+    return cullPersistentFrame(
+      { ...candidateFrame, renderables: [...candidates] },
+      candidates,
+      (snapshot) => projection.cullingWorldBounds(snapshot),
+    );
   }
 
   /** Internal topology fact; the renderer does not expose demand as public API. */
@@ -1246,10 +1347,15 @@ export class PersistentRenderScene {
     buildCandidateFrame: () => ExtractedFrame,
   ): ExtractedFrame {
     const candidateFrame = buildCandidateFrame();
+    this.projectReflectionProbes(candidateFrame.reflectionProbes ?? []);
     const candidates = entry.projection
       .materialize()
       .map((snapshot) => entry.projection.withTemporal(snapshot));
-    return cullPersistentFrame({ ...candidateFrame, renderables: [...candidates] }, candidates);
+    return cullPersistentFrame(
+      { ...candidateFrame, renderables: [...candidates] },
+      candidates,
+      (snapshot) => entry.projection.cullingWorldBounds(snapshot),
+    );
   }
 
   private syncGpuOwner(

package/src/shadow-atlas.ts

@@ -3,8 +3,8 @@
 // feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-1 (plan-strategy §D-1).
 //
 // Lazy-allocated `texture_depth_cube_array` (depth32float) + per-face 2D
-// TextureView cache. One layer per shadow-casting PointLight (cap = 4 enforced
-// by the PointLightShadow ECS component cardinality). Total texel footprint at
+// TextureView cache. One layer per admitted shadow-casting PointLight; the
+// renderer owns the bounded atlas admission policy. Total texel footprint at
 // the 512x512 default = 4 layers x 6 faces x 512 x 512 x 4 B = 24 MiB.
 //
 // Why a separate module (vs inlining into createRenderer / pipelineState):
@@ -53,19 +53,19 @@ import { GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING } from './gpu-t
 export interface ShadowAtlasOptions {
   /** Per-face square size in pixels. Default 512 (PointLightShadow.mapSize default). */
   readonly faceSize?: number;
-  /** Number of cube layers. Default 4 (= PointLightShadow cardinality cap). */
+  /** Number of cube layers. Default is the renderer atlas admission capacity. */
   readonly layers?: number;
 }
 
 /** Default per-face square size in pixels. Mirrors PointLightShadow.mapSize default. */
 export const SHADOW_ATLAS_DEFAULT_FACE_SIZE = 512;
-/** Default cube layer count. Mirrors PointLightShadow cardinality cap. */
+/** Default cube layer count. Renderer-owned point-shadow admission capacity. */
 export const SHADOW_ATLAS_DEFAULT_LAYERS = 4;
 
 /**
  * Cube-array depth atlas for point-light shadows.
  *
- * Shape: `texture_depth_cube_array` (depth32float) with `layers = 4` and per-
+ * Shape: `texture_depth_cube_array` (depth32float) with `layers` and per-
  * face size `faceSize x faceSize`. The cube_array sampling view feeds
  * `@group(0) @binding(5)` in URP shaders; the per-face 2D view feeds the
  * shadow-caster render pass attachment for one (layer, face) at a time

package/src/ssao-buffers.ts

@@ -106,6 +106,7 @@ export const SSAO_UNIFORM_BYTES = UNIFORM_BYTES;
 // recompile across enable/disable.
 
 interface SsaoFallbackResources {
+  readonly device: RenderSystemRuntime['device'];
   readonly texture: Texture;
   readonly view: TextureView;
   readonly sampler: Sampler;
@@ -126,7 +127,8 @@ export function getOrCreateSsaoFallbackTexture(
   runtime: RenderSystemRuntime,
 ): SsaoFallbackResources | null {
   const cached = fallbackCache.get(runtime);
-  if (cached !== undefined) return cached;
+  if (cached !== undefined && cached.device === runtime.device) return cached;
+  if (cached !== undefined) fallbackCache.delete(runtime);
 
   const device = runtime.device;
   const texRes = device.createTexture({
@@ -191,6 +193,7 @@ export function getOrCreateSsaoFallbackTexture(
   }
 
   const resources: SsaoFallbackResources = {
+    device,
     texture: texRes.value,
     view: viewRes.value,
     sampler: samplerRes.value,
@@ -205,6 +208,8 @@ export function getOrCreateSsaoFallbackTexture(
  * Fields are readonly per charter P5: one resource, one owner.
  */
 export interface SsaoBuffers {
+  /** Device identity that owns every handle in this bundle. */
+  readonly device: RenderSystemRuntime['device'];
   /** 64 padded vec4 uniform buffer for hemisphere samples. */
   readonly kernelBuffer: Buffer;
   readonly kernelBytes: number;
@@ -229,7 +234,8 @@ const cache = new WeakMap<RenderSystemRuntime, SsaoBuffers>();
  */
 export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffers | null {
   const cached = cache.get(runtime);
-  if (cached !== undefined) return cached;
+  if (cached !== undefined && cached.device === runtime.device) return cached;
+  if (cached !== undefined) cache.delete(runtime);
 
   const device = runtime.device;
 
@@ -322,6 +328,7 @@ export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffer
   }
 
   const buffers: SsaoBuffers = {
+    device,
     kernelBuffer: kernelBufferRes.value,
     kernelBytes: SSAO_KERNEL_SAMPLE_COUNT * BYTES_PER_KERNEL_ELEMENT,
     noiseTexture: noiseTexRes.value,