@forgeax/engine-render 0.1.20 → 0.1.21

package/src/pipeline-spec.ts

@@ -287,6 +287,69 @@ export function variantSetFromVertexLayoutProjection(
   return ok(parts.join('+'));
 }
 
+/**
+ * Derive the capability axes shared by every Standard PBR draw owner.
+ *
+ * The all-true key is the canonical empty key used by the shader manifest;
+ * every other capability pair stays explicit so a no-local-light frame on a
+ * device without storage buffers cannot accidentally select a storage-backed
+ * PSO. Vertex-color is supplied here because the empty-key rule is only valid
+ * when that geometry-owned axis is also true.
+ */
+export function standardCapabilityVariantSet(
+  clustered: boolean,
+  storageBuffer: boolean,
+  vertexColorAvailable: boolean,
+): string {
+  if (clustered && storageBuffer && vertexColorAvailable) return '';
+  return `CLUSTER_FORWARD_AVAILABLE=${clustered}+STORAGE_BUFFER_AVAILABLE=${storageBuffer}`;
+}
+
+/**
+ * Project the frame-owned Standard topology onto its material variant axes.
+ *
+ * `StandardTopologyInputValue.kind` is the only runtime authority for the
+ * cluster axis: a frame with local lights must request the clustered artifact,
+ * while the no-local-light topology requests the direct artifact.  Keeping
+ * this projection beside the canonical key builder prevents PBR, skin, and
+ * sprite-lit record owners from independently inferring the active lane from
+ * whichever bind group happened to be constructed first.
+ */
+export function standardTopologyVariantSet(
+  topology: { readonly kind: 'no-local-lights' | 'clustered' } | undefined,
+  storageBuffer: boolean,
+  vertexColorAvailable: boolean,
+): string {
+  return standardCapabilityVariantSet(
+    topology?.kind === 'clustered',
+    storageBuffer,
+    vertexColorAvailable,
+  );
+}
+
+/**
+ * Keep a clustered frame fail-closed when its unified group(2) resource is
+ * unavailable. A missing group is not evidence that the frame is direct; it
+ * is an invalid prepared resource state.
+ */
+export function standardTopologyBindGroupReady(
+  topology: { readonly kind: 'no-local-lights' | 'clustered' } | undefined,
+  clusterBindGroup: unknown,
+): boolean {
+  return (
+    topology?.kind !== 'clustered' || (clusterBindGroup !== null && clusterBindGroup !== undefined)
+  );
+}
+
+/** Derive the storage axis for Standard-compatible unlit material draws. */
+export function standardStorageVariantSet(
+  storageBuffer: boolean,
+  vertexColorAvailable: boolean,
+): string {
+  if (storageBuffer && vertexColorAvailable) return '';
+  return `STORAGE_BUFFER_AVAILABLE=${storageBuffer}+VERTEX_COLOR_AVAILABLE=${vertexColorAvailable}`;
+}
+
 /**
  * Build a `GPURenderPipelineDescriptor` from a PipelineSpec + shader modules.
  *
@@ -925,14 +988,14 @@ const TRI_GEOMETRY_PBR = {
   shaderUvSetCount: 8,
 };
 
-// M6 fix-up: URP-variant key string for the standard PBR shader. Mirrors the
-// boot-time variantSet computed at createRenderer.ts step 1b when
-// `isHdrpActive=false` and `storageBufferCapable=true` (the URP default
-// surface). The URP record path requests this exact string at every
+// M6 fix-up: non-clustered boot-variant key string for the standard PBR shader.
+// Mirrors the boot-time variantSet computed at createRenderer.ts step 1b when
+// clustered lighting is not yet admitted and `storageBufferCapable=true` (the
+// surface). The default record path requests this exact string at every
 // `getMaterialShaderPipeline` call site, so seeding the table with these
-// variants keeps the URP cache lookup hot from frame 1 instead of
+// variants keeps the default cache lookup hot from frame 1 instead of
 // skip-drawing the first ~1 frames while the async compile resolves.
-const URP_PBR_VARIANT_SET = 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true';
+const STANDARD_BOOT_VARIANT_SET = standardCapabilityVariantSet(false, true, false);
 
 /**
  * Build the boot-time pre-warm table: 15 standard PipelineSpec variants.
@@ -944,22 +1007,22 @@ const URP_PBR_VARIANT_SET = 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAI
  *
  * Matrix:
  *   - 8 base material variants — {unlit, standard-pbr} x {LDR, HDR} x {S1, S4}
- *   - 4 URP-variant standard-pbr — standard-pbr (variantSet=URP_PBR_VARIANT_SET)
- *     x {LDR, HDR} x {S1, S4}; URP record path requests these specs by
+ *   - 4 non-clustered standard-pbr — standard-pbr (variantSet=STANDARD_BOOT_VARIANT_SET)
+ *     x {LDR, HDR} x {S1, S4}; the default record path requests these specs by
  *     `getMaterialShaderPipeline` keying off `cacheKeyOf` so the boot-time
  *     prewarm seeds `materialShaderPipelineCache` and avoids a 1-frame
- *     async-compile skip-draw (M6 fix-up; see render-system-record.ts §URP)
+ *     async-compile skip-draw (M6 fix-up; see render-system-record.ts)
  *   - 3 fullscreen-post — tonemap (LDR S1) + skybox (HDR S1, HDR S4)
  *
- * Total: 15. The URP variant is PBR-only because:
- *   - unlit URP record path passes `variantSet=undefined` (the no-variant
+ * Total: 15. The non-clustered variant is PBR-only because:
+ *   - unlit record path passes `variantSet=undefined` (the no-variant
  *     boot-default entries already cover it; createRenderer.ts §unlitRsp)
  *   - sprite goes through `getMaterialShaderPipeline('forgeax::sprite', ...)`
  *     lazily at first transparent-LDR-split draw — no boot-time pre-warm.
- *   - HDRP variant (`variantSet=''` or compound `=true` form) is registered
+ *   - clustered variant (`variantSet=''` or compound `=true` form) is registered
  *     lazily when the clustered Standard profile activates, not at boot — adding clustered
  *     prewarm here would build PSOs against the URP layout (the boot-time
- *     `pbrModule` is the URP variant when `isHdrpActive=false`)
+ *     `pbrModule` is the non-clustered variant before a frame admits local lights)
  *
  * `ldrViewFormat` parameterises the LDR color attachment format. Callers
  * pass the runtime-resolved swap-chain view format (Channel 2 typically
@@ -1074,12 +1137,12 @@ export function buildSpecConstTable(
       renderState: undefined,
     },
 
-    // ── M6 fix-up: URP-variant standard-pbr prewarm ─────────────────────────
-    // URP record path (`getMaterialShaderPipeline`) requests
-    // `variantSet=URP_PBR_VARIANT_SET` for standard-shading entities; pre-M6
+    // ── M6 fix-up: non-clustered standard-pbr prewarm ─────────────────────────
+    // The default record path (`getMaterialShaderPipeline`) requests
+    // `variantSet=STANDARD_BOOT_VARIANT_SET` for standard-shading entities; pre-M6
     // the silent `selectStandardFallbackPipeline` shim served the no-variant
     // boot prewarm during the 1-frame async-compile warmup. With M6's
-    // explicit-failure surface, those URP requests must hit the boot prewarm
+    // explicit-failure surface, those requests must hit the boot prewarm
     // by their own variantSet — these 4 entries close that gap.
 
     // standard PBR URP LDR S1
@@ -1087,7 +1150,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_LDR_S1,
       geometry: TRI_GEOMETRY_PBR,
@@ -1098,7 +1161,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_LDR_S4,
       geometry: TRI_GEOMETRY_PBR,
@@ -1109,7 +1172,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_HDR_S1,
       geometry: TRI_GEOMETRY_PBR,
@@ -1120,7 +1183,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_HDR_S4,
       geometry: TRI_GEOMETRY_PBR,

package/src/point-shadow-inspection.ts

@@ -0,0 +1,55 @@
+import type { PointShadowSnapshot } from './render-system-extract';
+
+/**
+ * Detached point-shadow budget facts from one completed extract/record frame.
+ *
+ * `requested` is the number of PointLight + PointLightShadow pairs. The
+ * renderer owns the bounded cube-array atlas, so `admitted`, `shadowed`, and
+ * `shadowAtlasOccupancy` are all derived from the layer sentinel emitted by
+ * the same extract owner. No consumer needs to maintain a second budget
+ * ledger.
+ */
+export interface PointShadowInspection {
+  readonly status: 'inactive' | 'ready' | 'over-budget';
+  readonly requested: number;
+  readonly admitted: number;
+  readonly shadowed: number;
+  readonly shadowAtlasOccupancy: number;
+  readonly shadowAtlasCapacity: number;
+}
+
+/** Project point-shadow snapshots to the public, JSON-safe inspection shape. */
+export function inspectPointShadow(
+  snapshots: readonly PointShadowSnapshot[],
+  shadowAtlasCapacity: number,
+): PointShadowInspection {
+  const requested = snapshots.length;
+  const admitted = snapshots.reduce(
+    (count, snapshot) =>
+      snapshot.shadowAtlasLayer >= 0 && snapshot.shadowAtlasLayer < shadowAtlasCapacity
+        ? count + 1
+        : count,
+    0,
+  );
+  // Never publish a misleading `ready` state when any requested shadow owns
+  // no atlas layer. The extract sentinel is the single admission projection;
+  // a partial or all-sentinel frame is therefore a failed/over-budget
+  // admission, not an active shadow path with incomplete output.
+  const status =
+    requested === 0
+      ? ('inactive' as const)
+      : requested > shadowAtlasCapacity || admitted !== requested
+        ? ('over-budget' as const)
+        : ('ready' as const);
+  return Object.freeze({
+    status,
+    requested,
+    admitted,
+    // A point shadow only samples an atlas after it owns an atlas layer. Keep
+    // these names explicit for AI diagnostics while deriving both from the
+    // one layer projection above.
+    shadowed: admitted,
+    shadowAtlasOccupancy: admitted,
+    shadowAtlasCapacity,
+  });
+}

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -2,7 +2,7 @@ import { vec3 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
 import type { CameraSnapshot } from '../../render-contract';
-import type { RenderableSnapshot } from '../../render-system-extract';
+import type { RenderableSnapshot, SpotLightSnapshot } from '../../render-system-extract';
 import type { TemporalView } from '../../temporal/temporal-view';
 import type { ValidatedRenderable } from '../frame-snapshot';
 import { uploadMeshSsboBatch } from '../mesh-ssbo';
@@ -98,6 +98,47 @@ function temporalView(): TemporalView {
 }
 
 describe('temporal GPU payloads', () => {
+  it('publishes a projector-only SpotLight matrix into the explicit lane-0 contract', () => {
+    const { queue, uploads } = recordingQueue();
+    const projectorMatrix = translatedMatrix(9);
+    const projector: SpotLightSnapshot = {
+      kind: 'spot',
+      entity: 4,
+      position: vec3.create(0, 2, 0),
+      direction: vec3.create(0, -1, 0),
+      color: vec3.create(1, 1, 1),
+      intensity: 1,
+      invRangeSquared: 0.04,
+      cosInner: 0.95,
+      cosOuter: 0.8,
+      castShadow: false,
+      lightViewProj: projectorMatrix,
+      mapSize: 512,
+      nearPlane: 0.1,
+      farPlane: 25,
+      shadowAtlasTile: -1,
+      projectorAsset: { kind: 'texture' } as never,
+    };
+    writeViewUbo(
+      queue,
+      {} as Buffer,
+      camera(),
+      {
+        kind: 'directional',
+        direction: vec3.create(0, -1, 0),
+        color: vec3.create(1, 1, 1),
+        intensity: 1,
+      },
+      { point: [], spot: [projector] } as never,
+      [projector],
+      undefined,
+      undefined,
+      0,
+    );
+    const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
+    expect(payload[132 + 12]).toBe(9);
+  });
+
   it('writes temporal current/previous projection after the spot-light lanes', () => {
     const { queue, uploads } = recordingQueue();
     writeViewUbo(

package/src/record/__tests__/transparent-group2-selection.unit.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { selectPipelineLayoutForVariant } from '../../assembly/factory';
+import { resolvePipelineGroup2Contract } from '../../pbr-pipeline';
+import { projectDeviceOwnedBindGroup } from '../frame-lighting';
+import { selectMaterialGroup2 } from '../main-pass-material';
+
+const meshGroup = { label: 'pbr-mesh-bg' } as never;
+const clusterGroup = { label: 'hdrp-unified-bg-group2' } as never;
+
+describe('transparent material group 2 selection', () => {
+  it('uses the shared cluster layout only for standard materials', () => {
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'cluster')).toBe(clusterGroup);
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'mesh')).toBe(meshGroup);
+  });
+
+  it('returns null when a non-standard material lacks its ordinary mesh group', () => {
+    expect(selectMaterialGroup2(clusterGroup, null, 'mesh')).toBeNull();
+  });
+
+  it('resolves mesh, skin, and clustered skin from the composed shader artifact', () => {
+    expect(
+      resolvePipelineGroup2Contract('@group(2) @binding(0) var<storage> mesh: array<u32>;'),
+    ).toBe('mesh');
+    expect(
+      resolvePipelineGroup2Contract(
+        '@group(2) @binding(0) var<storage> mesh: array<u32>; @group(2) @binding(1) var<uniform> palette: mat4x4<f32>;',
+      ),
+    ).toBe('skin');
+    expect(
+      resolvePipelineGroup2Contract(
+        '@group(2) @binding(0) var<storage> mesh: array<u32>; @group(2) @binding(1) var<storage> palette: array<u32>; @group(2) @binding(4) var<storage> lights: array<u32>;',
+      ),
+    ).toBe('skin-cluster');
+  });
+
+  it('lets the resolved clustered contract select the unified group', () => {
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'cluster')).toBe(clusterGroup);
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'skin')).toBeNull();
+    // A skin-cluster PSO cannot consume the ordinary HDRP group. The caller
+    // must provide the dedicated skin bind group through the skin path; when
+    // it is absent, fail-stop instead of submitting a layout-invalid draw.
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'skin-cluster')).toBeNull();
+  });
+
+  it('keeps a mesh contract on the mesh pipeline despite the HDRP variant key', () => {
+    const pbrPipelineLayout = { label: 'pbr-pl' } as never;
+    const hdrpPipelineLayout = { label: 'hdrp-pbr-pl' } as never;
+    expect(
+      selectPipelineLayoutForVariant(
+        {
+          pbrPipelineLayout,
+          hdrpPbrPipelineLayout: hdrpPipelineLayout,
+          pbrSkinPipelineLayout: null,
+          hdrpSkinPipelineLayout: null,
+        },
+        '',
+        'pbr',
+      ),
+    ).toBe(pbrPipelineLayout);
+  });
+
+  it('rejects membership bindings from a retired device or layout', () => {
+    const deviceA = {} as never;
+    const deviceB = {} as never;
+    const layoutA = {} as never;
+    const layoutB = {} as never;
+    const bindGroup = {} as never;
+    const state = { device: deviceA, layout: layoutA, bindGroup };
+    expect(projectDeviceOwnedBindGroup(state, deviceA, layoutA)).toBe(bindGroup);
+    expect(projectDeviceOwnedBindGroup(state, deviceB, layoutA)).toBeNull();
+    expect(projectDeviceOwnedBindGroup(state, deviceA, layoutB)).toBeNull();
+  });
+});

package/src/record/__tests__/view-ubo-layout.unit.test.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const viewUboSrc = readFileSync(fileURLToPath(new URL('../view-ubo.ts', import.meta.url)), 'utf8');
+const commonWgslSrc = readFileSync(
+  fileURLToPath(new URL('../../../..//shader/src/common.wgsl', import.meta.url)),
+  'utf8',
+);
+
+describe('View UBO directional shadow ABI', () => {
+  it('keeps the 960 B payload inside the existing 1024 B slot', () => {
+    expect(viewUboSrc).toMatch(/VIEW_UNIFORM_BYTES\s*=\s*960/);
+    expect(viewUboSrc).toMatch(/VIEW_UNIFORM_SLOT_STRIDE\s*=\s*1024/);
+    expect(viewUboSrc).toMatch(/VIEW_PAYLOAD_FLOATS\s*=\s*240/);
+  });
+
+  it('packs all four cascade metrics into the existing vec4 lanes', () => {
+    expect(viewUboSrc).toMatch(/viewPayload\[108 \+ s \* 4 \+ lane\]/);
+    expect(viewUboSrc).not.toMatch(/viewPayload\[108 \+ s \* 4\]\s*=\s*lights\.splitPlanes/);
+  });
+
+  it('keeps bias at [126]/[127], directional filter at [128..131], and Spot at 132', () => {
+    expect(viewUboSrc).toMatch(/viewPayload\[126\]\s*=\s*lights\.depthBias/);
+    expect(viewUboSrc).toMatch(/viewPayload\[127\]\s*=\s*lights\.normalBias/);
+    expect(viewUboSrc).toMatch(/viewPayload\[128\]/);
+    expect(viewUboSrc).toMatch(/viewPayload\[129\]/);
+    expect(viewUboSrc).toMatch(/viewPayload\[130\]/);
+    expect(viewUboSrc).toMatch(/viewPayload\[131\]/);
+    expect(viewUboSrc).toMatch(/SPOT_LVP_BASE_FLOAT\s*=\s*132/);
+    expect(viewUboSrc).not.toMatch(/lights\.pcfKernelSize/);
+  });
+
+  it('declares one shared View binding with a vec4 directional filter carrier', () => {
+    const viewStruct = commonWgslSrc.match(/struct View \{[\s\S]*?\n\};/)?.[0] ?? '';
+    expect(viewStruct).toMatch(/directionalShadowFilter\s*:\s*vec4<f32>/);
+    expect(viewStruct).not.toMatch(/pcfKernelSize/);
+    expect(commonWgslSrc.match(/@group\(0\) @binding\(0\) var<uniform> view/g)).toHaveLength(1);
+  });
+});