@forgeax/engine-render 0.1.20 → 0.1.23

package/src/pipeline/standard-forward-lane.ts

@@ -5,6 +5,11 @@ import type {
 } from '@forgeax/engine-render-graph';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { SceneDataUnavailableError } from '../errors/render';
+import {
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
 import type {
   RenderPipeline,
   RenderPipelineBuildContext,
@@ -29,12 +34,19 @@ import {
   transmissionDemandForTopology,
 } from '../transmission/backdrop';
 import {
+  addReflectionFallbackObservationPass,
   addTypedFrameObservationPass,
   addTypedScenePass,
   addTypedSkyboxPass,
 } from '../typed-render-graph-primitives';
 import { addTypedShadowPasses } from '../typed-shadow-passes';
 import { addAuthoredVolumetricFogPasses } from '../volume/passes';
+import {
+  addStandardClusterMembershipPass,
+  importStandardClusterBuffers,
+  standardClusterReadAccesses,
+} from './standard-lighting/graph';
+import type { StandardTopologyInputValue } from './standard-lighting/topology';
 import { addStandardPost } from './standard-post';
 
 function target(
@@ -48,6 +60,7 @@ function target(
 function buildUrp(
   context: RenderPipelineBuildContext<RenderPipelineFrame>,
   topology: RenderPipelineTopology,
+  lighting: StandardTopologyInputValue,
 ): ReturnType<RenderPipeline['build']> {
   const graph = context.graph;
   const surface = importRenderPipelineSurface(graph, topology);
@@ -60,16 +73,14 @@ function buildUrp(
   const fxaa = !clearOnly && topology.camera.antialias === 'fxaa';
   const taa = !clearOnly && topology.camera.antialias === 'taa';
   const rawOnly = !clearOnly && topology.surface.profile?.kind === 'raw-only';
-  // A direct no-tone/no-FXAA lane writes the final display view directly;
-  // keeping a linear-LDR intermediate would add a redundant fullscreen pass.
-  // FXAA samples the scene before the Output Transform, so its input must
-  // remain float even when tone mapping is disabled. This prevents an
-  // eight-bit quantization before the OETF/display-encoded boundary.
+  // Every non-clear lane keeps a linear float scene target until the shared
+  // Output Transform. This includes no-AA and the no-storage fallback: the
+  // final dither and display encoding must have one graph-owned boundary.
   // MSAA resolves into a separate linear target before presentation. Treat
   // that resolved target like linear LDR so the shared Output Transform owns
   // its write into the surface storage view; without this, the resolve is
   // never presented and MSAA is indistinguishable from the no-AA path.
-  const linearLdr = !clearOnly && ((!hdr && topology.lane.storageBuffer) || fxaa || msaa);
+  const linearLdr = !clearOnly && !hdr;
   const temporalDemand = aggregateTemporalDemand({
     taa,
     motionBlur: !clearOnly && topology.temporal?.motionBlur === true,
@@ -88,7 +99,14 @@ function buildUrp(
   if (!depth.ok) return depth;
 
   const sceneResolved = clearOnly
-    ? ok(surface.value.display ?? surface.value.storage)
+    ? surface.value.display === undefined
+      ? target(graph, 'scene-color', {
+          format: topology.surface.storageFormat,
+          size: 'surface',
+          sampleCount: 1,
+          domain: 'display-encoded',
+        })
+      : ok(surface.value.display)
     : hdr || fxaa || linearLdr || msaa || rawOnly || needsTemporalIntermediate
       ? target(graph, 'scene-color', {
           format: sceneFormat,
@@ -123,9 +141,48 @@ function buildUrp(
     : sceneResolved;
   if (!scene.ok) return scene;
 
+  const reflectionFallback = topology.reflectionFallback?.enabled
+    ? target(graph, 'reflection-fallback-linear-hdr', {
+        format: 'rgba16float',
+        size: 'surface',
+        sampleCount: scene.value.sampleCount,
+        domain: 'linear-hdr',
+        usage:
+          GPU_TEXTURE_USAGE_COPY_SRC |
+          GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+          GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+      })
+    : ok(undefined);
+  if (!reflectionFallback.ok) return reflectionFallback;
+  if (reflectionFallback.value !== undefined) {
+    const initialized = graph.addRasterPass('reflection-fallback-clear', {
+      accesses: [{ resource: reflectionFallback.value.view, usage: 'color-attachment' }],
+      colorAttachments: [
+        {
+          view: reflectionFallback.value.view,
+          loadOp: 'clear',
+          storeOp: 'store',
+          clearValue: { r: 0, g: 0, b: 0, a: 0 },
+        },
+      ],
+      encode: () => {},
+    });
+    if (!initialized.ok) return initialized;
+  }
+
   const shadows = addTypedShadowPasses(graph, topology);
   if (!shadows.ok) return shadows;
 
+  const clusterBuffers = clearOnly ? ok(null) : importStandardClusterBuffers(graph, lighting);
+  if (!clusterBuffers.ok) return clusterBuffers;
+  const clusterMembership =
+    clusterBuffers.value === null
+      ? ok(undefined)
+      : addStandardClusterMembershipPass(graph, lighting, clusterBuffers.value);
+  if (!clusterMembership.ok) return clusterMembership;
+  const clusterReads =
+    clusterBuffers.value === null ? [] : standardClusterReadAccesses(clusterBuffers.value);
+
   const skybox = addTypedSkyboxPass(graph, scene.value);
   if (!skybox.ok) return skybox;
   const gpuDriven = context.projectGpuDriven({
@@ -141,25 +198,30 @@ function buildUrp(
   const main = addTypedScenePass(graph, {
     name: 'main',
     color: scene.value,
+    ...(reflectionFallback.value === undefined
+      ? {}
+      : { colorTargets: [scene.value, reflectionFallback.value] }),
     depth: depth.value,
     ...(msaa ? { resolve: sceneResolved.value } : {}),
     sampled: [
-      shadows.value.directional,
+      ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
       shadows.value.spot,
       ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
     ],
-    directionalShadow: shadows.value.directional,
+    ...(shadows.value.directional === undefined
+      ? {}
+      : { directionalShadow: shadows.value.directional }),
     spotShadow: shadows.value.spot,
     selector: { LightMode: ['Forward'] },
     colorLoadOp: 'load',
+    extraAccesses: clusterReads,
     ...(transmissionActive ? { recordMode: 'opaque' as const } : {}),
     ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
+    ...(context.occlusion === undefined ? {} : { occlusion: context.occlusion }),
   });
   if (!main.ok) return main;
 
-  const temporalLane = topology.lane.compute
-    ? (topology.standardProfile?.lighting ?? 'direct')
-    : 'cpu-webgl2';
+  const temporalLane = topology.lane.compute ? 'clustered' : 'cpu-webgl2';
   const temporalAdmission = standardTemporalLaneAdmission({
     lane: temporalLane,
     demand: temporalDemand,
@@ -191,6 +253,7 @@ function buildUrp(
     const producer = addStandardSceneDataPass(graph, temporal.value.temporal, depth.value);
     if (!producer.ok) return producer;
   }
+
   const transmission = addTransmissionBackdropPasses({
     graph,
     source: sceneResolved.value,
@@ -207,7 +270,7 @@ function buildUrp(
       depth: depth.value,
       ...(msaa ? { resolve: sceneResolved.value } : {}),
       sampled: [
-        shadows.value.directional,
+        ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
         shadows.value.spot,
         ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
       ],
@@ -217,6 +280,7 @@ function buildUrp(
       colorLoadOp: 'load',
       depthLoadOp: 'load',
       recordMode: 'transmission',
+      extraAccesses: clusterReads,
       // Inject the complete backdrop view so the Standard shader can select
       // the producer's optional roughness mip level. mipViews[0] is only the
       // copy destination view and intentionally exposes one level.
@@ -230,7 +294,7 @@ function buildUrp(
       depth: depth.value,
       ...(msaa ? { resolve: sceneResolved.value } : {}),
       sampled: [
-        shadows.value.directional,
+        ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
         shadows.value.spot,
         ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
       ],
@@ -240,6 +304,7 @@ function buildUrp(
       colorLoadOp: 'load',
       depthLoadOp: 'load',
       recordMode: 'transparent',
+      extraAccesses: clusterReads,
     });
     if (!transparentPass.ok) return transparentPass;
     const temporal = addTransmissionBackdropTemporalPass(graph, sceneResolved.value);
@@ -258,8 +323,9 @@ function buildUrp(
       topology,
       sceneResolved.value,
       depthSample.value,
-      shadows.value.directional.view,
+      shadows.value.directional?.view,
       shadows.value.spot.view,
+      clusterBuffers.value,
     );
     if (!volume.ok) return volume;
   }
@@ -292,8 +358,15 @@ function buildUrp(
     );
     if (!observation.ok) return observation;
   }
+  if (reflectionFallback.value?.sampleCount === 1) {
+    const fallbackObservation = addReflectionFallbackObservationPass(
+      graph,
+      reflectionFallback.value,
+    );
+    if (!fallbackObservation.ok) return fallbackObservation;
+  }
 
-  return addStandardPost(
+  const post = addStandardPost(
     context,
     topology,
     sceneResolved.value,
@@ -301,6 +374,10 @@ function buildUrp(
     surface.value,
     temporal.value?.temporal,
   );
+  if (!post.ok) return post;
+  const cubeCaptures = context.contributeCubeCaptures?.();
+  if (cubeCaptures !== undefined && !cubeCaptures.ok) return cubeCaptures;
+  return ok(undefined);
 }
 
 export const buildStandardForwardLane = buildUrp;

package/src/pipeline/standard-lighting/errors.ts

@@ -0,0 +1,6 @@
+import type { ClusterBinError } from '../../cluster-binner';
+import { StandardClusterIndexOverflowError } from '../../errors/render';
+
+export function fromClusterBinError(error: ClusterBinError): StandardClusterIndexOverflowError {
+  return new StandardClusterIndexOverflowError(error.detail.actual, error.detail.capacity);
+}

package/src/pipeline/standard-lighting/graph.ts

@@ -0,0 +1,158 @@
+import type {
+  GraphAccess,
+  GraphBuffer,
+  RenderGraphBuilder,
+  RenderGraphError,
+} from '@forgeax/engine-render-graph';
+import { ok, type Result } from '@forgeax/engine-types';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../../gpu-usage';
+import { getOrCreateHdrpBuffers, type HdrpBuffers } from '../../hdrp-buffers';
+import { BYTES_PER_DIRECT_LIGHT_SLOT } from '../../light-buffer-layout';
+import type { _InternalRenderPipelineContext } from '../../record/render-context';
+import type { RenderPipelineFrame } from '../../render-pipeline';
+import type { StandardTopologyInputValue } from './topology';
+
+/** Graph resources projected from one Standard lighting topology input. */
+export interface StandardClusterGraphBuffers {
+  readonly lightData: GraphBuffer;
+  readonly clusterGrid: GraphBuffer;
+  readonly lightIndexList: GraphBuffer;
+  readonly clusterUniform: GraphBuffer;
+  readonly lightBounds: GraphBuffer;
+}
+
+/** Stable graph-time projection; never retain a frame's typed-array payload. */
+interface StandardClusterGraphDescriptor {
+  readonly grid: { readonly x: number; readonly y: number; readonly z: number };
+}
+
+function projectDescriptor(input: StandardTopologyInputValue): StandardClusterGraphDescriptor {
+  const { x, y, z } = input.prepared.layout.grid;
+  return { grid: { x, y, z } };
+}
+
+function resolveBuffers(
+  frame: RenderPipelineFrame,
+  descriptor: StandardClusterGraphDescriptor,
+): HdrpBuffers {
+  const internal = frame as _InternalRenderPipelineContext;
+  const buffers = getOrCreateHdrpBuffers(internal.runtime, descriptor.grid);
+  if (buffers === null) throw new Error('Standard persistent buffer allocation failed');
+  return buffers;
+}
+
+/** Resolve membership execution from the frame's current prepared payload. */
+export function shouldExecuteStandardClusterMembershipPass(frame: RenderPipelineFrame): boolean {
+  const standardLighting = (frame as _InternalRenderPipelineContext).standardLighting;
+  return (
+    standardLighting?.kind === 'clustered' &&
+    standardLighting.transport.kind === 'compute-storage' &&
+    standardLighting.prepared.local.length > 0
+  );
+}
+
+/** Import the shared Standard Cluster buffers with sizes derived from layout. */
+export function importStandardClusterBuffers(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  input: StandardTopologyInputValue,
+): Result<StandardClusterGraphBuffers | null, RenderGraphError> {
+  if (input.kind === 'no-local-lights') return ok(null);
+  const layout = input.prepared.layout;
+  const descriptor = projectDescriptor(input);
+  const usage = GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
+  const lightData = graph.importBuffer(
+    'hdrp-light-data',
+    { size: layout.lightDataSlotCount * BYTES_PER_DIRECT_LIGHT_SLOT, usage },
+    (frame) => resolveBuffers(frame, descriptor).lightDataBuffer,
+  );
+  if (!lightData.ok) return lightData;
+  const clusterGrid = graph.importBuffer(
+    'hdrp-cluster-grid',
+    { size: layout.clusterGridU32Length * 4, usage },
+    (frame) => resolveBuffers(frame, descriptor).clusterGridBuffer,
+  );
+  if (!clusterGrid.ok) return clusterGrid;
+  const lightIndexList = graph.importBuffer(
+    'hdrp-light-index-list',
+    { size: layout.lightIndexListCapacity * 4, usage },
+    (frame) => resolveBuffers(frame, descriptor).lightIndexListBuffer,
+  );
+  if (!lightIndexList.ok) return lightIndexList;
+  const clusterUniform = graph.importBuffer(
+    'hdrp-cluster-uniform',
+    { size: 32, usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST },
+    (frame) => resolveBuffers(frame, descriptor).clusterUniformBuffer,
+  );
+  if (!clusterUniform.ok) return clusterUniform;
+  const lightBounds = graph.importBuffer(
+    'hdrp-light-bounds',
+    { size: layout.lightBoundsInt32Length * 4, usage },
+    (frame) => resolveBuffers(frame, descriptor).lightBoundsBuffer,
+  );
+  if (!lightBounds.ok) return lightBounds;
+  return ok({
+    lightData: lightData.value,
+    clusterGrid: clusterGrid.value,
+    lightIndexList: lightIndexList.value,
+    clusterUniform: clusterUniform.value,
+    lightBounds: lightBounds.value,
+  });
+}
+
+/** Accesses used by raster consumers of the shared Cluster payload. */
+export function standardClusterReadAccesses(
+  buffers: StandardClusterGraphBuffers,
+): readonly GraphAccess[] {
+  return [
+    { resource: buffers.lightData, usage: 'storage-read' },
+    { resource: buffers.clusterGrid, usage: 'storage-read' },
+    { resource: buffers.lightIndexList, usage: 'storage-read' },
+    { resource: buffers.clusterUniform, usage: 'uniform-read' },
+  ];
+}
+
+/**
+ * Add the sole GPU membership producer. CPU membership is already materialized
+ * in PreparedStandardLighting and therefore contributes no second pass.
+ */
+export function addStandardClusterMembershipPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  input: StandardTopologyInputValue,
+  buffers: StandardClusterGraphBuffers,
+): Result<void, RenderGraphError> {
+  if (input.kind === 'no-local-lights') return ok(undefined);
+  if (input.transport.kind !== 'compute-storage') return ok(undefined);
+  const descriptor = projectDescriptor(input);
+  return graph.addComputePass('cluster-membership-producer', {
+    accesses: [
+      { resource: buffers.clusterGrid, usage: 'storage-read' },
+      { resource: buffers.clusterUniform, usage: 'uniform-read' },
+      { resource: buffers.lightBounds, usage: 'storage-read' },
+      { resource: buffers.lightIndexList, usage: 'storage-write' },
+    ],
+    // Keep the clustered graph/ABI stable for a directional-only frame, but
+    // do not require a producer bind group when there is no local corpus to
+    // bin.  The zero-length prepared payload is already the complete result;
+    // executing this pass would only turn an otherwise valid frame into a
+    // null-backend encode failure.
+    executeIf: shouldExecuteStandardClusterMembershipPass,
+    encode: ({ pass, frame }) => {
+      const internal = frame as _InternalRenderPipelineContext;
+      const pipeline = internal.pipelineState.hdrpClusterMembershipPipeline;
+      const bindings = internal.hdrpClusterMembershipBindGroup;
+      if (pipeline === null || bindings === null) {
+        throw new Error(
+          'standard-cluster-transport-unavailable: selected compute Cluster producer is not ready',
+        );
+      }
+      const { x, y, z } = descriptor.grid;
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bindings);
+      pass.dispatchWorkgroups(Math.ceil((x * y * z) / 64));
+    },
+  });
+}

package/src/pipeline/standard-lighting/inspection.ts

@@ -0,0 +1,88 @@
+import type { StandardTopologyInputValue } from './topology';
+import type { StandardClusterTransport } from './transport';
+
+export interface StandardClusterTransportInspection {
+  readonly renderPath: 'forward' | 'deferred';
+  readonly transport: StandardClusterTransport['kind'];
+  readonly producer: StandardClusterTransport['producer'];
+  readonly requested: StandardClusterTransport['requestedLightCount'];
+  readonly admitted: StandardClusterTransport['admittedLightCount'];
+  readonly shadowed: number;
+  readonly maxLights: number;
+  readonly indexCount: StandardClusterTransport['membershipEntryCount'];
+  readonly occupied: StandardClusterTransport['occupiedClusterCount'];
+  readonly clusterGridBytes: number;
+  readonly lightIndexListBytes: number;
+  readonly lightDataBytes: number;
+  readonly lightBoundsBytes: number;
+  readonly grid: StandardClusterTransport['layout']['grid'];
+}
+
+export interface StandardNoLocalLightingInspection {
+  readonly renderPath: 'forward' | 'deferred';
+  readonly transport: 'not-required';
+  readonly producer: 'none';
+  readonly requested: 0;
+  readonly admitted: 0;
+  readonly shadowed: 0;
+  readonly maxLights: number;
+  readonly indexCount: 0;
+  readonly occupied: 0;
+  readonly clusterGridBytes: 0;
+  readonly lightIndexListBytes: 0;
+  readonly lightDataBytes: 0;
+  readonly lightBoundsBytes: 0;
+  readonly grid: StandardTopologyInputValue['prepared']['layout']['grid'];
+}
+
+export type StandardLightingInspection =
+  | StandardClusterTransportInspection
+  | StandardNoLocalLightingInspection;
+
+export function inspectStandardClusterTransport(
+  transport: StandardClusterTransport,
+  prepared: StandardTopologyInputValue['prepared'],
+): StandardClusterTransportInspection {
+  return Object.freeze({
+    renderPath: prepared.renderPath,
+    transport: transport.kind,
+    producer: transport.producer,
+    requested: transport.requestedLightCount,
+    admitted: transport.admittedLightCount,
+    shadowed: prepared.local.filter((light) => light.shadowed === true).length,
+    maxLights: prepared.maxLights,
+    indexCount: transport.membershipEntryCount,
+    occupied: transport.occupiedClusterCount,
+    clusterGridBytes: transport.clusterGridBytes,
+    lightIndexListBytes: transport.lightIndexListBytes,
+    lightDataBytes: transport.lightDataBytes,
+    lightBoundsBytes: transport.lightBoundsBytes,
+    // The inspection boundary is JSON-safe and detached from the mutable
+    // layout object carried by a per-frame prepared result.
+    grid: Object.freeze({ ...transport.layout.grid }),
+  });
+}
+
+export function inspectStandardLighting(
+  input: StandardTopologyInputValue,
+): StandardLightingInspection {
+  if (input.kind === 'no-local-lights') {
+    return Object.freeze({
+      renderPath: input.prepared.renderPath,
+      transport: 'not-required' as const,
+      producer: 'none' as const,
+      requested: 0 as const,
+      admitted: 0 as const,
+      shadowed: 0 as const,
+      maxLights: input.prepared.maxLights,
+      indexCount: 0 as const,
+      occupied: 0 as const,
+      clusterGridBytes: 0 as const,
+      lightIndexListBytes: 0 as const,
+      lightDataBytes: 0 as const,
+      lightBoundsBytes: 0 as const,
+      grid: Object.freeze({ ...input.prepared.layout.grid }),
+    });
+  }
+  return inspectStandardClusterTransport(input.transport, input.prepared);
+}

package/src/pipeline/standard-lighting/layout.ts

@@ -0,0 +1,31 @@
+export const DEFAULT_CLUSTER_GRID = { x: 16, y: 9, z: 24 } as const;
+export const CLUSTER_GRID_STRIDE_U32 = 2 as const;
+export const LIGHT_INDEX_LIST_CAPACITY = 1048576 as const;
+export const MAX_LIGHTS = 256 as const;
+
+export interface StandardClusterLayout {
+  readonly grid: { readonly x: number; readonly y: number; readonly z: number };
+  readonly clusterCount: number;
+  readonly clusterGridStrideU32: typeof CLUSTER_GRID_STRIDE_U32;
+  readonly clusterGridU32Length: number;
+  readonly lightIndexListCapacity: typeof LIGHT_INDEX_LIST_CAPACITY;
+  readonly lightDataSlotCount: typeof MAX_LIGHTS;
+  readonly lightBoundsInt32Length: number;
+}
+
+export function createStandardClusterLayout(
+  grid: { readonly x: number; readonly y: number; readonly z: number } = DEFAULT_CLUSTER_GRID,
+): StandardClusterLayout {
+  const clusterCount = grid.x * grid.y * grid.z;
+  return Object.freeze({
+    grid,
+    clusterCount,
+    clusterGridStrideU32: CLUSTER_GRID_STRIDE_U32,
+    clusterGridU32Length: clusterCount * CLUSTER_GRID_STRIDE_U32,
+    lightIndexListCapacity: LIGHT_INDEX_LIST_CAPACITY,
+    lightDataSlotCount: MAX_LIGHTS,
+    lightBoundsInt32Length: MAX_LIGHTS * 6,
+  });
+}
+
+export const STANDARD_CLUSTER_LAYOUT = createStandardClusterLayout();

package/src/pipeline/standard-lighting/light-frame.ts

@@ -0,0 +1,35 @@
+import type { Mat4, Vec3 } from '@forgeax/engine-math';
+import type {
+  DirectionalLightSnapshot,
+  PointLightSnapshot,
+  RectAreaDirectLightSnapshot,
+  SpotLightSnapshot,
+} from '../../render-system-extract';
+import type { StandardLightCount } from '../standard-profile';
+
+export interface StandardLocalLightInput {
+  readonly kind: 'point' | 'spot' | 'rect-area';
+  readonly position: Vec3;
+  readonly range: number;
+  /** Whether the shadow producer admitted this local light to its atlas. */
+  readonly shadowed: boolean;
+  /**
+   * The immutable extract snapshot used by the record payload packer. Keeping
+   * it on the POD frame prevents Forward/Deferred from rebuilding a second
+   * light list while leaving hand-authored unit fixtures source-free.
+   */
+  readonly source?: PointLightSnapshot | SpotLightSnapshot | RectAreaDirectLightSnapshot;
+}
+
+export interface StandardLightFrame {
+  readonly directional: DirectionalLightSnapshot | undefined;
+  readonly local: readonly StandardLocalLightInput[];
+  readonly view: Mat4;
+  readonly projection: Mat4;
+  readonly near: number;
+  readonly far: number;
+  readonly grid: { readonly x: number; readonly y: number; readonly z: number };
+  readonly lightCount: StandardLightCount;
+  /** Graph path carried into inspection from the active Standard profile. */
+  readonly renderPath: 'forward' | 'deferred';
+}

package/src/pipeline/standard-lighting/membership.ts

@@ -0,0 +1,43 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { bin, type ClusterBinScratch, createClusterBinScratch } from '../../cluster-binner';
+import type { RenderError } from '../../errors/render';
+import { fromClusterBinError } from './errors';
+import type { StandardClusterLayout } from './layout';
+import type { StandardLightFrame } from './light-frame';
+
+export interface StandardClusterMembership {
+  readonly clusterGrid: Uint32Array;
+  readonly lightIndexList: Uint32Array;
+  readonly lightBounds: Int32Array;
+  readonly membershipEntryCount: number;
+  readonly scratch: ClusterBinScratch;
+}
+
+export function deriveStandardMembership(
+  frame: StandardLightFrame,
+  layout: StandardClusterLayout,
+  scratch = createClusterBinScratch(),
+): Result<StandardClusterMembership, RenderError> {
+  const clusterGrid = new Uint32Array(layout.clusterGridU32Length);
+  const lightIndexList = new Uint32Array(layout.lightIndexListCapacity);
+  const result = bin(
+    frame.local,
+    frame.view,
+    frame.projection,
+    layout.grid,
+    frame.near,
+    frame.far,
+    clusterGrid,
+    lightIndexList,
+    layout.lightIndexListCapacity,
+    scratch,
+  );
+  if (!result.ok) return err(fromClusterBinError(result.error));
+  return ok({
+    clusterGrid,
+    lightIndexList,
+    lightBounds: scratch.lightBounds.slice(0, frame.local.length * 6),
+    membershipEntryCount: result.value,
+    scratch,
+  });
+}

package/src/pipeline/standard-lighting/prepare.ts

@@ -0,0 +1,37 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { type RenderError, StandardLightBudgetExceededError } from '../../errors/render';
+import { MAX_LIGHTS } from '../standard-profile';
+import { createStandardClusterLayout, type StandardClusterLayout } from './layout';
+import type { StandardLightFrame } from './light-frame';
+import { deriveStandardMembership, type StandardClusterMembership } from './membership';
+
+export type { StandardLightFrame } from './light-frame';
+
+export interface PreparedStandardLighting extends StandardClusterMembership {
+  readonly directional: StandardLightFrame['directional'];
+  readonly local: StandardLightFrame['local'];
+  readonly layout: StandardClusterLayout;
+  readonly membershipLightCount: number;
+  readonly renderPath: NonNullable<StandardLightFrame['renderPath']>;
+  readonly maxLights: StandardLightFrame['lightCount'];
+}
+
+export function prepareStandardLighting(
+  frame: StandardLightFrame,
+): Result<PreparedStandardLighting, RenderError> {
+  if (frame.local.length > frame.lightCount || frame.local.length > MAX_LIGHTS) {
+    return err(new StandardLightBudgetExceededError(frame.local.length, frame.lightCount));
+  }
+  const layout = createStandardClusterLayout(frame.grid);
+  const membership = deriveStandardMembership(frame, layout);
+  if (!membership.ok) return membership;
+  return ok({
+    ...membership.value,
+    directional: frame.directional,
+    local: frame.local,
+    layout,
+    membershipLightCount: frame.local.length,
+    renderPath: frame.renderPath,
+    maxLights: frame.lightCount,
+  });
+}