@forgeax/engine-render 0.1.21 → 0.1.24

package/src/volume/passes.ts

@@ -2,8 +2,8 @@ import type {
   GraphBuffer,
   GraphTextureView,
   RenderGraphBuilder,
-  RenderGraphError,
 } from '@forgeax/engine-render-graph';
+import { RenderGraphError } from '@forgeax/engine-render-graph';
 import type {
   BindGroup,
   BindGroupLayout,
@@ -14,18 +14,10 @@ import type {
   TextureView,
 } from '@forgeax/engine-rhi';
 import { RhiError } from '@forgeax/engine-rhi';
-import { ok, type Result } from '@forgeax/engine-types';
+import { err, ok, type Result } from '@forgeax/engine-types';
 import { GPU_TEXTURE_USAGE_TEXTURE_BINDING } from '../gpu-texture-usage';
-import {
-  GPU_BUFFER_USAGE_COPY_DST,
-  GPU_BUFFER_USAGE_STORAGE,
-  GPU_BUFFER_USAGE_UNIFORM,
-} from '../gpu-usage';
-import {
-  LIGHT_ARRAY_HEADER_BYTES,
-  LIGHT_ARRAY_MAX_SLOTS,
-  SPOT_LIGHT_STD430_BYTES,
-} from '../light-buffer-layout';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
+import type { StandardClusterGraphBuffers } from '../pipeline/standard-lighting/graph';
 import { VIEW_UNIFORM_BYTES } from '../record/view-ubo';
 import type { VolumetricFogFrameContext, VolumetricFogShaderSources } from '../render-contract';
 import type {
@@ -91,8 +83,10 @@ export interface VolumetricFogPassInputs {
   readonly view: GraphBuffer;
   readonly directionalShadow?: GraphTextureView;
   readonly spotShadow: GraphTextureView;
-  readonly pointLights: GraphBuffer;
-  readonly spotLights: GraphBuffer;
+  /** The single Standard Cluster light payload consumed by all volume stages. */
+  readonly lightData: GraphBuffer;
+  /** The Cluster uniform carries the admitted light count for slot guards. */
+  readonly clusterUniform: GraphBuffer;
   readonly selectedLightKind: 'directional' | 'point' | 'spot';
   readonly projector?: GraphTextureView;
 }
@@ -169,10 +163,26 @@ function importVolumeInputs(
   directionalShadow: GraphTextureView | undefined,
   spotShadow: GraphTextureView,
   selectedLightKind: 'directional' | 'point' | 'spot' | undefined,
+  clusterBuffers: StandardClusterGraphBuffers | null,
 ): Result<ImportedVolumeInputs | undefined, RenderGraphError> {
   const volume = topology.volumetricFog;
   if (volume?.enabled !== true || volume.format === undefined || volume.extent === undefined)
     return ok(undefined);
+  if (clusterBuffers === null) {
+    return err(
+      new RenderGraphError({
+        code: 'resource-descriptor-invalid',
+        expected: 'volumetric fog consumes the Standard Cluster light buffers',
+        hint: 'enable the storage-backed Standard Cluster transport before enabling volumetric fog',
+        detail: {
+          resourceLabel: 'volumetric-fog',
+          field: 'clusterBuffers',
+          expected: 'StandardClusterGraphBuffers',
+          actual: 'missing',
+        },
+      }),
+    );
+  }
   const texture = graph.importTexture(
     'volume-density',
     {
@@ -218,21 +228,6 @@ function importVolumeInputs(
     (frame) => frame.pipelineState.viewUniformBuffer,
   );
   if (!view.ok) return view;
-  const spotLights = graph.importBuffer(
-    'volume-spot-lights',
-    {
-      size: LIGHT_ARRAY_HEADER_BYTES + LIGHT_ARRAY_MAX_SLOTS * SPOT_LIGHT_STD430_BYTES,
-      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
-    },
-    (frame) => frame.pipelineState.spotLightsBuffer,
-  );
-  if (!spotLights.ok) return spotLights;
-  const pointLights = graph.importBuffer(
-    'volume-point-lights',
-    { size: 16 + 4 * 32, usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST },
-    (frame) => frame.pipelineState.pointLightsBuffer,
-  );
-  if (!pointLights.ok) return pointLights;
   let projector: GraphTextureView | undefined;
   if (volume.projector !== undefined) {
     const projectorTexture = graph.importTexture(
@@ -270,8 +265,8 @@ function importVolumeInputs(
     view: view.value,
     ...(directionalShadow === undefined ? {} : { directionalShadow }),
     spotShadow,
-    pointLights: pointLights.value,
-    spotLights: spotLights.value,
+    lightData: clusterBuffers.lightData,
+    clusterUniform: clusterBuffers.clusterUniform,
     selectedLightKind: selectedLightKind ?? 'directional',
     ...(projector === undefined ? {} : { projector }),
   });
@@ -283,6 +278,7 @@ export function addAuthoredVolumetricFogPasses(
   sceneDepth: GraphTextureView,
   directionalShadow: GraphTextureView | undefined,
   spotShadow: GraphTextureView,
+  clusterBuffers: StandardClusterGraphBuffers | null,
 ): Result<void, RenderGraphError> {
   // A paired Point+Spot volume stores the Spot shadow lane as well. The
   // topology's primary light remains PointLight for radiance selection, but
@@ -300,6 +296,7 @@ export function addAuthoredVolumetricFogPasses(
     directionalShadow,
     spotShadow,
     shadowLightKind,
+    clusterBuffers,
   );
   if (!imported.ok) return imported;
   if (imported.value === undefined) return ok(undefined);
@@ -342,8 +339,8 @@ export function addVolumetricFogPasses(
         resource: shadowResource,
         usage: 'sampled-read',
       },
-      { resource: inputs.spotLights, usage: 'storage-read' },
-      { resource: inputs.pointLights, usage: 'storage-read' },
+      { resource: inputs.lightData, usage: 'storage-read' },
+      { resource: inputs.clusterUniform, usage: 'uniform-read' },
       ...(inputs.projector === undefined
         ? []
         : [{ resource: inputs.projector, usage: 'sampled-read' as const }]),
@@ -365,19 +362,19 @@ export function addVolumetricFogPasses(
           },
         },
         { binding: 7, visibility: 4, buffer: { type: 'read-only-storage' } },
-        { binding: 8, visibility: 4, buffer: { type: 'read-only-storage' } },
+        { binding: 8, visibility: 4, buffer: { type: 'uniform' } },
       ]);
       const shadow = resources.textureView(shadowResource);
       const params = resources.buffer(inputs.params);
       const view = resources.buffer(inputs.view);
-      const spotLights = resources.buffer(inputs.spotLights);
-      const pointLights = resources.buffer(inputs.pointLights);
+      const lightData = resources.buffer(inputs.lightData);
+      const clusterUniform = resources.buffer(inputs.clusterUniform);
       const froxel = resources.textureView(inputs.resources.froxelView);
       if (!shadow.ok) throw shadow.error;
       if (!params.ok) throw params.error;
       if (!view.ok) throw view.error;
-      if (!spotLights.ok) throw spotLights.error;
-      if (!pointLights.ok) throw pointLights.error;
+      if (!lightData.ok) throw lightData.error;
+      if (!clusterUniform.ok) throw clusterUniform.error;
       if (!froxel.ok) throw froxel.error;
       const shadowSampler = frame.runtime.device.createSampler({ compare: 'less' });
       if (!shadowSampler.ok) throw shadowSampler.error;
@@ -387,8 +384,8 @@ export function addVolumetricFogPasses(
         { binding: 4, resource: { kind: 'sampler', value: shadowSampler.value } },
         { binding: 5, resource: { kind: 'buffer', value: { buffer: params.value } } },
         { binding: 6, resource: { kind: 'textureView', value: froxel.value as never } },
-        { binding: 7, resource: { kind: 'buffer', value: { buffer: spotLights.value } } },
-        { binding: 8, resource: { kind: 'buffer', value: { buffer: pointLights.value } } },
+        { binding: 7, resource: { kind: 'buffer', value: { buffer: lightData.value } } },
+        { binding: 8, resource: { kind: 'buffer', value: { buffer: clusterUniform.value } } },
       ]);
       pass.setPipeline(inject.pipeline);
       pass.setBindGroup(0, bindings);
@@ -406,8 +403,8 @@ export function addVolumetricFogPasses(
       { resource: inputs.resources.temporalView, usage: 'storage-write' },
       { resource: inputs.params, usage: 'uniform-read' },
       { resource: inputs.view, usage: 'uniform-read' },
-      { resource: inputs.spotLights, usage: 'storage-read' },
-      { resource: inputs.pointLights, usage: 'storage-read' },
+      { resource: inputs.lightData, usage: 'storage-read' },
+      { resource: inputs.clusterUniform, usage: 'uniform-read' },
       ...(inputs.projector === undefined
         ? []
         : [{ resource: inputs.projector, usage: 'sampled-read' as const }]),
@@ -449,7 +446,7 @@ export function addVolumetricFogPasses(
           },
         },
         { binding: 10, visibility: 4, buffer: { type: 'read-only-storage' } },
-        { binding: 11, visibility: 4, buffer: { type: 'read-only-storage' } },
+        { binding: 11, visibility: 4, buffer: { type: 'uniform' } },
         { binding: 12, visibility: 4, texture: { sampleType: 'float', viewDimension: '2d' } },
         { binding: 13, visibility: 4, sampler: { type: 'filtering' } },
       ]);
@@ -461,8 +458,8 @@ export function addVolumetricFogPasses(
       const temporalSeed = resources.textureView(inputs.resources.temporalView);
       const params = resources.buffer(inputs.params);
       const view = resources.buffer(inputs.view);
-      const spotLights = resources.buffer(inputs.spotLights);
-      const pointLights = resources.buffer(inputs.pointLights);
+      const lightData = resources.buffer(inputs.lightData);
+      const clusterUniform = resources.buffer(inputs.clusterUniform);
       const projector =
         inputs.projector === undefined ? undefined : resources.textureView(inputs.projector);
       if (!froxel.ok) throw froxel.error;
@@ -473,8 +470,8 @@ export function addVolumetricFogPasses(
       if (!temporalSeed.ok) throw temporalSeed.error;
       if (!params.ok) throw params.error;
       if (!view.ok) throw view.error;
-      if (!spotLights.ok) throw spotLights.error;
-      if (!pointLights.ok) throw pointLights.error;
+      if (!lightData.ok) throw lightData.error;
+      if (!clusterUniform.ok) throw clusterUniform.error;
       if (projector !== undefined && !projector.ok) throw projector.error;
       const sampler = frame.runtime.device.createSampler({
         minFilter: 'linear',
@@ -500,8 +497,8 @@ export function addVolumetricFogPasses(
         { binding: 7, resource: { kind: 'sampler', value: densitySampler.value } },
         { binding: 8, resource: { kind: 'textureView', value: historySeed.value as never } },
         { binding: 9, resource: { kind: 'textureView', value: temporalSeed.value as never } },
-        { binding: 10, resource: { kind: 'buffer', value: { buffer: spotLights.value } } },
-        { binding: 11, resource: { kind: 'buffer', value: { buffer: pointLights.value } } },
+        { binding: 10, resource: { kind: 'buffer', value: { buffer: lightData.value } } },
+        { binding: 11, resource: { kind: 'buffer', value: { buffer: clusterUniform.value } } },
         {
           binding: 12,
           resource: {