@aethervtt/shard-gpu 0.0.1 → 0.2.0

package/dist/ledger.d.ts

@@ -0,0 +1,106 @@
+/** Live GPU objects counted against one owner (`gpu.stats(owner)`). */
+export interface GpuStats {
+    buffers: number;
+    textures: number;
+    /** Their memory: buffer sizes, and texture sizes over every mip level and sample. */
+    bytes: number;
+}
+/**
+ * What a GPU object is for, from its usage flags (0062): `targets` (textures rendered into),
+ * `textures` (sampled only), `geometry` (vertex and index buffers), `storage`, `uniforms`,
+ * `staging` (mappable: uploads and readbacks), and `other`.
+ */
+export type GpuMemoryCategory = 'targets' | 'textures' | 'geometry' | 'storage' | 'uniforms' | 'staging' | 'other';
+/**
+ * What bytes written to the GPU were for (0055), from the label of the buffer or texture written:
+ * `instances` (instance records), `meshes` (vertex and index data), `materials` (material
+ * uniforms), `textures`, `lights`, `shadows` (shadow views), `view` (camera and per-frame
+ * uniforms, culling parameters: derived from the view, not the scene), and `other`.
+ */
+export declare const UPLOAD_CATEGORIES: readonly ['instances', 'meshes', 'materials', 'textures', 'lights', 'shadows', 'view', 'other'];
+export type UploadCategory = (typeof UPLOAD_CATEGORIES)[number];
+/** Bytes written and objects created by an owner since the device was made (`gpu.uploads(owner)`). */
+export interface GpuUploads {
+    /** Cumulative bytes written, indexed like `UPLOAD_CATEGORIES`. */
+    readonly bytes: Float64Array;
+    /** Buffers and textures created. */
+    created: number;
+}
+/** Index of each category in `UPLOAD_CATEGORIES` (and in `GpuUploads.bytes`). */
+export declare const Upload: {
+    readonly instances: 0;
+    readonly meshes: 1;
+    readonly materials: 2;
+    readonly textures: 3;
+    readonly lights: 4;
+    readonly shadows: 5;
+    readonly view: 6;
+    readonly other: 7;
+};
+/**
+ * Labels data textures (0064): on the baseline tier, a `data:instances` texture holds what the
+ * `instances` storage buffer would, and counts as it would.
+ */
+export declare const DATA_TEXTURE_PREFIX = "data:";
+/**
+ * The upload category of a buffer or texture, from its label. Textures are `textures`, except data
+ * textures, which count as the buffer they stand in for.
+ */
+export declare function uploadCategory(label: string | undefined, texture: boolean): number;
+/** Live bytes counted against an owner, or everyone, by category (`gpu.memory(owner)`). */
+export interface GpuMemory {
+    bytes: number;
+    byCategory: Partial<Record<GpuMemoryCategory, number>>;
+}
+/** The category of a buffer from its usage. */
+export declare function bufferCategory(usage: number): GpuMemoryCategory;
+/** The category of a texture from its usage. */
+export declare function textureCategory(usage: number): GpuMemoryCategory;
+/** The owner of objects made while no app runs, and of per-device objects apps share. */
+export declare const SHARED_OWNER = "gpu";
+interface Entry {
+    readonly owner: Owned;
+    readonly texture: boolean;
+    readonly category: GpuMemoryCategory;
+    /** Index into `UPLOAD_CATEGORIES`. */
+    readonly upload: number;
+    readonly bytes: number;
+    readonly ref: WeakRef<GPUBuffer | GPUTexture>;
+    live: boolean;
+}
+interface Owned extends GpuStats {
+    readonly name: string;
+    readonly entries: Set<Entry>;
+    readonly uploads: GpuUploads;
+}
+/**
+ * Counts the buffers and textures a device creates, by owner (0052). Destroying an object uncounts
+ * it; so does garbage collection of one nobody destroyed. `release(owner)` destroys what an owner
+ * still has, which is how a disposed app gives back everything it made.
+ */
+export declare class Ledger {
+    private readonly owners;
+    private readonly finalizer;
+    track(object: GPUBuffer | GPUTexture, owner: string, texture: boolean, bytes: number, category?: GpuMemoryCategory, label?: string): void;
+    drop(entry: Entry): void;
+    /** Counts bytes written into a tracked object against its owner and upload category. */
+    upload(object: object, bytes: number): void;
+    /** Cumulative bytes written and objects created by `owner`. */
+    uploads(owner: string): GpuUploads;
+    /** Destroys every object `owner` still has. Returns how many there were. */
+    release(owner: string): number;
+    /** Forgets everything without destroying it: the device it lived on is gone. */
+    clear(): void;
+    stats(owner?: string): GpuStats;
+    /** Live bytes of `owner` (or everyone) by category. Walks every live object: not per frame. */
+    memory(owner?: string): GpuMemory;
+    /** Owners that have live objects, sorted. */
+    names(): string[];
+    private owned;
+}
+/** [block width, block height, bytes per block] for compressed formats; texels are 1×1 blocks. */
+/** A format's block width, height, and bytes per block (1×1 texels for uncompressed ones). */
+export declare function blockOf(format: GPUTextureFormat): [number, number, number];
+/** Bytes a texture takes: every mip level (and 3D slice), times its sample count. */
+export declare function textureBytes(descriptor: GPUTextureDescriptor): number;
+export {};

package/dist/ledger.js

@@ -0,0 +1,222 @@
+const UPLOAD_CATEGORIES = [
+  "instances",
+  "meshes",
+  "materials",
+  "textures",
+  "lights",
+  "shadows",
+  "view",
+  "other"
+];
+const Upload = {
+  instances: 0,
+  meshes: 1,
+  materials: 2,
+  textures: 3,
+  lights: 4,
+  shadows: 5,
+  view: 6,
+  other: 7
+};
+const DATA_TEXTURE_PREFIX = "data:";
+function uploadCategory(label, texture) {
+  let l = label ?? "";
+  if (texture) {
+    if (!l.startsWith(DATA_TEXTURE_PREFIX)) return Upload.textures;
+    l = l.slice(DATA_TEXTURE_PREFIX.length);
+  }
+  if (l === "instances/visible") return Upload.view;
+  if (l.startsWith("instances")) return Upload.instances;
+  if (l.startsWith("mesh/") || l.startsWith("mesh ")) return Upload.meshes;
+  if (l.startsWith("material")) return Upload.materials;
+  if (l === "lights" || l.startsWith("lights/")) return Upload.lights;
+  if (l.startsWith("shadows/")) return Upload.shadows;
+  if (l.startsWith("camera:") || l.startsWith("window/") || l === "globals" || l.startsWith("cull/") || l.endsWith("/view") || l.includes("light-clusters"))
+    return Upload.view;
+  return Upload.other;
+}
+const MAP_READ = 1;
+const MAP_WRITE = 2;
+const INDEX = 16;
+const VERTEX = 32;
+const UNIFORM = 64;
+const STORAGE = 128;
+const INDIRECT = 256;
+const RENDER_ATTACHMENT = 16;
+function bufferCategory(usage) {
+  if (usage & (MAP_READ | MAP_WRITE)) return "staging";
+  if (usage & (VERTEX | INDEX)) return "geometry";
+  if (usage & (STORAGE | INDIRECT)) return "storage";
+  if (usage & UNIFORM) return "uniforms";
+  return "other";
+}
+function textureCategory(usage) {
+  return usage & RENDER_ATTACHMENT ? "targets" : "textures";
+}
+const SHARED_OWNER = "gpu";
+const entryOf = /* @__PURE__ */ new WeakMap();
+function destroyTracked() {
+  const tracked = entryOf.get(this);
+  if (tracked) tracked.ledger.drop(tracked.entry);
+  Object.getPrototypeOf(this).destroy.call(this);
+  return void 0;
+}
+class Ledger {
+  owners = /* @__PURE__ */ new Map();
+  finalizer = new FinalizationRegistry((entry) => this.drop(entry));
+  track(object, owner, texture, bytes, category = texture ? "textures" : "other", label) {
+    const owned = this.owned(owner);
+    const entry = {
+      owner: owned,
+      texture,
+      category,
+      upload: uploadCategory(label, texture),
+      bytes,
+      ref: new WeakRef(object),
+      live: true
+    };
+    owned.entries.add(entry);
+    if (texture) owned.textures++;
+    else owned.buffers++;
+    owned.bytes += bytes;
+    owned.uploads.created++;
+    entryOf.set(object, { ledger: this, entry });
+    this.finalizer.register(object, entry, entry);
+    object.destroy = destroyTracked;
+  }
+  drop(entry) {
+    if (!entry.live) return;
+    entry.live = false;
+    this.finalizer.unregister(entry);
+    const owned = entry.owner;
+    owned.entries.delete(entry);
+    if (entry.texture) owned.textures--;
+    else owned.buffers--;
+    owned.bytes -= entry.bytes;
+  }
+  /** Counts bytes written into a tracked object against its owner and upload category. */
+  upload(object, bytes) {
+    const tracked = entryOf.get(object);
+    if (!tracked || tracked.ledger !== this) return;
+    const entry = tracked.entry;
+    entry.owner.uploads.bytes[entry.upload] += bytes;
+  }
+  /** Cumulative bytes written and objects created by `owner`. */
+  uploads(owner) {
+    return this.owned(owner).uploads;
+  }
+  /** Destroys every object `owner` still has. Returns how many there were. */
+  release(owner) {
+    const owned = this.owners.get(owner);
+    if (!owned) return 0;
+    let n = 0;
+    for (const entry of [...owned.entries]) {
+      const object = entry.ref.deref();
+      this.drop(entry);
+      object?.destroy();
+      n++;
+    }
+    return n;
+  }
+  /** Forgets everything without destroying it: the device it lived on is gone. */
+  clear() {
+    for (const owned of this.owners.values()) {
+      for (const entry of owned.entries) {
+        entry.live = false;
+        this.finalizer.unregister(entry);
+      }
+      owned.entries.clear();
+      owned.buffers = owned.textures = owned.bytes = 0;
+    }
+  }
+  stats(owner) {
+    if (owner !== void 0) {
+      const owned = this.owners.get(owner);
+      return {
+        buffers: owned?.buffers ?? 0,
+        textures: owned?.textures ?? 0,
+        bytes: owned?.bytes ?? 0
+      };
+    }
+    const total = { buffers: 0, textures: 0, bytes: 0 };
+    for (const owned of this.owners.values()) {
+      total.buffers += owned.buffers;
+      total.textures += owned.textures;
+      total.bytes += owned.bytes;
+    }
+    return total;
+  }
+  /** Live bytes of `owner` (or everyone) by category. Walks every live object: not per frame. */
+  memory(owner) {
+    const result = { bytes: 0, byCategory: {} };
+    const by = result.byCategory;
+    for (const owned of this.owners.values()) {
+      if (owner !== void 0 && owned.name !== owner) continue;
+      for (const entry of owned.entries) {
+        result.bytes += entry.bytes;
+        by[entry.category] = (by[entry.category] ?? 0) + entry.bytes;
+      }
+    }
+    return result;
+  }
+  /** Owners that have live objects, sorted. */
+  names() {
+    return [...this.owners.values()].filter((o) => o.buffers + o.textures > 0).map((o) => o.name).sort();
+  }
+  owned(name) {
+    let owned = this.owners.get(name);
+    if (!owned) {
+      owned = {
+        name,
+        entries: /* @__PURE__ */ new Set(),
+        buffers: 0,
+        textures: 0,
+        bytes: 0,
+        uploads: { bytes: new Float64Array(UPLOAD_CATEGORIES.length), created: 0 }
+      };
+      this.owners.set(name, owned);
+    }
+    return owned;
+  }
+}
+function blockOf(format) {
+  if (format.startsWith("astc-")) {
+    const [w, h] = format.slice(5).split(/[x-]/).map(Number);
+    return [w, h, 16];
+  }
+  if (/^(bc1|bc4|etc2-rgb8|eac-r11)/.test(format)) return [4, 4, 8];
+  if (/^(bc|etc2|eac)/.test(format)) return [4, 4, 16];
+  if (/^(rgba32|rgb32)/.test(format)) return [1, 1, 16];
+  if (/^(rgba16|rg32)/.test(format) || format === "depth32float-stencil8") return [1, 1, 8];
+  if (/^(r8|stencil8)/.test(format)) return [1, 1, 1];
+  if (/^(rg8|r16|depth16)/.test(format)) return [1, 1, 2];
+  return [1, 1, 4];
+}
+function textureBytes(descriptor) {
+  const size = descriptor.size;
+  const width = Array.isArray(size) ? size[0] : size.width;
+  const height = (Array.isArray(size) ? size[1] : size.height) ?? 1;
+  const layers = (Array.isArray(size) ? size[2] : size.depthOrArrayLayers) ?? 1;
+  const is3d = descriptor.dimension === "3d";
+  const [bw, bh, bytes] = blockOf(descriptor.format);
+  let total = 0;
+  for (let level = 0; level < (descriptor.mipLevelCount ?? 1); level++) {
+    const w = Math.max(1, width >> level);
+    const h = Math.max(1, height >> level);
+    const d = is3d ? Math.max(1, layers >> level) : layers;
+    total += Math.ceil(w / bw) * Math.ceil(h / bh) * bytes * d;
+  }
+  return total * (descriptor.sampleCount ?? 1);
+}
+export {
+  DATA_TEXTURE_PREFIX,
+  Ledger,
+  SHARED_OWNER,
+  UPLOAD_CATEGORIES,
+  Upload,
+  blockOf,
+  bufferCategory,
+  textureBytes,
+  textureCategory,
+  uploadCategory
+};

package/dist/node.d.ts

@@ -1,5 +1,28 @@
 import { type CreateGpuContextOptions, type GpuContext } from './context.js';
 /** Defines `GPUBufferUsage`, `GPUTextureUsage`, etc. on globalThis, as browsers do. */
 export declare function installWebGpuGlobals(): void;
+/**
+ * `SHARD_DAWN_OPTIONS` passes Dawn options, `;`-separated: CI's Windows job picks the software
+ * rasterizer with `adapter=Microsoft Basic Render Driver`, and `backend=vulkan` picks a backend.
+ */
 export declare function nodeGpu(): GPU;
+/**
+ * A device through Dawn. `SHARD_TIER=baseline` runs every one at the baseline tier (0064), on a
+ * compatibility-mode device: the whole suite, checked against what baseline can do.
+ */
 export declare function createNodeGpuContext(options?: Omit<CreateGpuContextOptions, 'gpu'>): Promise<GpuContext>;
+/** What a headless canvas's WebGPU context was told, for tests to check. */
+export interface HeadlessCanvasContext extends GPUCanvasContext {
+    /** The last `configure` call's configuration; undefined while unconfigured. */
+    readonly configuration: GPUCanvasConfiguration | undefined;
+    /** `configure` calls so far. */
+    readonly configures: number;
+}
+export interface HeadlessCanvas extends OffscreenCanvas {
+    readonly gpuContext: HeadlessCanvasContext;
+}
+/**
+ * A canvas for headless tests (Node has none): its WebGPU context renders into a texture on the
+ * configured device, so a surface on it can be drawn into and captured like a real one.
+ */
+export declare function headlessCanvas(width: number, height: number): HeadlessCanvas;

package/dist/node.js

@@ -8,13 +8,63 @@ function installWebGpuGlobals() {
 }
 function nodeGpu() {
   installWebGpuGlobals();
-  return create([]);
+  const options = process.env.SHARD_DAWN_OPTIONS?.split(";").filter(Boolean) ?? [];
+  return create(options);
 }
 function createNodeGpuContext(options = {}) {
-  return createGpuContext({ ...options, gpu: nodeGpu() });
+  const tier = options.tier ?? (process.env.SHARD_TIER === "baseline" ? "baseline" : void 0);
+  return createGpuContext({ ...options, tier, gpu: nodeGpu() });
+}
+function headlessCanvas(width, height) {
+  let configuration;
+  let configures = 0;
+  let current;
+  const canvas = { width, height };
+  const context = {
+    get canvas() {
+      return canvas;
+    },
+    get configuration() {
+      return configuration;
+    },
+    get configures() {
+      return configures;
+    },
+    configure(config) {
+      configuration = config;
+      configures++;
+      current = void 0;
+    },
+    unconfigure() {
+      configuration = void 0;
+      current?.destroy();
+      current = void 0;
+    },
+    getConfiguration: () => configuration ?? null,
+    getCurrentTexture() {
+      if (!configuration) throw new Error("getCurrentTexture on an unconfigured canvas");
+      if (!current || current.width !== canvas.width || current.height !== canvas.height) {
+        current?.destroy();
+        const device = configuration.device;
+        const create2 = Object.getPrototypeOf(device).createTexture;
+        current = create2.call(device, {
+          label: "headless-canvas",
+          size: [canvas.width, canvas.height],
+          format: configuration.format,
+          usage: configuration.usage ?? GPUTextureUsage.RENDER_ATTACHMENT
+        });
+      }
+      return current;
+    }
+  };
+  canvas.gpuContext = context;
+  return Object.assign(canvas, {
+    getContext: (kind) => kind === "webgpu" ? context : null
+  });
 }
 export {
   createNodeGpuContext,
+  headlessCanvas,
   installWebGpuGlobals,
   nodeGpu
 };

package/dist/probe.d.ts

@@ -1,4 +1,6 @@
 import { ShardError } from '@aethervtt/shard-core';
+import { type GpuBackendChoice, type Webgl2ContextOptions } from './context.js';
+import { type GpuBackendName, type GpuCapabilities, type GpuTier, type GraphicsReason } from './tier.js';
 export interface ProbeWebGpuOptions {
     /** The WebGPU entry point. Defaults to `navigator.gpu`; in Node pass the `webgpu` package's. */
     gpu?: GPU;
@@ -36,3 +38,35 @@ export interface WebGpuSupport {
  * throws, so a host can show an honest message instead of a blank canvas.
  */
 export declare function probeWebGpu(options?: ProbeWebGpuOptions): Promise<WebGpuSupport>;
+export interface ProbeGraphicsOptions {
+    /** The WebGPU entry point. Defaults to `navigator.gpu`; in Node pass the `webgpu` package's. */
+    gpu?: GPU;
+    /** Which backends to try, as `createGpuContext` has it. Default 'auto'. */
+    backend?: GpuBackendChoice;
+    /** WebGL2 settings (a fake context, in tests). */
+    webgl2?: Webgl2ContextOptions;
+    /** `'baseline'`: classify the device the baseline tier would get (a compatibility-mode one). */
+    tier?: 'baseline';
+    powerPreference?: GPUPowerPreference;
+    /** Gives up after this long: some drivers never answer. Default 5000 ms. */
+    timeoutMs?: number;
+}
+/** What `probeGraphics` found: the backend and tier an app would get, and why not better (0064). */
+export interface GraphicsSupport {
+    backend: GpuBackendName | 'none';
+    tier: GpuTier | 'none';
+    /** Undefined when nothing opened. */
+    capabilities: GpuCapabilities | undefined;
+    /** Why a better option was skipped, or why none opened. */
+    reasons: GraphicsReason[];
+    adapter?: {
+        vendor: string;
+        architecture: string;
+        description: string;
+    };
+}
+/**
+ * Opens the device an app would get, the same way `createGpuContext` does, classifies it from what
+ * it can actually do, and destroys it again. Never throws: an honest `none` with reasons instead.
+ */
+export declare function probeGraphics(options?: ProbeGraphicsOptions): Promise<GraphicsSupport>;

package/dist/probe.js

@@ -1,4 +1,8 @@
 import { ShardError } from "@aethervtt/shard-core";
+import { openDevice } from "./context.js";
+import {
+  capabilitiesOf
+} from "./tier.js";
 const HINTS = {
   "no-webgpu": "This browser has no WebGPU. Use a current Chrome, Edge, or Safari, or enable WebGPU in its settings.",
   "no-adapter": "WebGPU is present but found no usable GPU. It may be blocklisted or disabled.",
@@ -75,6 +79,66 @@ function unsupported(reason, features, missing, detail) {
     missing
   };
 }
+async function probeGraphics(options = {}) {
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  const opening = openDevice({
+    gpu: options.gpu,
+    tier: options.tier,
+    powerPreference: options.powerPreference,
+    backend: options.backend,
+    webgl2: options.webgl2
+  });
+  try {
+    const opened = await Promise.race([opening, timeout]);
+    if (opened === "timeout") {
+      void opening.then((o) => o.device.destroy()).catch(() => {
+      });
+      return none([{ backend: "webgpu", code: "timeout", message: MESSAGES.timeout }]);
+    }
+    const info = opened.adapter.info;
+    const support = {
+      backend: opened.backend,
+      tier: opened.tier,
+      capabilities: capabilitiesOf(opened.device, opened.backend, opened.hdrSampleCount),
+      reasons: opened.reasons,
+      adapter: {
+        vendor: info?.vendor ?? "",
+        architecture: info?.architecture ?? "",
+        description: info?.description ?? ""
+      }
+    };
+    opened.device.destroy();
+    return support;
+  } catch (err) {
+    const error = err instanceof ShardError ? err : void 0;
+    if (error?.details?.length) {
+      return none(
+        error.details.map((d) => ({
+          backend: d.path,
+          code: d.code.replace(/^gpu\//, ""),
+          message: d.message
+        }))
+      );
+    }
+    return none([
+      {
+        backend: "webgpu",
+        code: error?.code.replace(/^gpu\//, "") ?? "device-failed",
+        message: error?.message ?? String(err)
+      }
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function none(reasons) {
+  return { backend: "none", tier: "none", capabilities: void 0, reasons };
+}
 export {
+  probeGraphics,
   probeWebGpu
 };

package/dist/surface.d.ts

@@ -0,0 +1,51 @@
+import type { GpuContext } from './context.js';
+/**
+ * How a surface composites over the page. premultiplied: its pixels are premultiplied RGBA, so a
+ * clear alpha of 0 shows what's under the canvas (0052).
+ */
+export type SurfaceAlpha = 'opaque' | 'premultiplied';
+export interface SurfaceOptions {
+    /** Default 'opaque'. */
+    alpha?: SurfaceAlpha;
+    /** Names it in errors and `render.describe`. Default `surface`, `surface-2`, … */
+    label?: string;
+}
+/**
+ * A configured canvas on a `GpuContext` (0052): its own canvas context and alpha mode, sized from a
+ * ResizeObserver, reconfigured after a device loss. It's a render target: cameras without a target
+ * render into their app's surface.
+ */
+export declare class Surface {
+    readonly label: string;
+    readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+    readonly alpha: SurfaceAlpha;
+    readonly context: GPUCanvasContext;
+    /** Cameras showing on a surface render at the RenderScale and are upscaled (0051). */
+    readonly renderScale = true;
+    /** Canvas pixels per CSS pixel (devicePixelRatio) at the last resize. */
+    pixelRatio: number;
+    /** The device it's configured for. */
+    readonly gpu: GpuContext;
+    private readonly observer;
+    private readonly resizeListeners;
+    private removed_;
+    /** @internal Made by `GpuContext.addSurface`. */
+    constructor(gpu: GpuContext, canvas: HTMLCanvasElement | OffscreenCanvas, context: GPUCanvasContext, options: Required<SurfaceOptions>);
+    get format(): GPUTextureFormat;
+    get width(): number;
+    get height(): number;
+    /** True once `remove()` was called. */
+    get removed(): boolean;
+    /** The texture to render into this frame. */
+    texture(): GPUTexture;
+    /** Calls `listener` after the canvas's backing size changes. Returns an unsubscribe function. */
+    onResize(listener: () => void): () => void;
+    /** Unconfigures the canvas, stops observing it, and takes it off the device. Idempotent. */
+    remove(): void;
+    /** @internal Configures the canvas for the current device, keeping its alpha mode. */
+    configure(): void;
+    /** Sizes the backing store from the element's CSS size (no-op for an OffscreenCanvas). */
+    private measure;
+    private onObserved;
+    private resize;
+}