@forgeax/engine-render-graph 0.1.7 → 0.1.20

package/dist/index.mjs

@@ -57,7 +57,7 @@ function resolutionError(label, cause) {
   });
 }
 var CompiledRenderGraphImpl = class {
-  constructor(generation, owner, device, resources, views, passes, info) {
+  constructor(generation, owner, device, resources, views, passes, info, colorTargetDescriptors) {
     this.generation = generation;
     this.owner = owner;
     this.device = device;
@@ -65,6 +65,7 @@ var CompiledRenderGraphImpl = class {
     this.views = views;
     this.passes = passes;
     this.info = info;
+    this.colorTargetDescriptors = colorTargetDescriptors;
   }
   generation;
   owner;
@@ -73,11 +74,28 @@ var CompiledRenderGraphImpl = class {
   views;
   passes;
   info;
+  colorTargetDescriptors;
   retired = false;
   retireResult;
   inspect() {
     return this.info;
   }
+  getColorTargetView(name) {
+    for (const view of this.views.values()) {
+      const resource = this.resources.get(view.record.textureId);
+      if (resource?.record.label === name) return view.view;
+    }
+    return void 0;
+  }
+  getColorTargetTexture(name) {
+    for (const resource of this.resources.values()) {
+      if (resource.record.label === name) return resource.texture;
+    }
+    return void 0;
+  }
+  getColorTargetDescriptor(name) {
+    return this.colorTargetDescriptors.get(name);
+  }
   execute(frame, runPass) {
     if (this.retired) {
       return err(
@@ -346,6 +364,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,
@@ -364,6 +485,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":
@@ -392,6 +528,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":
@@ -405,6 +543,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":
@@ -421,7 +560,13 @@ function rangesOverlap(left, right) {
   return aspectOverlap && left.mipStart < right.mipEnd && right.mipStart < left.mipEnd && left.layerStart < right.layerEnd && right.layerStart < left.layerEnd;
 }
 function freezeInfo(info) {
+  const freezeDescriptor = (descriptor) => {
+    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({
@@ -431,7 +576,14 @@ function freezeInfo(info) {
         })
       )
     ),
-    resources: Object.freeze(info.resources.map((resource) => Object.freeze({ ...resource })))
+    resources: Object.freeze(
+      info.resources.map(
+        (resource) => Object.freeze({
+          ...resource,
+          descriptor: freezeDescriptor(resource.descriptor)
+        })
+      )
+    )
   });
 }
 var RenderGraphBuilder = class {
@@ -563,7 +715,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,
@@ -579,15 +744,60 @@ 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,
-        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()) {
+      if (resource.record.kind !== "texture" || resource.texture === void 0) 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++,
@@ -596,7 +806,8 @@ var RenderGraphBuilder = class {
         allocated.value.resources,
         allocated.value.views,
         Object.freeze(analyzed.value.passes),
-        info
+        info,
+        colorTargetDescriptors
       )
     );
   }
@@ -641,6 +852,11 @@ var RenderGraphBuilder = class {
     const lastUseByResource = /* @__PURE__ */ new Map();
     const compiledPasses = [];
     const history = [];
+    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 === void 0) continue;
@@ -822,7 +1038,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({
@@ -966,6 +1183,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) {
@@ -1299,104 +1537,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)}`;