@forgeax/engine-render-graph 0.1.19 → 0.1.21

package/src/builder.ts

@@ -15,6 +15,7 @@ import {
   textureHandle,
   textureViewHandle,
 } from './kernel-internal.js';
+import { isTextureViewDimensionCompatible } from './resource-registry.js';
 import type {
   CompiledRenderGraph,
   CompiledRenderGraphInfo,
@@ -60,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;
@@ -108,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':
@@ -125,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':
@@ -160,6 +218,7 @@ function freezeInfo(info: CompiledRenderGraphInfo): CompiledRenderGraphInfo {
     return Object.freeze({ ...descriptor, size });
   };
   return Object.freeze({
+    generation: info.generation,
     passes: Object.freeze(
       info.passes.map((pass) =>
         Object.freeze({
@@ -351,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,
@@ -367,31 +439,63 @@ 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,
-        descriptor:
+      resources: [...allocated.value.resources.values()].map((resource) => {
+        const texture =
           resource.record.kind === 'texture'
-            ? {
-                kind: 'texture' as const,
-                format: resource.record.descriptor.format,
-                ...(resource.record.descriptor.domain === undefined
-                  ? {}
-                  : { domain: resource.record.descriptor.domain }),
-                size: resource.record.descriptor.size,
-                ...this.resolveExtent(resource.record.descriptor.size, options.surfaceSize),
-                mipLevelCount: resource.record.descriptor.mipLevelCount ?? 1,
-                sampleCount: resource.record.descriptor.sampleCount ?? 1,
-              }
+            ? (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 }
             : {
-                kind: 'buffer' as const,
-                size: resource.record.descriptor.size,
-              },
-        firstUse: resource.firstUse,
-        lastUse: resource.lastUse,
-        derivedUsage: resource.usage,
-      })),
+                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>();
@@ -493,10 +597,14 @@ export class RenderGraphBuilder<FrameCtx extends RenderGraphFrame> {
         const item = this.normalizeAccess(passIndex, pass, access);
         if (!item.ok) return item;
         normalized.push(item.value);
+        const resource = this.resources.get(item.value.resourceId);
         const usage =
-          this.resources.get(item.value.resourceId)?.kind === 'buffer'
+          (resource?.kind === 'texture' && resource.origin === 'created'
+            ? (resource.descriptor.usage ?? 0)
+            : 0) |
+          (resource?.kind === 'buffer'
             ? bufferUsage(access.usage as GraphBufferAccess)
-            : textureUsage(access.usage as GraphTextureAccess);
+            : textureUsage(access.usage as GraphTextureAccess));
         usageByResource.set(
           item.value.resourceId,
           (usageByResource.get(item.value.resourceId) ?? 0) | usage,
@@ -717,7 +825,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({
@@ -891,6 +1003,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

@@ -24,6 +24,7 @@ import type {
   GraphTexture,
   GraphTextureView,
   RenderGraphFrame,
+  RenderGraphPassInstrumentation,
   RenderGraphPassRunner,
 } from './types.js';
 
@@ -82,7 +83,11 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
     return this.colorTargetDescriptors.get(name);
   }
 
-  execute(frame: FrameCtx, runPass?: RenderGraphPassRunner): Result<void, RenderGraphError> {
+  execute(
+    frame: FrameCtx,
+    runPass?: RenderGraphPassRunner,
+    instrumentation?: RenderGraphPassInstrumentation<FrameCtx>,
+  ): Result<void, RenderGraphError> {
     if (this.retired) {
       return err(
         new RenderGraphError({
@@ -101,6 +106,8 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
       const resolver = this.createPassResolver(pass, resolved.value);
       try {
         if (pass.pass.descriptor.executeIf?.(frame) === false) continue;
+        const execution = { name: pass.name, kind: pass.pass.kind, executionIndex };
+        const scope = instrumentation?.begin(execution, frame);
         let encodeResult: Result<void, RenderGraphError> = ok(undefined);
         const encode = () => {
           switch (pass.pass.kind) {
@@ -172,11 +179,14 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
                     : { stencilReadOnly: attachment.stencilReadOnly }),
                 };
               }
-              const encoder = frame.encoder.beginRenderPass({
+              const baseDescriptor = {
                 label: pass.name,
                 colorAttachments,
                 ...(depthStencilAttachment === undefined ? {} : { depthStencilAttachment }),
-              });
+              };
+              const instrumentedDescriptor =
+                scope?.renderPassDescriptor?.(baseDescriptor) ?? baseDescriptor;
+              const encoder = frame.encoder.beginRenderPass(instrumentedDescriptor);
               try {
                 descriptor.encode({ pass: encoder, frame, resources: resolver });
               } finally {
@@ -186,9 +196,13 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
             }
             case 'compute': {
               const begin = pass.pass.descriptor.begin?.(frame);
+              const instrumentedBegin = scope?.computePassDescriptor?.(begin ?? {}) ?? begin;
               let encoder: RhiComputePassEncoder;
               try {
-                encoder = frame.encoder.beginComputePass({ ...(begin ?? {}), label: pass.name });
+                encoder = frame.encoder.beginComputePass({
+                  ...(instrumentedBegin ?? {}),
+                  label: pass.name,
+                });
               } catch (cause) {
                 pass.pass.descriptor.onBeginError?.(frame, cause);
                 throw cause;
@@ -202,14 +216,19 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
               break;
             }
             case 'copy':
-              pass.pass.descriptor.encode({ encoder: frame.encoder, frame, resources: resolver });
+              scope?.beforeCopy?.(frame.encoder);
+              try {
+                pass.pass.descriptor.encode({ encoder: frame.encoder, frame, resources: resolver });
+              } finally {
+                scope?.afterCopy?.(frame.encoder);
+              }
               break;
           }
         };
         if (runPass === undefined) {
           encode();
         } else {
-          runPass({ name: pass.name, kind: pass.pass.kind, executionIndex }, encode);
+          runPass(execution, encode);
         }
         if (!encodeResult.ok) return encodeResult;
       } catch (cause) {

package/src/index.ts

@@ -97,5 +97,7 @@ export type {
   RenderGraphCompileOptions,
   RenderGraphFrame,
   RenderGraphPassExecution,
+  RenderGraphPassInstrumentation,
+  RenderGraphPassInstrumentationScope,
   RenderGraphPassRunner,
 } from './types.js';

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

@@ -1,6 +1,7 @@
 import type {
   Buffer,
   ComputePassDescriptor,
+  RenderPassDescriptor,
   RhiCommandEncoder,
   RhiComputePassEncoder,
   RhiDevice,
@@ -45,7 +46,7 @@ export type GraphExtent =
 export interface GraphTextureDescriptor {
   readonly format: TextureFormat;
   readonly size: GraphExtent;
-  /** Additional RHI usage required by an external diagnostic consumer. */
+  /** Additional RHI usage required by an external diagnostic consumer such as readback. */
   readonly usage?: number | undefined;
   readonly mipLevelCount?: number | undefined;
   readonly sampleCount?: number | undefined;
@@ -97,6 +98,7 @@ export type GraphTextureAccess =
   | 'storage-read'
   | 'storage-write'
   | 'storage-read-write'
+  | 'sampled-storage-read-write'
   | 'color-attachment'
   | 'depth-stencil-read'
   | 'depth-stencil-write'
@@ -215,7 +217,20 @@ export interface CompiledRenderGraphInfo {
     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 {
@@ -230,13 +245,36 @@ export interface RenderGraphPassExecution {
 
 export type RenderGraphPassRunner = (pass: RenderGraphPassExecution, encode: () => void) => void;
 
+/**
+ * The graph-neutral boundary for observing and decorating an actual pass.
+ * Render owns the policy supplied here; the graph only preserves pass
+ * provenance and the existing encoder boundaries.
+ */
+export interface RenderGraphPassInstrumentationScope {
+  readonly renderPassDescriptor?: (descriptor: RenderPassDescriptor) => RenderPassDescriptor;
+  readonly computePassDescriptor?: (descriptor: ComputePassDescriptor) => ComputePassDescriptor;
+  readonly beforeCopy?: (encoder: RhiCommandEncoder) => void;
+  readonly afterCopy?: (encoder: RhiCommandEncoder) => void;
+}
+
+export interface RenderGraphPassInstrumentation<FrameCtx extends RenderGraphFrame> {
+  begin(
+    pass: RenderGraphPassExecution,
+    frame: FrameCtx,
+  ): RenderGraphPassInstrumentationScope | undefined;
+}
+
 export interface RenderGraphCompileOptions {
   readonly device: RhiDevice;
   readonly surfaceSize: { readonly width: number; readonly height: number };
 }
 
 export interface CompiledRenderGraph<FrameCtx extends RenderGraphFrame> {
-  execute(frame: FrameCtx, runPass?: RenderGraphPassRunner): Result<void, RenderGraphError>;
+  execute(
+    frame: FrameCtx,
+    runPass?: RenderGraphPassRunner,
+    instrumentation?: RenderGraphPassInstrumentation<FrameCtx>,
+  ): Result<void, RenderGraphError>;
   inspect(): CompiledRenderGraphInfo;
   retire(): Promise<Result<void, RenderGraphError>>;
 }