@forgeax/engine-render 0.1.20 → 0.1.21

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,
+  });
+}

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

@@ -0,0 +1,120 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { PreparedStandardLighting } from './prepare';
+import type { StandardClusterTransport } from './transport';
+
+/** A prepared frame with no local lights on a non-storage direct backend. */
+export interface StandardNoLocalTopologyInput {
+  readonly kind: 'no-local-lights';
+  readonly prepared: PreparedStandardLighting;
+}
+
+/** A prepared frame whose Standard surface uses one proven Cluster transport. */
+export interface StandardClusteredTopologyInput {
+  readonly kind: 'clustered';
+  readonly prepared: PreparedStandardLighting;
+  readonly transport: StandardClusterTransport;
+}
+
+/**
+ * The only lighting value accepted by a Standard topology adapter. It is a
+ * projection of one prepared frame, not a second light/config/capability
+ * input. Both Forward and Deferred keep the same object identity for a frame.
+ */
+export type StandardTopologyInput = StandardNoLocalTopologyInput | StandardClusteredTopologyInput;
+
+export type StandardTopologyInputValue = StandardTopologyInput;
+
+/**
+ * Stable identity for the graph-facing Standard lighting declaration.
+ *
+ * The prepared light payload itself is frame-local and must never be retained
+ * by a compiled graph. These are the only facts that affect the Cluster graph
+ * shape and persistent buffer contract, so the record owner can reject an old
+ * graph before uploading a payload derived from a different declaration.
+ */
+export function standardLightingTopologySignature(
+  input: StandardTopologyInputValue | undefined,
+): string {
+  if (input === undefined) return 'missing';
+  if (input.kind === 'no-local-lights') return 'no-local-lights';
+  return JSON.stringify({
+    kind: input.kind,
+    transport: input.transport.kind,
+    producer: input.transport.producer,
+    grid: input.prepared.layout.grid,
+    clusterGridU32Length: input.prepared.layout.clusterGridU32Length,
+    lightIndexListCapacity: input.prepared.layout.lightIndexListCapacity,
+    lightDataSlotCount: input.prepared.layout.lightDataSlotCount,
+    lightBoundsInt32Length: input.prepared.layout.lightBoundsInt32Length,
+  });
+}
+
+export interface StandardTopologyInputError {
+  readonly code: 'topology-input-invalid';
+  readonly expected: 'prepared Standard lighting topology input';
+  readonly hint: 'derive topology from prepared Standard lighting';
+  readonly detail: {
+    readonly field: 'kind' | 'prepared' | 'transport' | 'lights' | 'capabilities';
+  };
+}
+
+function invalid(
+  field: StandardTopologyInputError['detail']['field'],
+): Result<never, StandardTopologyInputError> {
+  return err({
+    code: 'topology-input-invalid',
+    expected: 'prepared Standard lighting topology input',
+    hint: 'derive topology from prepared Standard lighting',
+    detail: { field },
+  });
+}
+
+/**
+ * Validate that transport and prepared membership are the same derivation.
+ * The identity checks make it impossible for an adapter to silently combine
+ * one path's layout/counts with another path's prepared light corpus.
+ */
+export function deriveStandardTopologyInput(
+  input: StandardTopologyInput,
+): Result<StandardTopologyInputValue, StandardTopologyInputError> {
+  const candidate = input as StandardTopologyInput & {
+    readonly kind?: unknown;
+    readonly lights?: unknown;
+    readonly capabilities?: unknown;
+    readonly transport?: unknown;
+  };
+  if ('lights' in candidate) return invalid('lights');
+  if ('capabilities' in candidate) return invalid('capabilities');
+  if (input === null || typeof input !== 'object') return invalid('kind');
+  if (input.prepared === null || typeof input.prepared !== 'object') {
+    return invalid('prepared');
+  }
+
+  const prepared = input.prepared;
+  if (input.kind === 'no-local-lights') {
+    if (prepared.local.length !== 0 || 'transport' in candidate) return invalid('transport');
+    return ok(input);
+  }
+  if (input.kind !== 'clustered') return invalid('kind');
+  if (
+    !('transport' in candidate) ||
+    candidate.transport === null ||
+    typeof candidate.transport !== 'object'
+  ) {
+    return invalid('transport');
+  }
+
+  const transport = input.transport;
+  const requested = prepared.local.length;
+  const transportMatchesPrepared =
+    transport.layout === prepared.layout &&
+    transport.requestedLightCount === requested &&
+    transport.admittedLightCount === requested &&
+    transport.membershipEntryCount === prepared.membershipEntryCount &&
+    transport.lightBoundsBytes === prepared.lightBounds.byteLength;
+  const producerMatchesKind =
+    (transport.producer === 'gpu' && transport.kind === 'compute-storage') ||
+    (transport.producer === 'cpu' && transport.kind === 'cpu-storage');
+  if (!transportMatchesPrepared || !producerMatchesKind) return invalid('transport');
+  return ok(input);
+}

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

@@ -0,0 +1,77 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { type RenderError, StandardClusterTransportUnavailableError } from '../../errors/render';
+import type { PreparedStandardLighting } from './prepare';
+
+export interface StandardClusterCapabilities {
+  readonly compute: boolean;
+  readonly storageBuffer: boolean;
+  /**
+   * The graph producer is ready to encode the selected compute lane. The
+   * renderer supplies this from the actual pipeline + bind-group layout; it is
+   * required so capability admission cannot forge a GPU producer from
+   * `compute` alone.
+   */
+  readonly membershipPipelineReady: boolean;
+}
+
+/** Only transports with storage-backed membership representation exist. */
+export type StandardClusterTransportKind = 'compute-storage' | 'cpu-storage';
+export type StandardClusterMembershipProducer = 'cpu' | 'gpu';
+
+export interface StandardClusterTransport {
+  readonly kind: StandardClusterTransportKind;
+  readonly producer: StandardClusterMembershipProducer;
+  readonly layout: PreparedStandardLighting['layout'];
+  readonly requestedLightCount: number;
+  readonly admittedLightCount: number;
+  readonly membershipEntryCount: number;
+  readonly occupiedClusterCount: number;
+  readonly clusterGridBytes: number;
+  readonly lightIndexListBytes: number;
+  readonly lightDataBytes: number;
+  readonly lightBoundsBytes: number;
+}
+
+function occupiedClusterCount(prepared: PreparedStandardLighting): number {
+  let occupied = 0;
+  for (let index = 1; index < prepared.clusterGrid.length; index += 2) {
+    if ((prepared.clusterGrid[index] ?? 0) > 0) occupied += 1;
+  }
+  return occupied;
+}
+
+/**
+ * Select a transport from one prepared frame. Capability facts choose only a
+ * producer/storage pair; all counts and byte sizes come from that frame.
+ */
+export function selectStandardClusterTransport(
+  capabilities: StandardClusterCapabilities,
+  prepared: PreparedStandardLighting,
+): Result<StandardClusterTransport, RenderError> {
+  const requested = prepared.local.length;
+  if (!capabilities.storageBuffer) {
+    return err(
+      new StandardClusterTransportUnavailableError(
+        requested,
+        'enable a proven storage-buffer Cluster transport; compute without storage is not a membership path',
+      ),
+    );
+  }
+
+  const producer: StandardClusterMembershipProducer =
+    capabilities.compute && capabilities.membershipPipelineReady ? 'gpu' : 'cpu';
+  const kind: StandardClusterTransportKind = producer === 'gpu' ? 'compute-storage' : 'cpu-storage';
+  return ok({
+    kind,
+    producer,
+    layout: prepared.layout,
+    requestedLightCount: requested,
+    admittedLightCount: requested,
+    membershipEntryCount: prepared.membershipEntryCount,
+    occupiedClusterCount: occupiedClusterCount(prepared),
+    clusterGridBytes: prepared.layout.clusterGridU32Length * Uint32Array.BYTES_PER_ELEMENT,
+    lightIndexListBytes: prepared.membershipEntryCount * Uint32Array.BYTES_PER_ELEMENT,
+    lightDataBytes: requested * 64,
+    lightBoundsBytes: prepared.lightBounds.byteLength,
+  });
+}