@plasius/gpu-renderer 0.1.4 → 0.1.7

package/dist/index.cjs

@@ -21,12 +21,472 @@ var index_exports = {};
 __export(index_exports, {
   bindRendererToXrManager: () => bindRendererToXrManager,
   createGpuRenderer: () => createGpuRenderer,
+  createRendererDebugHooks: () => createRendererDebugHooks,
   defaultRendererClearColor: () => defaultRendererClearColor,
+  defaultRendererWorkerProfile: () => defaultRendererWorkerProfile,
+  getRendererWorkerManifest: () => getRendererWorkerManifest,
+  getRendererWorkerProfile: () => getRendererWorkerProfile,
+  rendererDebugOwner: () => rendererDebugOwner,
+  rendererWorkerManifests: () => rendererWorkerManifests,
+  rendererWorkerProfileNames: () => rendererWorkerProfileNames,
+  rendererWorkerProfiles: () => rendererWorkerProfiles,
+  rendererWorkerQueueClass: () => rendererWorkerQueueClass,
   supportsWebGpu: () => supportsWebGpu
 });
 module.exports = __toCommonJS(index_exports);
 var DEFAULT_CLEAR_COLOR = Object.freeze([0.07, 0.11, 0.18, 1]);
 var DEFAULT_CANVAS_SELECTOR = "canvas[data-plasius-gpu-renderer]";
+var rendererDebugOwner = "renderer";
+var rendererWorkerQueueClass = "render";
+var defaultRendererWorkerProfile = "realtime";
+function buildRendererWorkerBudgetLevels(jobType, queueClass, levels) {
+  return Object.freeze(
+    levels.map(
+      (level) => Object.freeze({
+        id: level.id,
+        estimatedCostMs: level.estimatedCostMs,
+        config: Object.freeze({
+          maxDispatchesPerFrame: level.config.maxDispatchesPerFrame,
+          maxJobsPerDispatch: level.config.maxJobsPerDispatch,
+          cadenceDivisor: level.config.cadenceDivisor,
+          workgroupScale: level.config.workgroupScale,
+          maxQueueDepth: level.config.maxQueueDepth,
+          metadata: Object.freeze({
+            owner: rendererDebugOwner,
+            queueClass,
+            jobType,
+            quality: level.id
+          })
+        })
+      })
+    )
+  );
+}
+var rendererWorkerProfileSpecs = {
+  realtime: {
+    description: "Frame-stage DAG for flat rendering with visibility, main encode, post-processing, and submit.",
+    suggestedAllocationIds: [
+      "renderer.surface.current",
+      "renderer.visibility.worklist",
+      "renderer.post-process.history"
+    ],
+    jobs: {
+      acquire: {
+        priority: 5,
+        dependencies: [],
+        domain: "resolution",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.surface.current"]
+      },
+      visibility: {
+        priority: 4,
+        dependencies: [],
+        domain: "geometry",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.4,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 128,
+              cadenceDivisor: 2,
+              workgroupScale: 0.5,
+              maxQueueDepth: 256
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 0.8,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 256,
+              cadenceDivisor: 1,
+              workgroupScale: 0.75,
+              maxQueueDepth: 384
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.2,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 512,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 512
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.visibility.worklist"]
+      },
+      mainEncode: {
+        priority: 4,
+        dependencies: ["acquire", "visibility"],
+        domain: "geometry",
+        importance: "critical",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 1.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 128,
+              cadenceDivisor: 1,
+              workgroupScale: 0.6,
+              maxQueueDepth: 192
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 2.1,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 256,
+              cadenceDivisor: 1,
+              workgroupScale: 0.8,
+              maxQueueDepth: 256
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 3,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 384,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 384
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.surface.current"]
+      },
+      postProcess: {
+        priority: 3,
+        dependencies: ["mainEncode"],
+        domain: "post-processing",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.5,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 64,
+              cadenceDivisor: 2,
+              workgroupScale: 0.5,
+              maxQueueDepth: 96
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 0.9,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 128,
+              cadenceDivisor: 1,
+              workgroupScale: 0.75,
+              maxQueueDepth: 128
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.4,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 192,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 192
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.post-process.history"]
+      },
+      submit: {
+        priority: 2,
+        dependencies: ["postProcess"],
+        domain: "resolution",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.surface.current"]
+      }
+    }
+  },
+  xr: {
+    description: "Frame-stage DAG for XR rendering with late-latch coordination before main encode and submit.",
+    suggestedAllocationIds: [
+      "renderer.xr.surface.current",
+      "renderer.xr.visibility.worklist"
+    ],
+    jobs: {
+      acquire: {
+        priority: 5,
+        dependencies: [],
+        domain: "xr",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.surface.current"]
+      },
+      visibility: {
+        priority: 4,
+        dependencies: [],
+        domain: "geometry",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.5,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 96,
+              cadenceDivisor: 2,
+              workgroupScale: 0.5,
+              maxQueueDepth: 192
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 0.9,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 192,
+              cadenceDivisor: 1,
+              workgroupScale: 0.75,
+              maxQueueDepth: 256
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.3,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 320,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 320
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.visibility.worklist"]
+      },
+      lateLatch: {
+        priority: 5,
+        dependencies: ["acquire"],
+        domain: "xr",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.15,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.surface.current"]
+      },
+      mainEncode: {
+        priority: 4,
+        dependencies: ["visibility", "lateLatch"],
+        domain: "xr",
+        importance: "critical",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 1.1,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 96,
+              cadenceDivisor: 1,
+              workgroupScale: 0.6,
+              maxQueueDepth: 128
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 1.8,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 192,
+              cadenceDivisor: 1,
+              workgroupScale: 0.8,
+              maxQueueDepth: 192
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 2.6,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 256,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 256
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.surface.current"]
+      },
+      submit: {
+        priority: 2,
+        dependencies: ["mainEncode"],
+        domain: "xr",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.surface.current"]
+      }
+    }
+  }
+};
+function buildRendererWorkerProfile(name, spec) {
+  return Object.freeze({
+    name,
+    description: spec.description,
+    jobs: Object.freeze(Object.keys(spec.jobs))
+  });
+}
+function buildRendererWorkerManifestJob(profileName, jobName, spec) {
+  const label = `renderer.${profileName}.${jobName}`;
+  return Object.freeze({
+    key: jobName,
+    label,
+    worker: Object.freeze({
+      jobType: label,
+      queueClass: rendererWorkerQueueClass,
+      priority: spec.priority,
+      dependencies: Object.freeze(
+        spec.dependencies.map((dependency) => `renderer.${profileName}.${dependency}`)
+      ),
+      schedulerMode: "dag"
+    }),
+    performance: Object.freeze({
+      id: label,
+      jobType: label,
+      queueClass: rendererWorkerQueueClass,
+      domain: spec.domain,
+      authority: "visual",
+      importance: spec.importance,
+      levels: buildRendererWorkerBudgetLevels(
+        label,
+        rendererWorkerQueueClass,
+        spec.levels
+      )
+    }),
+    debug: Object.freeze({
+      owner: rendererDebugOwner,
+      queueClass: rendererWorkerQueueClass,
+      jobType: label,
+      tags: Object.freeze(["renderer", profileName, jobName, spec.domain]),
+      suggestedAllocationIds: Object.freeze([...spec.suggestedAllocationIds])
+    })
+  });
+}
+function buildRendererWorkerManifest(name, spec) {
+  return Object.freeze({
+    schemaVersion: 1,
+    owner: rendererDebugOwner,
+    profile: name,
+    description: spec.description,
+    queueClass: rendererWorkerQueueClass,
+    schedulerMode: "dag",
+    suggestedAllocationIds: Object.freeze([...spec.suggestedAllocationIds]),
+    jobs: Object.freeze(
+      Object.entries(spec.jobs).map(
+        ([jobName, jobSpec]) => buildRendererWorkerManifestJob(name, jobName, jobSpec)
+      )
+    )
+  });
+}
+var rendererWorkerProfiles = Object.freeze(
+  Object.fromEntries(
+    Object.entries(rendererWorkerProfileSpecs).map(([name, spec]) => [
+      name,
+      buildRendererWorkerProfile(name, spec)
+    ])
+  )
+);
+var rendererWorkerProfileNames = Object.freeze(
+  Object.keys(rendererWorkerProfiles)
+);
+var rendererWorkerManifests = Object.freeze(
+  Object.fromEntries(
+    Object.entries(rendererWorkerProfileSpecs).map(([name, spec]) => [
+      name,
+      buildRendererWorkerManifest(name, spec)
+    ])
+  )
+);
+function getRendererWorkerProfile(name = defaultRendererWorkerProfile) {
+  const profile = rendererWorkerProfiles[name];
+  if (!profile) {
+    const available = rendererWorkerProfileNames.join(", ");
+    throw new Error(`Unknown renderer worker profile "${name}". Available: ${available}.`);
+  }
+  return profile;
+}
+function getRendererWorkerManifest(name = defaultRendererWorkerProfile) {
+  const manifest = rendererWorkerManifests[name];
+  if (!manifest) {
+    const available = rendererWorkerProfileNames.join(", ");
+    throw new Error(`Unknown renderer worker profile "${name}". Available: ${available}.`);
+  }
+  return manifest;
+}
 function clamp01(value) {
   return Math.min(1, Math.max(0, value));
 }
@@ -62,12 +522,111 @@ function normalizeColor(value) {
   }
   return [...DEFAULT_CLEAR_COLOR];
 }
+function readPositiveNumber(name, value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a finite number greater than zero.`);
+  }
+  return value;
+}
 function now() {
   if (typeof performance !== "undefined" && typeof performance.now === "function") {
     return performance.now();
   }
   return Date.now();
 }
+function normalizeFrameId(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error("frameIdFactory must return a non-empty string.");
+  }
+  return value.trim();
+}
+function resolveTargetFrameTimeMs(options, event) {
+  const {
+    targetFrameTimeMs: fixedTargetFrameTimeMs,
+    targetFrameRate,
+    getTargetFrameTimeMs
+  } = options;
+  if (typeof getTargetFrameTimeMs === "function") {
+    const resolved = getTargetFrameTimeMs(event);
+    return readPositiveNumber("getTargetFrameTimeMs()", resolved);
+  }
+  if (fixedTargetFrameTimeMs !== void 0) {
+    return fixedTargetFrameTimeMs;
+  }
+  if (targetFrameRate !== void 0) {
+    return 1e3 / targetFrameRate;
+  }
+  return void 0;
+}
+function createRendererDebugHooks(options = {}) {
+  const {
+    debugSession,
+    targetFrameTimeMs,
+    targetFrameRate,
+    getTargetFrameTimeMs,
+    onFrameStart,
+    onFrameComplete
+  } = options;
+  if (!debugSession || typeof debugSession.recordFrame !== "function") {
+    throw new Error(
+      "debugSession must expose recordFrame(sample). Use @plasius/gpu-debug createGpuDebugSession()."
+    );
+  }
+  const fixedTargetFrameTimeMs = readPositiveNumber(
+    "targetFrameTimeMs",
+    targetFrameTimeMs
+  );
+  const fixedTargetFrameRate = readPositiveNumber(
+    "targetFrameRate",
+    targetFrameRate
+  );
+  if (fixedTargetFrameTimeMs !== void 0 && fixedTargetFrameRate !== void 0) {
+    throw new Error(
+      "Provide either targetFrameTimeMs or targetFrameRate, not both."
+    );
+  }
+  if (getTargetFrameTimeMs !== void 0 && typeof getTargetFrameTimeMs !== "function") {
+    throw new Error("getTargetFrameTimeMs must be a function when provided.");
+  }
+  const resolvedOptions = {
+    targetFrameTimeMs: fixedTargetFrameTimeMs,
+    targetFrameRate: fixedTargetFrameRate,
+    getTargetFrameTimeMs
+  };
+  return {
+    onFrameStart(event) {
+      if (typeof onFrameStart === "function") {
+        onFrameStart({
+          ...event,
+          owner: rendererDebugOwner
+        });
+      }
+    },
+    onFrameComplete(event) {
+      const resolvedTargetFrameTimeMs = resolveTargetFrameTimeMs(
+        resolvedOptions,
+        event
+      );
+      if (typeof event.frameTimeMs === "number" && Number.isFinite(event.frameTimeMs) && event.frameTimeMs > 0) {
+        debugSession.recordFrame({
+          frameId: event.frameId,
+          frameTimeMs: event.frameTimeMs,
+          targetFrameTimeMs: resolvedTargetFrameTimeMs
+        });
+      }
+      if (typeof onFrameComplete === "function") {
+        onFrameComplete({
+          ...event,
+          owner: rendererDebugOwner,
+          targetFrameTimeMs: resolvedTargetFrameTimeMs
+        });
+      }
+    }
+  };
+}
 function readNavigator(navigatorOverride) {
   const currentNavigator = navigatorOverride ?? globalThis.navigator;
   if (!currentNavigator || typeof currentNavigator !== "object") {
@@ -148,8 +707,11 @@ async function createGpuRenderer(options = {}) {
     clearColor = DEFAULT_CLEAR_COLOR,
     requestAnimationFrame = globalThis.requestAnimationFrame?.bind(globalThis),
     cancelAnimationFrame = globalThis.cancelAnimationFrame?.bind(globalThis),
+    frameIdFactory,
+    onFrameStart,
     onBeforeEncode,
-    onAfterSubmit
+    onAfterSubmit,
+    onFrameComplete
   } = options;
   const gpu = readGpu(navigatorOverride);
   const adapter = await gpu.requestAdapter({ powerPreference });
@@ -176,6 +738,28 @@ async function createGpuRenderer(options = {}) {
     if (destroyed) {
       throw new Error("Renderer was destroyed.");
     }
+    const frameNumber = frame + 1;
+    const frameId = normalizeFrameId(
+      typeof frameIdFactory === "function" ? frameIdFactory({
+        frame: frameNumber,
+        timestamp,
+        canvas: targetCanvas,
+        xrActive
+      }) : `renderer.frame.${frameNumber}`
+    );
+    const frameTimeMs = lastTimestamp > 0 ? Math.max(0, timestamp - lastTimestamp) : void 0;
+    if (typeof onFrameStart === "function") {
+      onFrameStart({
+        frame: frameNumber,
+        frameId,
+        frameTimeMs,
+        timestamp,
+        device,
+        context,
+        canvas: targetCanvas,
+        xrActive
+      });
+    }
     const texture = context.getCurrentTexture?.();
     if (!texture || typeof texture.createView !== "function") {
       throw new Error("WebGPU context returned an invalid current texture.");
@@ -188,12 +772,16 @@ async function createGpuRenderer(options = {}) {
     if (typeof onBeforeEncode === "function") {
       onBeforeEncode({
         frame,
+        frameNumber,
+        frameId,
+        frameTimeMs,
         timestamp,
         device,
         context,
         encoder,
         pass,
-        canvas: targetCanvas
+        canvas: targetCanvas,
+        xrActive
       });
     }
     if (typeof pass.end === "function") {
@@ -201,19 +789,37 @@ async function createGpuRenderer(options = {}) {
     }
     const commandBuffer = encoder.finish();
     device.queue.submit([commandBuffer]);
-    frame += 1;
+    frame = frameNumber;
     lastTimestamp = timestamp;
     if (typeof onAfterSubmit === "function") {
       onAfterSubmit({
-        frame,
+        frame: frameNumber,
+        frameNumber,
+        frameId,
+        frameTimeMs,
         timestamp,
         device,
         context,
-        canvas: targetCanvas
+        canvas: targetCanvas,
+        xrActive
+      });
+    }
+    if (typeof onFrameComplete === "function") {
+      onFrameComplete({
+        frame: frameNumber,
+        frameId,
+        frameTimeMs,
+        timestamp,
+        device,
+        context,
+        canvas: targetCanvas,
+        xrActive
       });
     }
     return {
-      frame,
+      frame: frameNumber,
+      frameId,
+      frameTimeMs,
       timestamp
     };
   };
@@ -355,7 +961,16 @@ var defaultRendererClearColor = DEFAULT_CLEAR_COLOR;
 0 && (module.exports = {
   bindRendererToXrManager,
   createGpuRenderer,
+  createRendererDebugHooks,
   defaultRendererClearColor,
+  defaultRendererWorkerProfile,
+  getRendererWorkerManifest,
+  getRendererWorkerProfile,
+  rendererDebugOwner,
+  rendererWorkerManifests,
+  rendererWorkerProfileNames,
+  rendererWorkerProfiles,
+  rendererWorkerQueueClass,
   supportsWebGpu
 });
 //# sourceMappingURL=index.cjs.map