@forgeax/engine-render 0.1.20 → 0.1.23

package/src/record/view-ubo.ts

@@ -8,7 +8,7 @@
 
 import { mat4 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
-import type { FogFrame } from '../extract/environment';
+import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
 import type { PointsLinesStyle } from '../points-lines/snapshot';
 import type { CameraSnapshot } from '../render-contract';
 import type {
@@ -16,9 +16,9 @@ import type {
   ExtractedLights,
   SpotLightSnapshot,
 } from '../render-system-extract';
+import { SHADOW_ATLAS_DEFAULT_LAYERS } from '../shadow-atlas';
 import type { TemporalView as LegacyTemporalView } from '../temporal/temporal-view';
 import type { TemporalView } from '../temporal/view';
-import { clampPcfKernelSize } from './frame-snapshot';
 import { computeProjectionMatrix, computeViewMatrix } from './helpers';
 
 export const VIEW_UNIFORM_BYTES = 960;
@@ -29,13 +29,39 @@ export const POINTS_LINES_VIEW_BUFFER_SIZE =
   POINTS_LINES_VIEW_SLOT_STRIDE * POINTS_LINES_VIEW_SLOT_COUNT;
 export const VIEW_UNIFORM_SLOT_STRIDE = 1024;
 export const POINT_SHADOW_VIEW_SLOT_COUNT = 24;
+export const CUBE_CAPTURE_VIEW_SLOT_BASE = 1 + POINT_SHADOW_VIEW_SLOT_COUNT;
+export const REFLECTION_PROBE_VIEW_SLOT_BASE = CUBE_CAPTURE_VIEW_SLOT_BASE + 6;
+export const REFLECTION_PROBE_VIEW_SLOT_COUNT = 16;
 export const VIEW_UNIFORM_BUFFER_SIZE =
-  VIEW_UNIFORM_SLOT_STRIDE * (1 + POINT_SHADOW_VIEW_SLOT_COUNT);
+  VIEW_UNIFORM_SLOT_STRIDE * (REFLECTION_PROBE_VIEW_SLOT_BASE + REFLECTION_PROBE_VIEW_SLOT_COUNT);
 
 export function pointShadowViewOffset(layer: number, face: number): number {
   return VIEW_UNIFORM_SLOT_STRIDE * (1 + layer * 6 + face);
 }
 
+/** Project the accepted Directional quality union into the frozen View ABI. */
+function directionalShadowFilterCarrier(
+  quality: DirectionalShadowQuality | undefined,
+): readonly [number, number, number, number] {
+  if (quality === undefined) return [0, 0, 0, 0];
+  if (quality.kind === 'pcss') {
+    return [
+      quality.preset === 'medium' ? 4 : 5,
+      quality.angularRadiusRadians,
+      quality.maxPenumbraTexels,
+      0,
+    ];
+  }
+  switch (quality.kernel) {
+    case 1:
+      return [1, 0, 0, 0];
+    case 3:
+      return [2, 0, 0, 0];
+    case 5:
+      return [3, 0, 0, 0];
+  }
+}
+
 export function writePointsLinesViewUbo(
   queue: RhiQueue,
   buffer: Buffer,
@@ -95,10 +121,10 @@ export function writePointsLinesViewUbo(
  *   [24..26] cameraPos, [28..43] lightViewProj0 (was lightSpaceMatrix),
  *   [44..59] inverseViewProj, [60..75] lightViewProj1,
  *   [76..91] lightViewProj2, [92..107] lightViewProj3,
- *   [108]/[112]/[116]/[120] splitPlanes (vec4 stride),
+ *   [108..123] splitPlanes (vec4 lanes: split/world texel/depth span/reserved),
  *   [124] cascadeCount, [125] cascadeBlend,
- *   [126] depthBias, [127] normalBias, [128] pcfKernelSize (feat-20260621
- *   M3 / m3-t2-t3), [129..131] align pad,
+ *   [126] depthBias, [127] normalBias,
+ *   [128..131] directionalShadowFilter (profile/radius/max penumbra/reserved),
  *   [132..195] spotLightViewProj array<mat4x4<f32>, 4> (feat-20260625 w25:
  *   folded from standalone binding 9 to fix WebGL2 fragment uniform-buffer
  *   overflow; lane N = spot with shadowAtlasTile === N, 16 f32 / lane,
@@ -113,14 +139,11 @@ export function writeViewUbo(
   light: DirectionalLightSnapshot,
   lights: ExtractedLights,
   spotShadowSnapshots: readonly SpotLightSnapshot[],
-  fogOrTemporal?: FogFrame | TemporalView | LegacyTemporalView,
-  temporal?: TemporalView,
+  temporalOrOffset?: TemporalView | LegacyTemporalView | number,
+  projectorSpotIndex?: number,
 ): void {
-  const isTemporal =
-    fogOrTemporal !== undefined &&
-    ('currentJitterUv' in fogOrTemporal || 'currentUnjitteredViewProjection' in fogOrTemporal);
-  const fog = isTemporal ? undefined : fogOrTemporal;
-  const resolvedTemporal = temporal ?? (isTemporal ? fogOrTemporal : undefined);
+  const byteOffset = typeof temporalOrOffset === 'number' ? temporalOrOffset : 0;
+  const resolvedTemporal = typeof temporalOrOffset === 'number' ? undefined : temporalOrOffset;
   // Compose worldViewProj once per frame (view * proj).
   const projMatrix = computeProjectionMatrix(camera);
   const viewMatrix = computeViewMatrix(camera);
@@ -185,38 +208,49 @@ export function writeViewUbo(
   viewPayload[228] = camera.near;
   viewPayload[229] = camera.far;
   viewPayload[230] = camera.projection === 'orthographic' ? 1 : 0;
-  // splitPlanes at [108], [112], [116], [120] (vec4 stride = 4 floats).
+  const previousCameraPosition =
+    resolvedTemporal !== undefined && 'previousCameraPosition' in resolvedTemporal
+      ? resolvedTemporal.previousCameraPosition
+      : undefined;
+  if (previousCameraPosition !== undefined) {
+    viewPayload[232] = previousCameraPosition[0] ?? 0;
+    viewPayload[233] = previousCameraPosition[1] ?? 0;
+    viewPayload[234] = previousCameraPosition[2] ?? 0;
+    viewPayload[235] = 1;
+  }
+  // splitPlanes at [108..123] (four vec4 lanes: split/world texel/depth span/reserved).
   if (lights.splitPlanes !== undefined) {
     for (let s = 0; s < 4; s++) {
-      viewPayload[108 + s * 4] = lights.splitPlanes[s] ?? 0;
+      for (let lane = 0; lane < 4; lane++) {
+        viewPayload[108 + s * 4 + lane] = lights.splitPlanes[s * 4 + lane] ?? 0;
+      }
     }
   }
   // cascadeCount / cascadeBlend at [124..125].
   viewPayload[124] = lights.cascadeCount ?? 0;
   viewPayload[125] = lights.cascadeBlend ?? 0;
-  // feat-20260621-merge-directionallightshadow-into-directionallight M3 /
-  // m3-t2: shadow bias + PCF kernel width from the merged DirectionalLight
-  // land in the formerly-free tail pad at floats [126/127/128] (bytes
-  // 504/508/512). VIEW_PAYLOAD_FLOATS / VIEW_UBO_BYTES are unchanged --
-  // the WGSL View struct (common.wgsl) appends matching f32 at the same
-  // slots; the host tail pad shrinks 88 B -> 64 B, rest stays zero.
-  // pcfKernelSize is host-clamped to the nearest valid odd kernel {1,3,5}
-  // (cap 5, matching lighting-directional.wgsl MAX_PCF_HALF=2 from the
-  // merged 5.3-production-shadow-demos AC-14 variant-free loop) so the
-  // per-iteration radius clip has a fixed, legal bound; undefined
-  // (no cast-shadow / no shadow fields) defaults to 3.
+  // M1 directional shadow carrier: bias remains at [126]/[127], while the
+  // accepted quality union occupies the existing four-float tail [128..131].
+  // Point and Spot pcfKernelSize stay in their own snapshot paths and never
+  // enter this Directional View projection.
   viewPayload[126] = lights.depthBias ?? 0.005;
   viewPayload[127] = lights.normalBias ?? 0.05;
-  viewPayload[128] = clampPcfKernelSize(lights.pcfKernelSize);
+  const filterCarrier = directionalShadowFilterCarrier(lights.directionalShadowQuality);
+  viewPayload[128] = filterCarrier[0] ?? 0;
+  viewPayload[129] = filterCarrier[1] ?? 0;
+  viewPayload[130] = filterCarrier[2] ?? 0;
+  viewPayload[131] = filterCarrier[3] ?? 0;
 
   // feat-20260625-spot-light-shadow-mapping w25 (scope-amend webkit-fallback):
   // spotLightViewProj array<mat4x4<f32>, 4> at floats [132..195] (byte 528,
-  // 16 B-aligned after pcfKernelSize). Lane N = the spot with
+  // 16 B-aligned after directionalShadowFilter). Lane N = the spot with
   // `shadowAtlasTile === N` (cap = 4); the perspective matrix was already
   // computed by the extract stage (SpotLightSnapshot.lightViewProj) — record
-  // never recomputes it (Derive). Lanes for non-shadow / clipped spots (tile
-  // < 0 or lightViewProj undefined) stay zeroed; the WGSL sample path gates
-  // on `SpotLight.shadowAtlasTile >= 0` so zeroed lanes are never read.
+  // never recomputes it (Derive). The accepted projector is identified by its
+  // spot index, not by a negative shadow tile: a projector-only spot publishes
+  // its matrix in lane 0 so the shader never samples a zero matrix. Shadowed
+  // projector spots keep their shadow tile lane and carry the projector bit in
+  // the DirectLightSlot identity word.
   // Folded from the former standalone binding 9 UBO to keep the WebGL2
   // fallback fragment uniform-buffer count <= 11 (GLES 3.0).
   {
@@ -228,33 +262,24 @@ export function writeViewUbo(
       const ss = spotSnaps[i];
       if (ss === undefined) continue;
       const tile = ss.shadowAtlasTile;
-      if (tile < 0 || tile >= SPOT_LVP_LANE_COUNT) continue;
       const lvp = ss.lightViewProj;
       if (lvp === undefined) continue;
-      const base = SPOT_LVP_BASE_FLOAT + tile * SPOT_LVP_FLOATS_PER_LANE;
+      const lane =
+        tile >= 0 && tile < SPOT_LVP_LANE_COUNT ? tile : i === projectorSpotIndex ? 0 : -1;
+      if (lane < 0) continue;
+      const base = SPOT_LVP_BASE_FLOAT + lane * SPOT_LVP_FLOATS_PER_LANE;
       for (let f = 0; f < SPOT_LVP_FLOATS_PER_LANE; f++) {
         viewPayload[base + f] = lvp[f] ?? 0;
       }
     }
   }
 
-  // Fog is a resource-owner semantic carried by the shared View ABI. Keep the
-  // disabled payload zeroed and write only the selected frame facts so both
-  // direct and clustered lanes consume the same owner projection.
-  if (fog !== undefined) {
-    viewPayload[232] = fog.color[0] ?? 0;
-    viewPayload[233] = fog.color[1] ?? 0;
-    viewPayload[234] = fog.color[2] ?? 0;
-    viewPayload[235] = fog.density;
-    viewPayload[236] = fog.heightFalloff;
-    viewPayload[237] = fog.maxOpacity;
-  }
-
-  const viewUploadResult = queue.writeBuffer(viewUniformBuffer, 0, viewPayload);
+  const viewUploadResult = queue.writeBuffer(viewUniformBuffer, byteOffset, viewPayload);
   if (!viewUploadResult.ok) throw viewUploadResult.error;
 
   for (const snapshot of lights.pointShadow ?? []) {
-    if (snapshot.shadowAtlasLayer < 0 || snapshot.shadowAtlasLayer >= 4) continue;
+    if (snapshot.shadowAtlasLayer < 0 || snapshot.shadowAtlasLayer >= SHADOW_ATLAS_DEFAULT_LAYERS)
+      continue;
     for (let face = 0; face < 6; face += 1) {
       const facePayload = viewPayload.slice();
       const matrix = snapshot.shadowMatrices.subarray(face * 16, (face + 1) * 16);

package/src/reflection/filter.ts

@@ -0,0 +1,81 @@
+export interface ProbeFilterState {
+  readonly probeIndex: number;
+  readonly faceCount: number;
+  readonly mipCount: number;
+  readonly cursor: number;
+  readonly activeGeneration: number;
+}
+
+export function createProbeFilterState(input: {
+  readonly probeIndex: number;
+  readonly faceCount?: number;
+  readonly mipCount: number;
+  readonly activeGeneration?: number;
+}): ProbeFilterState {
+  return {
+    probeIndex: input.probeIndex,
+    faceCount: input.faceCount ?? 6,
+    mipCount: input.mipCount,
+    cursor: 0,
+    activeGeneration: input.activeGeneration ?? 0,
+  };
+}
+
+export function advanceProbeFilter(
+  state: ProbeFilterState,
+):
+  | { readonly probeIndex: number; readonly faceIndex: number; readonly mipLevel: number }
+  | undefined {
+  const total = state.faceCount * state.mipCount;
+  if (state.cursor >= total) return undefined;
+  return {
+    probeIndex: state.probeIndex,
+    faceIndex: state.cursor % state.faceCount,
+    mipLevel: Math.floor(state.cursor / state.faceCount),
+  };
+}
+
+export function commitProbeFilterStep(state: ProbeFilterState, success: boolean): ProbeFilterState {
+  if (!success) return state;
+  const nextCursor = state.cursor + 1;
+  const complete = nextCursor >= state.faceCount * state.mipCount;
+  return {
+    ...state,
+    cursor: nextCursor,
+    activeGeneration: complete ? state.activeGeneration + 1 : state.activeGeneration,
+  };
+}
+
+export function probeFilterIsSteady(state: ProbeFilterState): boolean {
+  return state.cursor >= state.faceCount * state.mipCount;
+}
+
+function normalize(vector: readonly [number, number, number]): [number, number, number] {
+  const length = Math.hypot(vector[0], vector[1], vector[2]);
+  if (length === 0) return [0, 0, 1];
+  return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+
+export function boxProjectReflectionDirection(
+  direction: readonly [number, number, number],
+  boxCenter: readonly [number, number, number],
+  halfExtents: readonly [number, number, number],
+  point: readonly [number, number, number],
+): [number, number, number] {
+  const ray = normalize(direction);
+  let distance = Number.POSITIVE_INFINITY;
+  for (let axis = 0; axis < 3; axis += 1) {
+    const component = ray[axis] ?? 0;
+    if (component === 0) continue;
+    const extent = halfExtents[axis] ?? 0;
+    const edge = component > 0 ? (boxCenter[axis] ?? 0) + extent : (boxCenter[axis] ?? 0) - extent;
+    const candidate = (edge - (point[axis] ?? 0)) / component;
+    if (candidate > 0) distance = Math.min(distance, candidate);
+  }
+  if (!Number.isFinite(distance)) return ray;
+  return normalize([
+    (point[0] ?? 0) + ray[0] * distance - (boxCenter[0] ?? 0),
+    (point[1] ?? 0) + ray[1] * distance - (boxCenter[1] ?? 0),
+    (point[2] ?? 0) + ray[2] * distance - (boxCenter[2] ?? 0),
+  ]);
+}

package/src/reflection/gpu-table.ts

@@ -0,0 +1,44 @@
+import type { Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
+
+export interface ReflectionProbeTableRow {
+  readonly primitiveKey?: string;
+  readonly index: number;
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly center: readonly [number, number, number];
+  readonly halfExtents: readonly [number, number, number];
+  readonly intensity: number;
+  readonly generation: number;
+  /** Renderer-owned filtered cube used by the Standard material lane. */
+  readonly filteredView?: TextureView;
+  /** Renderer-owned sampler paired with filteredView. */
+  readonly sampler?: Sampler;
+  /** Per-probe uniform payload; keeps MaterialAsset ABI unchanged. */
+  readonly uniformBuffer?: Buffer;
+}
+
+export interface ReflectionProbeTable {
+  readonly rows: readonly ReflectionProbeTableRow[];
+  readonly cpuIndexByPrimitive: (primitiveKey: string) => number | undefined;
+  readonly gpuIndexByPrimitive: (primitiveKey: string) => number | undefined;
+}
+
+export function buildReflectionProbeTable(
+  rows: readonly ReflectionProbeTableRow[],
+): ReflectionProbeTable {
+  const ordered = rows.slice().sort((a, b) => a.index - b.index);
+  const indices = new Map<string, number>();
+  for (const row of ordered) {
+    if (row.primitiveKey !== undefined) indices.set(row.primitiveKey, row.index);
+  }
+  const indexFor = (primitiveKey: string): number | undefined => indices.get(primitiveKey);
+  return {
+    rows: Object.freeze(ordered),
+    cpuIndexByPrimitive: indexFor,
+    gpuIndexByPrimitive: indexFor,
+  };
+}
+
+export function reflectionProbeTableBytes(table: ReflectionProbeTable): number {
+  return table.rows.length * 48;
+}

package/src/reflection/inspection.ts

@@ -0,0 +1,67 @@
+import type {
+  ReflectionFallbackFailureStage,
+  ReflectionFallbackInspection,
+  ReflectionFallbackReceipt,
+  ReflectionFallbackRecoveryAction,
+} from '../inspection-types';
+
+export interface ReflectionFallbackFailureInput {
+  readonly stage: ReflectionFallbackFailureStage;
+  readonly code: string;
+  readonly expected: string;
+  readonly detail?: Readonly<Record<string, unknown>>;
+}
+
+function recoveryFor(
+  receipt: ReflectionFallbackReceipt,
+  failure?: ReflectionFallbackFailureInput,
+): ReflectionFallbackRecoveryAction {
+  if (failure !== undefined) {
+    const code = failure.code.toLowerCase();
+    if (code.includes('device') || code.includes('format') || code.includes('capability')) {
+      return 'rebuild';
+    }
+    if (failure.stage === 'prepare' || failure.stage === 'filter') return 'recapture';
+    if (failure.stage === 'build' || failure.stage === 'encode') return 'rebuild';
+    if (failure.stage === 'finish' || failure.stage === 'submit') return 'retry';
+    // Completion failures may still retain a source-identical committed row;
+    // use it as LKG, otherwise retry the producer completion.
+    if (failure.stage === 'completion') {
+      if (receipt.source === 'probe' && (receipt.state === 'active' || receipt.state === 'lkg')) {
+        return 'use-LKG';
+      }
+      if (
+        receipt.source === 'skylight' &&
+        (receipt.state === 'active' || receipt.state === 'lkg')
+      ) {
+        return 'use-Skylight';
+      }
+      if (receipt.source === 'neutral' && receipt.state === 'neutral') return 'use-neutral';
+      return 'retry';
+    }
+  }
+  if (receipt.source === 'probe' && (receipt.state === 'active' || receipt.state === 'lkg')) {
+    return 'use-LKG';
+  }
+  if (receipt.source === 'skylight' || receipt.state === 'lkg') return 'use-Skylight';
+  return 'use-neutral';
+}
+
+/** Projects producer state and the latest closed failure into detached facts. */
+export function inspectReflectionFallback(
+  receipt: ReflectionFallbackReceipt,
+  failure?: ReflectionFallbackFailureInput,
+): ReflectionFallbackInspection {
+  return {
+    receipt,
+    recoveryAction: recoveryFor(receipt, failure),
+    ...(failure === undefined
+      ? {}
+      : {
+          failureStage: failure.stage,
+          failureCode: failure.code,
+          expected: failure.expected,
+          ...(failure.detail === undefined ? {} : { detail: failure.detail }),
+        }),
+  };
+}