@forgeax/engine-render 0.1.2

package/src/gpu-driven/batch-topology.ts

@@ -0,0 +1,423 @@
+import { RenderQueue } from '@forgeax/engine-types';
+import { isStandardPbrMaterialShader } from '../pbr-pipeline';
+import type { RenderSceneApplyResult, RenderSceneProjectionSlot } from '../render-scene-projection';
+import type {
+  GpuDrivenDrawSnapshot,
+  MaterialSnapshot,
+  RenderableSnapshot,
+} from '../render-system-extract';
+
+export interface GpuDrivenBatchKey {
+  readonly assetHandle: number;
+  readonly drawKind: 'indexed' | 'non-indexed';
+  readonly first: number;
+  readonly count: number;
+  readonly baseVertex: number;
+  readonly materialSlot: number;
+  readonly submeshIndex: number;
+  readonly passIndex: number;
+  readonly queue: number;
+  readonly topology: string;
+  readonly pipelineClass: string;
+  readonly materialResourceClass: string;
+  /** Material shader identity is part of topology, not a record-time guess. */
+  readonly materialClass: string;
+  /** Scene Fact resource revision invalidates stale resource bindings. */
+  readonly resourceRevision: number;
+  /** Scene Fact material revision keeps material payload changes isolated. */
+  readonly materialRevision: number;
+  /** Explicit alpha-test qualification (queue or alphaCutoff > 0). */
+  readonly alphaTest: boolean;
+  /** `true` means the raster state intentionally keeps both faces. */
+  readonly doubleSided: boolean;
+  /** Standard/custom PBR qualification used by the capability lane. */
+  readonly pbr: boolean;
+  /**
+   * ShadowCaster batch qualification; only explicit ineligible excludes a
+   * candidate. Unknown facts stay in the pool until the existing ShadowCaster
+   * dispatch and CascadeVolumeSet membership make the per-view decision.
+   */
+  readonly shadowCaster: boolean;
+}
+
+export interface GpuDrivenBatchSemantics {
+  readonly pipelineClass: string;
+  readonly materialClass: string;
+  readonly materialResourceClass: string;
+  readonly resourceRevision: number;
+  readonly materialRevision: number;
+  readonly alphaTest: boolean;
+  readonly doubleSided: boolean;
+  readonly pbr: boolean;
+  readonly shadowCaster: boolean;
+}
+
+export interface GpuDrivenCandidate {
+  readonly primitiveIndex: number;
+  readonly generation: number;
+  readonly drawItemIndex: number;
+  readonly instanceOrdinal: number;
+}
+
+export interface GpuDrivenBatch {
+  readonly batchId: number;
+  readonly generation: number;
+  readonly key: GpuDrivenBatchKey;
+  readonly candidates: readonly GpuDrivenCandidate[];
+  readonly visibleBase: number;
+  readonly visibleCapacity: number;
+  readonly indirectOffset: number;
+}
+
+export interface SubmissionPlan {
+  readonly revision: number;
+  readonly batches: readonly GpuDrivenBatch[];
+  readonly candidateCount: number;
+  readonly visibleCapacity: number;
+}
+
+export interface SubmissionCandidateMembershipEntry {
+  readonly batchId: number;
+  readonly candidate: GpuDrivenCandidate;
+}
+
+/**
+ * Immutable reverse membership for one submission topology.
+ *
+ * Candidate-domain owners publish stable primitive ids, while both the
+ * shadow view projector and cascade-local cache tokens need to answer the
+ * inverse question: which source batches contain this primitive? Keep that
+ * join beside the immutable SubmissionPlan so each consumer pays O(D) once
+ * per topology instead of rescanning every batch for every view/cascade.
+ */
+export interface SubmissionCandidateMembership {
+  readonly source: SubmissionPlan;
+  readonly byPrimitiveIndex: ReadonlyMap<number, readonly SubmissionCandidateMembershipEntry[]>;
+  /** O(1) lookup for batch metadata after a primitive-to-batch join. */
+  readonly byBatchId: ReadonlyMap<number, SubmissionPlan['batches'][number]>;
+}
+
+const submissionCandidateMembershipCache = new WeakMap<
+  SubmissionPlan,
+  SubmissionCandidateMembership
+>();
+
+export function buildSubmissionCandidateMembership(
+  source: SubmissionPlan,
+): SubmissionCandidateMembership {
+  const cached = submissionCandidateMembershipCache.get(source);
+  if (cached !== undefined) return cached;
+
+  const mutable = new Map<number, SubmissionCandidateMembershipEntry[]>();
+  const byBatchId = new Map<number, SubmissionPlan['batches'][number]>();
+  for (const batch of source.batches) {
+    byBatchId.set(batch.batchId, batch);
+    for (const candidate of batch.candidates) {
+      const entries = mutable.get(candidate.primitiveIndex) ?? [];
+      entries.push({ batchId: batch.batchId, candidate });
+      mutable.set(candidate.primitiveIndex, entries);
+    }
+  }
+  const byPrimitiveIndex = new Map<number, readonly SubmissionCandidateMembershipEntry[]>();
+  for (const [primitiveIndex, entries] of mutable) {
+    byPrimitiveIndex.set(primitiveIndex, Object.freeze(entries));
+  }
+  const membership: SubmissionCandidateMembership = {
+    source,
+    byPrimitiveIndex,
+    byBatchId,
+  };
+  submissionCandidateMembershipCache.set(source, membership);
+  return membership;
+}
+
+/**
+ * Build a submission while retaining the source topology identity.
+ *
+ * Visibility is allowed to replace candidates and capacities per view, but it
+ * must not allocate a second batch identity or change indirect slot ownership.
+ * This helper is shared by the forward and shadow capability lanes so compact
+ * arrays, aligned bases, and indirect offsets have one producer.
+ */
+export function buildBatchAlignedSubmission(
+  source: SubmissionPlan,
+  candidatesByBatch: ReadonlyMap<number, readonly GpuDrivenCandidate[]>,
+): SubmissionPlan {
+  let visibleBase = 0;
+  const batches: GpuDrivenBatch[] = [];
+  for (const sourceBatch of source.batches) {
+    const candidates = candidatesByBatch.get(sourceBatch.batchId) ?? [];
+    if (candidates.length === 0) continue;
+    visibleBase = alignInstanceBase(visibleBase);
+    batches.push(
+      Object.freeze({
+        ...sourceBatch,
+        candidates: Object.freeze([...candidates]),
+        visibleBase,
+        visibleCapacity: candidates.length,
+      }),
+    );
+    visibleBase += candidates.length;
+  }
+  return Object.freeze({
+    revision: source.revision,
+    batches: Object.freeze(batches),
+    candidateCount: batches.reduce((total, batch) => total + batch.candidates.length, 0),
+    visibleCapacity: visibleBase,
+  });
+}
+
+export interface BatchTopologyInspection {
+  readonly revision: number;
+  readonly batchCount: number;
+  readonly candidateCount: number;
+  readonly rebuilds: number;
+  readonly patches: number;
+  readonly ineligible: number;
+}
+
+interface MutableBatch {
+  readonly batchId: number;
+  readonly generation: number;
+  readonly key: GpuDrivenBatchKey;
+  readonly candidates: Map<string, GpuDrivenCandidate>;
+}
+
+function materialForDraw(
+  snapshot: RenderableSnapshot,
+  draw: GpuDrivenDrawSnapshot,
+): MaterialSnapshot {
+  return snapshot.materials[draw.materialSlot] ?? snapshot.material;
+}
+
+export function deriveGpuDrivenBatchSemantics(
+  snapshot: RenderableSnapshot,
+  draw: GpuDrivenDrawSnapshot,
+): GpuDrivenBatchSemantics {
+  const material = materialForDraw(snapshot, draw);
+  const cutoff = material.paramSnapshot?.alphaCutoff;
+  const alphaTest =
+    draw.queue === RenderQueue.AlphaTest || (typeof cutoff === 'number' && cutoff > 0);
+  const materialClass = material.materialShaderId ?? 'forgeax::default-unlit';
+  const pbr =
+    isStandardPbrMaterialShader(material.materialShaderId) ||
+    materialClass.toLowerCase().includes('pbr') ||
+    draw.pipelineClass.toLowerCase().includes('pbr');
+  return {
+    pipelineClass: draw.pipelineClass,
+    materialClass,
+    materialResourceClass: draw.materialResourceClass,
+    resourceRevision: snapshot.sceneFact?.revisions?.resource ?? 0,
+    materialRevision: snapshot.sceneFact?.revisions?.material ?? 0,
+    alphaTest,
+    doubleSided: material.renderState?.cullMode === 'none',
+    pbr,
+    // Material pass ownership is the authoritative per-slot caster fact. The
+    // scene fact remains a conservative fallback for older/test snapshots
+    // that predate the material projection field.
+    shadowCaster: material.shadowCaster ?? snapshot.sceneFact?.casterEligibility !== 'ineligible',
+  };
+}
+
+export function buildGpuDrivenBatchKey(
+  snapshot: RenderableSnapshot,
+  draw: GpuDrivenDrawSnapshot,
+): GpuDrivenBatchKey {
+  const semantics = deriveGpuDrivenBatchSemantics(snapshot, draw);
+  return {
+    assetHandle: snapshot.assetHandle,
+    drawKind: draw.kind,
+    first: draw.first,
+    count: draw.count,
+    baseVertex: draw.baseVertex,
+    materialSlot: draw.materialSlot,
+    submeshIndex: draw.submeshIndex,
+    passIndex: draw.passIndex,
+    queue: draw.queue,
+    topology: draw.topology,
+    ...semantics,
+  };
+}
+
+function eligibleKeys(slot: RenderSceneProjectionSlot): readonly GpuDrivenBatchKey[] {
+  const snapshot = slot.snapshot;
+  const draws = snapshot.gpuDrivenDraws;
+  // Batch topology is pass-agnostic. Rigid forward raster capability is
+  // decided by production-raster; excluding skin, sprites, or missing local
+  // bounds here would also remove valid ShadowCaster work from the shared
+  // indirect submission owner.
+  if (draws === undefined || draws.length === 0) return [];
+  return draws.map((draw) => buildGpuDrivenBatchKey(snapshot, draw));
+}
+
+function keyText(key: GpuDrivenBatchKey): string {
+  return JSON.stringify(key);
+}
+
+function alignInstanceBase(value: number): number {
+  // Raster binds each batch's visible-index and compact-transform segment at
+  // a static storage-buffer offset. WebGPU requires those offsets to satisfy
+  // minStorageBufferOffsetAlignment (256 bytes on the portable baseline), so
+  // both the u32 stream (64 entries) and mat4 stream (4 entries) align when
+  // the shared instance base is a multiple of 64.
+  return Math.ceil(value / 64) * 64;
+}
+
+/** Stable compatibility grouping; per-view visibility never mutates this owner. */
+export class BatchTopology {
+  private readonly batches = new Map<string, MutableBatch>();
+  private readonly membershipByPrimitive = new Map<
+    number,
+    readonly { readonly batchText: string; readonly candidateKey: string }[]
+  >();
+  private readonly ineligiblePrimitives = new Set<number>();
+  private readonly generationByBatchId: number[] = [];
+  private readonly freeBatchIds: number[] = [];
+  private revision = 0;
+  private rebuilds = 0;
+  private patches = 0;
+  private cachedPlan: SubmissionPlan | undefined;
+
+  rebuild(slots: readonly RenderSceneProjectionSlot[]): void {
+    this.batches.clear();
+    this.membershipByPrimitive.clear();
+    this.ineligiblePrimitives.clear();
+    this.generationByBatchId.length = 0;
+    this.freeBatchIds.length = 0;
+    for (const slot of slots) this.add(slot);
+    this.revision += 1;
+    this.rebuilds += 1;
+    this.cachedPlan = undefined;
+  }
+
+  apply(delta: RenderSceneApplyResult): boolean {
+    let changed = false;
+    for (const removed of delta.removedSlots) changed = this.remove(removed.slot) || changed;
+    for (const slot of delta.recreatedSlots) {
+      changed = this.remove(slot.slot) || changed;
+      changed = this.add(slot) || changed;
+    }
+    for (const slot of delta.updatedSlots) {
+      const instanceCount = slot.snapshot.instances?.instanceCount ?? 1;
+      const nextTexts = eligibleKeys(slot).flatMap((key) =>
+        Array.from({ length: instanceCount }, () => keyText(key)),
+      );
+      const current = this.membershipByPrimitive.get(slot.slot) ?? [];
+      if (
+        current.length === nextTexts.length &&
+        current.every((membership, index) => membership.batchText === nextTexts[index])
+      ) {
+        continue;
+      }
+      changed = this.remove(slot.slot) || changed;
+      changed = this.add(slot) || changed;
+    }
+    for (const slot of delta.createdSlots) changed = this.add(slot) || changed;
+    if (changed) {
+      this.revision += 1;
+      this.patches += 1;
+      this.cachedPlan = undefined;
+    }
+    return changed;
+  }
+
+  plan(): SubmissionPlan {
+    if (this.cachedPlan !== undefined) return this.cachedPlan;
+    const ordered = [...this.batches.values()].sort((left, right) => left.batchId - right.batchId);
+    let visibleBase = 0;
+    const batches = ordered.map((batch): GpuDrivenBatch => {
+      visibleBase = alignInstanceBase(visibleBase);
+      const candidates = [...batch.candidates.values()].sort(
+        (left, right) =>
+          left.primitiveIndex - right.primitiveIndex ||
+          left.drawItemIndex - right.drawItemIndex ||
+          left.instanceOrdinal - right.instanceOrdinal,
+      );
+      const result = {
+        batchId: batch.batchId,
+        generation: batch.generation,
+        key: batch.key,
+        candidates,
+        visibleBase,
+        visibleCapacity: candidates.length,
+        indirectOffset: batch.batchId * 20,
+      };
+      visibleBase += candidates.length;
+      return Object.freeze(result);
+    });
+    this.cachedPlan = Object.freeze({
+      revision: this.revision,
+      batches: Object.freeze(batches),
+      candidateCount: batches.reduce((total, batch) => total + batch.candidates.length, 0),
+      visibleCapacity: visibleBase,
+    });
+    return this.cachedPlan;
+  }
+
+  inspect(): BatchTopologyInspection {
+    let candidateCount = 0;
+    for (const batch of this.batches.values()) candidateCount += batch.candidates.size;
+    return {
+      revision: this.revision,
+      batchCount: this.batches.size,
+      candidateCount,
+      rebuilds: this.rebuilds,
+      patches: this.patches,
+      ineligible: this.ineligiblePrimitives.size,
+    };
+  }
+
+  private add(slot: RenderSceneProjectionSlot): boolean {
+    const keys = eligibleKeys(slot);
+    if (keys.length === 0) {
+      this.ineligiblePrimitives.add(slot.slot);
+      return false;
+    }
+    this.ineligiblePrimitives.delete(slot.slot);
+    const memberships: Array<{ batchText: string; candidateKey: string }> = [];
+    const instanceCount = slot.snapshot.instances?.instanceCount ?? 1;
+    for (let drawItemIndex = 0; drawItemIndex < keys.length; drawItemIndex += 1) {
+      const key = keys[drawItemIndex];
+      if (key === undefined) continue;
+      const text = keyText(key);
+      let batch = this.batches.get(text);
+      if (batch === undefined) {
+        const reused = this.freeBatchIds.pop();
+        const batchId = reused ?? this.generationByBatchId.length;
+        const generation = reused === undefined ? 0 : (this.generationByBatchId[batchId] ?? -1) + 1;
+        this.generationByBatchId[batchId] = generation;
+        batch = { batchId, generation, key, candidates: new Map() };
+        this.batches.set(text, batch);
+      }
+      for (let instanceOrdinal = 0; instanceOrdinal < instanceCount; instanceOrdinal += 1) {
+        const candidateKey = `${slot.slot}:${drawItemIndex}:${instanceOrdinal}`;
+        batch.candidates.set(candidateKey, {
+          primitiveIndex: slot.slot,
+          generation: slot.generation,
+          drawItemIndex,
+          instanceOrdinal,
+        });
+        memberships.push({ batchText: text, candidateKey });
+      }
+    }
+    this.membershipByPrimitive.set(slot.slot, memberships);
+    return true;
+  }
+
+  private remove(primitiveIndex: number): boolean {
+    this.ineligiblePrimitives.delete(primitiveIndex);
+    const memberships = this.membershipByPrimitive.get(primitiveIndex);
+    this.membershipByPrimitive.delete(primitiveIndex);
+    if (memberships === undefined) return false;
+    for (const membership of memberships) {
+      const batch = this.batches.get(membership.batchText);
+      if (batch === undefined) continue;
+      batch.candidates.delete(membership.candidateKey);
+      if (batch.candidates.size === 0) {
+        this.batches.delete(membership.batchText);
+        this.freeBatchIds.push(batch.batchId);
+      }
+    }
+    return true;
+  }
+}