@forgeax/engine-render-graph 0.1.32 → 0.1.34

package/src/compiled-graph.ts

@@ -26,6 +26,7 @@ import type {
   RenderGraphFrame,
   RenderGraphPassInstrumentation,
   RenderGraphPassRunner,
+  RenderGraphResourceAllocationInspection,
 } from './types.js';
 
 interface FrameResources {
@@ -34,6 +35,101 @@ interface FrameResources {
   readonly views: ReadonlyMap<number, TextureView>;
 }
 
+interface AllocationEntry {
+  readonly handle: unknown;
+  readonly bytes: number | undefined;
+}
+
+/**
+ * Compiled-graph owner ledger. It counts only graph-created physical handles;
+ * imported handles are references owned by the caller and remain byte-unknown.
+ */
+class RenderGraphAllocationLedger {
+  private readonly live = new Map<unknown, number | undefined>();
+  private readonly pending = new Map<unknown, number | undefined>();
+  private liveBytes = 0;
+  private pendingBytes = 0;
+  private peakBytes = 0;
+  private successfulAllocationCount = 0;
+  private successfulAllocationBytes = 0;
+  private retiredBytes = 0;
+  private unknownByteSizeCount = 0;
+  private readonly importedResourceCount: number;
+
+  constructor(entries: readonly AllocationEntry[], importedResourceCount: number) {
+    this.importedResourceCount = importedResourceCount;
+    for (const entry of entries) this.allocate(entry.handle, entry.bytes);
+  }
+
+  inspect(): RenderGraphResourceAllocationInspection {
+    return {
+      unit: 'engine-allocation-bytes',
+      physicalResidency: 'unknown',
+      liveBytes: this.liveBytes,
+      pendingRetirementBytes: this.pendingBytes,
+      peakBytes: this.peakBytes,
+      successfulAllocationCount: this.successfulAllocationCount,
+      successfulAllocationBytes: this.successfulAllocationBytes,
+      pendingRetirementCount: this.pending.size,
+      retiredBytes: this.retiredBytes,
+      failedAllocationRollbacks: 0,
+      failedAllocationRollbackBytes: 0,
+      unknownByteSizeCount: this.unknownByteSizeCount,
+      importedResourceCount: this.importedResourceCount,
+    };
+  }
+
+  retireAll(): void {
+    for (const handle of [...this.live.keys()]) this.retire(handle);
+  }
+
+  release(handle: unknown): void {
+    const pendingBytes = this.pending.get(handle);
+    if (pendingBytes !== undefined || this.pending.has(handle)) {
+      this.pending.delete(handle);
+      if (pendingBytes !== undefined) this.pendingBytes -= pendingBytes;
+      if (pendingBytes === undefined) this.unknownByteSizeCount -= 1;
+      this.retiredBytes += pendingBytes ?? 0;
+      return;
+    }
+    const liveBytes = this.live.get(handle);
+    if (liveBytes !== undefined || this.live.has(handle)) {
+      this.live.delete(handle);
+      if (liveBytes !== undefined) this.liveBytes -= liveBytes;
+      if (liveBytes === undefined) this.unknownByteSizeCount -= 1;
+      this.retiredBytes += liveBytes ?? 0;
+    }
+  }
+
+  private allocate(handle: unknown, bytes: number | undefined): void {
+    if (this.live.has(handle) || this.pending.has(handle)) return;
+    this.live.set(handle, bytes);
+    this.successfulAllocationCount += 1;
+    if (bytes === undefined) this.unknownByteSizeCount += 1;
+    else {
+      this.liveBytes += bytes;
+      this.successfulAllocationBytes += bytes;
+    }
+    this.updatePeak();
+  }
+
+  private retire(handle: unknown): void {
+    const bytes = this.live.get(handle);
+    if (bytes === undefined && !this.live.has(handle)) return;
+    this.live.delete(handle);
+    if (bytes !== undefined) {
+      this.liveBytes -= bytes;
+      this.pendingBytes += bytes;
+    }
+    this.pending.set(handle, bytes);
+    this.updatePeak();
+  }
+
+  private updatePeak(): void {
+    this.peakBytes = Math.max(this.peakBytes, this.liveBytes + this.pendingBytes);
+  }
+}
+
 function resolutionError(label: string, cause?: unknown): RenderGraphError {
   return new RenderGraphError({
     code: 'resource-resolution-failed',
@@ -48,6 +144,7 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
 {
   private retired = false;
   private retireResult: Promise<Result<void, RenderGraphError>> | undefined;
+  private readonly allocationLedger: RenderGraphAllocationLedger;
 
   constructor(
     private readonly generation: number,
@@ -58,10 +155,30 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
     private readonly passes: readonly CompiledPass<FrameCtx>[],
     private readonly info: CompiledRenderGraphInfo,
     private readonly colorTargetDescriptors: ReadonlyMap<string, ResolvedColorTargetDescriptor>,
-  ) {}
+  ) {
+    const infoByLabel = new Map(info.resources.map((resource) => [resource.label, resource]));
+    const seen = new Set<unknown>();
+    const entries: AllocationEntry[] = [];
+    let importedResourceCount = 0;
+    for (const compiled of resources.values()) {
+      if (compiled.usage === 0) continue;
+      const handle = compiled.texture ?? compiled.buffer;
+      if (compiled.record.origin === 'imported') {
+        importedResourceCount += 1;
+        continue;
+      }
+      if (handle === undefined || seen.has(handle)) continue;
+      seen.add(handle);
+      entries.push({
+        handle,
+        bytes: infoByLabel.get(compiled.record.label)?.byteSize,
+      });
+    }
+    this.allocationLedger = new RenderGraphAllocationLedger(entries, importedResourceCount);
+  }
 
   inspect(): CompiledRenderGraphInfo {
-    return this.info;
+    return { ...this.info, resourceAllocation: this.allocationLedger.inspect() };
   }
 
   getColorTargetView(name: string): TextureView | undefined {
@@ -260,6 +377,7 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
   }
 
   private async finishRetire(): Promise<Result<void, RenderGraphError>> {
+    this.allocationLedger.retireAll();
     try {
       await this.device.queue.onSubmittedWorkDone();
     } catch (cause) {
@@ -277,11 +395,13 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
     for (const compiled of this.resources.values()) {
       if (compiled.record.origin === 'imported') continue;
       if (compiled.texture === undefined && compiled.buffer === undefined) continue;
+      let destroyedSuccessfully = false;
       try {
         const destroyed =
           compiled.record.kind === 'texture'
             ? this.device.destroyTexture(compiled.texture as Texture)
             : this.device.destroyBuffer(compiled.buffer as Buffer);
+        destroyedSuccessfully = destroyed.ok;
         if (!destroyed.ok && firstFailure === undefined) {
           firstFailure = new RenderGraphError({
             code: 'resource-retire-failed',
@@ -301,6 +421,12 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
           hint: 'inspect detail.cause for the RHI destroy failure',
           detail: { generation: this.generation, resourceLabel: compiled.record.label, cause },
         });
+      } finally {
+        // A failed or throwing destroy leaves the handle owned by this
+        // graph. Keep its token pending so inspection reflects the
+        // retirement failure instead of claiming bytes were released.
+        if (destroyedSuccessfully)
+          this.allocationLedger.release(compiled.texture ?? compiled.buffer);
       }
     }
     return firstFailure === undefined ? ok(undefined) : err(firstFailure);

package/src/index.ts

@@ -68,6 +68,7 @@ export {
 export type {
   CompiledRenderGraph,
   CompiledRenderGraphInfo,
+  CompiledResourceByteSizeUnknownReason,
   CompiledResourceDescriptor,
   ComputeGraphPass,
   CopyGraphPass,
@@ -96,8 +97,11 @@ export type {
   RasterGraphPass,
   RenderGraphCompileOptions,
   RenderGraphFrame,
+  RenderGraphGenerationAllocationEntry,
+  RenderGraphGenerationAllocationInspection,
   RenderGraphPassExecution,
   RenderGraphPassInstrumentation,
   RenderGraphPassInstrumentationScope,
   RenderGraphPassRunner,
+  RenderGraphResourceAllocationInspection,
 } from './types.js';

package/src/types.ts

@@ -186,6 +186,11 @@ export interface GraphAccessInfo {
   readonly usage: GraphBufferAccess | GraphTextureAccess;
 }
 
+export type CompiledResourceByteSizeUnknownReason =
+  | 'imported-owner'
+  | 'format-or-layout-unknown'
+  | 'not-allocated';
+
 /** Detached physical allocation facts for one compiled graph resource. */
 export type CompiledResourceDescriptor =
   | {
@@ -226,6 +231,8 @@ export interface CompiledRenderGraphInfo {
     readonly physicalAllocationKey?: string | undefined;
     /** Descriptor-derived byte size when the format is uncompressed and known. */
     readonly byteSize?: number | undefined;
+    /** Why byteSize is absent; no zero is fabricated for an unknown owner/format. */
+    readonly byteSizeUnknownReason?: CompiledResourceByteSizeUnknownReason | undefined;
     /** Texture format retained for producer-owned resource inspection. */
     readonly format?: TextureFormat | undefined;
     /** Texture allocation facts retained for capability/lifetime inspection. */
@@ -236,6 +243,62 @@ export interface CompiledRenderGraphInfo {
   }[];
   /** Monotonic graph generation assigned when this graph was compiled. */
   readonly generation: number;
+  /**
+   * Graph-owned logical allocation facts. Imported resources are counted only
+   * as references; their physical bytes stay with the importing owner.
+   */
+  readonly resourceAllocation?: RenderGraphResourceAllocationInspection | undefined;
+}
+
+/**
+ * RenderGraph-owned logical allocation facts. Byte totals include only
+ * descriptor-derived sizes known by this package; physical GPU residency and
+ * imported-resource bytes remain unknown by contract.
+ */
+export interface RenderGraphResourceAllocationInspection {
+  readonly unit: 'engine-allocation-bytes';
+  readonly physicalResidency: 'unknown';
+  readonly liveBytes: number;
+  readonly pendingRetirementBytes: number;
+  readonly peakBytes: number;
+  readonly successfulAllocationCount: number;
+  readonly successfulAllocationBytes: number;
+  readonly pendingRetirementCount: number;
+  readonly retiredBytes: number;
+  readonly failedAllocationRollbacks: number;
+  readonly failedAllocationRollbackBytes: number;
+  readonly unknownByteSizeCount: number;
+  readonly importedResourceCount: number;
+}
+
+/** One graph generation included in the renderer-wide replacement ledger. */
+export interface RenderGraphGenerationAllocationEntry {
+  readonly generation: number;
+  /** A graph may be both the current active graph and an unsubmitted candidate. */
+  readonly roles: readonly ('active' | 'candidate' | 'retiring')[];
+  readonly retirement: 'active' | 'pending' | 'failed';
+  readonly allocation: RenderGraphResourceAllocationInspection;
+}
+
+/**
+ * Renderer-wide logical allocation facts across graph generations. Current
+ * live and pending bytes are summed across the generations that overlap;
+ * peakBytes is captured from simultaneous owner events instead of summing
+ * historical per-graph peaks. This does not estimate physical VRAM or include
+ * imported owner bytes.
+ */
+export interface RenderGraphGenerationAllocationInspection {
+  readonly unit: 'engine-allocation-bytes';
+  readonly physicalResidency: 'unknown';
+  readonly availability: 'complete' | 'partial' | 'unavailable';
+  readonly unavailableGenerationCount: number;
+  readonly entries: readonly RenderGraphGenerationAllocationEntry[];
+  readonly liveBytes: number;
+  readonly pendingRetirementBytes: number;
+  /** Peak simultaneous logical bytes observed by this renderer owner. */
+  readonly peakBytes: number;
+  readonly failedRetirementCount: number;
+  readonly failedRetirementBytes: number;
 }
 
 export interface RenderGraphFrame {