@aethervtt/shard-gpu 0.0.1 → 0.1.0

package/dist/context.js

@@ -1,6 +1,21 @@
 import { ShardError } from "@aethervtt/shard-core";
 import { LayoutCache, PipelineCache } from "./caches.js";
 import { toShardError } from "./errors.js";
+import {
+  blockOf,
+  bufferCategory,
+  DATA_TEXTURE_PREFIX,
+  Ledger,
+  SHARED_OWNER,
+  textureBytes,
+  textureCategory
+} from "./ledger.js";
+import { Surface } from "./surface.js";
+import {
+  capabilitiesOf,
+  isCoreDevice,
+  probeHdrSampleCount
+} from "./tier.js";
 const COMPRESSED_TEXTURE_FEATURES = [
   "texture-compression-bc",
   "texture-compression-astc",
@@ -16,45 +31,147 @@ class GpuContext {
   adapter;
   device;
   format;
-  canvas;
-  context;
   features;
+  /** The graphics API the device runs on (0064). */
+  backend;
+  /**
+   * The tier the engine runs at (0064): `full` on a core WebGPU device, `baseline` on anything
+   * else that runs the baseline subset. Kept across device replacement.
+   */
+  tier;
+  /** What the device can do, as far as the tiers care. */
+  capabilities;
+  /** Why better options were skipped while opening the device (no core adapter, say). */
+  reasons;
   pipelines;
   layouts;
   /** Increments when the device is replaced. */
   generation = 0;
-  /** Canvas pixels per CSS pixel (devicePixelRatio) at the last resize; 1 without a canvas. */
-  pixelRatio = 1;
+  /**
+   * How long the first adapter and device request took, in ms (0062's `coldStart.device`). Set by
+   * `createGpuContext`; 0 for a context built directly.
+   */
+  deviceMs = 0;
+  /**
+   * Who new buffers and textures count against. An app sets it to its owner while it runs (the
+   * render plugin's scope); otherwise it's `'gpu'`, the device's own.
+   */
+  owner = SHARED_OWNER;
   /** Most recent GPU errors, newest last. */
   errors = [];
+  /** Whether the device works now (0061). */
+  status = "ok";
   options;
   errorListeners = /* @__PURE__ */ new Set();
   lostListeners = /* @__PURE__ */ new Set();
-  constructor(options, adapter, device, format, context) {
+  surfaces_ = [];
+  ledger = new Ledger();
+  shared_ = /* @__PURE__ */ new Map();
+  recreating;
+  destroyed = false;
+  /** The WebGL2 shim's canvas contexts, when that's the backend. */
+  canvasContext;
+  constructor(options, adapter, device, format, opened = {}) {
     this.options = options;
     this.adapter = adapter;
     this.device = device;
     this.format = format;
-    this.canvas = options.canvas;
-    this.context = context;
     this.features = new Set(device.features);
+    this.backend = opened.backend ?? "webgpu";
+    this.tier = opened.tier ?? (isCoreDevice(device) ? "full" : "baseline");
+    this.capabilities = capabilitiesOf(device, this.backend, opened.hdrSampleCount);
+    this.reasons = opened.reasons ?? [];
+    this.canvasContext = opened.canvasContext;
     this.pipelines = new PipelineCache(this);
     this.layouts = new LayoutCache(this);
     this.attach(device);
   }
-  /** Match the canvas backing size to its CSS size. Returns true if it changed. */
-  resize() {
-    const canvas = this.canvas;
-    if (!canvas || !("clientWidth" in canvas)) return false;
-    const dpr = globalThis.devicePixelRatio ?? 1;
-    this.pixelRatio = dpr;
-    const width = Math.max(1, Math.floor(canvas.clientWidth * dpr));
-    const height = Math.max(1, Math.floor(canvas.clientHeight * dpr));
-    if (canvas.width === width && canvas.height === height) return false;
-    canvas.width = width;
-    canvas.height = height;
-    return true;
+  // --- surfaces ----------------------------------------------------------------
+  /** The canvases this device draws into, in the order they were added. */
+  get surfaces() {
+    return this.surfaces_;
+  }
+  /** Configures a canvas as a surface of this device. `surface.remove()` gives it back. */
+  addSurface(canvas, options = {}) {
+    const context = this.canvasContext ? this.canvasContext(canvas) : canvas.getContext("webgpu");
+    if (!context) {
+      const api = this.backend === "webgl2" ? "WebGL2" : "WebGPU";
+      throw new ShardError("gpu/no-context", `Could not get a ${api} canvas context`);
+    }
+    if (this.surfaces_.some((s) => s.canvas === canvas)) {
+      throw new ShardError("gpu/duplicate-surface", "This canvas is already a surface", {
+        hint: "Share the Surface itself (renderPlugin({ gpu, surface })), or remove it first."
+      });
+    }
+    const n = this.surfaces_.length;
+    const surface = new Surface(this, canvas, context, {
+      alpha: options.alpha ?? "opaque",
+      label: options.label ?? (n === 0 ? "surface" : `surface-${n + 1}`)
+    });
+    this.surfaces_.push(surface);
+    return surface;
+  }
+  /** @internal Called by `Surface.remove()`. */
+  forgetSurface(surface) {
+    const i = this.surfaces_.indexOf(surface);
+    if (i !== -1) this.surfaces_.splice(i, 1);
+  }
+  /** WebGL2: where shader translations came from, and what naga translated (0064). */
+  shaderCache() {
+    return this.device.shaderCache;
+  }
+  /**
+   * WebGL2: every shader translation this session used, as a baked set to ship as
+   * `webgl2.shaders` (0064). Undefined on WebGPU.
+   */
+  exportShaderCache() {
+    return this.device.exportShaders?.();
+  }
+  // --- accounting ----------------------------------------------------------------
+  /** Runs `fn` with new buffers and textures counted against `owner`. */
+  withOwner(owner, fn) {
+    const previous = this.owner;
+    this.owner = owner;
+    try {
+      return fn();
+    } finally {
+      this.owner = previous;
+    }
+  }
+  /** Live buffers and textures this device made for `owner`, or for everyone (0052). */
+  stats(owner) {
+    return this.ledger.stats(owner);
+  }
+  /** Live bytes for `owner` (or everyone) by what they're for: targets, textures, geometry... (0062). */
+  memory(owner) {
+    return this.ledger.memory(owner);
+  }
+  /**
+   * Bytes `owner` has written to the GPU since the device was made, by upload category, and the
+   * buffers and textures it created (0055). Cumulative: diff two reads for a frame's worth.
+   */
+  uploads(owner) {
+    return this.ledger.uploads(owner);
+  }
+  /** Owners with live objects, sorted. */
+  owners() {
+    return this.ledger.names();
   }
+  /** Destroys every buffer and texture `owner` still has. Returns how many. */
+  release(owner) {
+    return this.ledger.release(owner);
+  }
+  /**
+   * A per-device object every app on this device shares, made once by `create` and counted against
+   * the device, not whichever app asked first. Made again after a device loss.
+   */
+  shared(key, create) {
+    if (this.shared_.has(key)) return this.shared_.get(key);
+    const value = this.withOwner(SHARED_OWNER, () => create(this.device));
+    this.shared_.set(key, value);
+    return value;
+  }
+  // --- errors and loss -------------------------------------------------------------
   onError(listener) {
     this.errorListeners.add(listener);
     return () => this.errorListeners.delete(listener);
@@ -63,6 +180,10 @@ class GpuContext {
     this.lostListeners.add(listener);
     return () => this.lostListeners.delete(listener);
   }
+  /** Error and device-loss listeners, for teardown tests. */
+  get listenerCount() {
+    return { error: this.errorListeners.size, lost: this.lostListeners.size };
+  }
   reportError(error) {
     this.errors.push(error);
     if (this.errors.length > MAX_ERRORS) this.errors.shift();
@@ -80,27 +201,77 @@ class GpuContext {
     });
     return result;
   }
-  /** Gets a fresh adapter and device after a loss, and reconfigures the canvas. */
-  async recreate() {
-    const { adapter, device } = await requestDevice(this.options);
-    this.adapter = adapter;
-    this.device = device;
-    this.context?.configure(canvasConfig(device, this.format));
-    this.pipelines.clear();
-    this.layouts.clear();
-    this.generation++;
-    this.attach(device);
+  /**
+   * Gets a fresh adapter and device after a loss and reconfigures every surface with its alpha
+   * mode. Apps sharing the device all call it; they share one recreation.
+   */
+  recreate() {
+    this.recreating ??= this.recover().finally(() => {
+      this.recreating = void 0;
+    });
+    return this.recreating;
+  }
+  /** Replaces the device, retrying as `options.recovery` says; `failed` once every try failed. */
+  async recover() {
+    const attempts = Math.max(1, this.options.recovery?.attempts ?? 3);
+    const interval = this.options.recovery?.intervalMs ?? 1e3;
+    this.status = "lost";
+    let last;
+    for (let i = 0; i < attempts; i++) {
+      if (i > 0) await new Promise((resolve) => setTimeout(resolve, interval));
+      if (this.destroyed) return;
+      try {
+        await this.replaceDevice();
+        this.status = "ok";
+        return;
+      } catch (err) {
+        last = err;
+      }
+    }
+    this.status = "failed";
+    const error = new ShardError(
+      "gpu/recovery-failed",
+      `The GPU device couldn't be replaced after ${attempts} tries`,
+      { hint: "Tell the user 3D is unavailable; reloading the page tries again.", cause: last }
+    );
+    this.reportError(error);
+    throw error;
   }
   /** For tests and debugging: destroys the device and reports it as an unexpected loss. */
   simulateDeviceLoss() {
     this.handleLoss({ reason: "unknown", message: "Simulated device loss" });
     this.device.destroy();
   }
+  /** Removes every surface and destroys the device. */
   destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
     this.lostListeners.clear();
+    this.errorListeners.clear();
+    for (const surface of [...this.surfaces_]) surface.remove();
+    this.ledger.clear();
+    this.shared_.clear();
     this.device.destroy();
   }
+  async replaceDevice() {
+    const { adapter, device, hdrSampleCount } = await openDevice(
+      this.options,
+      this.tier,
+      this.backend
+    );
+    this.adapter = adapter;
+    this.device = device;
+    this.capabilities = capabilitiesOf(device, this.backend, hdrSampleCount);
+    this.ledger.clear();
+    this.shared_.clear();
+    this.pipelines.clear();
+    this.layouts.clear();
+    this.generation++;
+    this.attach(device);
+    for (const surface of this.surfaces_) surface.configure();
+  }
   attach(device) {
+    this.instrument(device);
     device.addEventListener("uncapturederror", (event) => {
       this.reportError(toShardError(event.error, void 0));
     });
@@ -110,30 +281,184 @@ class GpuContext {
       }
     });
   }
+  /**
+   * Counts every buffer and texture the device makes against the current owner, and every byte
+   * written into one against its owner and upload category.
+   */
+  instrument(device) {
+    const ledger = this.ledger;
+    const createBuffer = device.createBuffer.bind(device);
+    const createTexture = device.createTexture.bind(device);
+    device.createBuffer = (descriptor) => {
+      const buffer = createBuffer(descriptor);
+      const category = bufferCategory(descriptor.usage);
+      ledger.track(buffer, this.owner, false, descriptor.size, category, descriptor.label);
+      return buffer;
+    };
+    device.createTexture = (descriptor) => {
+      const texture = createTexture(descriptor);
+      const data = descriptor.label?.startsWith(DATA_TEXTURE_PREFIX) === true;
+      const category = data ? "storage" : textureCategory(descriptor.usage);
+      ledger.track(texture, this.owner, true, textureBytes(descriptor), category, descriptor.label);
+      return texture;
+    };
+    const queue = device.queue;
+    const writeBuffer = queue.writeBuffer.bind(queue);
+    const writeTexture = queue.writeTexture.bind(queue);
+    const copyExternal = queue.copyExternalImageToTexture?.bind(queue);
+    queue.writeBuffer = (buffer, offset, data, dataOffset, size) => {
+      writeBuffer(buffer, offset, data, dataOffset, size);
+      ledger.upload(buffer, writtenBytes(data, dataOffset, size));
+    };
+    queue.writeTexture = (destination, data, layout, size) => {
+      writeTexture(destination, data, layout, size);
+      ledger.upload(destination.texture, textureWriteBytes(destination.texture, data, layout, size));
+    };
+    if (copyExternal) {
+      queue.copyExternalImageToTexture = (source, destination, size) => {
+        copyExternal(source, destination, size);
+        const [w, h, d] = extent(size);
+        ledger.upload(destination.texture, w * h * d * 4);
+      };
+    }
+  }
   handleLoss(info) {
+    this.status = "lost";
     for (const listener of this.lostListeners) listener(info);
   }
 }
-function canvasConfig(device, format) {
+function writtenBytes(data, dataOffset, size) {
+  if (ArrayBuffer.isView(data)) {
+    const unit = data.BYTES_PER_ELEMENT ?? 1;
+    return (size ?? data.byteLength / unit - (dataOffset ?? 0)) * unit;
+  }
+  return size ?? data.byteLength - (dataOffset ?? 0);
+}
+function extent(size) {
+  if (Symbol.iterator in size) {
+    const a = [...size];
+    return [a[0] ?? 1, a[1] ?? 1, a[2] ?? 1];
+  }
+  const d = size;
+  return [d.width, d.height ?? 1, d.depthOrArrayLayers ?? 1];
+}
+function textureWriteBytes(texture, data, layout, size) {
+  const [w, h, d] = extent(size);
+  const bytes = ArrayBuffer.isView(data) ? data.byteLength : data.byteLength;
+  const total = bytes - (layout.offset ?? 0);
+  const [bw, bh, blockBytes] = blockOf(texture.format);
+  return Math.min(total, Math.ceil(w / bw) * Math.ceil(h / bh) * blockBytes * d);
+}
+async function openDevice(options, keep, keepBackend) {
+  const choice = keepBackend ?? options.backend ?? "auto";
+  const reasons = [];
+  if (choice !== "webgl2") {
+    const gpu = options.gpu ?? globalThis.navigator?.gpu;
+    if (gpu) {
+      try {
+        return await openWebGpu(gpu, options, keep, []);
+      } catch (err) {
+        if (choice === "webgpu") throw err;
+        const error = err instanceof ShardError ? err : void 0;
+        reasons.push({
+          backend: "webgpu",
+          code: error?.code.replace(/^gpu\//, "") ?? "device-failed",
+          message: error?.message ?? String(err)
+        });
+      }
+    } else if (choice === "webgpu") {
+      throw new ShardError("gpu/unsupported", "WebGPU is not available in this environment", {
+        hint: "Use a browser or webview with WebGPU, or pass `gpu` (e.g. from the `webgpu` package in Node)."
+      });
+    } else {
+      reasons.push({ backend: "webgpu", code: "no-webgpu", message: "This browser has no WebGPU" });
+    }
+  }
+  return openWebgl2(options, reasons);
+}
+async function openWebGpu(gpu, options, keep, reasons) {
+  const powerPreference = options.powerPreference ?? "high-performance";
+  const baseline = options.tier === "baseline" || keep === "baseline";
+  if (!baseline) {
+    const adapter2 = await gpu.requestAdapter({ powerPreference });
+    if (adapter2) {
+      const device2 = await requestDevice(adapter2, options);
+      const hdrSampleCount2 = await probeHdrSampleCount(device2);
+      return {
+        adapter: adapter2,
+        device: device2,
+        backend: "webgpu",
+        tier: tierOf(device2, false),
+        reasons,
+        hdrSampleCount: hdrSampleCount2,
+        gpu
+      };
+    }
+    if (keep === "full") throw new ShardError("gpu/no-adapter", "No WebGPU adapter was found");
+    reasons.push({
+      backend: "webgpu",
+      code: "no-core-adapter",
+      message: "No core WebGPU adapter; asking for a compatibility-mode one"
+    });
+  }
+  const adapter = await gpu.requestAdapter({ featureLevel: "compatibility", powerPreference });
+  if (!adapter) throw new ShardError("gpu/no-adapter", "No WebGPU adapter was found");
+  const device = await requestDevice(adapter, options);
+  const hdrSampleCount = await probeHdrSampleCount(device);
   return {
+    adapter,
     device,
-    format,
-    alphaMode: "opaque",
-    // COPY_SRC lets the renderer capture screenshots straight from the swapchain.
-    usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC
+    backend: "webgpu",
+    tier: tierOf(device, baseline),
+    reasons,
+    hdrSampleCount,
+    gpu
   };
 }
-async function requestDevice(options) {
-  const gpu = options.gpu ?? globalThis.navigator?.gpu;
-  if (!gpu) {
-    throw new ShardError("gpu/unsupported", "WebGPU is not available in this environment", {
-      hint: "Use a browser or webview with WebGPU, or pass `gpu` (e.g. from the `webgpu` package in Node)."
+async function openWebgl2(options, reasons) {
+  const webgl2 = await import("@aethervtt/shard-gpu-webgl2");
+  const settings = options.webgl2 ?? {};
+  const gpu = webgl2.createWebgl2Gpu({
+    canvas: options.canvas,
+    context: settings.context,
+    profile: settings.profile,
+    checkErrors: settings.checkErrors,
+    shaders: settings.shaders,
+    persist: settings.persist
+  });
+  const powerPreference = options.powerPreference ?? "high-performance";
+  const adapter = await gpu.requestAdapter({ powerPreference });
+  if (!adapter) {
+    const code = gpu.unavailable ?? "no-webgl2";
+    reasons.push({ backend: "webgl2", code, message: WEBGL2_MESSAGES[code] ?? code });
+    throw new ShardError("gpu/unsupported", "Neither WebGPU nor WebGL2 can run Shard here", {
+      hint: reasons.map((r) => `${r.backend}: ${r.message}`).join("; "),
+      // Each backend's reason, its backend as the path (probeGraphics reads them back).
+      details: reasons.map((r) => new ShardError(`gpu/${r.code}`, r.message, { path: r.backend }))
     });
   }
-  const adapter = await gpu.requestAdapter({
-    powerPreference: options.powerPreference ?? "high-performance"
-  });
-  if (!adapter) throw new ShardError("gpu/no-adapter", "No WebGPU adapter was found");
+  const device = await requestDevice(adapter, options);
+  const hdrSampleCount = await probeHdrSampleCount(device);
+  return {
+    adapter,
+    device,
+    backend: "webgl2",
+    tier: "baseline",
+    reasons,
+    hdrSampleCount,
+    gpu,
+    canvasContext: webgl2.canvasContext
+  };
+}
+const WEBGL2_MESSAGES = {
+  "no-webgl2": "This browser has no WebGL2",
+  "context-lost": "The WebGL2 context is lost",
+  "no-float-render-targets": "WebGL2 here has no float render targets (EXT_color_buffer_float)"
+};
+function tierOf(device, baseline) {
+  return baseline || !isCoreDevice(device) ? "baseline" : "full";
+}
+async function requestDevice(adapter, options) {
   const missing = (options.requiredFeatures ?? []).filter((f) => !adapter.features.has(f));
   if (missing.length > 0) {
     throw new ShardError(
@@ -149,25 +474,19 @@ async function requestDevice(options) {
       ...options.compressedTextures === false ? [] : COMPRESSED_TEXTURE_FEATURES
     ].filter((f, i, all) => all.indexOf(f) === i && adapter.features.has(f))
   ];
-  const device = await adapter.requestDevice({ label: "shard", requiredFeatures });
-  return { adapter, device };
+  return adapter.requestDevice({ label: "shard", requiredFeatures });
 }
 async function createGpuContext(options = {}) {
-  const { adapter, device } = await requestDevice(options);
-  const gpu = options.gpu ?? globalThis.navigator.gpu;
-  const format = gpu.getPreferredCanvasFormat();
-  let context;
-  if (options.canvas) {
-    const ctx = options.canvas.getContext("webgpu");
-    if (!ctx) throw new ShardError("gpu/no-context", "Could not get a WebGPU canvas context");
-    ctx.configure(canvasConfig(device, format));
-    context = ctx;
-  }
-  const result = new GpuContext(options, adapter, device, format, context);
-  result.resize();
+  const start = performance.now();
+  const opened = await openDevice(options);
+  const format = opened.gpu.getPreferredCanvasFormat();
+  const result = new GpuContext(options, opened.adapter, opened.device, format, opened);
+  result.deviceMs = performance.now() - start;
+  if (options.canvas) result.addSurface(options.canvas, { alpha: options.alpha });
   return result;
 }
 export {
   GpuContext,
-  createGpuContext
+  createGpuContext,
+  openDevice
 };

package/dist/errors.js

@@ -1,7 +1,14 @@
 import { ShardError } from "@aethervtt/shard-core";
 function toShardError(error, label) {
   const what = label ? `"${label}"` : "an unlabeled GPU object";
-  const isOom = typeof GPUOutOfMemoryError !== "undefined" && error instanceof GPUOutOfMemoryError;
+  if (error instanceof ShardError) {
+    return new ShardError(error.code, `${error.message} (in ${what})`, {
+      path: label,
+      hint: error.hint,
+      cause: error
+    });
+  }
+  const isOom = typeof GPUOutOfMemoryError !== "undefined" && error instanceof GPUOutOfMemoryError || error.name === "GPUOutOfMemoryError";
   return new ShardError(
     isOom ? "gpu/out-of-memory" : "gpu/validation",
     `WebGPU error in ${what}: ${error.message}`,

package/dist/index.d.ts

@@ -1,6 +1,10 @@
+export type { BakedTranslations } from '@aethervtt/shard-gpu-webgl2';
 export { GpuBuffer, type GpuBufferOptions } from './buffer.js';
 export { LayoutCache, PipelineCache } from './caches.js';
-export { type CreateGpuContextOptions, createGpuContext, type DeviceLostInfo, GpuContext, } from './context.js';
+export { type CreateGpuContextOptions, createGpuContext, type DeviceLostInfo, type GpuBackendChoice, GpuContext, type GpuStatus, type ShaderCacheStats, type Webgl2ContextOptions, } from './context.js';
 export { type GpuErrorListener, toShardError } from './errors.js';
 export { descriptorKey } from './key.js';
-export { type ProbeWebGpuOptions, probeWebGpu, type WebGpuSupport, type WebGpuUnsupportedReason, } from './probe.js';
+export { bufferCategory, DATA_TEXTURE_PREFIX, type GpuMemory, type GpuMemoryCategory, type GpuStats, type GpuUploads, SHARED_OWNER, textureBytes, textureCategory, UPLOAD_CATEGORIES, Upload, type UploadCategory, uploadCategory, } from './ledger.js';
+export { type GraphicsSupport, type ProbeGraphicsOptions, type ProbeWebGpuOptions, probeGraphics, probeWebGpu, type WebGpuSupport, type WebGpuUnsupportedReason, } from './probe.js';
+export { Surface, type SurfaceAlpha, type SurfaceOptions } from './surface.js';
+export { capabilitiesOf, type GpuBackendName, type GpuCapabilities, type GpuTier, type GraphicsReason, isCoreDevice, } from './tier.js';

package/dist/index.js

@@ -7,15 +7,43 @@ import {
 import { toShardError } from "./errors.js";
 import { descriptorKey } from "./key.js";
 import {
+  bufferCategory,
+  DATA_TEXTURE_PREFIX,
+  SHARED_OWNER,
+  textureBytes,
+  textureCategory,
+  UPLOAD_CATEGORIES,
+  Upload,
+  uploadCategory
+} from "./ledger.js";
+import {
+  probeGraphics,
   probeWebGpu
 } from "./probe.js";
+import { Surface } from "./surface.js";
+import {
+  capabilitiesOf,
+  isCoreDevice
+} from "./tier.js";
 export {
+  DATA_TEXTURE_PREFIX,
   GpuBuffer,
   GpuContext,
   LayoutCache,
   PipelineCache,
+  SHARED_OWNER,
+  Surface,
+  UPLOAD_CATEGORIES,
+  Upload,
+  bufferCategory,
+  capabilitiesOf,
   createGpuContext,
   descriptorKey,
+  isCoreDevice,
+  probeGraphics,
   probeWebGpu,
-  toShardError
+  textureBytes,
+  textureCategory,
+  toShardError,
+  uploadCategory
 };