@forgeax/engine-render 0.1.23 → 0.1.25

package/src/record/main-pass-sprite-draws.ts

@@ -717,12 +717,10 @@ function recordSpriteEntityDraws(
       spritePass.setVertexBuffer(0, spriteEntry.mesh.vertexBuffer.handle);
       lastSpriteVertexBuffer = spriteEntry.mesh.vertexBuffer;
     }
-    if (
-      spriteEntry.mesh.indexBuffer !== null &&
-      spriteEntry.mesh.indexBuffer !== lastSpriteIndexBuffer
-    ) {
-      spritePass.setIndexBuffer(spriteEntry.mesh.indexBuffer.handle, spriteEntry.mesh.indexFormat);
-      lastSpriteIndexBuffer = spriteEntry.mesh.indexBuffer;
+    const indexBuffer = spriteEntry.mesh.indexBuffer;
+    if (indexBuffer !== null && indexBuffer !== lastSpriteIndexBuffer) {
+      spritePass.setIndexBuffer(indexBuffer.handle, spriteEntry.mesh.indexFormat);
+      lastSpriteIndexBuffer = indexBuffer;
     }
 
     // Instance buffer resolution: same cap-gate logic as the geometry
@@ -858,7 +856,7 @@ function recordSpriteEntityDraws(
             new RhiError({
               code: 'limit-exceeded',
               expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-              hint: 'reduce instance count to fit within device.limits.maxStorageBufferBindingSize, or split transforms across multiple Instances entries',
+              hint: 'reduce the sprite batch to fit within device.limits.maxStorageBufferBindingSize or use a storage-capable backend',
               detail: {
                 maxStorageBufferBindingSize: cap,
                 requestedBytes,
@@ -955,6 +953,8 @@ function recordSpriteEntityDraws(
 
     spritePass.setBindGroup(2, spriteGroup2 as BindGroup, [i * MESH_PER_ENTITY_STRIDE]);
 
+    const materialSlot = materialSlotIndices[i]?.[0] ?? 0;
+
     // Per-entity sprite material bind group: same standard PBR user-region
     // layout as in the geometry pass sprite branch + Skylight merged entries
     // the geometry pass sprite branch + Skylight merged entries (same
@@ -999,7 +999,6 @@ function recordSpriteEntityDraws(
       bindGroupCounts,
     );
 
-    const materialSlot = materialSlotIndices[i]?.[0] ?? 0;
     spritePass.setBindGroup(1, spritePassBg, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
     spritePass.setBindGroup(3, spriteInstancesBg);
     spritePass.drawIndexed(spriteEntry.mesh.indexCount, spriteInstanceCount, 0, 0, 0);

package/src/record/main-pass.ts

@@ -16,6 +16,7 @@ import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { RenderRecordPhase } from '../render-contract';
 import type { MaterialSnapshot } from '../render-system-extract';
 import { resolveReflectionProbeBinding } from './frame-lighting';
+import { getOpaqueResourceIdentity } from './frame-snapshot';
 import { recordGeometryDraws } from './main-pass-geometry';
 import {
   applyMaterialTextureUvScales,
@@ -42,6 +43,18 @@ export function standardReflectionProbeIndex(
 
 const ZERO_SKYLIGHT_PAYLOAD = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
 
+function materialDiagnosticsEnabled(): boolean {
+  if (typeof globalThis !== 'object' || globalThis === null || !('process' in globalThis)) {
+    return false;
+  }
+  const processValue = (
+    globalThis as {
+      readonly process?: { readonly env?: Record<string, string | undefined> };
+    }
+  ).process;
+  return processValue?.env?.FORGEAX_MATERIAL_DIAGNOSTICS === '1';
+}
+
 export type MainPassOptions = {
   readonly colorViews?: readonly (TextureView | null)[];
   readonly colorFormats?: readonly GPUTextureFormat[];
@@ -52,8 +65,6 @@ export type MainPassOptions = {
   readonly transmissionBackdropView?: TextureView | null;
 };
 
-const TRANSMISSION_VARIANT_SET = 'TRANSMISSION_AVAILABLE=true';
-
 function isTransmissionMaterial(material: MaterialSnapshot): boolean {
   return (
     material.materialShaderId === 'forgeax::default-standard-pbr' &&
@@ -284,10 +295,6 @@ export function recordMainPass(
       : {
           ...c,
           splitLdrSprite: recordMode === 'transparent' ? false : c.splitLdrSprite,
-          validatedOrdered: c.validatedOrdered.map((entry) => ({
-            ...entry,
-            ...(recordMode === 'transmission' ? { variantSet: TRANSMISSION_VARIANT_SET } : {}),
-          })),
         };
 
   if (clusteredBindGroupMissing) {
@@ -420,6 +427,64 @@ export function recordMainPass(
             brdfLutSampler: skylightFallback.sampler,
             intensityBuffer: skylightFallback.intensityBuffer,
           };
+    if (materialDiagnosticsEnabled()) {
+      const activeCache =
+        activeViews === undefined ? undefined : getOrCreateIblCache(runtime.deviceScope);
+      const prefilterViewMipCount =
+        activeCache?.prefilterFaceViewsByMip?.length ?? (activeViews === undefined ? 1 : 0);
+      frameState.iblBindingInspection = {
+        status: 'binding-chain-consistent',
+        frameId: frameState.frameNumber,
+        deviceGeneration: runtime.deviceScope.generation,
+        active: activeViews === undefined ? 'fallback' : 'active',
+        cache: {
+          identity: getOpaqueResourceIdentity((activeCache ?? skylightFallback) as object),
+          generation: runtime.deviceScope.generation,
+          prefilterMipCount: prefilterViewMipCount,
+          prefilterViewMipCount,
+        },
+        sampler: {
+          expected: {
+            magFilter: 'linear',
+            minFilter: 'linear',
+            mipmapFilter: 'linear',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+            addressModeW: 'clamp-to-edge',
+          },
+          identities: [
+            getOpaqueResourceIdentity(skylightResources.irradianceSampler as object),
+            getOpaqueResourceIdentity(skylightResources.prefilterSampler as object),
+            getOpaqueResourceIdentity(skylightResources.brdfLutSampler as object),
+          ],
+        },
+        resources: {
+          irradiance: {
+            viewIdentity: getOpaqueResourceIdentity(skylightResources.irradianceView as object),
+            samplerIdentity: getOpaqueResourceIdentity(
+              skylightResources.irradianceSampler as object,
+            ),
+            deviceGeneration: runtime.deviceScope.generation,
+          },
+          prefilter: {
+            viewIdentity: getOpaqueResourceIdentity(skylightResources.prefilterView as object),
+            samplerIdentity: getOpaqueResourceIdentity(
+              skylightResources.prefilterSampler as object,
+            ),
+            deviceGeneration: runtime.deviceScope.generation,
+          },
+          brdfLut: {
+            viewIdentity: getOpaqueResourceIdentity(skylightResources.brdfLutView as object),
+            samplerIdentity: getOpaqueResourceIdentity(skylightResources.brdfLutSampler as object),
+            deviceGeneration: runtime.deviceScope.generation,
+          },
+          intensityBufferIdentity: getOpaqueResourceIdentity(
+            skylightResources.intensityBuffer as object,
+          ),
+        },
+        errors: [],
+      };
+    }
     // Per-entity material uploads (D-P9 retained path).
     // feat-20260613 fix-issue-1 (D-8 channelMap split): the payload mirrors
     // the post-split sidecar paramSchema for default-standard-pbr (14 entries
@@ -490,6 +555,7 @@ export function recordMainPass(
       },
       materialBgShared: frameState.materialBgShared,
       materialBgAssemblyCache: c.materialBgAssemblyCache,
+      frameState,
       bindGroupCounts,
       ...(transmissionBackdropView === undefined ? {} : { transmissionBackdropView }),
     };
@@ -551,6 +617,28 @@ export function recordMainPass(
           mat.materialParamSchema ??
           (materialShaderId !== undefined ? runtime.getParamSchema?.(materialShaderId) : undefined);
         applyParamSnapshotToUbo(slotPayloadF32, schema, mat.paramSnapshot);
+        const processValue = (
+          globalThis as {
+            process?: { env?: Record<string, string | undefined> };
+          }
+        ).process;
+        if (
+          processValue?.env?.FORGEAX_MATERIAL_PIPELINE_DIAGNOSTICS === '1' &&
+          (materialShaderId === 'forgeax::default-standard-pbr' ||
+            materialShaderId === 'forgeax::pbr-skin')
+        ) {
+          console.error(
+            `[render-material] UBO receipt: ${JSON.stringify({
+              entityIndex: entry.renderableIndex,
+              materialHandle: mat.materialHandle,
+              materialShaderId,
+              clearcoat: slotPayloadF32[32],
+              clearcoatRoughness: slotPayloadF32[33],
+              clearcoatNormalScale: slotPayloadF32[34],
+              paramSnapshot: mat.paramSnapshot,
+            })}`,
+          );
+        }
         applyMaterialTextureUvScales(slotPayloadF32, mat, world);
         // Missing-texture detection: structural debug-pink fallback overrides
         // the baseColor/colorTint slot when a bound baseColorTexture handle

package/src/record/mesh-ssbo.ts

@@ -79,12 +79,18 @@ export function extractEntryResourceHandle(entry: {
   return v as object;
 }
 
+// Object-only terminal marker keeps a shorter resource chain from colliding
+// with a longer chain that shares the same prefix.
+const BIND_GROUP_CHAIN_LEAF_KEY: object = {};
+
 /**
  * feat-20260622-handle-to-id-allocator-elimination M2 / w7: walks a nested
  * WeakMap chain to find or create a BindGroup leaf. Each handle in the
- * `handles` array is a chain node; the final leaf is a Map<string, BindGroup>
- * keyed by `variant` (D-2). Chain keys are always object references, never
- * numeric ids — GC reclaims entries for dead handles automatically.
+ * `handles` array is a chain node; a dedicated object terminal marker points
+ * to the final Map<string, BindGroup> keyed by `variant` (D-2). The marker
+ * prevents variable-depth chains with a shared prefix from treating a nested
+ * WeakMap as a leaf. Chain keys are always object references, never numeric
+ * ids — GC reclaims entries for dead handles automatically.
  *
  * On cache hit returns the cached BindGroup. On miss calls `factory`,
  * bumps `bindGroupCounts.createBindGroup`, stores the result at the leaf,
@@ -99,9 +105,7 @@ export function getOrCreateFromChain(
   counts: { createBindGroup: number; keys: string[] },
 ): BindGroup {
   let node = root;
-  for (let i = 0; i < handles.length - 1; i++) {
-    // biome-ignore lint/style/noNonNullAssertion: handles length guards the index
-    const h = handles[i]!;
+  for (const h of handles) {
     let next = node.get(h) as WeakMap<object, unknown> | undefined;
     if (next === undefined) {
       next = new WeakMap();
@@ -109,12 +113,10 @@ export function getOrCreateFromChain(
     }
     node = next;
   }
-  // biome-ignore lint/style/noNonNullAssertion: known non-empty at call sites
-  const last = handles[handles.length - 1]!;
-  let leaf = node.get(last) as Map<string, BindGroup> | undefined;
+  let leaf = node.get(BIND_GROUP_CHAIN_LEAF_KEY) as Map<string, BindGroup> | undefined;
   if (leaf === undefined) {
     leaf = new Map();
-    node.set(last, leaf);
+    node.set(BIND_GROUP_CHAIN_LEAF_KEY, leaf);
   }
   const hit = leaf.get(variant);
   if (hit !== undefined) return hit;
@@ -125,6 +127,26 @@ export function getOrCreateFromChain(
   return bg;
 }
 
+/**
+ * Read a cached bind group using the same variable-depth chain contract as
+ * `getOrCreateFromChain`. Readers must traverse the terminal marker instead
+ * of assuming that the last handle directly stores the variant map.
+ */
+export function findFromChain(
+  root: WeakMap<object, unknown>,
+  handles: readonly object[],
+  variant: string,
+): BindGroup | undefined {
+  let node = root;
+  for (const handle of handles) {
+    const next = node.get(handle);
+    if (next === undefined) return undefined;
+    node = next as WeakMap<object, unknown>;
+  }
+  const leaf = node.get(BIND_GROUP_CHAIN_LEAF_KEY) as Map<string, BindGroup> | undefined;
+  return leaf?.get(variant);
+}
+
 /**
  * feat-20260622-handle-to-id-allocator-elimination M2 / w8: per-entity bind
  * group lookup-or-create helper (D-2). Two-step lookup: outer Map.get(outerKey)