@forgeax/engine-render 0.1.35 → 0.1.37

package/src/record/shadow-pass.ts

@@ -1,4 +1,5 @@
 import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
+import { box3, frustum } from '@forgeax/engine-math';
 import {
   type BindGroup,
   type BindGroupEntry,
@@ -24,6 +25,7 @@ import {
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { instanceUploadRangesForResident } from '../instances';
+import { deriveInstancesUnionBounds } from '../instances-derived-bounds';
 import {
   buildPbrMaterialUserRegionEntries,
   createPbrSkinMeshBindGroupEntries,
@@ -643,6 +645,29 @@ function shadowCasterKeys(c: _InternalRenderPipelineContext): ReadonlySet<string
   return c.gpuDrivenShadowDrawKeys ?? new Set<string>();
 }
 
+function shadowViewContains(source: RenderableSnapshot, planes: Float32Array | undefined): boolean {
+  if (planes === undefined || planes.length === 0 || source.localAabb === undefined) return true;
+  // The extracted mesh AABB is bind-pose geometry, not a conservative bound
+  // for the current skin palette. Keep skinned residuals until extraction owns
+  // a deformation-aware bound.
+  if (source.skin !== undefined) return true;
+  if (source.spriteInstances !== undefined) return true;
+  let worldBounds: Float32Array;
+  if (source.instances !== undefined) {
+    if (source.instances.instanceCount === 0) return false;
+    const derived = deriveInstancesUnionBounds({
+      meshAabb: source.localAabb,
+      entityWorld: source.transform.world,
+      transforms: source.instances.transforms,
+    });
+    if (derived === undefined) return true;
+    worldBounds = derived;
+  } else {
+    worldBounds = box3.transformBox3(box3.create(), source.localAabb, source.transform.world);
+  }
+  return frustum.intersectsBox(planes as frustum.Frustum, worldBounds as box3.Box3Like);
+}
+
 function validateShadowOwnership(
   c: _InternalRenderPipelineContext,
   identity: ShadowViewIdentity,
@@ -654,12 +679,39 @@ function validateShadowOwnership(
     (c.gpuDrivenShadowDrawKeys === undefined || c.gpuDrivenShadowDrawKeys.size === 0)
   )
     return;
-  const expectedKeys = shadowCasterKeys(c);
+  const viewPlanes = c.shadowViewPlanesByView?.get(shadowViewIdentityKey(identity));
+  const visibleRenderableIndices =
+    viewPlanes === undefined
+      ? undefined
+      : new Set(
+          (c.shadowValidatedOrdered ?? c.validatedOrdered)
+            .filter((entry) => shadowViewContains(entry.source, viewPlanes))
+            .map((entry) => entry.renderableIndex),
+        );
+  const allExpectedKeys = shadowCasterKeys(c);
+  const visibleExpectedKeys =
+    visibleRenderableIndices === undefined || c.shadowCasterMembership === undefined
+      ? allExpectedKeys
+      : new Set(
+          c.shadowCasterMembership
+            .filter((membership) => visibleRenderableIndices.has(membership.renderableIndex))
+            .map((membership) =>
+              gpuDrivenShadowDrawKey(
+                membership.worldEntity,
+                membership.materialHandle,
+                membership.drawItemIndex,
+                membership.passIndex,
+              ),
+            ),
+        );
   const claimed = claimedKeys ?? new Set<string>();
   const overlap = [...claimed].filter((key) => recordedKeys.has(key));
   const union = new Set([...claimed, ...recordedKeys]);
-  const missing = [...expectedKeys].filter((key) => !union.has(key));
-  const unexpectedClaims = [...claimed].filter((key) => !expectedKeys.has(key));
+  const missing = [...visibleExpectedKeys].filter((key) => !union.has(key));
+  // GPU ownership is projected before its own per-view culling. A claim may
+  // therefore be outside the CPU residual's conservative visible subset and
+  // is still valid as long as it belongs to the extracted caster membership.
+  const unexpectedClaims = [...claimed].filter((key) => !allExpectedKeys.has(key));
   // `shadowCasterMembership` describes the concrete draws that the GPU
   // producer is eligible to claim.  A renderable that stays on the CPU lane
   // (for example a clustered frame without a compatible GPU-driven PBR
@@ -674,7 +726,7 @@ function validateShadowOwnership(
   throw new RhiError({
     code: 'internal-error',
     expected: `disjoint ShadowCaster ownership for ${shadowViewIdentityKey(identity)}`,
-    hint: `claimed=${[...claimed].sort().join(',')} recorded=${[...recordedKeys].sort().join(',')} missing=${missing.sort().join(',')} unexpectedClaims=${unexpectedClaims.sort().join(',')}`,
+    hint: `expected=${[...allExpectedKeys].sort().join(',')} visibleExpected=${[...visibleExpectedKeys].sort().join(',')} claimed=${[...claimed].sort().join(',')} recorded=${[...recordedKeys].sort().join(',')} missing=${missing.sort().join(',')} unexpectedClaims=${unexpectedClaims.sort().join(',')}`,
   });
 }
 
@@ -842,9 +894,11 @@ export function encodeDirectionalShadowPass(
   cascadeIndex: number,
   viewport: { readonly x: number; readonly y: number; readonly w: number; readonly h: number },
   drawFeatures?: (view: BindGroup) => void,
+  forceRaster = false,
 ): void {
   const directionalIdentity = { kind: 'directional' as const, index: cascadeIndex };
   if (
+    !forceRaster &&
     (c.gpuDrivenShadowViews?.cacheHit(directionalIdentity) === true ||
       (c.gpuDrivenShadowViews === undefined && c.directionalShadowCacheReuse)) &&
     drawFeatures === undefined
@@ -941,6 +995,8 @@ export function encodeDirectionalShadowPass(
     }),
     shadowShaderMap(c),
     claimedKeys,
+    false,
+    c.shadowViewPlanesByView?.get(shadowViewIdentityKey(directionalIdentity)),
   );
   validateShadowOwnership(c, directionalIdentity, claimedKeys, recordedKeys);
   c.frameState.directionalShadowCacheRecorded =
@@ -1047,6 +1103,7 @@ export function encodePointShadowPass(
     shadowShaderMap(c),
     claimedKeys,
     true,
+    c.shadowViewPlanesByView?.get(shadowViewIdentityKey(pointIdentity)),
   );
   validateShadowOwnership(c, pointIdentity, claimedKeys, recordedKeys);
 }
@@ -1171,6 +1228,8 @@ export function encodeSpotShadowPass(
     }),
     shadowShaderMap(c),
     claimedKeys,
+    false,
+    c.shadowViewPlanesByView?.get(shadowViewIdentityKey(spotIdentity)),
   );
   validateShadowOwnership(c, spotIdentity, claimedKeys, recordedKeys);
 }
@@ -1303,6 +1362,7 @@ export function recordShadowCasterDraws(
   shadowDispatchByRenderableIdx: ShadowDispatchMap,
   gpuDrivenShadowDrawKeys: ReadonlySet<string> | undefined,
   reflected = false,
+  viewPlanes?: Float32Array,
 ): ReadonlySet<string> {
   const {
     runtime,
@@ -1330,6 +1390,7 @@ export function recordShadowCasterDraws(
   for (let i = 0; i < validatedOrdered.length; i++) {
     const entry = validatedOrdered[i];
     if (entry === undefined) continue;
+    if (!shadowViewContains(entry.source, viewPlanes)) continue;
 
     // feat-20260609 M2: skip entities that don't match the pass selector.
     if (matchedIndices !== null && !matchedIndices.has(entry.renderableIndex)) continue;

package/src/record/typed-frame-graph.ts

@@ -2639,7 +2639,11 @@ export function ensureCompiledFrameGraph(
         ? {}
         : {
             projectGpuDrivenShadow: (identity) =>
-              gpuDriven.projectShadow?.(builder, identity) ?? ok(undefined),
+              // A newly compiled graph must include the shadow compute passes
+              // even when the producer cache hit. The graph owns its pass
+              // list; importing only the cached view resources would reuse
+              // stale indirect arguments after a topology replacement.
+              gpuDriven.projectShadow?.(builder, identity, true) ?? ok(undefined),
           }),
       contributeShadowFeatures: () =>
         (featureShadows ??= projectRenderFeatureShadows(

package/src/recovery/render-system-candidate.ts

@@ -53,6 +53,7 @@ import { prepareFrameLighting } from '../record/frame-lighting';
 import type { RenderFrameState, ValidatedRenderable } from '../record/frame-snapshot';
 import { resolveGeometryInstanceBuffer } from '../record/main-pass-geometry';
 import { computeSplitLdrSprite } from '../record/main-pass-sprite-draws';
+import type { PreparedResolverCaches } from '../record/prepared-material-bindings';
 import { ensureProbeBlendRecordBuffer } from '../record/probe-blend-buffer';
 import {
   prepareRecoveryPipelineReadiness,
@@ -90,15 +91,6 @@ import type {
   RecoveryPointsLinesCandidate,
 } from './types';
 
-export interface PreparedResolverCaches {
-  readonly preparedPipelineIds: WeakMap<object, string>;
-  readonly preparedMaterialPipelineShaders: WeakMap<object, string>;
-  readonly preparedGroup0Pipelines: WeakSet<object>;
-  readonly preparedViewOnlyPipelines: WeakSet<object>;
-  readonly preparedRenderMaterialPipelines: WeakSet<object>;
-  readonly preparedAssetHandles: WeakMap<RenderResourceScope, Map<string, number>>;
-}
-
 export interface RecoveryFrameSeed {
   readonly frame: ExtractedFrame;
   readonly worlds: readonly RenderResourceScope[];

package/src/render-contract.ts

@@ -478,8 +478,8 @@ export interface Renderer {
   destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
   state(): RendererState;
-  /** Detached world bounds for one record in the last extracted World; undefined if unavailable. */
-  bounds(world: World, entity: number): RenderSceneBounds | undefined;
+  /** Detached bounds from an extracted World or the bound publication source; undefined if unavailable. */
+  bounds(world: World | RenderPublicationIdentity, entity: number): RenderSceneBounds | undefined;
   inspect(): RenderInspection;
   observe(
     receipt: FrameReceipt,

package/src/render-system-extract-tail.ts

@@ -2137,6 +2137,11 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           if (asset.kind !== 'material') {
             materialSnap = defaultMaterialSnapshot(handleRaw);
           } else {
+            // Program selection belongs to the shared source; RuntimeMaterialValue
+            // only projects the numeric parameter content resolved below.
+            const source = world.sharedRefs.resolve<string, Asset>(tagged);
+            const programOwner =
+              source.ok && source.value.kind === 'material' ? source.value : asset;
             // feat-20260529 M3 / w11: material parent chain inheritance via
             // read-through _materialWalk accessor (plan-strategy D-6).
             // The old direct asset.passes / asset.values read never
@@ -2186,7 +2191,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                   };
             try {
               materialProgramSelections = materialProgramSelectionsForMaterial(
-                asset,
+                programOwner,
                 assets,
                 materialContext,
               );
@@ -2198,10 +2203,14 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               // publication error instead of guessing from module names/order.
               if (isMissingMaterialProgram(error) && materialContext?.geometry === 'mesh') {
                 try {
-                  const skinnedSelections = materialProgramSelectionsForMaterial(asset, assets, {
-                    ...materialContext,
-                    geometry: 'skinned',
-                  });
+                  const skinnedSelections = materialProgramSelectionsForMaterial(
+                    programOwner,
+                    assets,
+                    {
+                      ...materialContext,
+                      geometry: 'skinned',
+                    },
+                  );
                   if (
                     skinnedSelections?.some(materialProgramSelectionRequiresSkin) === true &&
                     gpuDrivenMesh !== undefined
@@ -2238,7 +2247,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                     ]),
                   );
             const materialSceneIndexProgramKeys = materialSceneIndexProgramKeysForMaterial(
-              asset,
+              programOwner,
               assets,
               materialContext,
             );

package/src/render-system-extract.ts

@@ -2362,9 +2362,16 @@ export function resolveMaterialSnapshot(
   if (!resolvedResult.ok) return defaultMaterialSnapshot(handleRaw);
   const resolved = resolvedResult.value;
   const allPasses = resolved.passes;
-  const materialProgramKeys = materialProgramKeysForMaterial(asset, assetsRef, materialContext);
+  // Numeric World content changes values, never the immutable program owner.
+  const source = world.sharedRefs.resolve<string, Asset>(tagged);
+  const programOwner = source.ok && source.value.kind === 'material' ? source.value : asset;
+  const materialProgramKeys = materialProgramKeysForMaterial(
+    programOwner,
+    assetsRef,
+    materialContext,
+  );
   const materialSceneIndexProgramKeys = materialSceneIndexProgramKeysForMaterial(
-    asset,
+    programOwner,
     assetsRef,
     materialContext,
   );

package/src/render-system.ts

@@ -1,6 +1,6 @@
 import { projectCaptureScene } from './capture/scene-projection';
 import { renderMaterialContext } from './extract/material-context';
-import { RenderPublicationError } from './publication/contract';
+import { RenderPublicationError, type RenderPublicationIdentity } from './publication/contract';
 import { preparePublicationGeometry } from './publication/prepare-geometry';
 import type { PreparedRenderPublication } from './publication/receiver';
 import { type RenderResourceScope, renderTime } from './publication/resource-scope';
@@ -357,7 +357,7 @@ export interface RecoveryProductionEvidence {
  * whose shader identity is `forgeax::default-standard-pbr`).
  */
 export interface RenderSystem {
-  bounds(world: World, entity: number): RenderSceneBounds | undefined;
+  bounds(world: World | RenderPublicationIdentity, entity: number): RenderSceneBounds | undefined;
   /** Publish one renderer-owned read-only Surface dynamic page for the next frame. */
   setSurfaceDynamicInput(frame: SurfaceDynamicInputFrame | undefined): void;
   /** Complete explicit SSR capability preparation before drawing a device generation. */
@@ -1851,7 +1851,6 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
           ) {
             return preparedMaterialBindings(
               runtime,
-              caches,
               worlds,
               materialShaderId,
               material.world,

package/src/scene/render-scene.ts

@@ -29,6 +29,7 @@ import type { InstanceProjectionStore } from '../instances';
 import { fingerprintNumericArray, InstanceBoundsCache } from '../instances-derived-bounds';
 import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRetainedSnapshot } from '../points-lines/snapshot';
+import type { RenderPublicationIdentity } from '../publication/contract';
 import type { PreparedRenderPublication } from '../publication/receiver';
 import type { RenderResourceScope } from '../publication/resource-scope';
 import { worldEntityKey } from '../record/frame-snapshot';
@@ -2568,9 +2569,10 @@ export class PersistentRenderScene {
   }
 
   /** Read existing culling bounds; never expose cached mutable arrays. */
-  bounds(world: World, entity: number): RenderSceneBounds | undefined {
+  bounds(world: World | RenderPublicationIdentity, entity: number): RenderSceneBounds | undefined {
     const entry = this.composition;
-    const worldId = entry?.worlds.indexOf(world) ?? -1;
+    const identity = 'source' in world ? `${world.source}:${world.epoch}` : world.identity;
+    const worldId = entry?.worlds.findIndex((source) => source.identity === identity) ?? -1;
     if (entry === undefined || worldId < 0) return undefined;
     const slot = entry.projection.slot(worldId, entity);
     if (slot === undefined) return undefined;

package/src/typed-shadow-passes.ts

@@ -109,6 +109,13 @@ export function addTypedShadowPasses(
         index: cascade,
       });
       if (shadowProjection !== undefined && !shadowProjection.ok) return shadowProjection;
+      // Every pass in this freshly compiled graph owns a newly allocated
+      // raster target. Populate it once even when the producer cache hits or
+      // the GPU shadow projection is not admitted on this frame. The encoder
+      // receives the same one-shot fence so its cache-hit fast path cannot
+      // return before setting the atlas viewport and recording the casters.
+      let forceRasterPending = true;
+      let forceRasterEncodePending = false;
       const added = recordShadowPass(
         graph,
         `shadowCascade${cascade}`,
@@ -128,10 +135,20 @@ export function addTypedShadowPasses(
             shadowFeatures === undefined
               ? undefined
               : (view) => shadowFeatures.encode(pass, frame, resources, view),
+            forceRasterEncodePending,
           ),
-        (frame) =>
-          shadowFeatures !== undefined ||
-          !shadowViewCacheReuse(frame, { kind: 'directional', index: cascade }),
+        (frame) => {
+          forceRasterEncodePending = false;
+          if (forceRasterPending) {
+            forceRasterPending = false;
+            forceRasterEncodePending = true;
+            return true;
+          }
+          return (
+            shadowFeatures !== undefined ||
+            !shadowViewCacheReuse(frame, { kind: 'directional', index: cascade })
+          );
+        },
         [
           ...(shadowProjection?.ok === true && shadowProjection.value?.graphResources !== undefined
             ? shadowViewRasterAccesses(shadowProjection.value.graphResources)
@@ -197,6 +214,7 @@ export function addTypedShadowPasses(
           face,
         });
         if (shadowProjection !== undefined && !shadowProjection.ok) return shadowProjection;
+        let forceRasterPending = true;
         const identity = { kind: 'point' as const, index: pointIndex, face };
         const cacheReuse = (frame: RenderPipelineFrame): boolean =>
           shadowViewCacheReuse(frame, identity);
@@ -228,7 +246,13 @@ export function addTypedShadowPasses(
                 ? undefined
                 : (view) => shadowFeatures.encode(pass, frame, resources, view),
             ),
-          (frame) => shadowFeatures !== undefined || !cacheReuse(frame),
+          (frame) => {
+            if (forceRasterPending) {
+              forceRasterPending = false;
+              return true;
+            }
+            return shadowFeatures !== undefined || !cacheReuse(frame);
+          },
           [
             ...(shadowProjection?.ok === true &&
             shadowProjection.value?.graphResources !== undefined
@@ -250,6 +274,7 @@ export function addTypedShadowPasses(
   for (let spotIndex = 0; spotIndex < Math.max(1, topology.shadow.spotCount); spotIndex += 1) {
     const shadowProjection = projectGpuDrivenShadow?.({ kind: 'spot', index: spotIndex });
     if (shadowProjection !== undefined && !shadowProjection.ok) return shadowProjection;
+    let forceRasterPending = true;
     const identity = { kind: 'spot' as const, index: spotIndex };
     const cacheReuse = (frame: RenderPipelineFrame): boolean =>
       shadowViewCacheReuse(frame, identity);
@@ -267,7 +292,13 @@ export function addTypedShadowPasses(
             ? undefined
             : (view) => shadowFeatures.encode(pass, frame, resources, view),
         ),
-      (frame) => shadowFeatures !== undefined || !cacheReuse(frame),
+      (frame) => {
+        if (forceRasterPending) {
+          forceRasterPending = false;
+          return true;
+        }
+        return shadowFeatures !== undefined || !cacheReuse(frame);
+      },
       [
         ...(shadowProjection?.ok === true && shadowProjection.value?.graphResources !== undefined
           ? shadowViewRasterAccesses(shadowProjection.value.graphResources)