@forgeax/engine-render-graph 0.1.21 → 0.1.23

package/README.md

@@ -107,6 +107,40 @@ label. Compute work that targets the parent command encoder, such as resolving t
 belongs in `after`; pass commands remain in `encode`. `onBeginError` lets the pass owner terminalize
 feature-local evidence before the graph returns `pass-encode-failed`.
 
+### Pass instrumentation
+
+Renderer-owned instrumentation may be supplied as the third argument to
+`compiled.execute(frame, runPass, instrumentation)`. The graph calls
+`instrumentation.begin` immediately before each executable pass and applies the
+returned descriptor decorator at the actual `beginRenderPass` or
+`beginComputePass` boundary. This is the single seam for pass-level timestamp
+queries and similar graph-neutral observation; it preserves pass name, kind, and
+execution index without moving timing policy into the graph.
+
+```ts
+compiled.execute(frame, undefined, {
+  begin: (pass) =>
+    pass.kind === 'compute'
+      ? {
+          computePassDescriptor: (descriptor) => ({
+            ...descriptor,
+            timestampWrites: {
+              querySet,
+              beginningOfPassWriteIndex: 0,
+              endOfPassWriteIndex: 1,
+            },
+          }),
+        }
+      : undefined,
+});
+```
+
+The graph never calls a backend-specific command-encoder timestamp helper.
+Pass instrumentation must preserve any producer-owned descriptor facts; a
+policy owner that cannot merge an existing `timestampWrites` pair should fail
+closed instead of overwriting it. Copy passes expose `beforeCopy`/`afterCopy`
+hooks for non-timing instrumentation, but WebGPU has no portable copy-pass
+timestamp descriptor.
 > [!NOTE]
 > `timestampWrites` and an `after(frame)` callback are neutral graph seams. They
 > let a pipeline owner place a backend command at a declared pass boundary, but

package/dist/compiled-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiled-graph.d.ts","sourceRoot":"","sources":["../src/compiled-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,SAAS,EACT,OAAO,EACP,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAW,gBAAgB,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,EAEb,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EAKvB,gBAAgB,EAChB,8BAA8B,EAC9B,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAiBpB,qBAAa,uBAAuB,CAAC,QAAQ,SAAS,gBAAgB,CACpE,YAAW,mBAAmB,CAAC,QAAQ,CAAC;IAMtC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,sBAAsB;IAXzC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAsD;gBAGvD,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC,EAC1D,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,EAClD,MAAM,EAAE,SAAS,YAAY,CAAC,QAAQ,CAAC,EAAE,EACzC,IAAI,EAAE,uBAAuB,EAC7B,sBAAsB,EAAE,WAAW,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAG7F,OAAO,IAAI,uBAAuB;IAIlC,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAQzD,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAOxD,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,6BAA6B,GAAG,SAAS;IAIjF,OAAO,CACL,KAAK,EAAE,QAAQ,EACf,OAAO,CAAC,EAAE,qBAAqB,EAC/B,eAAe,CAAC,EAAE,8BAA8B,CAAC,QAAQ,CAAC,GACzD,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC;IA8JjC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;YAOnC,YAAY;IA+C1B,OAAO,CAAC,qBAAqB;IAiD7B,OAAO,CAAC,kBAAkB;CAwE3B"}
+{"version":3,"file":"compiled-graph.d.ts","sourceRoot":"","sources":["../src/compiled-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,SAAS,EACT,OAAO,EACP,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAW,gBAAgB,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,EAEb,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EAKvB,gBAAgB,EAChB,8BAA8B,EAC9B,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAiBpB,qBAAa,uBAAuB,CAAC,QAAQ,SAAS,gBAAgB,CACpE,YAAW,mBAAmB,CAAC,QAAQ,CAAC;IAMtC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,sBAAsB;IAXzC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAsD;gBAGvD,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC,EAC1D,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,EAClD,MAAM,EAAE,SAAS,YAAY,CAAC,QAAQ,CAAC,EAAE,EACzC,IAAI,EAAE,uBAAuB,EAC7B,sBAAsB,EAAE,WAAW,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAG7F,OAAO,IAAI,uBAAuB;IAIlC,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAQzD,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAOxD,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,6BAA6B,GAAG,SAAS;IAIjF,OAAO,CACL,KAAK,EAAE,QAAQ,EACf,OAAO,CAAC,EAAE,qBAAqB,EAC/B,eAAe,CAAC,EAAE,8BAA8B,CAAC,QAAQ,CAAC,GACzD,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAqKjC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;YAOnC,YAAY;IA+C1B,OAAO,CAAC,qBAAqB;IAiD7B,OAAO,CAAC,kBAAkB;CAwE3B"}

package/dist/index.mjs

@@ -114,9 +114,9 @@ var CompiledRenderGraphImpl = class {
       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 = () => {
+          const scope = instrumentation?.begin(execution, frame);
           switch (pass.pass.kind) {
             case "raster": {
               const descriptor = pass.pass.descriptor;
@@ -165,7 +165,8 @@ var CompiledRenderGraphImpl = class {
               const baseDescriptor = {
                 label: pass.name,
                 colorAttachments,
-                ...depthStencilAttachment === void 0 ? {} : { depthStencilAttachment }
+                ...depthStencilAttachment === void 0 ? {} : { depthStencilAttachment },
+                ...pass.pass.descriptor.occlusionQuerySet === void 0 ? {} : { occlusionQuerySet: pass.pass.descriptor.occlusionQuerySet }
               };
               const instrumentedDescriptor = scope?.renderPassDescriptor?.(baseDescriptor) ?? baseDescriptor;
               const encoder = frame.encoder.beginRenderPass(instrumentedDescriptor);