@forgeax/engine-render-graph 0.1.7 → 0.1.20

package/src/builder.ts

@@ -1,6 +1,7 @@
 import type { Buffer, RhiCaps, Texture, TextureView } from '@forgeax/engine-rhi';
 import { CompiledRenderGraphImpl } from './compiled-graph.js';
 import { err, ok, RenderGraphError, type Result } from './errors.js';
+import type { ResolvedColorTargetDescriptor } from './graph.js';
 import {
   accessResourceId,
   bufferHandle,
@@ -14,9 +15,11 @@ import {
   textureHandle,
   textureViewHandle,
 } from './kernel-internal.js';
+import { isTextureViewDimensionCompatible } from './resource-registry.js';
 import type {
   CompiledRenderGraph,
   CompiledRenderGraphInfo,
+  CompiledResourceDescriptor,
   ComputeGraphPass,
   CopyGraphPass,
   GraphAccess,
@@ -58,6 +61,60 @@ const TEXTURE_USAGE = {
 
 let nextGeneration = 1;
 
+function textureByteSize(
+  format: GPUTextureFormat,
+  extent: { readonly width: number; readonly height: number; readonly depthOrArrayLayers: number },
+  mipLevelCount: number,
+): number | undefined {
+  const bytesPerTexel =
+    format === 'r8unorm' || format === 'r8snorm' || format === 'r8uint' || format === 'r8sint'
+      ? 1
+      : format === 'rg8unorm' ||
+          format === 'rg8snorm' ||
+          format === 'rg8uint' ||
+          format === 'rg8sint'
+        ? 2
+        : format === 'rgba8unorm' ||
+            format === 'rgba8unorm-srgb' ||
+            format === 'rgba8snorm' ||
+            format === 'rgba8uint' ||
+            format === 'rgba8sint' ||
+            format === 'r32float' ||
+            format === 'r32uint' ||
+            format === 'r32sint'
+          ? 4
+          : format === 'rg16float' ||
+              format === 'rg16uint' ||
+              format === 'rg16sint' ||
+              format === 'rg16snorm' ||
+              format === 'rg16unorm'
+            ? 4
+            : format === 'rgba16float' ||
+                format === 'rgba16uint' ||
+                format === 'rgba16sint' ||
+                format === 'rgba16snorm' ||
+                format === 'rgba16unorm' ||
+                format === 'rg32float' ||
+                format === 'rg32uint' ||
+                format === 'rg32sint'
+              ? 8
+              : format === 'rgba32float' || format === 'rgba32uint' || format === 'rgba32sint'
+                ? 16
+                : undefined;
+  if (bytesPerTexel === undefined) return undefined;
+  let bytes = 0;
+  let width = extent.width;
+  let height = extent.height;
+  let depth = extent.depthOrArrayLayers;
+  for (let level = 0; level < mipLevelCount; level += 1) {
+    bytes += width * height * depth * bytesPerTexel;
+    width = Math.max(1, Math.floor(width / 2));
+    height = Math.max(1, Math.floor(height / 2));
+    depth = Math.max(1, Math.floor(depth / 2));
+  }
+  return bytes;
+}
+
 interface NormalizedRange {
   readonly mipStart: number;
   readonly mipEnd: number;
@@ -106,6 +163,8 @@ function textureUsage(access: GraphTextureAccess): number {
     case 'storage-write':
     case 'storage-read-write':
       return TEXTURE_USAGE.storageBinding;
+    case 'sampled-storage-read-write':
+      return TEXTURE_USAGE.storageBinding | TEXTURE_USAGE.textureBinding;
     case 'color-attachment':
     case 'depth-stencil-read':
     case 'depth-stencil-write':
@@ -123,6 +182,7 @@ function accessMode(access: GraphBufferAccess | GraphTextureAccess): {
 } {
   switch (access) {
     case 'storage-read-write':
+    case 'sampled-storage-read-write':
       return { read: true, write: true };
     case 'storage-write':
     case 'color-attachment':
@@ -151,7 +211,14 @@ function rangesOverlap(
 }
 
 function freezeInfo(info: CompiledRenderGraphInfo): CompiledRenderGraphInfo {
+  const freezeDescriptor = (descriptor: CompiledResourceDescriptor) => {
+    if (descriptor.kind !== 'texture') return Object.freeze({ ...descriptor });
+    const size =
+      typeof descriptor.size === 'string' ? descriptor.size : Object.freeze({ ...descriptor.size });
+    return Object.freeze({ ...descriptor, size });
+  };
   return Object.freeze({
+    generation: info.generation,
     passes: Object.freeze(
       info.passes.map((pass) =>
         Object.freeze({
@@ -161,7 +228,14 @@ function freezeInfo(info: CompiledRenderGraphInfo): CompiledRenderGraphInfo {
         }),
       ),
     ),
-    resources: Object.freeze(info.resources.map((resource) => Object.freeze({ ...resource }))),
+    resources: Object.freeze(
+      info.resources.map((resource) =>
+        Object.freeze({
+          ...resource,
+          descriptor: freezeDescriptor(resource.descriptor),
+        }),
+      ),
+    ),
   });
 }
 
@@ -336,7 +410,20 @@ export class RenderGraphBuilder<FrameCtx extends RenderGraphFrame> {
     );
     if (!allocated.ok) return allocated;
 
+    const generation = nextGeneration;
+    const physicalAllocationKeys = new WeakMap<object, string>();
+    let nextPhysicalAllocationKey = 1;
+    const physicalKey = (resource: CompiledResource<FrameCtx>): string | undefined => {
+      const handle = resource.texture ?? resource.buffer;
+      if (handle === undefined) return undefined;
+      const existing = physicalAllocationKeys.get(handle);
+      if (existing !== undefined) return existing;
+      const key = `allocation-${nextPhysicalAllocationKey++}`;
+      physicalAllocationKeys.set(handle, key);
+      return key;
+    };
     const info = freezeInfo({
+      generation,
       passes: analyzed.value.passes.map((pass, executionIndex) => ({
         name: pass.name,
         kind: pass.pass.kind,
@@ -352,16 +439,78 @@ export class RenderGraphBuilder<FrameCtx extends RenderGraphFrame> {
           (dependency) => analyzed.value.passes[dependency]?.name ?? 'unknown',
         ),
       })),
-      resources: [...allocated.value.resources.values()].map((resource) => ({
-        label: resource.record.label,
-        kind: resource.record.kind,
-        origin: resource.record.origin,
-        firstUse: resource.firstUse,
-        lastUse: resource.lastUse,
-        derivedUsage: resource.usage,
-      })),
+      resources: [...allocated.value.resources.values()].map((resource) => {
+        const texture =
+          resource.record.kind === 'texture'
+            ? (resource.record.descriptor as GraphTextureDescriptor)
+            : undefined;
+        const buffer =
+          resource.record.kind === 'buffer'
+            ? (resource.record.descriptor as GraphBufferDescriptor)
+            : undefined;
+        const allocationKey = physicalKey(resource);
+        const extent =
+          texture === undefined ? undefined : this.resolveExtent(texture.size, options.surfaceSize);
+        return {
+          label: resource.record.label,
+          kind: resource.record.kind,
+          origin: resource.record.origin,
+          descriptor:
+            texture === undefined
+              ? {
+                  kind: 'buffer' as const,
+                  size: buffer?.size ?? 0,
+                }
+              : {
+                  kind: 'texture' as const,
+                  format: texture.format,
+                  ...(texture.domain === undefined ? {} : { domain: texture.domain }),
+                  size: texture.size,
+                  width: extent?.width ?? 1,
+                  height: extent?.height ?? 1,
+                  depthOrArrayLayers: extent?.depthOrArrayLayers ?? 1,
+                  mipLevelCount: texture.mipLevelCount ?? 1,
+                  sampleCount: texture.sampleCount ?? 1,
+                },
+          firstUse: resource.firstUse,
+          lastUse: resource.lastUse,
+          derivedUsage: resource.usage,
+          ...(allocationKey === undefined ? {} : { physicalAllocationKey: allocationKey }),
+          ...(texture === undefined ? {} : { format: texture.format }),
+          ...(texture === undefined
+            ? buffer === undefined
+              ? {}
+              : { byteSize: buffer.size }
+            : {
+                byteSize: textureByteSize(
+                  texture.format,
+                  this.resolveExtent(texture.size, options.surfaceSize),
+                  texture.mipLevelCount ?? 1,
+                ),
+              }),
+          ...(texture === undefined
+            ? {}
+            : {
+                dimension: texture.dimension ?? '2d',
+                extent,
+              }),
+        };
+      }),
     });
 
+    const colorTargetDescriptors = new Map<string, ResolvedColorTargetDescriptor>();
+    for (const resource of allocated.value.resources.values()) {
+      if (resource.record.kind !== 'texture' || resource.texture === undefined) continue;
+      const extent = this.resolveExtent(resource.record.descriptor.size, options.surfaceSize);
+      colorTargetDescriptors.set(resource.record.label, {
+        texture: resource.texture,
+        format: resource.record.descriptor.format,
+        size: { width: extent.width, height: extent.height },
+        usage: resource.usage,
+        sample: resource.record.descriptor.sampleCount ?? 1,
+      });
+    }
+
     return ok(
       new CompiledRenderGraphImpl(
         nextGeneration++,
@@ -371,6 +520,7 @@ export class RenderGraphBuilder<FrameCtx extends RenderGraphFrame> {
         allocated.value.views,
         Object.freeze(analyzed.value.passes),
         info,
+        colorTargetDescriptors,
       ),
     );
   }
@@ -431,6 +581,12 @@ export class RenderGraphBuilder<FrameCtx extends RenderGraphFrame> {
     const compiledPasses: CompiledPass<FrameCtx>[] = [];
     const history: NormalizedAccess[] = [];
 
+    for (const resource of this.resources.values()) {
+      if (resource.kind !== 'texture' || resource.origin !== 'created') continue;
+      const usage = resource.descriptor.usage ?? 0;
+      if (usage !== 0) usageByResource.set(resource.id, usage);
+    }
+
     for (let passIndex = 0; passIndex < this.passes.length; passIndex++) {
       const pass = this.passes[passIndex];
       if (pass === undefined) continue;
@@ -665,7 +821,11 @@ export class RenderGraphBuilder<FrameCtx extends RenderGraphFrame> {
           continue;
         }
         if (!left.write && !right.write) continue;
-        if (left.usage === right.usage && left.usage === 'storage-read-write') continue;
+        if (
+          left.usage === right.usage &&
+          (left.usage === 'storage-read-write' || left.usage === 'sampled-storage-read-write')
+        )
+          continue;
         const label = this.resources.get(left.resourceId)?.label;
         return err(
           new RenderGraphError({
@@ -839,6 +999,27 @@ export class RenderGraphBuilder<FrameCtx extends RenderGraphFrame> {
         }
       }
     }
+    for (const view of this.views.values()) {
+      const texture = this.resources.get(view.textureId);
+      if (texture?.kind !== 'texture') continue;
+      const allocationDimension = texture.descriptor.dimension ?? '2d';
+      const viewDimension = view.descriptor.dimension;
+      if (!isTextureViewDimensionCompatible(allocationDimension, viewDimension)) {
+        return err(
+          new RenderGraphError({
+            code: 'resource-descriptor-invalid',
+            expected: `texture '${texture.label}' view dimension matches allocation dimension`,
+            hint: 'use a 3d view only for a 3d allocation and preserve array views on 2d allocations',
+            detail: {
+              resourceLabel: texture.label,
+              field: 'dimension',
+              expected: allocationDimension,
+              actual: viewDimension ?? '2d',
+            },
+          }),
+        );
+      }
+    }
     return ok(undefined);
   }
 

package/src/compiled-graph.ts

@@ -8,6 +8,7 @@ import type {
   TextureView,
 } from '@forgeax/engine-rhi';
 import { err, ok, RenderGraphError, type Result } from './errors.js';
+import type { ResolvedColorTargetDescriptor } from './graph.js';
 import type {
   CompiledPass,
   CompiledResource,
@@ -55,12 +56,32 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
     private readonly views: ReadonlyMap<number, CompiledView<FrameCtx>>,
     private readonly passes: readonly CompiledPass<FrameCtx>[],
     private readonly info: CompiledRenderGraphInfo,
+    private readonly colorTargetDescriptors: ReadonlyMap<string, ResolvedColorTargetDescriptor>,
   ) {}
 
   inspect(): CompiledRenderGraphInfo {
     return this.info;
   }
 
+  getColorTargetView(name: string): TextureView | undefined {
+    for (const view of this.views.values()) {
+      const resource = this.resources.get(view.record.textureId);
+      if (resource?.record.label === name) return view.view;
+    }
+    return undefined;
+  }
+
+  getColorTargetTexture(name: string): Texture | undefined {
+    for (const resource of this.resources.values()) {
+      if (resource.record.label === name) return resource.texture;
+    }
+    return undefined;
+  }
+
+  getColorTargetDescriptor(name: string): ResolvedColorTargetDescriptor | undefined {
+    return this.colorTargetDescriptors.get(name);
+  }
+
   execute(frame: FrameCtx, runPass?: RenderGraphPassRunner): Result<void, RenderGraphError> {
     if (this.retired) {
       return err(

package/src/errors.ts

@@ -66,6 +66,28 @@ export type RenderGraphErrorCode = keyof RenderGraphErrorDetailByCode;
 /** Detail union projected from the private code-to-detail map. */
 export type RenderGraphErrorDetail = RenderGraphErrorDetailByCode[RenderGraphErrorCode];
 
+/** Failure stages for the shared float/output surface contract. */
+export type SurfaceFailureKind =
+  | 'allocation'
+  | 'attachment'
+  | 'sampled-read'
+  | 'view-domain'
+  | 'raw-endpoint';
+
+/** Closed error codes derived from the surface failure kinds. */
+export type SurfaceFailureCode = `surface-${SurfaceFailureKind}-failed`;
+
+/** Shared detail for graph and render-surface recovery. */
+export interface RenderSurfaceFailureDetail {
+  readonly lane: string;
+  readonly stage: string;
+  readonly target: string;
+  readonly format: string;
+  readonly domain: string;
+  readonly endpoint: string;
+  readonly capability: string;
+}
+
 /**
  * Constructor arguments correlated by code. `detail` remains optional to
  * preserve the existing envelope behavior for callers that only need the

package/src/index.ts

@@ -14,10 +14,13 @@ export {
   RenderGraphError,
   type RenderGraphErrorCode,
   type RenderGraphErrorDetail,
+  type RenderSurfaceFailureDetail,
   type ResourceAllocFailedDetail,
   type Result,
   type ResultErr,
   type ResultOk,
+  type SurfaceFailureCode,
+  type SurfaceFailureKind,
 } from './errors.js';
 export type {
   BufferRole,
@@ -65,6 +68,7 @@ export {
 export type {
   CompiledRenderGraph,
   CompiledRenderGraphInfo,
+  CompiledResourceDescriptor,
   ComputeGraphPass,
   CopyGraphPass,
   GraphAccess,

package/src/pipeline/__tests__/color-value-domain.test.ts

@@ -32,6 +32,14 @@ describe('ColorValueDomain', () => {
     expect(JSON.parse(serializeColorResourceDescriptor(descriptor))).toEqual(descriptor);
   });
 
+  it('keeps display-encoded as an explicit domain for float storage', () => {
+    const descriptor: ColorResourceDescriptor = {
+      domain: 'display-encoded',
+      format: 'rgba16float',
+    };
+    expect(JSON.parse(serializeColorResourceDescriptor(descriptor))).toEqual(descriptor);
+  });
+
   it.each([undefined, 'gamma-magic'])('rejects a missing or unknown domain: %s', (value) => {
     const result = deserializeColorValueDomain(value);
     expect(result.ok).toBe(false);

package/src/resource-registry.ts

@@ -26,6 +26,16 @@ import type {
 } from './graph.js';
 import type { ColorValueDomain } from './pipeline/color-value-domain.js';
 
+/** Check the only allocation/view dimension combinations supported by WebGPU. */
+export function isTextureViewDimensionCompatible(
+  allocationDimension: GPUTextureDimension,
+  viewDimension: GPUTextureViewDimension | undefined,
+): boolean {
+  if (viewDimension === undefined) return true;
+  if (allocationDimension === '3d') return viewDimension === '3d';
+  return viewDimension !== '3d';
+}
+
 /**
  * Per-resource GPU allocation metadata carried through compile.
  * When the resource was registered via addColorTarget, colorTarget

package/src/types.ts

@@ -10,6 +10,7 @@ import type {
   TextureView,
 } from '@forgeax/engine-rhi';
 import type { RenderGraphError, Result } from './errors.js';
+import type { ColorValueDomain } from './pipeline/color-value-domain.js';
 
 declare const graphTextureBrand: unique symbol;
 declare const graphTextureViewBrand: unique symbol;
@@ -44,10 +45,14 @@ export type GraphExtent =
 export interface GraphTextureDescriptor {
   readonly format: TextureFormat;
   readonly size: GraphExtent;
+  /** Additional RHI usage required by an external diagnostic consumer. */
+  readonly usage?: number | undefined;
   readonly mipLevelCount?: number | undefined;
   readonly sampleCount?: number | undefined;
   readonly dimension?: GPUTextureDimension | undefined;
   readonly viewFormats?: readonly TextureFormat[] | undefined;
+  /** Explicit semantic color domain; never inferred from the attachment format. */
+  readonly domain?: ColorValueDomain | undefined;
 }
 
 export interface ImportedTextureDescriptor extends GraphTextureDescriptor {
@@ -92,6 +97,7 @@ export type GraphTextureAccess =
   | 'storage-read'
   | 'storage-write'
   | 'storage-read-write'
+  | 'sampled-storage-read-write'
   | 'color-attachment'
   | 'depth-stencil-read'
   | 'depth-stencil-write'
@@ -174,6 +180,26 @@ export interface GraphAccessInfo {
   readonly usage: GraphBufferAccess | GraphTextureAccess;
 }
 
+/** Detached physical allocation facts for one compiled graph resource. */
+export type CompiledResourceDescriptor =
+  | {
+      readonly kind: 'texture';
+      readonly format: TextureFormat;
+      /** Explicit semantic color domain retained in detached graph facts. */
+      readonly domain?: ColorValueDomain | undefined;
+      /** Authored extent retained so consumers can validate the allocation contract. */
+      readonly size: GraphExtent;
+      readonly width: number;
+      readonly height: number;
+      readonly depthOrArrayLayers: number;
+      readonly mipLevelCount: number;
+      readonly sampleCount: number;
+    }
+  | {
+      readonly kind: 'buffer';
+      readonly size: number;
+    };
+
 export interface CompiledRenderGraphInfo {
   readonly passes: readonly {
     readonly name: string;
@@ -186,10 +212,24 @@ export interface CompiledRenderGraphInfo {
     readonly label: string;
     readonly kind: GraphResourceKind;
     readonly origin: GraphResourceOrigin;
+    readonly descriptor: CompiledResourceDescriptor;
     readonly firstUse: number | null;
     readonly lastUse: number | null;
     readonly derivedUsage: number;
+    /** Stable compile-local identity of the physical RHI allocation. */
+    readonly physicalAllocationKey?: string | undefined;
+    /** Descriptor-derived byte size when the format is uncompressed and known. */
+    readonly byteSize?: number | undefined;
+    /** Texture format retained for producer-owned resource inspection. */
+    readonly format?: TextureFormat | undefined;
+    /** Texture allocation facts retained for capability/lifetime inspection. */
+    readonly dimension?: GPUTextureDimension | undefined;
+    readonly extent?:
+      | { readonly width: number; readonly height: number; readonly depthOrArrayLayers: number }
+      | undefined;
   }[];
+  /** Monotonic graph generation assigned when this graph was compiled. */
+  readonly generation: number;
 }
 
 export interface RenderGraphFrame {