@aethervtt/shard-gpu 0.0.1 → 0.2.0

package/dist/caches.d.ts

@@ -10,17 +10,29 @@ export declare class PipelineCache {
     private readonly render_;
     private readonly compute_;
     private readonly gpu;
+    /** Compiles in flight, and when the current run of them started (0062's `coldStart.pipelines`). */
+    private compiling;
+    private busySince;
+    private busyTotal;
     constructor(gpu: GpuContext);
+    /**
+     * Wall time, in ms, during which at least one pipeline was compiling, counted since the cache was
+     * made. Compiles that overlap count once.
+     */
+    busyMs(now?: number): number;
     render(descriptor: GPURenderPipelineDescriptor): GPURenderPipeline | undefined;
     compute(descriptor: GPUComputePipelineDescriptor): GPUComputePipeline | undefined;
     /** Pipelines still compiling. */
     get pending(): number;
     /** Resolves when every pipeline requested so far has finished compiling (or failed). */
     whenIdle(): Promise<void>;
+    /** Why the pipeline for `descriptor` failed, if it did (0061): callers draw a fallback instead. */
+    failure(descriptor: GPURenderPipelineDescriptor | GPUComputePipelineDescriptor): ShardError | undefined;
     /** Errors from pipelines that failed to compile, by label. */
     failures(): ShardError[];
     clear(): void;
     private get;
+    private compiled;
 }
 /** Bind group layouts, pipeline layouts, and samplers: equal descriptors give the same object. */
 export declare class LayoutCache {

package/dist/caches.js

@@ -6,9 +6,20 @@ class PipelineCache {
   render_ = /* @__PURE__ */ new Map();
   compute_ = /* @__PURE__ */ new Map();
   gpu;
+  /** Compiles in flight, and when the current run of them started (0062's `coldStart.pipelines`). */
+  compiling = 0;
+  busySince = 0;
+  busyTotal = 0;
   constructor(gpu) {
     this.gpu = gpu;
   }
+  /**
+   * Wall time, in ms, during which at least one pipeline was compiling, counted since the cache was
+   * made. Compiles that overlap count once.
+   */
+  busyMs(now = performance.now()) {
+    return this.busyTotal + (this.compiling > 0 ? now - this.busySince : 0);
+  }
   render(descriptor) {
     return this.get(this.render_, descriptor, (d) => this.gpu.device.createRenderPipelineAsync(d));
   }
@@ -30,6 +41,12 @@ class PipelineCache {
     }
     await Promise.all(pending);
   }
+  /** Why the pipeline for `descriptor` failed, if it did (0061): callers draw a fallback instead. */
+  failure(descriptor) {
+    const key = descriptorKey(descriptor);
+    const state = this.render_.get(key) ?? this.compute_.get(key);
+    return state?.status === "failed" ? state.error : void 0;
+  }
   /** Errors from pipelines that failed to compile, by label. */
   failures() {
     const out = [];
@@ -46,15 +63,19 @@ class PipelineCache {
     const key = descriptorKey(descriptor);
     const state = map.get(key);
     if (state?.status === "ready") return state.pipeline;
+    if (state?.status === "failed") return void 0;
     if (state) {
       this.skipped++;
       return void 0;
     }
+    if (this.compiling++ === 0) this.busySince = performance.now();
     const promise = create(descriptor).then(
       (pipeline) => {
+        this.compiled();
         map.set(key, { status: "ready", pipeline });
       },
       (err) => {
+        this.compiled();
         const error = toShardError(err, descriptor.label);
         map.set(key, { status: "failed", error });
         this.gpu.reportError(error);
@@ -64,6 +85,9 @@ class PipelineCache {
     this.skipped++;
     return void 0;
   }
+  compiled() {
+    if (--this.compiling === 0) this.busyTotal += performance.now() - this.busySince;
+  }
 }
 class LayoutCache {
   bindGroupLayouts = /* @__PURE__ */ new Map();

package/dist/context.d.ts

@@ -1,9 +1,56 @@
 import { ShardError } from '@aethervtt/shard-core';
+import type { BakedTranslations } from '@aethervtt/shard-gpu-webgl2';
 import { LayoutCache, PipelineCache } from './caches.js';
 import { type GpuErrorListener } from './errors.js';
+import { type GpuMemory, type GpuStats, type GpuUploads } from './ledger.js';
+import { Surface, type SurfaceAlpha, type SurfaceOptions } from './surface.js';
+import { type GpuBackendName, type GpuCapabilities, type GpuTier, type GraphicsReason } from './tier.js';
+/** The graphics API to run on (0064): 'auto' tries WebGPU, then WebGL2. */
+export type GpuBackendChoice = 'auto' | GpuBackendName;
+/** WebGL2 settings, for tests and tools. */
+export interface Webgl2ContextOptions {
+    /** 'minimum' holds the device to WebGL2's floor (tests of the least capable devices). */
+    profile?: 'native' | 'minimum';
+    /** Checks GL errors after every submit: a round trip to the GPU process, so for dev and tests. */
+    checkErrors?: boolean;
+    /** A context to use as it is: tests pass a fake one. */
+    context?: WebGL2RenderingContext;
+    /**
+     * A baked translation set (`shard shaders bake`), or where it's served: with every shader in it,
+     * naga, the WGSL translator, never loads.
+     */
+    shaders?: string | URL | BakedTranslations;
+    /** Keeps translations in IndexedDB across sessions. Default true where there is IndexedDB. */
+    persist?: boolean;
+}
+/** Where WebGL2's translations came from this session (0064's shader cache). */
+export interface ShaderCacheStats {
+    hits: {
+        memory: number;
+        baked: number;
+        stored: number;
+    };
+    misses: {
+        entry: string;
+        stage: 'vertex' | 'fragment';
+        ms: number;
+    }[];
+    nagaLoadMs: number | undefined;
+    baked: number;
+}
 export interface CreateGpuContextOptions {
-    /** Omit for offscreen/headless rendering. */
+    /**
+     * The graphics API (0064). 'auto' (default): WebGPU when it gives a device, through exactly the
+     * request Shard has always made; else WebGL2, running the baseline tier. 'webgpu' never falls
+     * back; 'webgl2' doesn't try WebGPU.
+     */
+    backend?: GpuBackendChoice;
+    /** WebGL2 settings, when it's the backend. */
+    webgl2?: Webgl2ContextOptions;
+    /** A canvas to add as the first surface. Omit for a device only (headless, or surfaces later). */
     canvas?: HTMLCanvasElement | OffscreenCanvas;
+    /** The canvas surface's alpha mode. Default 'opaque'. */
+    alpha?: SurfaceAlpha;
     /** The WebGPU entry point. Defaults to `navigator.gpu`; in Node pass the `webgpu` package's. */
     gpu?: GPU;
     /** Requested if the adapter supports them. */
@@ -16,51 +63,172 @@ export interface CreateGpuContextOptions {
      * true; Basis textures transcode to whichever the device ends up with.
      */
     compressedTextures?: boolean;
+    /**
+     * How a lost device is replaced (0061): up to `attempts` tries, `intervalMs` apart, before the
+     * context gives up (`status: 'failed'`). Default 3 tries, 1 s apart.
+     */
+    recovery?: {
+        attempts?: number;
+        intervalMs?: number;
+    };
+    /**
+     * `'baseline'` runs the baseline tier (0064) even where the full one would: on WebGPU, a
+     * compatibility-mode device. Omitted, the device decides: `full` on a core WebGPU device,
+     * `baseline` on a compatibility-mode one (asked for only when no core adapter is found).
+     */
+    tier?: 'baseline';
 }
+/** Whether the device works: `lost` between a loss and its replacement, `failed` if that gave up. */
+export type GpuStatus = 'ok' | 'lost' | 'failed';
 export interface DeviceLostInfo {
     reason: string;
     message: string;
 }
 /**
- * The adapter, device, and optional canvas, plus the caches every renderer needs. After a device
- * loss, `recreate()` gets a new device and bumps `generation`; `GpuBuffer`s and caches rebuild
- * against it.
+ * The adapter and device, the canvases it draws into (surfaces), and the caches every renderer
+ * needs. Several apps can share one (0052): each counts its buffers and textures under its own
+ * owner. After a device loss, `recreate()` gets a new device and bumps `generation`; `GpuBuffer`s,
+ * caches, and surfaces rebuild against it.
  */
 export declare class GpuContext {
     adapter: GPUAdapter;
     device: GPUDevice;
     readonly format: GPUTextureFormat;
-    readonly canvas: HTMLCanvasElement | OffscreenCanvas | undefined;
-    readonly context: GPUCanvasContext | undefined;
     readonly features: ReadonlySet<string>;
+    /** The graphics API the device runs on (0064). */
+    readonly backend: GpuBackendName;
+    /**
+     * 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.
+     */
+    readonly tier: GpuTier;
+    /** What the device can do, as far as the tiers care. */
+    capabilities: GpuCapabilities;
+    /** Why better options were skipped while opening the device (no core adapter, say). */
+    readonly reasons: readonly GraphicsReason[];
     readonly pipelines: PipelineCache;
     readonly layouts: LayoutCache;
     /** Increments when the device is replaced. */
     generation: number;
-    /** Canvas pixels per CSS pixel (devicePixelRatio) at the last resize; 1 without a canvas. */
-    pixelRatio: number;
+    /**
+     * 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: number;
+    /**
+     * 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: string;
     /** Most recent GPU errors, newest last. */
     readonly errors: ShardError[];
+    /** Whether the device works now (0061). */
+    status: GpuStatus;
     private readonly options;
     private readonly errorListeners;
     private readonly lostListeners;
-    constructor(options: CreateGpuContextOptions, adapter: GPUAdapter, device: GPUDevice, format: GPUTextureFormat, context: GPUCanvasContext | undefined);
-    /** Match the canvas backing size to its CSS size. Returns true if it changed. */
-    resize(): boolean;
+    private readonly surfaces_;
+    private readonly ledger;
+    private readonly shared_;
+    private recreating;
+    private destroyed;
+    /** The WebGL2 shim's canvas contexts, when that's the backend. */
+    private readonly canvasContext;
+    constructor(options: CreateGpuContextOptions, adapter: GPUAdapter, device: GPUDevice, format: GPUTextureFormat, opened?: {
+        backend?: GpuBackendName;
+        tier?: GpuTier;
+        reasons?: GraphicsReason[];
+        hdrSampleCount?: 1 | 4;
+        canvasContext?: (canvas: HTMLCanvasElement | OffscreenCanvas) => unknown;
+    });
+    /** The canvases this device draws into, in the order they were added. */
+    get surfaces(): readonly Surface[];
+    /** Configures a canvas as a surface of this device. `surface.remove()` gives it back. */
+    addSurface(canvas: HTMLCanvasElement | OffscreenCanvas, options?: SurfaceOptions): Surface;
+    /** @internal Called by `Surface.remove()`. */
+    forgetSurface(surface: Surface): void;
+    /** WebGL2: where shader translations came from, and what naga translated (0064). */
+    shaderCache(): ShaderCacheStats | undefined;
+    /**
+     * WebGL2: every shader translation this session used, as a baked set to ship as
+     * `webgl2.shaders` (0064). Undefined on WebGPU.
+     */
+    exportShaderCache(): BakedTranslations | undefined;
+    /** Runs `fn` with new buffers and textures counted against `owner`. */
+    withOwner<T>(owner: string, fn: () => T): T;
+    /** Live buffers and textures this device made for `owner`, or for everyone (0052). */
+    stats(owner?: string): GpuStats;
+    /** Live bytes for `owner` (or everyone) by what they're for: targets, textures, geometry... (0062). */
+    memory(owner?: string): GpuMemory;
+    /**
+     * 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: string): GpuUploads;
+    /** Owners with live objects, sorted. */
+    owners(): string[];
+    /** Destroys every buffer and texture `owner` still has. Returns how many. */
+    release(owner: string): number;
+    /**
+     * 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<T>(key: string, create: (device: GPUDevice) => T): T;
     onError(listener: GpuErrorListener): () => void;
     onDeviceLost(listener: (info: DeviceLostInfo) => void): () => void;
+    /** Error and device-loss listeners, for teardown tests. */
+    get listenerCount(): {
+        error: number;
+        lost: number;
+    };
     reportError(error: ShardError): void;
     /**
      * Runs `fn` inside a validation error scope. Errors are reported asynchronously (WebGPU
      * resolves error scopes later) with `label` naming the object.
      */
     validate<T>(label: string, fn: () => T): T;
-    /** Gets a fresh adapter and device after a loss, and reconfigures the canvas. */
+    /**
+     * 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(): Promise<void>;
+    /** Replaces the device, retrying as `options.recovery` says; `failed` once every try failed. */
+    private recover;
     /** For tests and debugging: destroys the device and reports it as an unexpected loss. */
     simulateDeviceLoss(): void;
+    /** Removes every surface and destroys the device. */
     destroy(): void;
+    private replaceDevice;
     private attach;
+    /**
+     * Counts every buffer and texture the device makes against the current owner, and every byte
+     * written into one against its owner and upload category.
+     */
+    private instrument;
     private handleLoss;
 }
+export interface OpenedDevice {
+    adapter: GPUAdapter;
+    device: GPUDevice;
+    backend: GpuBackendName;
+    tier: GpuTier;
+    reasons: GraphicsReason[];
+    /** See `GpuCapabilities.hdrSampleCount`. */
+    hdrSampleCount: 1 | 4;
+    /** The entry point the device came from (its preferred canvas format). */
+    gpu: Pick<GPU, 'getPreferredCanvasFormat'>;
+    /** WebGL2: the shim's canvas contexts. */
+    canvasContext?: (canvas: HTMLCanvasElement | OffscreenCanvas) => unknown;
+}
+/**
+ * The device for `options` (0064): on WebGPU, a core device through exactly the request Shard has
+ * always made, else a compatibility-mode one; failing both (or asked to), a WebGL2 one. Both of
+ * the latter run the baseline tier. `keep` and `keepBackend` replace a lost device as it was: a
+ * core device isn't swapped for a compatibility one mid-session, or WebGPU for WebGL2.
+ */
+export declare function openDevice(options: CreateGpuContextOptions, keep?: GpuTier, keepBackend?: GpuBackendName): Promise<OpenedDevice>;
+/**
+ * A device, plus a first surface when `options.canvas` is given. On WebGPU without a core adapter
+ * it opens a compatibility-mode device and runs the baseline tier (`gpu.tier`, 0064).
+ */
 export declare function createGpuContext(options?: CreateGpuContextOptions): Promise<GpuContext>;