@forgeax/engine-render 0.1.4 → 0.1.6

package/src/gpu-driven/view-gpu.ts

@@ -24,10 +24,6 @@ import {
   GPU_BUFFER_USAGE_UNIFORM,
 } from '../gpu-usage';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
-import type {
-  RenderVisibilityViewDescriptor,
-  RenderVisibilityViewKind,
-} from '../render-system-extract';
 import type { SubmissionPlan } from './batch-topology';
 
 const COMPUTE_STAGE = 0x4;
@@ -212,173 +208,6 @@ function nextCapacity(required: number): number {
   return 2 ** Math.ceil(Math.log2(Math.max(1, required)));
 }
 
-export interface CpuVisibilityCandidate {
-  /** Stable projection slot; generation disambiguates slot reuse. */
-  readonly stableId: number;
-  readonly generation: number;
-  /** Candidate-domain index consumed by CascadeVolumeSet membership. */
-  readonly candidateIndex: number | undefined;
-  readonly worldAabb: Float32Array | undefined;
-  readonly casterEligible: boolean;
-  readonly batchId: number | undefined;
-  readonly instanceOrdinal: number | undefined;
-}
-
-export interface CpuVisibleItem {
-  readonly stableId: number;
-  readonly generation: number;
-  readonly candidateIndex: number | undefined;
-  readonly batchId: number | undefined;
-  readonly instanceOrdinal: number | undefined;
-}
-
-export interface CpuVisibilityBatchSpan {
-  readonly batchId: number;
-  readonly first: number;
-  readonly count: number;
-  readonly capacity: number;
-  readonly overflow: boolean;
-}
-
-export interface CpuVisibilityViewResult {
-  readonly viewId: string;
-  readonly kind: RenderVisibilityViewKind;
-  readonly cascadeIndex: number | undefined;
-  readonly stableIds: readonly number[];
-  readonly generations: readonly number[];
-  readonly compactVisible: readonly CpuVisibleItem[];
-  readonly batchSpans: readonly CpuVisibilityBatchSpan[];
-  readonly capacity: number;
-  readonly overflow: boolean;
-  readonly volumeRevision: number | undefined;
-  readonly spatialIndexRevision: number | undefined;
-}
-
-export interface CpuVisibilityCascadeMaskEntry {
-  readonly stableId: number;
-  readonly generation: number;
-  /** Bit 0..2 corresponds to cascade 0..2. */
-  readonly cascadeMask: number;
-}
-
-export interface CpuMultiViewVisibilityResult {
-  readonly views: readonly CpuVisibilityViewResult[];
-  readonly cascadeMasks: readonly CpuVisibilityCascadeMaskEntry[];
-  readonly spatialIndexRevision: number | undefined;
-}
-
-function aabbIntersectsPlanes(planes: Float32Array, aabb: Float32Array | undefined): boolean {
-  if (aabb === undefined || planes.length < 24) return true;
-  for (let planeIndex = 0; planeIndex < 6; planeIndex += 1) {
-    const offset = planeIndex * 4;
-    const normalX = planes[offset] ?? 0;
-    const normalY = planes[offset + 1] ?? 0;
-    const normalZ = planes[offset + 2] ?? 0;
-    const vertexX = normalX >= 0 ? (aabb[3] ?? 0) : (aabb[0] ?? 0);
-    const vertexY = normalY >= 0 ? (aabb[4] ?? 0) : (aabb[1] ?? 0);
-    const vertexZ = normalZ >= 0 ? (aabb[5] ?? 0) : (aabb[2] ?? 0);
-    if (normalX * vertexX + normalY * vertexY + normalZ * vertexZ + (planes[offset + 3] ?? 0) < 0) {
-      return false;
-    }
-  }
-  return true;
-}
-
-/**
- * CPU production executor for the shared main/CSM visibility contract.
- *
- * The executor consumes stable Scene Fact candidates and memberships already
- * selected by CascadeVolumeSet. It deliberately keeps the main list separate
- * from the caster domain, so a main-view cull cannot remove a shadow caster.
- */
-export function executeCpuMultiViewVisibility(input: {
-  readonly views: readonly RenderVisibilityViewDescriptor[];
-  readonly candidates: readonly CpuVisibilityCandidate[];
-  /** Broadphase-selected domains keyed by view. */
-  readonly candidatesByView?: ReadonlyMap<string, readonly CpuVisibilityCandidate[]>;
-  readonly capacityByView?: ReadonlyMap<string, number>;
-  readonly capacityByBatch?: ReadonlyMap<number, number>;
-}): CpuMultiViewVisibilityResult {
-  const candidates = [...input.candidates].sort(
-    (left, right) => left.stableId - right.stableId || left.generation - right.generation,
-  );
-  const cascadeMaskByStableId = new Map<number, number>();
-  for (const view of input.views) {
-    if (view.kind !== 'cascade' || view.cascadeIndex === undefined) continue;
-    const domain = input.candidatesByView?.get(view.viewId) ?? candidates;
-    for (const candidate of domain) {
-      if (!view.casterCandidateIndices.has(candidate.candidateIndex ?? -1)) continue;
-      cascadeMaskByStableId.set(
-        candidate.stableId,
-        (cascadeMaskByStableId.get(candidate.stableId) ?? 0) | (1 << view.cascadeIndex),
-      );
-    }
-  }
-  const cascadeMasks = candidates.map((candidate) =>
-    Object.freeze({
-      stableId: candidate.stableId,
-      generation: candidate.generation,
-      cascadeMask: cascadeMaskByStableId.get(candidate.stableId) ?? 0,
-    }),
-  );
-  const views = input.views.map((view) => {
-    const domain = input.candidatesByView?.get(view.viewId) ?? candidates;
-    const visible = domain.filter((candidate) => {
-      if (view.kind === 'cascade') {
-        return (
-          candidate.casterEligible &&
-          view.casterCandidateIndices.has(candidate.candidateIndex ?? -1)
-        );
-      }
-      return aabbIntersectsPlanes(view.planes, candidate.worldAabb);
-    });
-    const capacity = Math.max(0, input.capacityByView?.get(view.viewId) ?? visible.length);
-    const compactVisible = visible.slice(0, capacity).map((candidate) => ({
-      stableId: candidate.stableId,
-      generation: candidate.generation,
-      candidateIndex: candidate.candidateIndex,
-      batchId: candidate.batchId,
-      instanceOrdinal: candidate.instanceOrdinal,
-    }));
-    const counts = new Map<number, number>();
-    for (const candidate of visible) {
-      if (candidate.batchId === undefined) continue;
-      counts.set(candidate.batchId, (counts.get(candidate.batchId) ?? 0) + 1);
-    }
-    const batchSpans: CpuVisibilityBatchSpan[] = [];
-    let first = 0;
-    for (const [batchId, count] of [...counts.entries()].sort(([left], [right]) => left - right)) {
-      const batchCapacity = Math.max(0, input.capacityByBatch?.get(batchId) ?? count);
-      batchSpans.push({
-        batchId,
-        first,
-        count: Math.min(count, batchCapacity),
-        capacity: batchCapacity,
-        overflow: count > batchCapacity,
-      });
-      first += Math.min(count, batchCapacity);
-    }
-    return Object.freeze({
-      viewId: view.viewId,
-      kind: view.kind,
-      cascadeIndex: view.cascadeIndex,
-      stableIds: Object.freeze(compactVisible.map((candidate) => candidate.stableId)),
-      generations: Object.freeze(compactVisible.map((candidate) => candidate.generation)),
-      compactVisible: Object.freeze(compactVisible),
-      batchSpans: Object.freeze(batchSpans),
-      capacity,
-      overflow: visible.length > capacity || batchSpans.some((span) => span.overflow),
-      volumeRevision: view.volumeRevision,
-      spatialIndexRevision: view.spatialIndexRevision,
-    });
-  });
-  return Object.freeze({
-    views: Object.freeze(views),
-    cascadeMasks: Object.freeze(cascadeMasks),
-    spatialIndexRevision: input.views[0]?.spatialIndexRevision,
-  });
-}
-
 function bufferBinding(buffer: Buffer): {
   readonly kind: 'buffer';
   readonly value: { buffer: Buffer };
@@ -388,6 +217,7 @@ function bufferBinding(buffer: Buffer): {
 
 export class GpuDrivenView {
   private buffers: ViewBuffers | undefined;
+  private supersededBuffers: ViewBuffers[] = [];
   private bindGroup: BindGroup | undefined;
   private candidateCapacity = 0;
   private batchCapacity = 0;
@@ -635,7 +465,6 @@ export class GpuDrivenView {
 
   addPasses<FrameCtx extends RenderGraphFrame>(
     builder: RenderGraphBuilder<FrameCtx>,
-    labelPrefix = 'gpu-driven',
   ): Result<GpuDrivenViewGraphResources, RenderGraphError> {
     const buffers = this.buffers;
     const bindGroup = this.bindGroup;
@@ -655,80 +484,79 @@ export class GpuDrivenView {
         }),
       );
     }
-    const scenePrefix = labelPrefix === 'gpu-driven' ? 'gpu-scene' : `${labelPrefix}.scene`;
     const importBuffer = (name: string, buffer: Buffer, size: number, usage: number) =>
       builder.importBuffer(name, { size, usage }, () => buffer);
     const primitive = importBuffer(
-      `${scenePrefix}.primitive`,
+      'gpu-scene.primitive',
       this.scenePrimitive as Buffer,
       this.sceneCapacity * GPU_SCENE_LAYOUTS.primitive.stride,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!primitive.ok) return primitive;
     const transform = importBuffer(
-      `${scenePrefix}.transform`,
+      'gpu-scene.transform',
       this.sceneTransform as Buffer,
       this.sceneCapacity * GPU_SCENE_LAYOUTS.transform.stride,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!transform.ok) return transform;
     const instance = importBuffer(
-      `${scenePrefix}.instance`,
+      'gpu-scene.instance',
       this.sceneInstance as Buffer,
       this.sceneCapacity * GPU_SCENE_LAYOUTS.instance.stride,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!instance.ok) return instance;
     const material = importBuffer(
-      `${scenePrefix}.material`,
+      'gpu-scene.material',
       this.sceneMaterial as Buffer,
       this.sceneCapacity * GPU_SCENE_LAYOUTS.material.stride,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!material.ok) return material;
     const candidates = importBuffer(
-      `${labelPrefix}.candidates`,
+      'gpu-driven.candidates',
       buffers.candidates,
       this.candidateCapacity * CANDIDATE_STRIDE,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     );
     if (!candidates.ok) return candidates;
     const batches = importBuffer(
-      `${labelPrefix}.batches`,
+      'gpu-driven.batches',
       buffers.batches,
       this.batchCapacity * BATCH_STRIDE,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     );
     if (!batches.ok) return batches;
     const view = importBuffer(
-      `${labelPrefix}.view`,
+      'gpu-driven.view',
       buffers.view,
       VIEW_BYTES,
       GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
     );
     if (!view.ok) return view;
     const counters = importBuffer(
-      `${labelPrefix}.counters`,
+      'gpu-driven.counters',
       buffers.counters,
       this.batchCapacity * 8,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!counters.ok) return counters;
     const visible = importBuffer(
-      `${labelPrefix}.visible`,
+      'gpu-driven.visible',
       buffers.visible,
       this.candidateCapacity * 8,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!visible.ok) return visible;
     const indirect = importBuffer(
-      `${labelPrefix}.indirect`,
+      'gpu-driven.indirect',
       buffers.indirect,
       this.indirectCapacity * 20,
       GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_INDIRECT | GPU_BUFFER_USAGE_COPY_SRC,
     );
     if (!indirect.ok) return indirect;
-    const reset = builder.addComputePass(`${labelPrefix}.view-reset`, {
+    const reset = builder.addComputePass('gpu-driven.view-reset', {
       accesses: [
         { resource: view.value, usage: 'uniform-read' },
         { resource: counters.value, usage: 'storage-read-write' },
@@ -740,7 +568,7 @@ export class GpuDrivenView {
       },
     });
     if (!reset.ok) return reset;
-    const cull = builder.addComputePass(`${labelPrefix}.frustum-compact`, {
+    const cull = builder.addComputePass('gpu-driven.frustum-compact', {
       accesses: [
         { resource: primitive.value, usage: 'storage-read' },
         { resource: instance.value, usage: 'storage-read' },
@@ -757,7 +585,7 @@ export class GpuDrivenView {
       },
     });
     if (!cull.ok) return cull;
-    const finalize = builder.addComputePass(`${labelPrefix}.finalize-indirect`, {
+    const finalize = builder.addComputePass('gpu-driven.finalize-indirect', {
       accesses: [
         { resource: batches.value, usage: 'storage-read' },
         { resource: view.value, usage: 'uniform-read' },
@@ -783,9 +611,11 @@ export class GpuDrivenView {
   }
 
   dispose(): void {
-    if (this.buffers !== undefined) {
-      for (const buffer of Object.values(this.buffers)) this.device.destroyBuffer(buffer);
-    }
+    const buffers = [
+      ...this.supersededBuffers,
+      ...(this.buffers === undefined ? [] : [this.buffers]),
+    ];
+    this.supersededBuffers = [];
     this.buffers = undefined;
     this.bindGroup = undefined;
     this.plan = undefined;
@@ -794,9 +624,23 @@ export class GpuDrivenView {
     this.sceneTransform = undefined;
     this.sceneMaterial = undefined;
     this.sceneCapacity = 0;
+    this.destroyAfterSubmittedWork(buffers);
     void this.pipelineLayout;
   }
 
+  /**
+   * @internal
+   * Accept the current buffer generation after its typed graph compiles.
+   * Superseded imports stay alive while the last-known-good graph remains
+   * executable, then retire behind the queue fence only after promotion.
+   */
+  _commitResourceReplacement(): void {
+    const buffers = this.supersededBuffers;
+    if (buffers.length === 0) return;
+    this.supersededBuffers = [];
+    this.destroyAfterSubmittedWork(buffers);
+  }
+
   private rebuildBuffers(
     candidateCapacity: number,
     batchCapacity: number,
@@ -835,9 +679,7 @@ export class GpuDrivenView {
         return result;
       }
     }
-    if (this.buffers !== undefined) {
-      for (const buffer of Object.values(this.buffers)) this.device.destroyBuffer(buffer);
-    }
+    if (this.buffers !== undefined) this.supersededBuffers.push(this.buffers);
     this.buffers = created as ViewBuffers;
     this.candidateCapacity = nextCandidate;
     this.batchCapacity = nextBatch;
@@ -846,4 +688,16 @@ export class GpuDrivenView {
     this.bindGroup = undefined;
     return ok(undefined);
   }
+
+  private destroyAfterSubmittedWork(generations: readonly ViewBuffers[]): void {
+    if (generations.length === 0) return;
+    const release = (): void => {
+      for (const buffers of generations) {
+        for (const buffer of Object.values(buffers)) {
+          this.device.destroyBuffer(buffer);
+        }
+      }
+    };
+    void this.device.queue.onSubmittedWorkDone().then(release, release);
+  }
 }

package/src/gpu-resource.ts

@@ -22,7 +22,7 @@
 //   - Concept compression (charter F1 / AGENTS.md design axiom): a
 //     single union `type GpuResource = GpuBuffer | GpuTexture` covers
 //     both buffer and texture lifecycles so AI-user-facing code that
-//     just wants "any GPU resource I need to dispose" reaches one
+//     just wants "a GPU resource I need to dispose" reaches one
 //     symbol. Parallel classes (not a runtime-tagged generic
 //     `GpuResource<'buffer' | 'texture'>`) so the shape mirrors the
 //     RHI opaque-handle taxonomy verbatim and TS narrowing on
@@ -63,7 +63,7 @@ import type { Buffer, Result, RhiDevice, RhiError, Texture } from '@forgeax/engi
  * `'destroy-after-destroy'` forwarded from `device.destroyBuffer(...)`.
  *
  * @example
- *   import { GpuBuffer } from '@forgeax/engine-render/internal';
+ *   import { GpuBuffer } from './gpu-resource';
  *   const created = device.createBuffer({ size: 64, usage: GPUBufferUsage.STORAGE });
  *   if (!created.ok) return;
  *   const gpuBuf = new GpuBuffer(device, created.value);
@@ -115,7 +115,7 @@ export class GpuBuffer {
  * on the RHI shim's TEXTURE_META_MAP; the local flag is a derived view.
  *
  * @example
- *   import { GpuTexture } from '@forgeax/engine-render/internal';
+ *   import { GpuTexture } from './gpu-resource';
  *   const r = device.createTexture({ size: [w, h, 1], format: 'rgba8unorm', usage: ... });
  *   if (!r.ok) return;
  *   const gpuTex = new GpuTexture(device, r.value);
@@ -151,7 +151,7 @@ export class GpuTexture {
 
 /**
  * Union of runtime-managed GPU resources requiring explicit
- * `.destroy()`. AI-user-facing code that needs to dispose "any GPU
+ * `.destroy()`. AI-user-facing code that needs to dispose "a GPU
  * resource" types its parameter as `GpuResource` and lets TS narrow
  * via `instanceof GpuBuffer / GpuTexture` if branch-specific access
  * is required. Charter F1 single-entry indexability.

package/src/gpu-scene-schema.ts

@@ -1,103 +1,5 @@
 export type GpuSceneScalar = 'u32' | 'i32' | 'f32';
-
-/**
- * Renderer-owned mobility fact. `unknown` is intentional: a renderer must not
- * infer staticness from how often an entity happened to move in one frame.
- * Authoring/pack producers may provide the other two values explicitly.
- */
-export type SceneMobility = 'static' | 'dynamic' | 'unknown';
-
-/**
- * Explicit shadow-caster eligibility. `unknown` is not an eligible state; it
- * keeps missing authoring/pack data visible to the later visibility owner.
- */
-export type SceneCasterEligibility = 'eligible' | 'ineligible' | 'unknown';
-
-export type SceneFactRevisionDomain =
-  | 'transform'
-  | 'geometry'
-  | 'material'
-  | 'eligibility'
-  | 'space'
-  | 'batch'
-  | 'resource';
-
-export interface SceneFactRevisions {
-  readonly transform: number;
-  readonly geometry: number;
-  readonly material: number;
-  readonly eligibility: number;
-  readonly space: number;
-  readonly batch: number;
-  readonly resource: number;
-}
-
-/** Optional producer-owned facts carried by a RenderableSnapshot. */
-export interface RenderSceneFactInput {
-  readonly mobility?: SceneMobility;
-  readonly casterEligibility?: SceneCasterEligibility;
-  readonly revisions?: Partial<SceneFactRevisions>;
-}
-
-export type SceneBoundsFact =
-  | {
-      readonly status: 'present';
-      /** [minX, minY, minZ, maxX, maxY, maxZ] in world space. */
-      readonly worldAabb: Float32Array;
-      /** [minX, minY, minZ, maxX, maxY, maxZ] in local space. */
-      readonly localAabb: Float32Array;
-    }
-  | {
-      readonly status: 'missing';
-      readonly reason: 'missing-local-aabb' | 'invalid-local-aabb' | 'invalid-world-transform';
-    };
-
-export interface RenderSceneFact {
-  readonly slot: number;
-  readonly generation: number;
-  readonly worldId: number;
-  readonly entityKey: number;
-  readonly bounds: SceneBoundsFact;
-  readonly mobility: SceneMobility;
-  readonly casterEligibility: SceneCasterEligibility;
-  readonly revisions: SceneFactRevisions;
-}
-
-export type SceneFactDiagnosticCode = 'missing-bounds' | 'invalid-revision' | 'stale-generation';
-
-export interface SceneFactDiagnostic {
-  readonly code: SceneFactDiagnosticCode;
-  readonly slot?: number;
-  readonly generation?: number;
-  readonly worldId?: number;
-  readonly entityKey?: number;
-  readonly expectedGeneration?: number;
-  readonly actualGeneration?: number;
-  readonly domain?: SceneFactRevisionDomain;
-  readonly reason?: string;
-}
-
-/** Stable primitive flag bits; the extra fact bits do not change the table ABI. */
-export const GPU_SCENE_PRIMITIVE_FLAGS = Object.freeze({
-  active: 1,
-  hasBounds: 2,
-  gpuDriven: 4,
-  static: 8,
-  dynamic: 16,
-  casterEligible: 32,
-  casterIneligible: 64,
-  casterUnknown: 128,
-});
-
-const TYPE_LAYOUT = {
-  u32: { size: 4, alignment: 4 },
-  i32: { size: 4, alignment: 4 },
-  f32: { size: 4, alignment: 4 },
-  'vec4<f32>': { size: 16, alignment: 16 },
-  'mat4x4<f32>': { size: 64, alignment: 16 },
-} satisfies Readonly<Record<string, { readonly size: number; readonly alignment: number }>>;
-
-export type GpuSceneFieldType = keyof typeof TYPE_LAYOUT;
+export type GpuSceneFieldType = GpuSceneScalar | 'vec4<f32>' | 'mat4x4<f32>';
 
 export interface GpuSceneField {
   readonly name: string;
@@ -121,6 +23,16 @@ export interface GpuSceneTableLayout {
   readonly fields: readonly GpuSceneFieldLayout[];
 }
 
+const TYPE_LAYOUT: Readonly<
+  Record<GpuSceneFieldType, { readonly size: number; readonly alignment: number }>
+> = {
+  u32: { size: 4, alignment: 4 },
+  i32: { size: 4, alignment: 4 },
+  f32: { size: 4, alignment: 4 },
+  'vec4<f32>': { size: 16, alignment: 16 },
+  'mat4x4<f32>': { size: 64, alignment: 16 },
+};
+
 function align(value: number, alignment: number): number {
   return Math.ceil(value / alignment) * alignment;
 }