@forgeax/engine-render 0.1.19 → 0.1.21

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

@@ -34,6 +34,13 @@ import {
   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(
@@ -47,6 +54,7 @@ function target(
 function buildUrp(
   context: RenderPipelineBuildContext<RenderPipelineFrame>,
   topology: RenderPipelineTopology,
+  lighting: StandardTopologyInputValue,
 ): ReturnType<RenderPipeline['build']> {
   const graph = context.graph;
   const surface = importRenderPipelineSurface(graph, topology);
@@ -59,16 +67,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,
@@ -87,7 +93,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,
@@ -125,6 +138,16 @@ function buildUrp(
   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({
@@ -143,22 +166,23 @@ 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]),
     ],
-    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 }),
   });
   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,
@@ -190,6 +214,7 @@ function buildUrp(
     const producer = addStandardSceneDataPass(graph, temporal.value.temporal, depth.value);
     if (!producer.ok) return producer;
   }
+
   const transmission = addTransmissionBackdropPasses({
     graph,
     source: sceneResolved.value,
@@ -206,7 +231,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]),
       ],
@@ -216,6 +241,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.
@@ -229,7 +255,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]),
       ],
@@ -239,14 +265,34 @@ function buildUrp(
       colorLoadOp: 'load',
       depthLoadOp: 'load',
       recordMode: 'transparent',
+      extraAccesses: clusterReads,
     });
     if (!transparentPass.ok) return transparentPass;
     const temporal = addTransmissionBackdropTemporalPass(graph, sceneResolved.value);
     if (!temporal.ok) return temporal;
   }
 
+  if (topology.volumetricFog?.enabled === true) {
+    const depthSample = graph.view(depth.value.texture, {
+      label: 'scene-depth.sample',
+      dimension: '2d',
+      aspect: 'depth-only',
+    });
+    if (!depthSample.ok) return depthSample;
+    const volume = addAuthoredVolumetricFogPasses(
+      graph,
+      topology,
+      sceneResolved.value,
+      depthSample.value,
+      shadows.value.directional?.view,
+      shadows.value.spot.view,
+    );
+    if (!volume.ok) return volume;
+  }
+
   const features = context.contributeFeatures([
     {
+      name: 'linear-hdr',
       kind: 'scene-color',
       texture: scene.value.texture,
       view: scene.value.view,
@@ -273,7 +319,7 @@ function buildUrp(
     if (!observation.ok) return observation;
   }
 
-  return addStandardPost(
+  const post = addStandardPost(
     context,
     topology,
     sceneResolved.value,
@@ -281,6 +327,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,157 @@
+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 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 * 64, 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,34 @@
+import type { Mat4, Vec3 } from '@forgeax/engine-math';
+import type {
+  DirectionalLightSnapshot,
+  PointLightSnapshot,
+  SpotLightSnapshot,
+} from '../../render-system-extract';
+import type { StandardLightCount } from '../standard-profile';
+
+export interface StandardLocalLightInput {
+  readonly kind: 'point' | 'spot';
+  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;
+}
+
+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,
+  });
+}