@vibecook/ice 0.11.0 → 0.15.0-desk.1

package/dist/types/packages/desk/src/gpu-memory.d.ts

@@ -0,0 +1,54 @@
+/** A format's block: its footprint in texels and its bytes. `guessed` — a format this table does not know, weighed as 4 bytes a texel. */
+export interface FormatBlock {
+    readonly w: number;
+    readonly h: number;
+    readonly bytes: number;
+    readonly guessed?: boolean;
+}
+export declare function formatBlock(format: string): FormatBlock;
+/** An extent's width, height and depth-or-layers — the list form (`[w, h?, d?]`) or the dictionary form. */
+export declare function extentOf(size: GPUExtent3DStrict): [number, number, number];
+/** The bytes of `size` texels of `format` in one mip (a copy's weight): ⌈w / bw⌉ × ⌈h / bh⌉ × blockBytes × depth. */
+export declare function regionBytes(format: string, size: GPUExtent3DStrict): number;
+/** A texture's logical bytes by the formula above. */
+export declare function textureBytes(d: {
+    readonly size: GPUExtent3DStrict;
+    readonly format: string;
+    readonly mipLevelCount?: number;
+    readonly sampleCount?: number;
+    readonly dimension?: GPUTextureDimension;
+}): number;
+/** One ledger row: the live bytes, and how many textures and buffers make them. */
+export interface GpuMemoryRow {
+    readonly bytes: number;
+    readonly textures: number;
+    readonly buffers: number;
+}
+/** The ledger's reading: live bytes by label prefix (the kind), textures and buffers apart, the total; and its turnover. */
+export interface GpuMemory {
+    /** Live bytes by the resource's label prefix — `paper`, `board`, `photo` …; `?` for an unlabelled one. */
+    readonly byLabel: Readonly<Record<string, GpuMemoryRow>>;
+    readonly textures: number;
+    readonly buffers: number;
+    readonly total: number;
+    /** Resources made since the install (a make every frame is a finding), destroyed, and taken by the collector undestroyed. */
+    readonly made: number;
+    readonly destroyed: number;
+    readonly collected: number;
+    /** Textures whose format the byte table does not know (weighed as 4 bytes a texel). */
+    readonly guessed: number;
+}
+export interface MemoryLedger {
+    /** The ledger as of now (a fresh copy). */
+    read(): GpuMemory;
+    /** The `n` heaviest live labels, full label (`board/ink 12` — every board's raster its own row), heaviest first. */
+    top(n?: number): readonly {
+        readonly label: string;
+        readonly bytes: number;
+        readonly count: number;
+    }[];
+    /** Restore the device's own `createTexture` / `createBuffer`. What it made meanwhile still reports its `destroy` to nobody. Idempotent. */
+    detach(): void;
+}
+/** Keep a ledger of `device`'s live textures and buffers from now on. One per device: asking twice returns the one. */
+export declare function instrumentMemory(device: GPUDevice): MemoryLedger;

package/dist/types/packages/desk/src/gpu-profiler.d.ts

@@ -0,0 +1,141 @@
+import type { GpuMemory, MemoryLedger } from "./gpu-memory";
+import { type KindDraws, type PassCounts, type PassTime, type PassTiming } from "./pass-instrument";
+import type { SubmitInstrument, UploadTally } from "./submit-instrument";
+export interface GpuFrameCounts extends PassCounts {
+    /** `queue.submit` calls in the frame. */
+    readonly submits: number;
+    /** Uploads (`writeBuffer` + `writeTexture` + `copyExternalImageToTexture`) and their bytes. */
+    readonly writes: number;
+    readonly uploadBytes: number;
+    /** The `copyExternalImageToTexture` uploads alone (a picture, a calendar tile). */
+    readonly externals: number;
+}
+export interface GpuFrameReport {
+    /** The profiler's frame number (monotonic across arms). */
+    readonly frame: number;
+    /** "frame": one the desk drew; "loose": GPU work the host's boundary closed with no frame in it — reported, never in the window. */
+    readonly kind: "frame" | "loose";
+    /** `performance.now()` at the frame's first command encoder. */
+    readonly at: number;
+    /** THE HEADLINE: GPU ms from the first timed pass's begin to the last one's end; null when untimed. */
+    readonly span: number | null;
+    /** The passes' own durations summed — NOT the frame's time: overlapping passes count twice, the GPU's waits between them not at all. */
+    readonly sum: number | null;
+    /** The GPU BUSY in the frame: the union of its passes' intervals — overlaps once, waits not at all; `span − busy` is what it waited (the drawable). */
+    readonly busy: number | null;
+    /** The timed passes, ms from the frame's earliest timestamp. */
+    readonly passes: readonly PassTime[];
+    readonly counts: GpuFrameCounts;
+    /** Draws and instances by the kind that drew (the pipeline's label prefix). */
+    readonly byKind: Readonly<Record<string, KindDraws>>;
+    /** The frame's uploads by the written resource's label prefix. */
+    readonly uploads: Readonly<Record<string, UploadTally>>;
+    /** CPU ms: `encode` — the frame's first command encoder to its close; `flush` — the host's flush that held it (null: none, a tool's frame). */
+    readonly cpu: {
+        readonly encode: number;
+        readonly flush: number | null;
+    };
+    /** The ledger's live GPU memory as the frame completed; null when the host keeps no ledger. */
+    readonly memory: GpuMemory | null;
+    readonly timing: PassTiming;
+    /** Every timestamp delta a whole multiple of 100 µs — Dawn's quantisation (`UNQUANTISED_TIMESTAMPS_FLAG` turns it off); null untimed. */
+    readonly quantised: boolean | null;
+}
+/** Rolling percentiles over the window: nearest rank. */
+export interface Rolling {
+    readonly n: number;
+    readonly p50: number;
+    readonly p95: number;
+    readonly max: number;
+}
+export interface GpuProfileStats {
+    readonly armed: boolean;
+    /** Drawn frames in the window (loose work never enters it). */
+    readonly frames: number;
+    /** The GPU span; null while no frame in the window was timed. */
+    readonly span: Rolling | null;
+    /** The GPU busy (the span less the waits). */
+    readonly busy: Rolling | null;
+    readonly encode: Rolling | null;
+    readonly flush: Rolling | null;
+    readonly draws: Rolling | null;
+    readonly instances: Rolling | null;
+    readonly pipelines: Rolling | null;
+    readonly bindGroups: Rolling | null;
+    readonly passes: Rolling | null;
+    readonly submits: Rolling | null;
+    readonly uploadBytes: Rolling | null;
+    /** Most timed frames in the window read quantised → true (a real delta lands on a 100 µs multiple now and then, by chance — one frame is not the clock); else false; nothing timed → null. */
+    readonly quantised: boolean | null;
+    /** The switch that unquantises timestamps — what the dock says when `quantised`. */
+    readonly unquantise: string;
+    /** Samples dropped for a full readback ring, and readbacks in flight (this arming). */
+    readonly dropped: number;
+    readonly inFlight: number;
+}
+export interface TraceEvent {
+    readonly name: string;
+    readonly ph: "X" | "C" | "M";
+    readonly ts: number;
+    readonly dur?: number;
+    readonly pid: number;
+    readonly tid: number;
+    readonly cat?: string;
+    readonly args?: Readonly<Record<string, unknown>>;
+}
+/** A Chrome trace-event file (the JSON object format): Perfetto's and chrome://tracing's. */
+export interface TraceJson {
+    readonly traceEvents: readonly TraceEvent[];
+    readonly displayTimeUnit: "ms";
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface GpuProfiler {
+    /** The device has timestamp-query: frames are timed. */
+    readonly supported: boolean;
+    armed(): boolean;
+    /** Arm — refcounted: the first arm installs the instruments; returns this arm's release (the last release takes them all off). */
+    arm(): () => void;
+    /** The frames completed since the last take (drained, oldest first) — a rig's reading. */
+    take(): GpuFrameReport[];
+    /** The last frame completed. */
+    last(): GpuFrameReport | null;
+    /** Rolling p50 / p95 / max over the window's drawn frames. */
+    stats(): GpuProfileStats;
+    /** Called with every frame completed while armed; returns the unsubscribe. */
+    subscribe(listener: (report: GpuFrameReport) => void): () => void;
+    /** The host's boundary — its flush ended after `ms`: work with no frame is closed as loose, and the frames it held are given its ms. */
+    flushed(ms: number): void;
+    /** The next `n` frames as a trace-event JSON (arming for as long as it takes); at `timeoutMs` (10 s) it answers with what came. */
+    capture(n: number, opts?: {
+        readonly timeoutMs?: number;
+        readonly measure?: boolean;
+    }): Promise<TraceJson>;
+    /** Disarm whatever holds it and stop. */
+    dispose(): void;
+}
+export interface GpuProfilerOptions {
+    readonly device: GPUDevice;
+    /** The submit instrument, held while armed and released after — the host's (the layer's `submits()` may hold it for good). */
+    readonly submits: {
+        hold(): SubmitInstrument;
+        release(): void;
+    };
+    /** The host's memory ledger, if it keeps one. */
+    readonly ledger?: () => MemoryLedger | undefined;
+    /** Drawn frames in the rolling window (120). */
+    readonly window?: number;
+    /** The encoders whose submit closes a frame (the pass instrument's default: `ground`, `hold`). */
+    readonly frameEncoders?: readonly string[];
+}
+/** Nearest-rank percentiles of `values`; null when empty. */
+export declare function rolling(values: readonly number[]): Rolling | null;
+/** The GPU's busy time in `passes`: the union of their intervals — overlapping passes counted once, the gaps between them not at all. */
+export declare function busyOf(passes: readonly PassTime[]): number | null;
+/** The span of `passes`: first begin → last end; null when there are none. */
+export declare function spanOf(passes: readonly PassTime[]): number | null;
+export declare function createGpuProfiler(opts: GpuProfilerOptions): GpuProfiler;
+/** Frames → a trace-event JSON: CPU spans on the main thread, each GPU pass on a track of its own, the span, counters. µs throughout. */
+export declare function traceOf(frames: readonly GpuFrameReport[], where: ReadonlyMap<number, {
+    readonly flushAt: number | null;
+    readonly firstSubmit: number;
+}>, meta?: Readonly<Record<string, unknown>>): TraceJson;

package/dist/types/packages/desk/src/gpu-wrap.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Replace `obj[key]` with `value`; the undo puts back exactly what was there — the own property it had, or no own property at all
+ * (the prototype's method shows through again, so "the wrappers are gone" is literal). Wrapped over since, the undo leaves
+ * ours beneath theirs: the caller's wrapper must then pass through.
+ */
+export declare function swapMethod<T extends object, K extends keyof T>(obj: T, key: K, value: T[K]): () => void;
+/** A resource's label prefix — its kind: `paper/notes` → `paper`; no label → `?`. */
+export declare const prefixOf: (label: string | undefined) => string;