@zephyr3d/scene 0.9.14 → 0.9.15

package/dist/render/rendergraph/device_pool_allocator.js

@@ -1,29 +1,36 @@
 import { getDevice } from '../../app/api.js';
 
-/**
- * Bridges the render graph's {@link RGTextureAllocator} interface to the
- * engine's device resource pool (`device.pool`).
- *
- * Transient textures are fetched from the pool on `allocate()` and
- * returned to the pool on `release()`, enabling automatic reuse
- * across frames without manual lifecycle management.
- *
- * Usage:
- * ```ts
- * const allocator = new DevicePoolAllocator();
- * const executor = new RenderGraphExecutor(allocator, width, height);
- * ```
- *
- * @public
+/**
+ * Bridges the render graph's {@link RGTextureAllocator} interface to the
+ * engine's device resource pool (`device.pool`).
+ *
+ * Transient textures are fetched from the pool on `allocate()` and
+ * returned to the pool on `release()`, enabling automatic reuse
+ * across frames without manual lifecycle management.
+ *
+ * Usage:
+ * ```ts
+ * const allocator = new DevicePoolAllocator();
+ * const executor = new RenderGraphExecutor(allocator, width, height);
+ * ```
+ *
+ * @public
  */ class DevicePoolAllocator {
-    /**
-   * Allocate a transient texture from the device pool.
-   *
-   * @param desc - Texture descriptor from the render graph pass.
-   * @param size - Resolved pixel dimensions.
-   * @returns A pooled Texture2D instance.
+    _device;
+    /**
+   * Creates a new instance of the DevicePoolAllocator.
+   * @param device - Optional device instance to use for resource allocation. If not provided, the global device will be used.
+   */ constructor(device){
+        this._device = device ?? null;
+    }
+    /**
+   * Allocate a transient texture from the device pool.
+   *
+   * @param desc - Texture descriptor from the render graph pass.
+   * @param size - Resolved pixel dimensions.
+   * @returns A pooled Texture2D instance.
    */ allocate(desc, size) {
-        const device = getDevice();
+        const device = this._device ?? getDevice();
         const mipmapping = (desc.mipLevels ?? 1) > 1;
         const texture = device.pool.fetchTemporalTexture2D(false, desc.format, size.width, size.height, mipmapping);
         if (desc.mipLevels && texture.mipLevelCount < desc.mipLevels) {
@@ -32,41 +39,41 @@ import { getDevice } from '../../app/api.js';
         }
         return texture;
     }
-    /**
-   * Release a transient texture back to the device pool.
-   *
-   * @param texture - The texture to release.
+    /**
+   * Release a transient texture back to the device pool.
+   *
+   * @param texture - The texture to release.
    */ release(texture) {
-        const device = getDevice();
+        const device = this._device ?? getDevice();
         device.pool.releaseTexture(texture);
     }
-    /**
-   * Retain a pooled texture so it can be owned outside the graph lifetime.
-   *
-   * @param texture - The texture to retain.
+    /**
+   * Retain a pooled texture so it can be owned outside the graph lifetime.
+   *
+   * @param texture - The texture to retain.
    */ retain(texture) {
-        const device = getDevice();
+        const device = this._device ?? getDevice();
         device.pool.retainTexture(texture);
     }
-    /**
-   * Allocate a temporary framebuffer from the device pool.
-   *
-   * @param desc - Framebuffer descriptor from the render graph pass.
-   * @returns A pooled FrameBuffer instance.
+    /**
+   * Allocate a temporary framebuffer from the device pool.
+   *
+   * @param desc - Framebuffer descriptor from the render graph pass.
+   * @returns A pooled FrameBuffer instance.
    */ allocateFramebuffer(desc) {
-        const device = getDevice();
+        const device = this._device ?? getDevice();
         const colors = Array.isArray(desc.colorAttachments) ? desc.colorAttachments : desc.colorAttachments ? [
             desc.colorAttachments
         ] : [];
         const depthAttachment = desc.depthAttachment ?? null;
         return device.pool.fetchTemporalFramebuffer(false, desc.width ?? 0, desc.height ?? 0, colors, depthAttachment, desc.mipmapping ?? false, desc.sampleCount ?? 1, desc.ignoreDepthStencil ?? true, desc.attachmentMipLevel ?? 0, desc.attachmentCubeface ?? 0, desc.attachmentLayer ?? 0);
     }
-    /**
-   * Release a temporary framebuffer back to the device pool.
-   *
-   * @param framebuffer - The framebuffer to release.
+    /**
+   * Release a temporary framebuffer back to the device pool.
+   *
+   * @param framebuffer - The framebuffer to release.
    */ releaseFramebuffer(framebuffer) {
-        const device = getDevice();
+        const device = this._device ?? getDevice();
         device.pool.releaseFrameBuffer(framebuffer);
     }
 }

package/dist/render/rendergraph/device_pool_allocator.js.map

@@ -1 +1 @@
-{"version":3,"file":"device_pool_allocator.js","sources":["../../../src/render/rendergraph/device_pool_allocator.ts"],"sourcesContent":["import type { FrameBuffer, Texture2D, TextureFormat } from '@zephyr3d/device';\r\nimport type { RGFramebufferDesc, RGTextureAllocator, RGTextureDesc, RGResolvedSize } from './types';\r\nimport { getDevice } from '../../app/api';\r\n\r\n/**\r\n * Bridges the render graph's {@link RGTextureAllocator} interface to the\r\n * engine's device resource pool (`device.pool`).\r\n *\r\n * Transient textures are fetched from the pool on `allocate()` and\r\n * returned to the pool on `release()`, enabling automatic reuse\r\n * across frames without manual lifecycle management.\r\n *\r\n * Usage:\r\n * ```ts\r\n * const allocator = new DevicePoolAllocator();\r\n * const executor = new RenderGraphExecutor(allocator, width, height);\r\n * ```\r\n *\r\n * @public\r\n */\r\nexport class DevicePoolAllocator implements RGTextureAllocator<Texture2D, FrameBuffer> {\r\n  /**\r\n   * Allocate a transient texture from the device pool.\r\n   *\r\n   * @param desc - Texture descriptor from the render graph pass.\r\n   * @param size - Resolved pixel dimensions.\r\n   * @returns A pooled Texture2D instance.\r\n   */\r\n  allocate(desc: RGTextureDesc, size: RGResolvedSize): Texture2D {\r\n    const device = getDevice();\r\n    const mipmapping = (desc.mipLevels ?? 1) > 1;\r\n    const texture = device.pool.fetchTemporalTexture2D(\r\n      false,\r\n      desc.format,\r\n      size.width,\r\n      size.height,\r\n      mipmapping\r\n    );\r\n    if (desc.mipLevels && texture.mipLevelCount < desc.mipLevels) {\r\n      device.pool.releaseTexture(texture);\r\n      throw new Error(\r\n        `DevicePoolAllocator: texture \"${desc.label ?? '<unnamed>'}\" requested ${desc.mipLevels} ` +\r\n          `mip levels, but only ${texture.mipLevelCount} were allocated.`\r\n      );\r\n    }\r\n    return texture;\r\n  }\r\n\r\n  /**\r\n   * Release a transient texture back to the device pool.\r\n   *\r\n   * @param texture - The texture to release.\r\n   */\r\n  release(texture: Texture2D): void {\r\n    const device = getDevice();\r\n    device.pool.releaseTexture(texture);\r\n  }\r\n\r\n  /**\r\n   * Retain a pooled texture so it can be owned outside the graph lifetime.\r\n   *\r\n   * @param texture - The texture to retain.\r\n   */\r\n  retain(texture: Texture2D): void {\r\n    const device = getDevice();\r\n    device.pool.retainTexture(texture);\r\n  }\r\n\r\n  /**\r\n   * Allocate a temporary framebuffer from the device pool.\r\n   *\r\n   * @param desc - Framebuffer descriptor from the render graph pass.\r\n   * @returns A pooled FrameBuffer instance.\r\n   */\r\n  allocateFramebuffer(desc: RGFramebufferDesc): FrameBuffer {\r\n    const device = getDevice();\r\n    const colors = Array.isArray(desc.colorAttachments)\r\n      ? (desc.colorAttachments as Array<Texture2D | TextureFormat>)\r\n      : desc.colorAttachments\r\n        ? [desc.colorAttachments as Texture2D | TextureFormat]\r\n        : [];\r\n    const depthAttachment = (desc.depthAttachment ?? null) as Texture2D | TextureFormat | null;\r\n    return device.pool.fetchTemporalFramebuffer(\r\n      false,\r\n      desc.width ?? 0,\r\n      desc.height ?? 0,\r\n      colors,\r\n      depthAttachment,\r\n      desc.mipmapping ?? false,\r\n      desc.sampleCount ?? 1,\r\n      desc.ignoreDepthStencil ?? true,\r\n      desc.attachmentMipLevel ?? 0,\r\n      desc.attachmentCubeface ?? 0,\r\n      desc.attachmentLayer ?? 0\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Release a temporary framebuffer back to the device pool.\r\n   *\r\n   * @param framebuffer - The framebuffer to release.\r\n   */\r\n  releaseFramebuffer(framebuffer: FrameBuffer): void {\r\n    const device = getDevice();\r\n    device.pool.releaseFrameBuffer(framebuffer);\r\n  }\r\n}\r\n"],"names":["DevicePoolAllocator","allocate","desc","size","device","getDevice","mipmapping","mipLevels","texture","pool","fetchTemporalTexture2D","format","width","height","mipLevelCount","releaseTexture","Error","label","release","retain","retainTexture","allocateFramebuffer","colors","Array","isArray","colorAttachments","depthAttachment","fetchTemporalFramebuffer","sampleCount","ignoreDepthStencil","attachmentMipLevel","attachmentCubeface","attachmentLayer","releaseFramebuffer","framebuffer","releaseFrameBuffer"],"mappings":";;AAIA;;;;;;;;;;;;;;;AAeC,IACM,MAAMA,mBAAAA,CAAAA;AACX;;;;;;AAMC,MACDC,QAASC,CAAAA,IAAmB,EAAEC,IAAoB,EAAa;AAC7D,QAAA,MAAMC,MAASC,GAAAA,SAAAA,EAAAA;AACf,QAAA,MAAMC,aAAa,CAACJ,KAAKK,SAAS,IAAI,CAAA,IAAK,CAAA;AAC3C,QAAA,MAAMC,OAAUJ,GAAAA,MAAAA,CAAOK,IAAI,CAACC,sBAAsB,CAChD,KAAA,EACAR,IAAKS,CAAAA,MAAM,EACXR,IAAKS,CAAAA,KAAK,EACVT,IAAAA,CAAKU,MAAM,EACXP,UAAAA,CAAAA;QAEF,IAAIJ,IAAAA,CAAKK,SAAS,IAAIC,OAAAA,CAAQM,aAAa,GAAGZ,IAAAA,CAAKK,SAAS,EAAE;YAC5DH,MAAOK,CAAAA,IAAI,CAACM,cAAc,CAACP,OAAAA,CAAAA;YAC3B,MAAM,IAAIQ,KACR,CAAA,CAAC,8BAA8B,EAAEd,KAAKe,KAAK,IAAI,WAAY,CAAA,YAAY,EAAEf,IAAAA,CAAKK,SAAS,CAAC,CAAC,CAAC,GACxF,CAAC,qBAAqB,EAAEC,OAAQM,CAAAA,aAAa,CAAC,gBAAgB,CAAC,CAAA;AAErE;QACA,OAAON,OAAAA;AACT;AAEA;;;;MAKAU,OAAAA,CAAQV,OAAkB,EAAQ;AAChC,QAAA,MAAMJ,MAASC,GAAAA,SAAAA,EAAAA;QACfD,MAAOK,CAAAA,IAAI,CAACM,cAAc,CAACP,OAAAA,CAAAA;AAC7B;AAEA;;;;MAKAW,MAAAA,CAAOX,OAAkB,EAAQ;AAC/B,QAAA,MAAMJ,MAASC,GAAAA,SAAAA,EAAAA;QACfD,MAAOK,CAAAA,IAAI,CAACW,aAAa,CAACZ,OAAAA,CAAAA;AAC5B;AAEA;;;;;MAMAa,mBAAAA,CAAoBnB,IAAuB,EAAe;AACxD,QAAA,MAAME,MAASC,GAAAA,SAAAA,EAAAA;AACf,QAAA,MAAMiB,MAASC,GAAAA,KAAAA,CAAMC,OAAO,CAACtB,IAAKuB,CAAAA,gBAAgB,CAC7CvB,GAAAA,IAAAA,CAAKuB,gBAAgB,GACtBvB,IAAKuB,CAAAA,gBAAgB,GACnB;AAACvB,YAAAA,IAAAA,CAAKuB;AAA8C,SAAA,GACpD,EAAE;QACR,MAAMC,eAAAA,GAAmBxB,IAAKwB,CAAAA,eAAe,IAAI,IAAA;AACjD,QAAA,OAAOtB,OAAOK,IAAI,CAACkB,wBAAwB,CACzC,OACAzB,IAAKU,CAAAA,KAAK,IAAI,CAAA,EACdV,KAAKW,MAAM,IAAI,GACfS,MACAI,EAAAA,eAAAA,EACAxB,KAAKI,UAAU,IAAI,KACnBJ,EAAAA,IAAAA,CAAK0B,WAAW,IAAI,CAAA,EACpB1B,IAAK2B,CAAAA,kBAAkB,IAAI,IAC3B3B,EAAAA,IAAAA,CAAK4B,kBAAkB,IAAI,GAC3B5B,IAAK6B,CAAAA,kBAAkB,IAAI,CAC3B7B,EAAAA,IAAAA,CAAK8B,eAAe,IAAI,CAAA,CAAA;AAE5B;AAEA;;;;MAKAC,kBAAAA,CAAmBC,WAAwB,EAAQ;AACjD,QAAA,MAAM9B,MAASC,GAAAA,SAAAA,EAAAA;QACfD,MAAOK,CAAAA,IAAI,CAAC0B,kBAAkB,CAACD,WAAAA,CAAAA;AACjC;AACF;;;;"}
+{"version":3,"file":"device_pool_allocator.js","sources":["../../../src/render/rendergraph/device_pool_allocator.ts"],"sourcesContent":["import type { FrameBuffer, Texture2D, TextureFormat, AbstractDevice } from '@zephyr3d/device';\nimport type { RGFramebufferDesc, RGTextureAllocator, RGTextureDesc, RGResolvedSize } from './types';\nimport { getDevice } from '../../app/api';\nimport type { Nullable } from '@zephyr3d/base';\n\n/**\n * Bridges the render graph's {@link RGTextureAllocator} interface to the\n * engine's device resource pool (`device.pool`).\n *\n * Transient textures are fetched from the pool on `allocate()` and\n * returned to the pool on `release()`, enabling automatic reuse\n * across frames without manual lifecycle management.\n *\n * Usage:\n * ```ts\n * const allocator = new DevicePoolAllocator();\n * const executor = new RenderGraphExecutor(allocator, width, height);\n * ```\n *\n * @public\n */\nexport class DevicePoolAllocator implements RGTextureAllocator<Texture2D, FrameBuffer> {\n  private _device: Nullable<AbstractDevice>;\n  /**\n   * Creates a new instance of the DevicePoolAllocator.\n   * @param device - Optional device instance to use for resource allocation. If not provided, the global device will be used.\n   */\n  constructor(device?: AbstractDevice) {\n    this._device = device ?? null;\n  }\n  /**\n   * Allocate a transient texture from the device pool.\n   *\n   * @param desc - Texture descriptor from the render graph pass.\n   * @param size - Resolved pixel dimensions.\n   * @returns A pooled Texture2D instance.\n   */\n  allocate(desc: RGTextureDesc, size: RGResolvedSize): Texture2D {\n    const device = this._device ?? getDevice();\n    const mipmapping = (desc.mipLevels ?? 1) > 1;\n    const texture = device.pool.fetchTemporalTexture2D(\n      false,\n      desc.format,\n      size.width,\n      size.height,\n      mipmapping\n    );\n    if (desc.mipLevels && texture.mipLevelCount < desc.mipLevels) {\n      device.pool.releaseTexture(texture);\n      throw new Error(\n        `DevicePoolAllocator: texture \"${desc.label ?? '<unnamed>'}\" requested ${desc.mipLevels} ` +\n          `mip levels, but only ${texture.mipLevelCount} were allocated.`\n      );\n    }\n    return texture;\n  }\n\n  /**\n   * Release a transient texture back to the device pool.\n   *\n   * @param texture - The texture to release.\n   */\n  release(texture: Texture2D): void {\n    const device = this._device ?? getDevice();\n    device.pool.releaseTexture(texture);\n  }\n\n  /**\n   * Retain a pooled texture so it can be owned outside the graph lifetime.\n   *\n   * @param texture - The texture to retain.\n   */\n  retain(texture: Texture2D): void {\n    const device = this._device ?? getDevice();\n    device.pool.retainTexture(texture);\n  }\n\n  /**\n   * Allocate a temporary framebuffer from the device pool.\n   *\n   * @param desc - Framebuffer descriptor from the render graph pass.\n   * @returns A pooled FrameBuffer instance.\n   */\n  allocateFramebuffer(desc: RGFramebufferDesc): FrameBuffer {\n    const device = this._device ?? getDevice();\n    const colors = Array.isArray(desc.colorAttachments)\n      ? (desc.colorAttachments as Array<Texture2D | TextureFormat>)\n      : desc.colorAttachments\n        ? [desc.colorAttachments as Texture2D | TextureFormat]\n        : [];\n    const depthAttachment = (desc.depthAttachment ?? null) as Texture2D | TextureFormat | null;\n    return device.pool.fetchTemporalFramebuffer(\n      false,\n      desc.width ?? 0,\n      desc.height ?? 0,\n      colors,\n      depthAttachment,\n      desc.mipmapping ?? false,\n      desc.sampleCount ?? 1,\n      desc.ignoreDepthStencil ?? true,\n      desc.attachmentMipLevel ?? 0,\n      desc.attachmentCubeface ?? 0,\n      desc.attachmentLayer ?? 0\n    );\n  }\n\n  /**\n   * Release a temporary framebuffer back to the device pool.\n   *\n   * @param framebuffer - The framebuffer to release.\n   */\n  releaseFramebuffer(framebuffer: FrameBuffer): void {\n    const device = this._device ?? getDevice();\n    device.pool.releaseFrameBuffer(framebuffer);\n  }\n}\n"],"names":["DevicePoolAllocator","_device","device","allocate","desc","size","getDevice","mipmapping","mipLevels","texture","pool","fetchTemporalTexture2D","format","width","height","mipLevelCount","releaseTexture","Error","label","release","retain","retainTexture","allocateFramebuffer","colors","Array","isArray","colorAttachments","depthAttachment","fetchTemporalFramebuffer","sampleCount","ignoreDepthStencil","attachmentMipLevel","attachmentCubeface","attachmentLayer","releaseFramebuffer","framebuffer","releaseFrameBuffer"],"mappings":";;AAKA;;;;;;;;;;;;;;;AAeC,IACM,MAAMA,mBAAAA,CAAAA;IACHC,OAAkC;AAC1C;;;MAIA,WAAA,CAAYC,MAAuB,CAAE;QACnC,IAAI,CAACD,OAAO,GAAGC,MAAU,IAAA,IAAA;AAC3B;AACA;;;;;;AAMC,MACDC,QAASC,CAAAA,IAAmB,EAAEC,IAAoB,EAAa;AAC7D,QAAA,MAAMH,MAAS,GAAA,IAAI,CAACD,OAAO,IAAIK,SAAAA,EAAAA;AAC/B,QAAA,MAAMC,aAAa,CAACH,KAAKI,SAAS,IAAI,CAAA,IAAK,CAAA;AAC3C,QAAA,MAAMC,OAAUP,GAAAA,MAAAA,CAAOQ,IAAI,CAACC,sBAAsB,CAChD,KAAA,EACAP,IAAKQ,CAAAA,MAAM,EACXP,IAAKQ,CAAAA,KAAK,EACVR,IAAAA,CAAKS,MAAM,EACXP,UAAAA,CAAAA;QAEF,IAAIH,IAAAA,CAAKI,SAAS,IAAIC,OAAAA,CAAQM,aAAa,GAAGX,IAAAA,CAAKI,SAAS,EAAE;YAC5DN,MAAOQ,CAAAA,IAAI,CAACM,cAAc,CAACP,OAAAA,CAAAA;YAC3B,MAAM,IAAIQ,KACR,CAAA,CAAC,8BAA8B,EAAEb,KAAKc,KAAK,IAAI,WAAY,CAAA,YAAY,EAAEd,IAAAA,CAAKI,SAAS,CAAC,CAAC,CAAC,GACxF,CAAC,qBAAqB,EAAEC,OAAQM,CAAAA,aAAa,CAAC,gBAAgB,CAAC,CAAA;AAErE;QACA,OAAON,OAAAA;AACT;AAEA;;;;MAKAU,OAAAA,CAAQV,OAAkB,EAAQ;AAChC,QAAA,MAAMP,MAAS,GAAA,IAAI,CAACD,OAAO,IAAIK,SAAAA,EAAAA;QAC/BJ,MAAOQ,CAAAA,IAAI,CAACM,cAAc,CAACP,OAAAA,CAAAA;AAC7B;AAEA;;;;MAKAW,MAAAA,CAAOX,OAAkB,EAAQ;AAC/B,QAAA,MAAMP,MAAS,GAAA,IAAI,CAACD,OAAO,IAAIK,SAAAA,EAAAA;QAC/BJ,MAAOQ,CAAAA,IAAI,CAACW,aAAa,CAACZ,OAAAA,CAAAA;AAC5B;AAEA;;;;;MAMAa,mBAAAA,CAAoBlB,IAAuB,EAAe;AACxD,QAAA,MAAMF,MAAS,GAAA,IAAI,CAACD,OAAO,IAAIK,SAAAA,EAAAA;AAC/B,QAAA,MAAMiB,MAASC,GAAAA,KAAAA,CAAMC,OAAO,CAACrB,IAAKsB,CAAAA,gBAAgB,CAC7CtB,GAAAA,IAAAA,CAAKsB,gBAAgB,GACtBtB,IAAKsB,CAAAA,gBAAgB,GACnB;AAACtB,YAAAA,IAAAA,CAAKsB;AAA8C,SAAA,GACpD,EAAE;QACR,MAAMC,eAAAA,GAAmBvB,IAAKuB,CAAAA,eAAe,IAAI,IAAA;AACjD,QAAA,OAAOzB,OAAOQ,IAAI,CAACkB,wBAAwB,CACzC,OACAxB,IAAKS,CAAAA,KAAK,IAAI,CAAA,EACdT,KAAKU,MAAM,IAAI,GACfS,MACAI,EAAAA,eAAAA,EACAvB,KAAKG,UAAU,IAAI,KACnBH,EAAAA,IAAAA,CAAKyB,WAAW,IAAI,CAAA,EACpBzB,IAAK0B,CAAAA,kBAAkB,IAAI,IAC3B1B,EAAAA,IAAAA,CAAK2B,kBAAkB,IAAI,GAC3B3B,IAAK4B,CAAAA,kBAAkB,IAAI,CAC3B5B,EAAAA,IAAAA,CAAK6B,eAAe,IAAI,CAAA,CAAA;AAE5B;AAEA;;;;MAKAC,kBAAAA,CAAmBC,WAAwB,EAAQ;AACjD,QAAA,MAAMjC,MAAS,GAAA,IAAI,CAACD,OAAO,IAAIK,SAAAA,EAAAA;QAC/BJ,MAAOQ,CAAAA,IAAI,CAAC0B,kBAAkB,CAACD,WAAAA,CAAAA;AACjC;AACF;;;;"}

package/dist/render/rendergraph/executor.js

@@ -1,5 +1,16 @@
 import { RGHandle } from './types.js';
+import { getDevice } from '../../app/api.js';
 
+const DEFAULT_PROFILING_OPTIONS = {
+    enabled: false,
+    graph: true,
+    pass: true,
+    subpass: true,
+    includePendingUploads: true,
+    allowCrossFrame: false,
+    maxPendingFrames: 3,
+    label: 'RenderGraph'
+};
 /**
  * Executes a compiled render graph with automatic resource lifecycle management.
  *
@@ -16,6 +27,11 @@ import { RGHandle } from './types.js';
  * @typeParam TTexture - The concrete texture type (e.g. `Texture2D`).
  * @public
  */ class RenderGraphExecutor {
+    static _defaultProfilingOptions = false;
+    static _latestProfileResult = null;
+    static _latestPendingProfileFrame = null;
+    static _latestResolvedProfileSerial = 0;
+    static _nextProfileSerial = 0;
     /** @internal */ _allocator;
     /** @internal */ _backbufferWidth;
     /** @internal */ _backbufferHeight;
@@ -25,10 +41,45 @@ import { RGHandle } from './types.js';
     /** @internal */ _importedTextureAliases = new Map();
     /** @internal */ _resolvedImportedTextures = new Map();
     /** @internal */ _cleanupCallbacks = [];
-    constructor(allocator, backbufferWidth, backbufferHeight){
+    /** @internal */ _profilingOptions;
+    /** @internal */ _pendingProfileFrames = [];
+    /** @internal */ _latestProfileResult = null;
+    /** @internal */ _latestResolvedProfileSerial = 0;
+    constructor(allocator, backbufferWidth, backbufferHeight, options){
         this._allocator = allocator;
         this._backbufferWidth = backbufferWidth;
         this._backbufferHeight = backbufferHeight;
+        this._profilingOptions = this._normalizeProfilingOptions(options?.profiling ?? RenderGraphExecutor._defaultProfilingOptions, options?.device);
+    }
+    /**
+   * Set the default profiling options used by newly constructed render graph executors.
+   */ static setDefaultProfilingOptions(options) {
+        RenderGraphExecutor._defaultProfilingOptions = options;
+    }
+    /**
+   * Get the latest resolved profile result from any render graph executor.
+   */ static getLatestProfileResult() {
+        return RenderGraphExecutor._latestProfileResult;
+    }
+    /**
+   * Resolve the latest pending render graph profile result from any executor.
+   */ static resolveProfileResult() {
+        return RenderGraphExecutor._latestPendingProfileFrame?.resolvePromise ?? Promise.resolve(RenderGraphExecutor._latestProfileResult);
+    }
+    /**
+   * Enable, disable, or update timestamp profiling for this executor.
+   */ setProfilingOptions(options) {
+        this._profilingOptions = this._normalizeProfilingOptions(options, this._profilingOptions.device);
+    }
+    /**
+   * Get the latest resolved profile result produced by this executor.
+   */ getLatestProfileResult() {
+        return this._latestProfileResult;
+    }
+    /**
+   * Resolve the latest pending profile result produced by this executor.
+   */ resolveProfileResult() {
+        return this._pendingProfileFrames[this._pendingProfileFrames.length - 1]?.resolvePromise ?? Promise.resolve(this._latestProfileResult);
     }
     /**
    * Update the backbuffer dimensions used for 'backbuffer-relative' sizing.
@@ -56,6 +107,7 @@ import { RGHandle } from './types.js';
    */ execute(compiled) {
         this._cleanupCallbacks.length = 0;
         this._resolveImportedTextureAliases(compiled);
+        const profileFrame = this._beginProfileFrame();
         // Build per-pass allocation and release schedules
         const allocateAt = new Map(); // passIndex -> transient texture resourceIds to allocate
         const releaseAt = new Map(); // passIndex -> transient texture resourceIds to release
@@ -111,15 +163,19 @@ import { RGHandle } from './types.js';
                 // Execute the pass with exception safety for resource cleanup.
                 // Release errors must not hide the original pass execution error.
                 let passError = null;
+                const passProfile = this._beginPassProfileScope(profileFrame, pass);
                 try {
                     if (pass.subpasses.length > 0) {
                         const accessScope = this._createAccessScope(pass);
                         const ctx = this._createContext(accessScope);
                         for (const subpass of pass.subpasses){
+                            const subpassProfile = this._beginSubpassProfileScope(profileFrame, passProfile, pass, subpass.name);
                             try {
                                 subpass.executeFn(ctx, pass.data);
                             } catch (e) {
                                 throw this._wrapSubpassError(pass.name, subpass.name, e);
+                            } finally{
+                                this._endProfileScope(profileFrame, subpassProfile);
                             }
                         }
                     } else if (pass.executeFn) {
@@ -129,6 +185,8 @@ import { RGHandle } from './types.js';
                     }
                 } catch (e) {
                     passError = e;
+                } finally{
+                    this._endProfileScope(profileFrame, passProfile);
                 }
                 let releaseError = null;
                 const framebuffersToRelease = releaseFramebufferAt.get(i);
@@ -171,6 +229,7 @@ import { RGHandle } from './types.js';
         } catch (e) {
             executionError = e;
         } finally{
+            this._finishProfileFrame(profileFrame);
             let cleanupError = null;
             try {
                 this._runCleanupCallbacks();
@@ -212,6 +271,216 @@ import { RGHandle } from './types.js';
         this._resolvedImportedTextures.clear();
     }
     // ─── Private ────────────────────────────────────────────────────────
+    /** @internal */ _normalizeProfilingOptions(options, fallbackDevice) {
+        const source = typeof options === 'object' ? options : {};
+        const enabled = typeof options === 'boolean' ? options : source.enabled ?? true;
+        return {
+            enabled,
+            graph: source.graph ?? DEFAULT_PROFILING_OPTIONS.graph,
+            pass: source.pass ?? DEFAULT_PROFILING_OPTIONS.pass,
+            subpass: source.subpass ?? DEFAULT_PROFILING_OPTIONS.subpass,
+            includePendingUploads: source.includePendingUploads ?? DEFAULT_PROFILING_OPTIONS.includePendingUploads,
+            allowCrossFrame: source.allowCrossFrame ?? DEFAULT_PROFILING_OPTIONS.allowCrossFrame,
+            maxPendingFrames: Math.max(1, source.maxPendingFrames ?? DEFAULT_PROFILING_OPTIONS.maxPendingFrames),
+            label: source.label ?? DEFAULT_PROFILING_OPTIONS.label,
+            device: source.device ?? fallbackDevice
+        };
+    }
+    /** @internal */ _getProfilingDevice() {
+        if (this._profilingOptions.device) {
+            return this._profilingOptions.device;
+        }
+        try {
+            return getDevice();
+        } catch  {
+            return null;
+        }
+    }
+    /** @internal */ _beginProfileFrame() {
+        if (!this._profilingOptions.enabled) {
+            return null;
+        }
+        const device = this._getProfilingDevice();
+        const supported = !!device?.getDeviceCaps().miscCaps.supportTimestampQuery;
+        const rootResult = {
+            name: this._profilingOptions.label,
+            type: 'graph',
+            queryId: 0,
+            durationMs: 0,
+            status: supported ? 'resolved' : 'unsupported',
+            children: [],
+            message: supported ? undefined : 'GPU timestamp queries are not supported'
+        };
+        const result = {
+            frameId: device?.frameInfo.frameCounter ?? -1,
+            status: rootResult.status,
+            graph: rootResult,
+            passes: rootResult.children
+        };
+        const root = {
+            result: rootResult,
+            queryId: 0,
+            ended: false
+        };
+        const frame = {
+            serial: ++RenderGraphExecutor._nextProfileSerial,
+            device,
+            supported,
+            result,
+            root,
+            scopes: [],
+            resolvePromise: Promise.resolve(result)
+        };
+        if (this._profilingOptions.graph) {
+            this._beginTimestampScope(frame, root, this._profilingOptions.label);
+        }
+        return frame;
+    }
+    /** @internal */ _beginPassProfileScope(frame, pass) {
+        if (!frame || !this._profilingOptions.pass && !this._profilingOptions.subpass) {
+            return null;
+        }
+        return this._beginProfileScope(frame, frame.root, 'pass', pass.name, this._profilingOptions.pass);
+    }
+    /** @internal */ _beginSubpassProfileScope(frame, passScope, pass, subpassName) {
+        if (!frame || !this._profilingOptions.subpass) {
+            return null;
+        }
+        const parent = passScope ?? frame.root;
+        return this._beginProfileScope(frame, parent, 'subpass', subpassName, true, `${pass.name}/${subpassName}`);
+    }
+    /** @internal */ _beginProfileScope(frame, parent, type, name, queryEnabled, queryLabel) {
+        const status = frame.supported && !queryEnabled ? 'resolved' : frame.supported ? 'pending' : 'unsupported';
+        const result = {
+            name,
+            type,
+            queryId: 0,
+            durationMs: 0,
+            status,
+            children: [],
+            message: frame.supported ? undefined : 'GPU timestamp queries are not supported'
+        };
+        parent.result.children.push(result);
+        const scope = {
+            result,
+            queryId: 0,
+            ended: false
+        };
+        if (queryEnabled) {
+            this._beginTimestampScope(frame, scope, queryLabel ?? name);
+        }
+        return scope;
+    }
+    /** @internal */ _beginTimestampScope(frame, scope, label) {
+        if (!frame.supported || !frame.device) {
+            scope.result.status = 'unsupported';
+            scope.result.message = 'GPU timestamp queries are not supported';
+            return;
+        }
+        const queryId = frame.device.beginTimestampQuery(label, {
+            includePendingUploads: this._profilingOptions.includePendingUploads,
+            allowCrossFrame: this._profilingOptions.allowCrossFrame
+        });
+        scope.queryId = queryId;
+        scope.result.queryId = queryId;
+        if (queryId > 0) {
+            scope.result.status = 'pending';
+            frame.scopes.push(scope);
+        } else {
+            scope.result.status = 'unsupported';
+            scope.result.message = 'GPU timestamp query was not started';
+        }
+    }
+    /** @internal */ _endProfileScope(frame, scope) {
+        if (!frame || !frame.device || !scope || scope.ended) {
+            return;
+        }
+        scope.ended = true;
+        if (scope.queryId > 0) {
+            frame.device.endTimestampQuery(scope.queryId);
+        }
+    }
+    /** @internal */ _finishProfileFrame(frame) {
+        if (!frame) {
+            return;
+        }
+        this._endProfileScope(frame, frame.root);
+        if (frame.scopes.length === 0 || !frame.device) {
+            frame.result.status = this._aggregateProfileStatus(frame.result.graph);
+            this._publishProfileResult(frame);
+            return;
+        }
+        frame.resolvePromise = Promise.all(frame.scopes.map((scope)=>frame.device.resolveTimestampQuery(scope.queryId))).then((results)=>{
+            for(let i = 0; i < results.length; i++){
+                this._applyTimestampResult(frame.scopes[i], results[i]);
+            }
+            frame.result.status = this._aggregateProfileStatus(frame.result.graph);
+            this._publishProfileResult(frame);
+            return frame.result;
+        }).catch((err)=>{
+            const message = err instanceof Error ? err.message : String(err);
+            for (const scope of frame.scopes){
+                scope.result.status = 'failed';
+                scope.result.message = message;
+            }
+            frame.result.status = 'failed';
+            this._publishProfileResult(frame);
+            return frame.result;
+        });
+        this._trackPendingProfileFrame(frame);
+    }
+    /** @internal */ _trackPendingProfileFrame(frame) {
+        this._pendingProfileFrames.push(frame);
+        while(this._pendingProfileFrames.length > this._profilingOptions.maxPendingFrames){
+            this._pendingProfileFrames.shift();
+        }
+        RenderGraphExecutor._latestPendingProfileFrame = frame;
+    }
+    /** @internal */ _publishProfileResult(frame) {
+        this._pendingProfileFrames = this._pendingProfileFrames.filter((pending)=>pending !== frame);
+        if (frame.serial >= this._latestResolvedProfileSerial) {
+            this._latestResolvedProfileSerial = frame.serial;
+            this._latestProfileResult = frame.result;
+        }
+        if (frame.serial >= RenderGraphExecutor._latestResolvedProfileSerial) {
+            RenderGraphExecutor._latestResolvedProfileSerial = frame.serial;
+            RenderGraphExecutor._latestProfileResult = frame.result;
+        }
+        if (RenderGraphExecutor._latestPendingProfileFrame === frame) {
+            RenderGraphExecutor._latestPendingProfileFrame = null;
+        }
+    }
+    /** @internal */ _applyTimestampResult(scope, result) {
+        scope.result.queryId = result.id;
+        scope.result.durationMs = result.durationMs;
+        scope.result.status = result.status;
+        scope.result.message = result.message;
+    }
+    /** @internal */ _aggregateProfileStatus(scope) {
+        const statuses = [];
+        const collect = (node)=>{
+            statuses.push(node.status);
+            for (const child of node.children){
+                collect(child);
+            }
+        };
+        collect(scope);
+        for (const status of [
+            'failed',
+            'invalid',
+            'exhausted',
+            'pending',
+            'auto-closed'
+        ]){
+            if (statuses.includes(status)) {
+                return status;
+            }
+        }
+        if (statuses.includes('unsupported')) {
+            return 'unsupported';
+        }
+        return 'resolved';
+    }
     /** @internal */ _resolveSize(desc) {
         const mode = desc.sizeMode ?? 'backbuffer-relative';
         if (mode === 'absolute') {