@forgeax/engine-render-graph 0.1.19 → 0.1.21

package/dist/index.mjs

@@ -96,7 +96,7 @@ var CompiledRenderGraphImpl = class {
   getColorTargetDescriptor(name) {
     return this.colorTargetDescriptors.get(name);
   }
-  execute(frame, runPass) {
+  execute(frame, runPass, instrumentation) {
     if (this.retired) {
       return err(
         new RenderGraphError({
@@ -113,6 +113,8 @@ var CompiledRenderGraphImpl = class {
       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 = ok(void 0);
         const encode = () => {
           switch (pass.pass.kind) {
@@ -160,11 +162,13 @@ var CompiledRenderGraphImpl = class {
                   ...attachment.stencilReadOnly === void 0 ? {} : { stencilReadOnly: attachment.stencilReadOnly }
                 };
               }
-              const encoder = frame.encoder.beginRenderPass({
+              const baseDescriptor = {
                 label: pass.name,
                 colorAttachments,
                 ...depthStencilAttachment === void 0 ? {} : { depthStencilAttachment }
-              });
+              };
+              const instrumentedDescriptor = scope?.renderPassDescriptor?.(baseDescriptor) ?? baseDescriptor;
+              const encoder = frame.encoder.beginRenderPass(instrumentedDescriptor);
               try {
                 descriptor.encode({ pass: encoder, frame, resources: resolver });
               } finally {
@@ -174,9 +178,13 @@ var CompiledRenderGraphImpl = class {
             }
             case "compute": {
               const begin = pass.pass.descriptor.begin?.(frame);
+              const instrumentedBegin = scope?.computePassDescriptor?.(begin ?? {}) ?? begin;
               let encoder;
               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;
@@ -190,14 +198,19 @@ var CompiledRenderGraphImpl = class {
               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 === void 0) {
           encode();
         } else {
-          runPass({ name: pass.name, kind: pass.pass.kind, executionIndex }, encode);
+          runPass(execution, encode);
         }
         if (!encodeResult.ok) return encodeResult;
       } catch (cause) {
@@ -364,6 +377,109 @@ var CompiledRenderGraphImpl = class {
   }
 };
 
+// src/resource-registry.ts
+function isTextureViewDimensionCompatible(allocationDimension, viewDimension) {
+  if (viewDimension === void 0) return true;
+  if (allocationDimension === "3d") return viewDimension === "3d";
+  return viewDimension !== "3d";
+}
+var ResourceRegistry = class {
+  resources = /* @__PURE__ */ new Map();
+  add(key, descriptor) {
+    const entry = {
+      key,
+      descriptor,
+      lifetime: descriptor.lifetime
+    };
+    return this.register(entry);
+  }
+  /**
+   * Register a color target resource (D-8).
+   * Same semantics as addResource with kind:'texture' plus GPU texture
+   * allocation metadata. Existing callers default to a transient target.
+   */
+  addColorTarget(name, desc) {
+    const lifetime = desc.lifetime ?? "transient";
+    const colorTargetMeta = {
+      format: desc.format,
+      size: desc.size,
+      sample: desc.sample ?? 1,
+      usage: desc.usage ?? 16 | 4,
+      // RENDER_ATTACHMENT | TEXTURE_BINDING
+      ...desc.domain !== void 0 ? { domain: desc.domain } : {},
+      ...desc.viewFormats !== void 0 ? { viewFormats: desc.viewFormats } : {}
+    };
+    const entry = {
+      key: name,
+      descriptor: { kind: "texture", lifetime },
+      lifetime,
+      colorTarget: colorTargetMeta
+    };
+    return this.register(entry);
+  }
+  /**
+   * Register a color target alias that folds into the source's physical
+   * texture at compile time (KB-1 MoveNode pattern, D-2).
+   * The source must already be registered via addColorTarget.
+   */
+  addColorTargetAlias(name, source) {
+    if (this.resources.has(name)) return this.duplicateResource(name);
+    const sourceMeta = this.resources.get(source)?.colorTarget;
+    if (sourceMeta === void 0) {
+      return err(
+        new RenderGraphError({
+          code: "alias-source-missing",
+          expected: `alias '${name}' source '${source}' must be a registered color target`,
+          hint: `call addColorTarget('${source}', ...) before retrying alias '${name}'`,
+          detail: { aliasKey: name, sourceKey: source }
+        })
+      );
+    }
+    const entry = {
+      key: name,
+      descriptor: { kind: "texture", lifetime: "transient" },
+      lifetime: "transient",
+      colorTarget: {
+        format: sourceMeta.format,
+        size: sourceMeta.size,
+        sample: sourceMeta.sample,
+        usage: sourceMeta.usage,
+        ...sourceMeta.domain !== void 0 ? { domain: sourceMeta.domain } : {},
+        ...sourceMeta.viewFormats !== void 0 ? { viewFormats: sourceMeta.viewFormats } : {},
+        aliasedFrom: source
+      }
+    };
+    return this.register(entry);
+  }
+  duplicateResource(key) {
+    return err(
+      new RenderGraphError({
+        code: "duplicate-resource",
+        expected: `resource key '${key}' registered exactly once`,
+        hint: `remove the duplicate resource declaration for '${key}' or use a different key`,
+        detail: { resourceKey: key }
+      })
+    );
+  }
+  register(entry) {
+    if (this.resources.has(entry.key)) return this.duplicateResource(entry.key);
+    this.resources.set(entry.key, entry);
+    return ok(entry);
+  }
+  get(key) {
+    return this.resources.get(key);
+  }
+  getColorTargetMeta(key) {
+    return this.resources.get(key)?.colorTarget;
+  }
+  has(key) {
+    return this.resources.has(key);
+  }
+  entries() {
+    return this.resources.values();
+  }
+};
+
 // src/builder.ts
 var BUFFER_USAGE = {
   copySrc: 4,
@@ -382,6 +498,21 @@ var TEXTURE_USAGE = {
   renderAttachment: 16
 };
 var nextGeneration = 1;
+function textureByteSize(format, extent, mipLevelCount) {
+  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 : void 0;
+  if (bytesPerTexel === void 0) return void 0;
+  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;
+}
 function bufferUsage(access) {
   switch (access) {
     case "uniform-read":
@@ -410,6 +541,8 @@ function textureUsage(access) {
     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":
@@ -423,6 +556,7 @@ function textureUsage(access) {
 function accessMode(access) {
   switch (access) {
     case "storage-read-write":
+    case "sampled-storage-read-write":
       return { read: true, write: true };
     case "storage-write":
     case "color-attachment":
@@ -445,6 +579,7 @@ function freezeInfo(info) {
     return Object.freeze({ ...descriptor, size });
   };
   return Object.freeze({
+    generation: info.generation,
     passes: Object.freeze(
       info.passes.map(
         (pass) => Object.freeze({
@@ -593,7 +728,20 @@ var RenderGraphBuilder = class {
       analyzed.value.lastUseByResource
     );
     if (!allocated.ok) return allocated;
+    const generation = nextGeneration;
+    const physicalAllocationKeys = /* @__PURE__ */ new WeakMap();
+    let nextPhysicalAllocationKey = 1;
+    const physicalKey = (resource) => {
+      const handle = resource.texture ?? resource.buffer;
+      if (handle === void 0) return void 0;
+      const existing = physicalAllocationKeys.get(handle);
+      if (existing !== void 0) 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,
@@ -609,26 +757,47 @@ var RenderGraphBuilder = class {
           (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: resource.record.kind === "texture" ? {
-          kind: "texture",
-          format: resource.record.descriptor.format,
-          ...resource.record.descriptor.domain === void 0 ? {} : { 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
-        } : {
-          kind: "buffer",
-          size: resource.record.descriptor.size
-        },
-        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 : void 0;
+        const buffer = resource.record.kind === "buffer" ? resource.record.descriptor : void 0;
+        const allocationKey = physicalKey(resource);
+        const extent = texture === void 0 ? void 0 : this.resolveExtent(texture.size, options.surfaceSize);
+        return {
+          label: resource.record.label,
+          kind: resource.record.kind,
+          origin: resource.record.origin,
+          descriptor: texture === void 0 ? {
+            kind: "buffer",
+            size: buffer?.size ?? 0
+          } : {
+            kind: "texture",
+            format: texture.format,
+            ...texture.domain === void 0 ? {} : { 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 === void 0 ? {} : { physicalAllocationKey: allocationKey },
+          ...texture === void 0 ? {} : { format: texture.format },
+          ...texture === void 0 ? buffer === void 0 ? {} : { byteSize: buffer.size } : {
+            byteSize: textureByteSize(
+              texture.format,
+              this.resolveExtent(texture.size, options.surfaceSize),
+              texture.mipLevelCount ?? 1
+            )
+          },
+          ...texture === void 0 ? {} : {
+            dimension: texture.dimension ?? "2d",
+            extent
+          }
+        };
+      })
     });
     const colorTargetDescriptors = /* @__PURE__ */ new Map();
     for (const resource of allocated.value.resources.values()) {
@@ -711,7 +880,8 @@ var RenderGraphBuilder = class {
         const item = this.normalizeAccess(passIndex, pass, access);
         if (!item.ok) return item;
         normalized.push(item.value);
-        const usage = this.resources.get(item.value.resourceId)?.kind === "buffer" ? bufferUsage(access.usage) : textureUsage(access.usage);
+        const resource = this.resources.get(item.value.resourceId);
+        const usage = (resource?.kind === "texture" && resource.origin === "created" ? resource.descriptor.usage ?? 0 : 0) | (resource?.kind === "buffer" ? bufferUsage(access.usage) : textureUsage(access.usage));
         usageByResource.set(
           item.value.resourceId,
           (usageByResource.get(item.value.resourceId) ?? 0) | usage
@@ -882,7 +1052,8 @@ var RenderGraphBuilder = class {
           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({
@@ -1026,6 +1197,27 @@ var RenderGraphBuilder = class {
         }
       }
     }
+    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(void 0);
   }
   allocate(options, usageByResource, firstUseByResource, lastUseByResource) {
@@ -1359,104 +1551,6 @@ function validateColorDomainConnection(source, destination, conversion) {
   };
 }
 
-// src/resource-registry.ts
-var ResourceRegistry = class {
-  resources = /* @__PURE__ */ new Map();
-  add(key, descriptor) {
-    const entry = {
-      key,
-      descriptor,
-      lifetime: descriptor.lifetime
-    };
-    return this.register(entry);
-  }
-  /**
-   * Register a color target resource (D-8).
-   * Same semantics as addResource with kind:'texture' plus GPU texture
-   * allocation metadata. Existing callers default to a transient target.
-   */
-  addColorTarget(name, desc) {
-    const lifetime = desc.lifetime ?? "transient";
-    const colorTargetMeta = {
-      format: desc.format,
-      size: desc.size,
-      sample: desc.sample ?? 1,
-      usage: desc.usage ?? 16 | 4,
-      // RENDER_ATTACHMENT | TEXTURE_BINDING
-      ...desc.domain !== void 0 ? { domain: desc.domain } : {},
-      ...desc.viewFormats !== void 0 ? { viewFormats: desc.viewFormats } : {}
-    };
-    const entry = {
-      key: name,
-      descriptor: { kind: "texture", lifetime },
-      lifetime,
-      colorTarget: colorTargetMeta
-    };
-    return this.register(entry);
-  }
-  /**
-   * Register a color target alias that folds into the source's physical
-   * texture at compile time (KB-1 MoveNode pattern, D-2).
-   * The source must already be registered via addColorTarget.
-   */
-  addColorTargetAlias(name, source) {
-    if (this.resources.has(name)) return this.duplicateResource(name);
-    const sourceMeta = this.resources.get(source)?.colorTarget;
-    if (sourceMeta === void 0) {
-      return err(
-        new RenderGraphError({
-          code: "alias-source-missing",
-          expected: `alias '${name}' source '${source}' must be a registered color target`,
-          hint: `call addColorTarget('${source}', ...) before retrying alias '${name}'`,
-          detail: { aliasKey: name, sourceKey: source }
-        })
-      );
-    }
-    const entry = {
-      key: name,
-      descriptor: { kind: "texture", lifetime: "transient" },
-      lifetime: "transient",
-      colorTarget: {
-        format: sourceMeta.format,
-        size: sourceMeta.size,
-        sample: sourceMeta.sample,
-        usage: sourceMeta.usage,
-        ...sourceMeta.domain !== void 0 ? { domain: sourceMeta.domain } : {},
-        ...sourceMeta.viewFormats !== void 0 ? { viewFormats: sourceMeta.viewFormats } : {},
-        aliasedFrom: source
-      }
-    };
-    return this.register(entry);
-  }
-  duplicateResource(key) {
-    return err(
-      new RenderGraphError({
-        code: "duplicate-resource",
-        expected: `resource key '${key}' registered exactly once`,
-        hint: `remove the duplicate resource declaration for '${key}' or use a different key`,
-        detail: { resourceKey: key }
-      })
-    );
-  }
-  register(entry) {
-    if (this.resources.has(entry.key)) return this.duplicateResource(entry.key);
-    this.resources.set(entry.key, entry);
-    return ok(entry);
-  }
-  get(key) {
-    return this.resources.get(key);
-  }
-  getColorTargetMeta(key) {
-    return this.resources.get(key)?.colorTarget;
-  }
-  has(key) {
-    return this.resources.has(key);
-  }
-  entries() {
-    return this.resources.values();
-  }
-};
-
 // src/graph.ts
 function poolKey(meta) {
   return `${meta.format}:${meta.width}x${meta.height}:${meta.usage}:${meta.sample}:${JSON.stringify(meta.viewFormats)}`;