@forgeax/engine-render 0.1.3 → 0.1.6

package/src/record/frame-lighting.ts

@@ -2,15 +2,15 @@
 // feat-20260704 M5/w31: further-split from frame.ts (AC-05 <=1500 lines/file).
 // Pure leaf helpers invoked once each from recordFrame; behavior verbatim.
 
-import { mat4, vec3 } from '@forgeax/engine-math';
+import { mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import {
   type BindGroup,
   type BindGroupLayout,
   RhiError,
   type TextureView,
 } from '@forgeax/engine-rhi';
+import { toShared } from '@forgeax/engine-types';
 import { bin, type ClusterBinProfilePhase, type ClusterBinProfileRunner } from '../cluster-binner';
-import { environmentConsumerSnapshot } from '../environment/generation';
 import {
   HdrpIndexListOverflowError,
   HdrpLightBudgetExceededError,
@@ -24,7 +24,6 @@ import {
   HDRP_UNIFORM_LIGHT_CAPACITY,
   packClusterUniform,
 } from '../hdrp-buffers';
-import { DEFAULT_CLUSTER_GRID, LIGHT_INDEX_LIST_CAPACITY } from '../hdrp-pipeline';
 import {
   LIGHT_ARRAY_HEADER_BYTES,
   LIGHT_ARRAY_MAX_SLOTS,
@@ -35,20 +34,18 @@ import {
   packSpotLight,
   SPOT_LIGHT_STD430_BYTES,
 } from '../light-buffer-layout';
-import type { PipelineState, RenderSystemInternals } from '../render-system';
+import { DEFAULT_CLUSTER_GRID, LIGHT_INDEX_LIST_CAPACITY } from '../pipeline/standard-profile';
+import type { CameraSnapshot, RenderHdrpClusterPhase } from '../render-contract';
 import type {
-  CameraSnapshot,
   DirectionalLightSnapshot,
   ExtractedLights,
   RenderableSnapshot,
   SkyboxSnapshot,
   SkylightSnapshot,
 } from '../render-system-extract';
-import type { RenderHdrpClusterPhase } from '../renderer';
 import { ShadowAtlas } from '../shadow-atlas';
 import { getOrCreateSsaoBuffers } from '../ssao-buffers';
 import { getSsaoParameters } from '../ssao-config';
-import type { RecordProfileRunner } from './frame';
 import type { BindGroupCounts, RenderFrameState } from './frame-snapshot';
 import {
   computeProjectionMatrix,
@@ -59,109 +56,9 @@ import {
   warnMultiLightSpot,
 } from './helpers';
 import { getOrCreateFromChain, MESH_SSBO_BYTES, MESH_UBO_FULL_ARRAY_BYTES } from './mesh-ssbo';
+import type { PipelineState, RecordProfileRunner, RenderSystemInternals } from './render-context';
 import { VIEW_UNIFORM_BYTES } from './view-ubo';
 
-export interface EnvironmentSunConsumerInput {
-  readonly generation: number;
-  readonly signature: string;
-  readonly direction: readonly [number, number, number];
-  readonly color: readonly [number, number, number];
-  readonly illuminance: number;
-  readonly atmosphere?:
-    | {
-        readonly turbidity: number;
-        readonly rayleigh: number;
-        readonly mieCoefficient: number;
-        readonly mieDirectionalG: number;
-        readonly sunAngularRadius: number;
-      }
-    | undefined;
-  readonly source?: { readonly worldId: number; readonly entity: number } | undefined;
-}
-
-export interface EnvironmentSunConsumerSnapshot {
-  readonly generation: number;
-  readonly signature: string;
-  readonly source: { readonly worldId: number; readonly entity: number } | undefined;
-  readonly consumers: readonly {
-    readonly kind: 'ibl' | 'direct' | 'csm' | 'background' | 'sun-disc';
-    readonly generation: number;
-  }[];
-  readonly ibl: {
-    readonly includesSunDisc: false;
-    readonly sunContribution: 0;
-  };
-  readonly direct: {
-    readonly direction: readonly [number, number, number];
-    readonly color: readonly [number, number, number];
-    readonly illuminance: number;
-    readonly secondarySunContribution: 0;
-  };
-  readonly csm: { readonly direction: readonly [number, number, number] };
-  readonly background: { readonly includesSunDisc: true };
-  readonly sunDisc: {
-    readonly direction: readonly [number, number, number];
-    readonly color: readonly [number, number, number];
-    readonly illuminance: number;
-  };
-  readonly atmosphere?: EnvironmentSunConsumerInput['atmosphere'];
-  readonly materials: { readonly mirrorSunCount: 1; readonly metalSunCount: 1 };
-}
-
-export function createEnvironmentConsumerSnapshot(
-  input: EnvironmentSunConsumerInput,
-): EnvironmentSunConsumerSnapshot {
-  const consumers = ['ibl', 'direct', 'csm', 'background', 'sun-disc'].map((kind) => ({
-    kind: kind as EnvironmentSunConsumerSnapshot['consumers'][number]['kind'],
-    generation: input.generation,
-  }));
-  return {
-    generation: input.generation,
-    signature: input.signature,
-    source: input.source,
-    consumers,
-    ibl: { includesSunDisc: false, sunContribution: 0 },
-    direct: {
-      direction: input.direction,
-      color: input.color,
-      illuminance: input.illuminance,
-      secondarySunContribution: 0,
-    },
-    // Keep the source-facing Sun vector in the immutable snapshot; the
-    // renderer's DirectionalLight/CSM consumers negate it at their existing
-    // outgoing-direction boundary.
-    csm: { direction: input.direction },
-    background: { includesSunDisc: true },
-    sunDisc: {
-      direction: input.direction,
-      color: input.color,
-      illuminance: input.illuminance,
-    },
-    ...(input.atmosphere === undefined ? {} : { atmosphere: input.atmosphere }),
-    materials: { mirrorSunCount: 1, metalSunCount: 1 },
-  };
-}
-
-export interface EnvironmentWorldConsumerInput {
-  readonly worldId: number;
-  readonly resourceOwner: boolean;
-  readonly directionalLightCount: number;
-  readonly atmosphere?: EnvironmentSunConsumerSnapshot | undefined;
-}
-
-export function consumeEnvironmentWorlds(worlds: readonly EnvironmentWorldConsumerInput[]): {
-  readonly atmosphereSunConsumptions: number;
-  readonly ordinaryDirectionalLightCount: number;
-} {
-  const owner = worlds.find((world) => world.resourceOwner && world.atmosphere !== undefined);
-  return {
-    atmosphereSunConsumptions: owner === undefined ? 0 : 1,
-    ordinaryDirectionalLightCount: worlds
-      .filter((world) => world.atmosphere === undefined)
-      .reduce((total, world) => total + world.directionalLightCount, 0),
-  };
-}
-
 function runHdrpClusterProfilePhase<T>(
   runner: RecordProfileRunner | undefined,
   phase: RenderHdrpClusterPhase,
@@ -220,6 +117,15 @@ export function buildPerFrameBindGroups(
     // `getColorTargetView` returns undefined and we fall through to the
     // 1x1 fallback view that keeps the BGL satisfied.
     if (includeView) {
+      const shadowSampler = pipelineState.perPassResources.shadowSampler;
+      if (shadowSampler === null) {
+        return {
+          viewBindGroup: null,
+          meshBindGroup: null,
+          hdrpClusterBindGroup: null,
+          hdrpClusterMembershipBindGroup,
+        };
+      }
       const graphShadowView = graphTargets?.directionalShadow;
       const b3View =
         graphShadowView !== undefined ? graphShadowView : pipelineState.shadowFallbackTextureView;
@@ -251,7 +157,7 @@ export function buildPerFrameBindGroups(
           pipelineState.pointLightsBuffer,
           pipelineState.spotLightsBuffer,
           b3View,
-          pipelineState.perPassResources.shadowSampler,
+          shadowSampler,
           b5View,
           pipelineState.shadowParamsBuffer,
           b8View,
@@ -294,7 +200,7 @@ export function buildPerFrameBindGroups(
                 binding: 4,
                 resource: {
                   kind: 'sampler',
-                  value: pipelineState.perPassResources.shadowSampler,
+                  value: shadowSampler,
                 },
               },
               // feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1:
@@ -460,9 +366,6 @@ export function prepareFrameLighting(
   internals: RenderSystemInternals,
   frameState: RenderFrameState,
   lights: ExtractedLights,
-  environmentSun: EnvironmentSunConsumerSnapshot | undefined = environmentConsumerSnapshot(
-    frameState.environmentGeneration,
-  ),
 ): {
   light: DirectionalLightSnapshot;
   pointLights: ExtractedLights['point'];
@@ -538,26 +441,7 @@ export function prepareFrameLighting(
   //
   // Each variant carries the discriminant `kind` so the record-time packing
   // call sites can run exhaustive switch (charter P2 + AC-03).
-  const directionalLight: DirectionalLightSnapshot | undefined =
-    environmentSun === undefined
-      ? lights.directional
-      : {
-          kind: 'directional',
-          direction: vec3.create(
-            -(environmentSun.direct.direction[0] ?? 0),
-            -(environmentSun.direct.direction[1] ?? 0),
-            -(environmentSun.direct.direction[2] ?? 0),
-          ),
-          color: vec3.create(
-            environmentSun.direct.color[0] * environmentSun.direct.illuminance,
-            environmentSun.direct.color[1] * environmentSun.direct.illuminance,
-            environmentSun.direct.color[2] * environmentSun.direct.illuminance,
-          ),
-          // The extracted environment snapshot keeps raw sun colour + one
-          // illuminance fact. Collapse that product exactly once here so the
-          // existing view UBO path matches the analytic producer radiometry.
-          intensity: 1,
-        };
+  const directionalLight: DirectionalLightSnapshot | undefined = lights.directional;
   const pointLights = lights.point;
   const spotLights = lights.spot;
 
@@ -720,7 +604,7 @@ export function warnZeroLightStandard(
     const env = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process;
     if (env?.env?.NODE_ENV !== 'production') {
       console.warn(
-        '[forgeax] standard material renders black with 0 lights of any type (no Skylight, and directional + point + spot all empty); spawn at least one light (Skylight, DirectionalLight, PointLight, or SpotLight) or switch material to an unlit shader (Materials.unlit(...)). See AGENTS.md section Breaking changes 2026-05-19.',
+        '[forgeax] standard material renders black with 0 lights of every type (no Skylight, and directional + point + spot all empty); spawn at least one light (Skylight, DirectionalLight, PointLight, or SpotLight) or switch material to an unlit shader (Materials.unlit(...)). See AGENTS.md section Breaking changes 2026-05-19.',
       );
     }
   }
@@ -730,8 +614,9 @@ export function warnZeroLightStandard(
  * feat-20260704 M3/w18: HDRP per-frame CPU cluster binning + light-data /
  * cluster-grid / light-index-list / cluster-uniform / SSAO uniform buffer
  * uploads. Extracted verbatim from `recordFrame`. Runs only when the HDRP
- * pipeline is active and there is at least one punctual light; otherwise it is
- * a no-op (URP / SSAO-off paths untouched).
+ * pipeline is active. A zero-punctual frame explicitly clears the persistent
+ * cluster buffers so stale membership cannot leak across frames; direct and
+ * non-clustered paths remain untouched.
  *
  * feat-20260608-cluster-lighting M5 / w21 + M6 / w23 + r2 fix-up: fail-soft
  * semantics preserved verbatim — index-list-overflow and light-budget-exceeded
@@ -751,12 +636,45 @@ export function writeHdrpClusterAndSsaoBuffers(
   membershipBindGroupLayout: BindGroupLayout | null = null,
 ): void {
   const hdrpLightCount = pointLights.length + spotLights.length;
-  const ssaoEnabled = frameState.installedPipelineConfig?.ssao?.enabled === true;
-  // ClusterUniform also carries the HDRP SSAO intensity. Keep the upload
-  // alive for a directional-light-only SSAO scene; the previous punctual-light
-  // gate left that lane at its zero-initialized intensity and made SSAO config
-  // changes visually inert.
-  if (!frameState.isHdrpActive || (hdrpLightCount === 0 && !ssaoEnabled)) return;
+  if (!frameState.isHdrpActive) return;
+  if (hdrpLightCount === 0) {
+    const grid = frameState.installedPipelineConfig?.clusterGrid ?? DEFAULT_CLUSTER_GRID;
+    const hdrpBuffers = getOrCreateHdrpBuffers(internals, grid);
+    if (hdrpBuffers === null) return;
+    const lightCapacity = hdrpBuffers.storageBuffer ? 256 : HDRP_UNIFORM_LIGHT_CAPACITY;
+    const clusterSsaoConfig = frameState.installedPipelineConfig?.ssao;
+    const clusterSsaoIntensity =
+      clusterSsaoConfig !== undefined && clusterSsaoConfig.enabled === true
+        ? (clusterSsaoConfig.intensity ?? 1.0)
+        : 0;
+    const clusterUniformPayload = packClusterUniform(
+      grid,
+      camera.near,
+      camera.far,
+      clusterSsaoIntensity,
+      0,
+      lightCapacity,
+    );
+    const clusterUniformUpload = internals.device.queue.writeBuffer(
+      hdrpBuffers.clusterUniformBuffer,
+      0,
+      new Uint8Array(clusterUniformPayload),
+    );
+    if (!clusterUniformUpload.ok) internals.errorRegistry.fire(clusterUniformUpload.error);
+    const clusterGridClear = internals.device.queue.writeBuffer(
+      hdrpBuffers.clusterGridBuffer,
+      0,
+      new Uint8Array(hdrpBuffers.clusterGridBytes),
+    );
+    if (!clusterGridClear.ok) internals.errorRegistry.fire(clusterGridClear.error);
+    const lightIndexListClear = internals.device.queue.writeBuffer(
+      hdrpBuffers.lightIndexListBuffer,
+      0,
+      new Uint8Array(hdrpBuffers.lightIndexListBytes),
+    );
+    if (!lightIndexListClear.ok) internals.errorRegistry.fire(lightIndexListClear.error);
+    return;
+  }
   const HDRP_LIGHT_BUDGET = 256;
   let effectivePointLights = pointLights;
   let effectiveSpotLights = spotLights;
@@ -795,8 +713,6 @@ export function writeHdrpClusterAndSsaoBuffers(
     gpuMembership = frameState.hdrpClusterMembershipBindGroup !== null;
   }
 
-  let attemptedTotal = 0;
-  let overflow = false;
   const { clusterGrid, gridX, gridY, gridZ, clusterGridBuf, lightIndexListBuf, lightIndexCount } =
     runHdrpClusterProfilePhase(profilePhase, 'record/scene-state/hdrp-cluster/binner', () => {
       const binnerProfile: ClusterBinProfileRunner | undefined =
@@ -822,20 +738,20 @@ export function writeHdrpClusterAndSsaoBuffers(
         profilePhase,
         'record/scene-state/hdrp-cluster/binner/input-preparation',
         () => {
-          const hdrpLights: Array<{ position: Float32Array; range: number }> = [];
+          const hdrpLights: Array<{ position: Vec3; range: number }> = [];
           for (const pl of effectivePointLights) {
             const range =
               Number.isFinite(pl.invRangeSquared) && pl.invRangeSquared > 0
                 ? Math.sqrt(1 / pl.invRangeSquared)
                 : 1000;
-            hdrpLights.push({ position: pl.position as unknown as Float32Array, range });
+            hdrpLights.push({ position: pl.position, range });
           }
           for (const sl of effectiveSpotLights) {
             const range =
               Number.isFinite(sl.invRangeSquared) && sl.invRangeSquared > 0
                 ? Math.sqrt(1 / sl.invRangeSquared)
                 : 1000;
-            hdrpLights.push({ position: sl.position as unknown as Float32Array, range });
+            hdrpLights.push({ position: sl.position, range });
           }
 
           const clusterGrid =
@@ -880,10 +796,7 @@ export function writeHdrpClusterAndSsaoBuffers(
         'record/scene-state/hdrp-cluster/binner/bin-core',
         () =>
           bin(
-            hdrpLights as unknown as Array<{
-              position: import('@forgeax/engine-math').Vec3;
-              range: number;
-            }>,
+            hdrpLights,
             viewMatrix,
             projMatrix,
             { x: gridX, y: gridY, z: gridZ },
@@ -917,8 +830,6 @@ export function writeHdrpClusterAndSsaoBuffers(
         clusterGridBuf.fill(0);
       }
 
-      attemptedTotal = binResult.ok ? binResult.value : binResult.error.detail.actual;
-      overflow = !binResult.ok;
       return {
         clusterGrid,
         gridX,
@@ -930,21 +841,6 @@ export function writeHdrpClusterAndSsaoBuffers(
       };
     });
 
-  if (internals.membershipTiming?.usesCpuControl() === true) {
-    const clusterValueCount = gridX * gridY * gridZ * 2;
-    internals.membershipTiming.recordMembershipOutput({
-      schemaVersion: 1,
-      lightCount: effectiveLightCount,
-      grid: { x: gridX, y: gridY, z: gridZ },
-      clusterOffsetsAndCounts: Array.from(clusterGridBuf.subarray(0, clusterValueCount)),
-      attemptedTotal,
-      writtenTotal: lightIndexCount,
-      capacity: LIGHT_INDEX_LIST_CAPACITY,
-      overflow,
-      lightIndexPrefix: Array.from(lightIndexListBuf.subarray(0, lightIndexCount)),
-    });
-  }
-
   const hdrpPayload = runHdrpClusterProfilePhase(
     profilePhase,
     'record/scene-state/hdrp-cluster/payload-packing',
@@ -979,9 +875,6 @@ export function writeHdrpClusterAndSsaoBuffers(
       }
       for (const sl of effectiveSpotLights) {
         if (slotIdx >= lightCapacity) break;
-        // M2: the same 64B bytes serve storage and uniform fallback. The
-        // packer reads SpotLightSnapshot.shadowAtlasTile directly; no second
-        // tile allocation or transport-specific projection is allowed.
         const packed = packLightSlot(sl);
         lightDataPayload.set(packed, slotIdx * 16);
         slotIdx += 1;
@@ -1018,20 +911,6 @@ export function writeHdrpClusterAndSsaoBuffers(
   runHdrpClusterProfilePhase(profilePhase, 'record/scene-state/hdrp-cluster/buffer-upload', () => {
     if (hdrpPayload !== null) {
       const { hdrpBuffers, lightDataUploadPayload, clusterUniformPayload } = hdrpPayload;
-      if (gpuMembership) {
-        internals.membershipTiming?.recordGpuMembershipSource({
-          clusterGridBuffer: hdrpBuffers.clusterGridBuffer,
-          clusterGridBytes: gridX * gridY * gridZ * 2 * 4,
-          lightIndexListBuffer: hdrpBuffers.lightIndexListBuffer,
-          lightIndexListBytes: Math.max(4, lightIndexCount * 4),
-          lightCount: effectiveLightCount,
-          grid: { x: gridX, y: gridY, z: gridZ },
-          attemptedTotal,
-          writtenTotal: lightIndexCount,
-          capacity: LIGHT_INDEX_LIST_CAPACITY,
-          overflow,
-        });
-      }
       const lightDataUpload = internals.device.queue.writeBuffer(
         hdrpBuffers.lightDataBuffer,
         0,
@@ -1076,7 +955,7 @@ export function writeHdrpClusterAndSsaoBuffers(
     // ── feat-20260612-hdrp-ssao M1 / w6 + M7 / w33 ───────────────
     // Per-frame SSAO uniform write (plan-strategy D-1 + D-C):
     //   view + projection + inverseProjection at offsets 0/64/128 +
-    //   intensityPad (vec4 — x=intensity, yzw padding) at offset 192;
+    //   intensityPad (vec4 — x=intensity, y=radius, z=bias) at offset 192;
     //   total 256 B (matches host SSAO_UNIFORM_BYTES + WGSL struct).
     // Single writeBuffer covers all four fields so one queue entry
     // updates the entire UBO.
@@ -1097,13 +976,12 @@ export function writeHdrpClusterAndSsaoBuffers(
         // Float32Array of 64 (256 B): 3 mat4 (48) + intensityPad vec4 (4)
         // + 12 trailing padding floats. We only fill the declared region.
         const ssaoUniformPayload = new Float32Array(64);
-        ssaoUniformPayload.set(sView as unknown as Float32Array, 0);
-        ssaoUniformPayload.set(sProj as unknown as Float32Array, 16);
-        ssaoUniformPayload.set(invProjOnly as unknown as Float32Array, 32);
-        // intensityPad carries intensity, radius, and bias in x/y/z. The
-        // graph calc pass writes the same payload again with any custom
-        // addSsaoPasses params; this early write keeps the shared UBO valid
-        // for the typed HDRP route before its fullscreen pass executes.
+        ssaoUniformPayload.set(sView, 0);
+        ssaoUniformPayload.set(sProj, 16);
+        ssaoUniformPayload.set(invProjOnly, 32);
+        // intensityPad carries the same resolved values as the graph SSAO
+        // calc pass; this early write keeps the shared UBO valid before the
+        // typed fullscreen pass executes.
         const ssaoConfig = frameState.installedPipelineConfig?.ssao;
         const parameters = getSsaoParameters(
           ssaoConfig !== undefined && ssaoConfig.enabled === true ? ssaoConfig : undefined,
@@ -1163,8 +1041,9 @@ export function resolveSkyboxActive(
   // GPU view is not ready. getCubemapGpuView returns undefined if the
   // equirect-to-cube upload has not completed yet.
   if (skybox !== undefined && tonemapActive) {
-    // biome-ignore lint/suspicious/noExplicitAny: branded Handle cast from snapshot raw number
-    const cubemapView = internals.gpuStore.getCubemapGpuView(skybox.equirectHandle as any);
+    const cubemapView = internals.gpuStore.getCubemapGpuView(
+      toShared<'EquirectAsset'>(skybox.equirectHandle),
+    );
     if (cubemapView === undefined) {
       // The skybox reuses the Skylight's equirect handle; the cubemap
       // projection is driven lazily by the single trigger in `driveLazy