@forgeax/engine-render 0.1.28 → 0.1.30

package/src/gpu-driven/shadow-views.ts

@@ -0,0 +1,539 @@
+import {
+  type GraphAccess,
+  type GraphResourceResolver,
+  type RenderGraphBuilder,
+  RenderGraphError,
+  type RenderGraphFrame,
+} from '@forgeax/engine-render-graph';
+import type { Result, RhiDevice, RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import { err, ok, RhiError } from '@forgeax/engine-rhi';
+import type { GpuScene } from '../gpu-scene';
+import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
+import {
+  buildBatchAlignedSubmission,
+  buildSubmissionCandidateMembership,
+  type GpuDrivenCandidate,
+  type SubmissionPlan,
+} from './batch-topology';
+import { GpuDrivenView, type GpuDrivenViewGraphResources } from './view-gpu';
+
+export type ShadowViewKind = 'directional' | 'point' | 'spot';
+
+export interface ShadowViewIdentity {
+  readonly kind: ShadowViewKind;
+  readonly index: number;
+  /** Optional point-light index when `index` identifies the cube face. */
+  readonly face?: number;
+}
+
+export type ShadowViewCacheState = 'hit' | 'invalidated';
+
+export interface ShadowViewUpdateInput {
+  readonly identity: ShadowViewIdentity;
+  readonly sourcePlan: SubmissionPlan;
+  readonly scene: GpuScene;
+  readonly planes: Float32Array;
+  readonly cacheToken?: string;
+  readonly candidatePrimitiveIndices?: readonly number[] | ReadonlySet<number>;
+}
+
+export interface ShadowViewUpdate {
+  readonly identity: ShadowViewIdentity;
+  readonly cache: ShadowViewCacheState;
+  readonly generation: number;
+  readonly sourcePlan: SubmissionPlan;
+  readonly plan: SubmissionPlan;
+  readonly view: GpuDrivenView;
+}
+
+export interface ShadowViewProjection {
+  readonly identity: ShadowViewIdentity;
+  readonly cache: ShadowViewCacheState;
+  readonly generation: number;
+  readonly plan: SubmissionPlan;
+  readonly view: GpuDrivenView;
+  readonly passNames: readonly string[];
+  readonly graphResources: GpuDrivenViewGraphResources | undefined;
+}
+
+export interface ShadowViewSubmission {
+  readonly identity: ShadowViewIdentity;
+  readonly cache: ShadowViewCacheState;
+  readonly generation: number;
+  readonly plan: SubmissionPlan;
+  readonly view: GpuDrivenView;
+}
+
+/**
+ * The only record-side hook a capable shadow lane needs after the shared
+ * groups are bound.  The callback owns material/mesh binding policy and emits
+ * the indirect draws for this view; it receives the pool projection rather
+ * than rebuilding a candidate list from the frame.
+ */
+export interface ShadowViewGpuRecordInput {
+  readonly identity: ShadowViewIdentity;
+  readonly projection: ShadowViewProjection;
+  readonly pass: RhiRenderPassEncoder;
+  readonly resources: GraphResourceResolver;
+}
+
+export type ShadowViewGpuRecorder = (input: ShadowViewGpuRecordInput) => void;
+
+export interface ShadowViewGpuPass {
+  readonly projection: ShadowViewProjection;
+  readonly resources: GraphResourceResolver;
+  readonly record: ShadowViewGpuRecorder;
+}
+
+export interface ShadowViewInspection {
+  readonly identity: ShadowViewIdentity;
+  readonly cache: ShadowViewCacheState;
+  readonly generation: number;
+  readonly sourceRevision: number;
+  readonly candidateCount: number;
+  readonly batchCount: number;
+  readonly resourceGeneration: number;
+}
+
+interface SceneBuffers {
+  readonly primitive: GpuScene['primitiveBuffer'];
+  readonly instance: GpuScene['instanceBuffer'];
+  readonly transform: GpuScene['transformBuffer'];
+  readonly material: GpuScene['materialBuffer'];
+}
+
+interface ShadowViewRecord {
+  readonly identity: ShadowViewIdentity;
+  readonly view: GpuDrivenView;
+  sourcePlan: SubmissionPlan;
+  plan: SubmissionPlan;
+  scene: GpuScene;
+  cacheToken: string;
+  contentRevision: number;
+  planes: Float32Array;
+  candidateSignature: string;
+  generation: number;
+  cache: ShadowViewCacheState;
+  invalidated: boolean;
+  published: boolean;
+  resourceGeneration: number;
+  sceneBuffers: SceneBuffers;
+}
+
+function identityKey(identity: ShadowViewIdentity): string {
+  return `${identity.kind}:${identity.index}:${identity.face ?? ''}`;
+}
+
+export function shadowViewIdentityKey(identity: ShadowViewIdentity): string {
+  return identityKey(identity);
+}
+
+function validateIdentity(identity: ShadowViewIdentity): RhiError | undefined {
+  if (!Number.isInteger(identity.index) || identity.index < 0) {
+    return new RhiError({
+      code: 'internal-error',
+      expected: 'shadow view index is a non-negative integer',
+      hint: 'publish a stable directional cascade, point face, or spot atlas index',
+    });
+  }
+  if (
+    identity.face !== undefined &&
+    (!Number.isInteger(identity.face) || identity.face < 0 || identity.face > 5)
+  ) {
+    return new RhiError({
+      code: 'internal-error',
+      expected: 'point shadow face is an integer from 0 through 5',
+      hint: 'publish a valid cube face for the point shadow view',
+    });
+  }
+  return undefined;
+}
+
+function copyPlanes(planes: Float32Array): Result<Float32Array, RhiError> {
+  if (planes.length < 24) {
+    return err(
+      new RhiError({
+        code: 'internal-error',
+        expected: 'shadow view publishes six clipping planes',
+        hint: 'provide a 24-float frustum plane array before updating the view',
+      }),
+    );
+  }
+  return ok(new Float32Array(planes.subarray(0, 24)));
+}
+
+function samePlanes(left: Float32Array, right: Float32Array): boolean {
+  if (left.length !== right.length) return false;
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) return false;
+  }
+  return true;
+}
+
+function sceneBuffers(scene: GpuScene): SceneBuffers {
+  return {
+    primitive: scene.primitiveBuffer,
+    instance: scene.instanceBuffer,
+    transform: scene.transformBuffer,
+    material: scene.materialBuffer,
+  };
+}
+
+function sameSceneBuffers(left: SceneBuffers, right: SceneBuffers): boolean {
+  return (
+    left.primitive === right.primitive &&
+    left.instance === right.instance &&
+    left.transform === right.transform &&
+    left.material === right.material
+  );
+}
+
+function candidateIndices(
+  values: readonly number[] | ReadonlySet<number> | undefined,
+): Result<readonly number[] | undefined, RhiError> {
+  if (values === undefined) return ok(undefined);
+  const entries = Array.from(values);
+  for (const entry of entries) {
+    if (!Number.isInteger(entry) || entry < 0) {
+      return err(
+        new RhiError({
+          code: 'internal-error',
+          expected: 'shadow candidate primitive indices are non-negative integers',
+          hint: 'derive ShadowCaster membership from the shared BatchTopology channel index',
+        }),
+      );
+    }
+  }
+  return ok(Object.freeze([...new Set(entries)].sort((left, right) => left - right)));
+}
+
+function projectPlan(
+  source: SubmissionPlan,
+  primitiveIndices: readonly number[] | undefined,
+): SubmissionPlan {
+  if (primitiveIndices === undefined) return source;
+  const membership = buildSubmissionCandidateMembership(source);
+  const candidatesByBatch = new Map<number, GpuDrivenCandidate[]>();
+  for (const primitiveIndex of primitiveIndices) {
+    for (const entry of membership.byPrimitiveIndex.get(primitiveIndex) ?? []) {
+      const candidates = candidatesByBatch.get(entry.batchId) ?? [];
+      candidates.push(entry.candidate);
+      candidatesByBatch.set(entry.batchId, candidates);
+    }
+  }
+  const immutableCandidates = new Map<number, readonly GpuDrivenCandidate[]>();
+  for (const [batchId, candidates] of candidatesByBatch) {
+    immutableCandidates.set(batchId, Object.freeze(candidates));
+  }
+  return buildBatchAlignedSubmission(source, immutableCandidates);
+}
+
+function candidateSignature(primitiveIndices: readonly number[] | undefined): string {
+  return primitiveIndices === undefined ? '*' : primitiveIndices.join(',');
+}
+
+export function shadowViewLabelPrefix(identity: ShadowViewIdentity): string {
+  switch (identity.kind) {
+    case 'directional':
+      return `gpu-driven.shadow.directional-cascade-${identity.index}`;
+    case 'point':
+      return `gpu-driven.shadow.point-cube-face-${identity.index}${
+        identity.face === undefined ? '' : `-${identity.face}`
+      }`;
+    case 'spot':
+      return `gpu-driven.shadow.spot-atlas-${identity.index}`;
+  }
+}
+
+/**
+ * Accesses consumed by a shadow raster adapter.  These are the same imported
+ * scene and view-local resources written by GpuDrivenView.addPasses(...), so
+ * the graph inserts the compute-to-raster dependency without a second graph
+ * or a manual barrier owner.
+ */
+export function shadowViewRasterAccesses(
+  resources: GpuDrivenViewGraphResources,
+): readonly GraphAccess[] {
+  return Object.freeze([
+    { resource: resources.primitive, usage: 'storage-read' },
+    { resource: resources.instance, usage: 'storage-read' },
+    { resource: resources.transform, usage: 'storage-read' },
+    { resource: resources.material, usage: 'storage-read' },
+    { resource: resources.visible, usage: 'storage-read' },
+    { resource: resources.indirect, usage: 'indirect-read' },
+  ] satisfies GraphAccess[]);
+}
+
+function passNames(identity: ShadowViewIdentity): readonly string[] {
+  const prefix = shadowViewLabelPrefix(identity);
+  return Object.freeze([
+    `${prefix}.view-reset`,
+    `${prefix}.frustum-compact`,
+    `${prefix}.finalize-indirect`,
+  ]);
+}
+
+function graphStateError(identity: ShadowViewIdentity): RenderGraphError {
+  return new RenderGraphError({
+    code: 'resource-descriptor-invalid',
+    expected: 'ShadowViewStatePool.update(...) precedes project(...)',
+    hint: 'publish the shared scene, topology channel, and view planes before graph projection',
+    detail: {
+      resourceLabel: identityKey(identity),
+      field: 'state',
+      expected: 'updated',
+      actual: 'not-updated',
+    },
+  });
+}
+
+/**
+ * Renderer-owned shadow view state. The pool shares one scene/topology source;
+ * each directional, point, or spot entry owns only view constants, visibility,
+ * counters, indirect arguments, and its cache decision.
+ */
+export class ShadowViewStatePool {
+  private readonly records = new Map<string, ShadowViewRecord>();
+  private readonly activeKeys = new Set<string>();
+  private readonly retiring = new Map<string, ShadowViewRecord>();
+  private readonly pendingPublication = new Set<string>();
+
+  private constructor(
+    private readonly device: RhiDevice,
+    private readonly shaderModuleFactory: PipelineBuilderShaderModuleFactory,
+  ) {}
+
+  static create(input: {
+    readonly device: RhiDevice;
+    readonly shaderModuleFactory: PipelineBuilderShaderModuleFactory;
+  }): Result<ShadowViewStatePool, RhiError> {
+    return ok(new ShadowViewStatePool(input.device, input.shaderModuleFactory));
+  }
+
+  update(input: ShadowViewUpdateInput): Result<ShadowViewUpdate, RhiError> {
+    const identityError = validateIdentity(input.identity);
+    if (identityError !== undefined) return err(identityError);
+    const planes = copyPlanes(input.planes);
+    if (!planes.ok) return planes;
+    const indices = candidateIndices(input.candidatePrimitiveIndices);
+    if (!indices.ok) return indices;
+    const key = identityKey(input.identity);
+    this.activeKeys.add(key);
+    this.retiring.delete(key);
+    const previous = this.records.get(key);
+    const token = input.cacheToken ?? '';
+    const contentRevision = input.scene.contentRevision;
+    const signature = candidateSignature(indices.value);
+    const currentSceneBuffers = sceneBuffers(input.scene);
+    const cacheHit =
+      previous !== undefined &&
+      !previous.invalidated &&
+      previous.sourcePlan === input.sourcePlan &&
+      previous.scene === input.scene &&
+      previous.published &&
+      previous.cacheToken === token &&
+      previous.contentRevision === contentRevision &&
+      previous.candidateSignature === signature &&
+      samePlanes(previous.planes, planes.value) &&
+      sameSceneBuffers(previous.sceneBuffers, currentSceneBuffers) &&
+      previous.resourceGeneration === previous.view.inspect().resourceGeneration;
+    if (cacheHit && previous !== undefined) {
+      previous.cache = 'hit';
+      return ok({
+        identity: previous.identity,
+        cache: 'hit',
+        generation: previous.generation,
+        sourcePlan: previous.sourcePlan,
+        plan: previous.plan,
+        view: previous.view,
+      });
+    }
+
+    const selectedPlan = projectPlan(input.sourcePlan, indices.value);
+    let view = previous?.view;
+    if (view === undefined) {
+      const created = GpuDrivenView.create({
+        device: this.device,
+        shaderModuleFactory: this.shaderModuleFactory,
+        labelPrefix: `${shadowViewLabelPrefix(input.identity)}.view`,
+      });
+      if (!created.ok) return created;
+      view = created.value;
+    }
+    const updated = view.update(selectedPlan, input.scene, planes.value);
+    if (!updated.ok) return updated;
+    const generation = (previous?.generation ?? 0) + 1;
+    const record: ShadowViewRecord = {
+      identity: Object.freeze({ ...input.identity }),
+      view,
+      sourcePlan: input.sourcePlan,
+      plan: selectedPlan,
+      scene: input.scene,
+      cacheToken: token,
+      contentRevision,
+      planes: planes.value,
+      candidateSignature: signature,
+      generation,
+      cache: 'invalidated',
+      invalidated: false,
+      published: false,
+      resourceGeneration: view.inspect().resourceGeneration,
+      sceneBuffers: currentSceneBuffers,
+    };
+    this.records.set(key, record);
+    this.pendingPublication.add(key);
+    return ok({
+      identity: record.identity,
+      cache: 'invalidated',
+      generation,
+      sourcePlan: record.sourcePlan,
+      plan: record.plan,
+      view: record.view,
+    });
+  }
+
+  project<FrameCtx extends RenderGraphFrame>(
+    builder: RenderGraphBuilder<FrameCtx>,
+    identity: ShadowViewIdentity,
+  ): Result<ShadowViewProjection, RenderGraphError> {
+    const record = this.records.get(identityKey(identity));
+    if (record === undefined) return err(graphStateError(identity));
+    const cacheHit = record.cache === 'hit' && !record.invalidated;
+    const projected = record.view.addPasses(
+      builder,
+      shadowViewLabelPrefix(record.identity),
+      !cacheHit,
+    );
+    if (!projected.ok) return projected;
+    return ok({
+      identity: record.identity,
+      cache: cacheHit ? 'hit' : 'invalidated',
+      generation: record.generation,
+      plan: record.plan,
+      view: record.view,
+      passNames: cacheHit ? Object.freeze([]) : passNames(record.identity),
+      graphResources: projected.value,
+    });
+  }
+
+  invalidate(identity?: ShadowViewIdentity): void {
+    if (identity === undefined) {
+      for (const record of this.records.values()) {
+        record.invalidated = true;
+        record.cache = 'invalidated';
+      }
+      return;
+    }
+    const record = this.records.get(identityKey(identity));
+    if (record !== undefined) {
+      record.invalidated = true;
+      record.cache = 'invalidated';
+    }
+  }
+
+  cacheState(identity: ShadowViewIdentity): ShadowViewCacheState | undefined {
+    const record = this.records.get(identityKey(identity));
+    if (record === undefined) return undefined;
+    return record.invalidated ? 'invalidated' : record.cache;
+  }
+
+  cacheHit(identity: ShadowViewIdentity): boolean {
+    return this.activeKeys.has(identityKey(identity)) && this.cacheState(identity) === 'hit';
+  }
+
+  isActive(identity: ShadowViewIdentity): boolean {
+    return this.activeKeys.has(identityKey(identity));
+  }
+
+  submission(identity: ShadowViewIdentity): ShadowViewSubmission | undefined {
+    const key = identityKey(identity);
+    if (!this.activeKeys.has(key)) return undefined;
+    const record = this.records.get(key);
+    if (record === undefined) return undefined;
+    return {
+      identity: record.identity,
+      cache: record.cache,
+      generation: record.generation,
+      plan: record.plan,
+      view: record.view,
+    };
+  }
+
+  /**
+   * Keep only the active view identities for the current frame. Removed light
+   * views are disposed through their own queue-fenced resource owner instead
+   * of remaining in inspection or changing the compiled topology forever.
+   */
+  retain(identities: readonly ShadowViewIdentity[]): void {
+    const active = new Set(identities.map(identityKey));
+    for (const [key, record] of this.records) {
+      if (active.has(key)) continue;
+      this.activeKeys.delete(key);
+      this.retiring.set(key, record);
+    }
+  }
+
+  /** @internal Commit every view resource replacement after a successful submit. */
+  _commitResourceReplacement(): void {
+    for (const record of this.records.values()) record.view._commitResourceReplacement();
+    for (const key of this.pendingPublication) {
+      const record = this.records.get(key);
+      if (record !== undefined) record.published = true;
+    }
+    this.pendingPublication.clear();
+    for (const [key, record] of this.retiring) {
+      record.view.dispose();
+      this.records.delete(key);
+      this.retiring.delete(key);
+    }
+  }
+
+  /**
+   * Abort a staged frame before its queue submit barrier. A candidate view
+   * must not become a cache hit merely because graph encoding succeeded: the
+   * next frame has to rebuild it after any submit/finish failure.
+   */
+  _abortResourceReplacement(): void {
+    for (const key of this.pendingPublication) {
+      const record = this.records.get(key);
+      if (record === undefined) continue;
+      record.published = false;
+      record.invalidated = true;
+      record.cache = 'invalidated';
+    }
+    this.pendingPublication.clear();
+  }
+
+  inspect(): readonly ShadowViewInspection[] {
+    return Object.freeze(
+      [...this.records.values()]
+        .filter((record) => this.activeKeys.has(identityKey(record.identity)))
+        .sort((left, right) =>
+          identityKey(left.identity).localeCompare(identityKey(right.identity)),
+        )
+        .map((record) => {
+          const view = record.view.inspect();
+          return Object.freeze({
+            identity: record.identity,
+            cache: record.cache,
+            generation: record.generation,
+            sourceRevision: record.sourcePlan.revision,
+            candidateCount: record.plan.candidateCount,
+            batchCount: record.plan.batches.length,
+            resourceGeneration: view.resourceGeneration,
+          });
+        }),
+    );
+  }
+
+  dispose(): void {
+    const views = new Set([...this.records.values()].map((record) => record.view));
+    for (const view of views) view.dispose();
+    this.records.clear();
+    this.activeKeys.clear();
+    this.retiring.clear();
+    this.pendingPublication.clear();
+  }
+}
+
+export { ShadowViewStatePool as GpuDrivenShadowViewPool };