@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/inspection-types.ts

@@ -0,0 +1,80 @@
+/**
+ * Renderer-owned inspection PODs. Keeping these projections free of renderer
+ * implementation imports prevents the observation contract from reopening the
+ * extract/record dependency graph.
+ */
+
+import type { PointsLinesInspection } from './points-lines/inspection';
+
+export interface BatchTopologyInspection {
+  readonly revision: number;
+  readonly batchCount: number;
+  readonly candidateCount: number;
+  readonly rebuilds: number;
+  readonly patches: number;
+  readonly ineligible: number;
+}
+
+export interface GpuSceneTableInspection {
+  readonly capacity: number;
+  readonly bytes: number;
+}
+
+type GpuSceneTableName = 'primitive' | 'instance' | 'transform' | 'drawTemplate' | 'material';
+
+export interface GpuSceneInspection {
+  readonly capacity: number;
+  readonly tables: Readonly<Record<GpuSceneTableName, GpuSceneTableInspection>>;
+  readonly uploadRanges: number;
+  readonly uploadBytes: number;
+  readonly capacityGrows: number;
+  readonly fullRebuilds: number;
+  readonly clearedSlots: number;
+  readonly noChangeFrames: number;
+}
+
+export interface GpuDrivenProductionInspection {
+  readonly gpuOwnedSnapshotsMaterialized: number;
+  readonly filteredPlanBuilds: number;
+  readonly gpuOwnedEntityCount: number;
+  readonly candidateUploadBytes: number;
+  readonly batchUploadBytes: number;
+  readonly viewConstantsUploadBytes: number;
+  readonly batchBindGroupCreates: number;
+  readonly viewBindGroupCreates: number;
+  readonly topologyRevision: number | undefined;
+  readonly validatedGpuOwnedRows: number;
+  readonly cpuFallbackDrawItems: number;
+}
+
+export type RenderSceneResyncReason =
+  | 'attach'
+  | 'asset-catalog-changed'
+  | 'shared-ref-changed'
+  | 'journal-overflow'
+  | 'unsupported-change'
+  | 'non-rigid-lane'
+  | 'explicit-invalidate';
+
+export interface PersistentRenderSceneInspection {
+  readonly worldEntitiesScanned: number;
+  readonly fullRebuilds: number;
+  readonly noChangeFrames: number;
+  readonly deltaFrames: number;
+  readonly transformUpdates: number;
+  readonly lastResyncReason: RenderSceneResyncReason | undefined;
+  readonly projectionRecords: number;
+  readonly topology: BatchTopologyInspection;
+  readonly gpu:
+    | { readonly status: 'inactive' }
+    | { readonly status: 'unsupported'; readonly reason: 'storage-buffer-unavailable' }
+    | ({ readonly status: 'resident' } & GpuSceneInspection)
+    | { readonly status: 'rebuild-pending' }
+    | { readonly status: 'error' };
+  /** Bounded retained authoring observations; no graph or backend handles. */
+  readonly pointsLines: readonly PointsLinesInspection[];
+}
+
+export type RenderSceneInspection = PersistentRenderSceneInspection & {
+  readonly gpuDriven: GpuDrivenProductionInspection;
+};

package/src/instance-buffer-cache.ts

@@ -0,0 +1,95 @@
+// @forgeax/engine-runtime / instance-buffer-cache
+//
+// feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M-4 / w16.
+//
+// SSOT for the per-RenderSystem instance-transform GPU storage cache:
+//   - the cache entry shape (buffer + uploaded bookkeeping fingerprints)
+//   - the dispose-path walk that releases every entry's GpuBuffer
+//
+// Moved out of render-system-record.ts so the entry shape stays
+// independent of the record pipeline (architecture-principles §4 pipeline
+// isolation: a cache structure that 4+ consumers share is decoupled from
+// the consumer that records frames). Per-frame Map.delete cleanup keeps
+// its existing semantics inline at the record stage (plan-strategy D-7
+// + OOS-11: dispose path is the new branch, per-frame stays as-is).
+
+import type { GpuBuffer } from './gpu-resource';
+
+/**
+ * One entry of the per-RenderSystem instance-transform GPU storage cache.
+ *
+ * The `buffer` field is a `GpuBuffer` wrapper (feat-20260612 M-2/M-3): it
+ * holds the raw RHI handle, owns the lifecycle (`destroy()` + `isDestroyed`)
+ * and routes dispose through the RHI shim's destroy bookkeeping SSOT. The
+ * two `uploaded*` fields are the cache invalidation fingerprint -- when the
+ * archetype version bumps or the byte length changes, the record stage
+ * allocates a fresh GpuBuffer and replaces the entry.
+ */
+export interface InstanceBufferCacheEntry {
+  readonly buffer: GpuBuffer;
+  readonly uploadedByteLength: number;
+  readonly uploadedArchVersion: number;
+}
+
+function destroyInstanceBufferEntries(
+  entries: Iterable<InstanceBufferCacheEntry>,
+  errorRegistry?: InstanceBufferCacheErrorSink,
+): void {
+  for (const entry of entries) {
+    if (entry.buffer.isDestroyed) continue;
+    const r = entry.buffer.destroy();
+    if (!r.ok && errorRegistry) errorRegistry.fire(r.error);
+  }
+}
+
+/**
+ * Minimal error-registry surface accepted by disposeInstanceBuffers —
+ * only needs `fire`, matching RhiErrorListenerRegistry (feat-20260619 D-6).
+ */
+export interface InstanceBufferCacheErrorSink {
+  fire(e: { code: string }): void;
+}
+
+/**
+ * Walk an instance-buffer cache Map, destroy every entry's GpuBuffer, then
+ * clear the Map. Called from `Renderer.dispose()` (M-5) as the per-frame
+ * instance-buffer release step in the dispose chain
+ * (plan-strategy D-2: gpuStore.destroyAll -> graph.drain ->
+ * frameState.instanceBuffers cleanup -> ...).
+ *
+ * Idempotent (architecture-principles §6): a second call after the Map was
+ * cleared is a no-op. Each `.destroy()` routes through the RHI shim's
+ * per-handle bookkeeping; a stray second-destroy on a handle that the
+ * runtime did not flip surfaces as the structured 'destroy-after-destroy'
+ * RhiError from the shim. That error is *not* re-thrown -- this helper
+ * is a sweep that tolerates per-handle failures so the dispose chain can
+ * make progress (mirrors `GpuResidencyCache.destroyAll`'s policy;
+ * plan-strategy D-3 / D-8).
+ *
+ * feat-20260619 M4 (D-6): the optional `errorRegistry` parameter unifies
+ * the dispose path with the per-frame path — destroy failures fire
+ * errorRegistry + sweep continues. Callers that lack an error registry
+ * (unit tests of the helper itself) omit the parameter safely.
+ *
+ * Per-frame Map.delete cleanup at the record stage keeps its existing
+ * 'just delete the key' semantics (plan-strategy D-7 + OOS-11): the
+ * per-frame path bumps fingerprints when the archetype version changes,
+ * letting the next record stage replace the entry; only the dispose
+ * exit path walks-then-destroys.
+ */
+export function disposeInstanceBuffers(
+  map: Map<number, InstanceBufferCacheEntry>,
+  errorRegistry?: InstanceBufferCacheErrorSink,
+): void {
+  destroyInstanceBufferEntries(map.values(), errorRegistry);
+  map.clear();
+}
+
+/** Destroy transient uniform-fallback chunks allocated for the previous frame. */
+export function disposeTransientInstanceBuffers(
+  entries: InstanceBufferCacheEntry[],
+  errorRegistry?: InstanceBufferCacheErrorSink,
+): void {
+  destroyInstanceBufferEntries(entries, errorRegistry);
+  entries.length = 0;
+}

package/src/internal.ts

@@ -0,0 +1,9 @@
+// Non-stable implementation seam for engine-owned consumers and tests.
+
+export {
+  type ResolvedTilesetRuntime,
+  resolveTilesetRuntime,
+  type TilesetAtlasLookup,
+  type TilesetRuntimeError,
+  type TilesetRuntimeErrorCode,
+} from '@forgeax/engine-assets-runtime';

package/src/lifecycle.ts

@@ -0,0 +1,168 @@
+import type { AssetRuntimeError } from '@forgeax/engine-assets-runtime';
+import type { RenderGraphError } from '@forgeax/engine-render-graph';
+import type { RhiError } from '@forgeax/engine-rhi';
+import type { SkinError } from '@forgeax/engine-skinning';
+import type { ImageError } from '@forgeax/engine-types';
+import type { RenderError } from './errors/render';
+import type { PostProcessError } from './post-process-errors';
+
+export interface RendererLostInfo {
+  readonly reason: string;
+  readonly message: string;
+}
+
+export type RendererLostListener = (info: RendererLostInfo) => void;
+
+export type RendererError =
+  | RhiError
+  | RenderGraphError
+  | ImageError
+  | RenderError
+  | AssetRuntimeError
+  | SkinError
+  | PostProcessError;
+
+export type RendererErrorListener = (error: RendererError) => void;
+
+export type HealthReason = 'alive' | 'device-lost' | 'internal-fault';
+
+export interface HealthDetailDeviceLost {
+  readonly lostReason: 'unknown' | 'destroyed';
+  readonly message: string;
+}
+
+export interface HealthDetailInternalFault {
+  readonly message: string;
+}
+
+export type HealthSnapshot =
+  | { readonly reason: 'alive'; readonly recoverable: boolean }
+  | {
+      readonly reason: 'device-lost';
+      readonly detail: HealthDetailDeviceLost;
+      readonly recoverable: boolean;
+    }
+  | {
+      readonly reason: 'internal-fault';
+      readonly detail: HealthDetailInternalFault;
+      readonly recoverable: boolean;
+    };
+
+export type HealthChangeListener = (snapshot: HealthSnapshot) => void;
+
+export {
+  DEVICE_RESOURCE_KINDS,
+  type DeviceResourceKind,
+  DeviceResourceRef,
+  DeviceScope,
+  type DeviceScopeReceipt,
+  type DeviceScopeState,
+  type LifecycleFailure,
+  type LifecycleResourceSpec,
+  type LifecycleResult,
+  LifecycleTransaction,
+  type ResourceRef,
+} from './device/device-scope';
+
+export class LostListenerRegistry {
+  private readonly listeners = new Set<RendererLostListener>();
+  private fired = false;
+  private lastInfo: RendererLostInfo | null = null;
+
+  add(listener: RendererLostListener): () => void {
+    this.listeners.add(listener);
+    if (this.fired && this.lastInfo) listener(this.lastInfo);
+    return () => this.listeners.delete(listener);
+  }
+
+  fire(info: RendererLostInfo): void {
+    this.fired = true;
+    this.lastInfo = info;
+    for (const listener of this.listeners) listener(info);
+  }
+
+  clear(): void {
+    this.listeners.clear();
+  }
+}
+
+export class RhiErrorListenerRegistry {
+  private readonly listeners: RendererErrorListener[] = [];
+  private fired = false;
+  private lastError: RendererError | null = null;
+
+  add(listener: RendererErrorListener): () => void {
+    this.listeners.push(listener);
+    if (this.fired && this.lastError) {
+      try {
+        listener(this.lastError);
+      } catch (error) {
+        console.error('[RhiErrorListenerRegistry] late-attach listener threw:', error);
+      }
+    }
+    return () => {
+      const index = this.listeners.indexOf(listener);
+      if (index >= 0) this.listeners.splice(index, 1);
+    };
+  }
+
+  fire(error: RendererError): void {
+    this.fired = true;
+    this.lastError = error;
+    if (this.listeners.length === 0) {
+      console.error(`[RhiError ${error.code}] expected: ${error.expected}; hint: ${error.hint}`);
+      return;
+    }
+    for (const listener of this.listeners) {
+      try {
+        listener(error);
+      } catch (cause) {
+        console.error('[RhiErrorListenerRegistry] listener threw:', cause);
+      }
+    }
+  }
+
+  clear(): void {
+    this.listeners.length = 0;
+  }
+}
+
+export class HealthListenerRegistry {
+  private readonly listeners = new Set<HealthChangeListener>();
+  private fired = false;
+  private lastSnapshot: HealthSnapshot | null = null;
+
+  add(listener: HealthChangeListener): () => void {
+    this.listeners.add(listener);
+    if (this.fired && this.lastSnapshot) {
+      try {
+        listener(this.lastSnapshot);
+      } catch (error) {
+        console.error('[HealthListenerRegistry] late-attach listener threw:', error);
+      }
+    }
+    return () => this.listeners.delete(listener);
+  }
+
+  fire(snapshot: HealthSnapshot): void {
+    this.fired = true;
+    this.lastSnapshot = snapshot;
+    for (const listener of this.listeners) {
+      try {
+        listener(snapshot);
+      } catch (error) {
+        console.error('[HealthListenerRegistry] listener threw:', error);
+      }
+    }
+  }
+
+  clear(): void {
+    this.listeners.clear();
+  }
+
+  getLastSnapshot(): HealthSnapshot {
+    return this.fired && this.lastSnapshot
+      ? this.lastSnapshot
+      : { reason: 'alive', recoverable: false };
+  }
+}