@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/objects/images/texture-budget.js

@@ -0,0 +1,215 @@
+import { createContext, useEffect, useSyncExternalStore } from 'react';
+import { createLogger } from '../../utils/logging';
+const logger = createLogger('texture-budget');
+/** Bytes one RGBA texel occupies. */
+const BYTES_PER_PIXEL = 4;
+/**
+ * How much a full mipmap chain adds over the base level: the 1/4 + 1/16 + … geometric series sums to
+ * 1/3, so a mipmapped texture costs ~4/3 its base size. The atlas textures upload with mipmaps on
+ * (see `makeAtlasTexture`), so the budget counts them, or it would under-report GPU use by a third.
+ */
+const MIPMAP_FACTOR = 4 / 3;
+/** A megabyte, the unit `memoryLimit` is given in. */
+const BYTES_PER_MB = 1024 * 1024;
+/**
+ * How much the resize factor must move before subscribers are told. A change this small shifts an
+ * atlas edge by well under a pixel, so re-deriving every texture for it would be churn with no
+ * visible effect — the point of the gate is to keep a burst of atlas mounts, each nudging the total,
+ * from re-scaling the whole scene once per mount.
+ */
+const FACTOR_EPSILON = 1e-3;
+/**
+ * The GPU footprint of an atlas of the given pixel size: RGBA, with the mipmap chain counted. Reads
+ * the atlas's full (packed) dimensions — the resize factor scales this down, so budgeting against
+ * the full size is what the factor is solved from.
+ * @param width - Atlas width in pixels.
+ * @param height - Atlas height in pixels.
+ * @returns The size in bytes.
+ */
+export function getAtlasSizeBytes(width, height) {
+    return width * height * BYTES_PER_PIXEL * MIPMAP_FACTOR;
+}
+/**
+ * The scene's shared texture-memory budget. Every image atlas registers its full size here, and the
+ * store solves for one linear resize factor that brings the resizable atlases within `memoryLimit` —
+ * shared by all of them, so their relative sizes are preserved with no priority.
+ *
+ * The factor is exposed through `useSyncExternalStore`: an atlas that mounts, unmounts, or a limit
+ * that changes recomputes it, and a material move re-derives only the resizable atlases' textures —
+ * never a repack, since uv regions are normalized and so invariant to the canvas's pixel size.
+ * Recompute runs synchronously per registration; the render churn that would cause is left to
+ * React's automatic batching to coalesce, and the `FACTOR_EPSILON` gate keeps sub-pixel nudges from
+ * notifying at all. When no cap is set the whole apparatus stands down: {@link TextureBudget.isActive}
+ * is false, atlases skip registration entirely (see {@link useResizeFactor}), and the factor is 1.
+ */
+export class TextureBudget {
+    /** The cap in megabytes, or undefined/`0` for no cap — a falsy value scales nothing. */
+    memoryLimitMb;
+    /** Every registered atlas; the entry object is its own handle. */
+    atlases = new Set();
+    /** Subscribers to the resize factor — the mounted resizable atlases. */
+    listeners = new Set();
+    /** The current shared linear resize factor; `1` means no scaling. */
+    factor = 1;
+    /**
+     * @param memoryLimitMb - The cap in megabytes, or undefined/`0` for no cap.
+     */
+    constructor(memoryLimitMb) {
+        this.memoryLimitMb = memoryLimitMb;
+    }
+    /**
+     * Whether a cap is in force. False for an absent or zero limit — nothing can be compressed, so
+     * consumers skip the budget entirely rather than do work that resolves to "no scaling".
+     * @returns Whether a positive limit is set.
+     */
+    isActive() {
+        return !!this.memoryLimitMb;
+    }
+    /**
+     * Changes the cap. Called when the renderer's `memoryLimit` prop changes, so a caller can raise,
+     * lower, or clear it at runtime and the resizable atlases re-derive their textures live.
+     * @param memoryLimitMb - The new cap, or undefined/`0` for no cap.
+     */
+    setMemoryLimit(memoryLimitMb) {
+        if (memoryLimitMb === this.memoryLimitMb)
+            return;
+        const wasActive = this.isActive();
+        this.memoryLimitMb = memoryLimitMb;
+        if (this.isActive() !== wasActive) {
+            // The cap turned on or off: recompute and always notify, so every atlas hook re-runs to
+            // register or drop itself and re-reads the factor, even when its numeric value did not move.
+            this.factor = this.computeResizeFactor();
+            this.notify();
+        }
+        else {
+            this.recompute();
+        }
+    }
+    /**
+     * Registers one atlas's full size, recomputing the factor. Only called while {@link isActive}, so
+     * an uncapped scene never populates this set.
+     * @param entry - The atlas's dimensions and kind; pass the same object back to unregister.
+     */
+    register(entry) {
+        this.atlases.add(entry);
+        this.recompute();
+    }
+    /**
+     * Drops an atlas's contribution, recomputing the factor.
+     * @param entry - The object {@link register} was given.
+     */
+    unregister(entry) {
+        if (this.atlases.delete(entry))
+            this.recompute();
+    }
+    /**
+     * The current shared resize factor.
+     * @returns The factor in `(0, 1]`.
+     */
+    getResizeFactor() {
+        return this.factor;
+    }
+    /**
+     * Subscribes to factor and active-state changes.
+     * @param listener - Called when the factor moves past {@link FACTOR_EPSILON} or the cap toggles.
+     * @returns The unsubscribe function.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Recomputes the factor and, if it moved materially, notifies subscribers. */
+    recompute() {
+        const next = this.computeResizeFactor();
+        if (Math.abs(next - this.factor) < FACTOR_EPSILON)
+            return;
+        this.factor = next;
+        this.notify();
+    }
+    /** Notifies every subscriber. */
+    notify() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    /**
+     * Solves for the linear factor that fits the resizable atlases in the budget the fixed ones leave.
+     *
+     * Every degenerate case falls back to `1` — no scaling — rather than forcing a fit: no cap, nothing
+     * resizable to scale, or a cap the fixed atlases alone already exceed (canvases cannot be
+     * compressed, so there is nothing to give). The factor is only ever clamped up to `1`, never down
+     * to a floor: an image is scaled by however much the budget demands.
+     * @returns The factor in `(0, 1]`.
+     */
+    computeResizeFactor() {
+        // Silent: reached only when a cap is cleared at runtime, since an atlas never registers without
+        // one (see useResizeFactor, which logs the no-cap case at the point it skips the work).
+        if (!this.memoryLimitMb)
+            return 1;
+        let totalResizable = 0;
+        let totalFixed = 0;
+        for (const entry of this.atlases) {
+            const bytes = getAtlasSizeBytes(entry.width, entry.height);
+            if (entry.resizable)
+                totalResizable += bytes;
+            else
+                totalFixed += bytes;
+        }
+        if (totalResizable === 0) {
+            logger.debug('no resizable atlases, atlases will not be scaled');
+            return 1;
+        }
+        const budget = this.memoryLimitMb * BYTES_PER_MB - totalFixed;
+        if (budget <= 0) {
+            logger.debug('memory limit too low to resize textures, atlases will not be scaled');
+            return 1;
+        }
+        const factor = Math.sqrt(budget / totalResizable);
+        if (factor >= 1)
+            return 1;
+        logger.debug('resize factor: %s (budget %d bytes, resizable %d bytes)', factor.toFixed(3), budget, totalResizable);
+        return factor;
+    }
+}
+/**
+ * The scene's texture budget, provided by `Renderer`. The default is an uncapped budget, so an image
+ * layer rendered outside a `Renderer` (a test, a story) behaves exactly as before this existed —
+ * everything uploads at full size.
+ */
+export const TextureBudgetContext = createContext(new TextureBudget());
+/**
+ * Registers an atlas with the scene budget for its mounted lifetime and returns the resize factor it
+ * should upload at: the shared factor for a resizable atlas, always `1` for a fixed one (its pixels
+ * still count toward the budget, they just never scale).
+ *
+ * When the budget is inactive — no `memoryLimit` — the atlas is not registered at all: there is
+ * nothing to solve, so an uncapped scene does no per-atlas budget work. Turning a cap on at runtime
+ * flips `isActive`, which re-runs the registration effect.
+ * @param budget - The scene budget from context.
+ * @param atlas - The atlas to register and read a factor for.
+ * @returns The linear factor this atlas's canvas should be scaled by before upload, in `(0, 1]`.
+ */
+export function useResizeFactor(budget, atlas) {
+    // The inline getters/subscribe close over `budget`; the React Compiler memoizes them on it, so
+    // `useSyncExternalStore` sees stable references and does not re-subscribe every render. They must
+    // be arrows (not `budget.subscribe`) so the call keeps its `this`.
+    const active = useSyncExternalStore((listener) => budget.subscribe(listener), () => budget.isActive());
+    const factor = useSyncExternalStore((listener) => budget.subscribe(listener), () => budget.getResizeFactor());
+    useEffect(() => {
+        // No cap in force: registering would only feed a computation that resolves to "no scaling", so
+        // an uncapped scene does no per-atlas budget work. A later `setMemoryLimit` flips `active` and
+        // re-runs this to register. The no-cap case is logged once by `Renderer`, not here per atlas.
+        if (!active)
+            return;
+        const entry = {
+            width: atlas.image.width,
+            height: atlas.image.height,
+            resizable: atlas.resizable,
+        };
+        budget.register(entry);
+        return () => budget.unregister(entry);
+    }, [budget, atlas, active]);
+    // A fixed atlas never scales; an uncapped budget leaves the factor at 1, so this is 1 then too.
+    return atlas.resizable ? factor : 1;
+}

package/dist/objects/images/worker/atlas-worker.d.ts

@@ -0,0 +1,56 @@
+import { type Placement, type SourceReport } from '../pack-sources';
+/**
+ * The one source the worker takes: a `Blob`.
+ *
+ * The worker could draw a bitmap or an offscreen canvas too, but it never receives one. A `Blob` is
+ * the only source that crosses by copy. Its handle clones and the bytes stay put, so the def that
+ * owns the source keeps it. Any other source would have to move, a moved source is dead on the main
+ * thread, and the next repack of that layer would then find nothing to draw. Tier selection keeps
+ * those sources on the main thread, where they pack inline.
+ */
+export type WorkerSource = Blob;
+/**
+ * What the main thread sends.
+ *
+ * Every message carries the `id` of the pack it belongs to. One worker serves every pack, so two
+ * layers can be in flight at once and the worker must keep their sources apart.
+ */
+export type AtlasWorkerRequest = 
+/** One batch of sources, in the order they were collected. Sent as many times as needed. */
+{
+    type: 'sources';
+    id: number;
+    sources: WorkerSource[];
+}
+/** No more batches: decode what has arrived, pack it, and reply. */
+ | {
+    type: 'pack';
+    id: number;
+    maxDimension: number;
+}
+/** Nobody wants this pack any more. Drop it and reply nothing. */
+ | {
+    type: 'cancel';
+    id: number;
+};
+/** One atlas the worker packed. The bitmap is transferred out, not cloned. */
+export interface WorkerAtlas {
+    /** The atlas's pixels, moved out of the offscreen canvas they were drawn into. */
+    bitmap: ImageBitmap;
+    /** Every placement on this atlas, addressing sources by their index in the batches. */
+    placements: Placement[];
+    /** Whether these pixels may be downscaled to fit a memory budget. */
+    resizable: boolean;
+}
+/** What the worker sends back — at most one of these per pack, carrying that pack's `id`. */
+export type AtlasWorkerResponse = {
+    type: 'packed';
+    id: number;
+    atlases: WorkerAtlas[];
+    reports: SourceReport[];
+} | {
+    type: 'failed';
+    id: number;
+    message: string;
+};
+//# sourceMappingURL=atlas-worker.d.ts.map

package/dist/objects/images/worker/atlas-worker.js

@@ -0,0 +1,123 @@
+import { packSources, } from '../pack-sources';
+/**
+ * Waits for every batch to decode, packs them, and moves each atlas's pixels out of its canvas.
+ * @param id - Which pack to run.
+ * @param maxDimension - Largest atlas edge in pixels.
+ * @returns The reply to post back, or null when the pack was canceled and nothing is owed.
+ */
+async function pack(id, maxDimension) {
+    // `requestFor` and not `requests.get`, because a layer with no sources sends its closing message
+    // and nothing else. That is an empty pack, and it still owes a reply: without one the layer
+    // waits forever and draws nothing. The only other way to reach this with no state is a cancel
+    // that arrived first, and that happens only when the closing message was never sent, so the
+    // empty reply it produces goes to a caller that has already forgotten the id and is discarded.
+    const request = requestFor(id);
+    request.packing = true;
+    const decoded = await Promise.all(request.decoding);
+    requests.delete(id);
+    // The only yield point in a pack. `packSources` runs straight through once it starts, so this is
+    // the last moment a cancel can save the worker's time for the next pack.
+    if (request.canceled) {
+        closeDecoded(decoded);
+        return null;
+    }
+    // `createAtlasCanvas` returns an `OffscreenCanvas` here and never takes its fallback branch. A
+    // worker runs at all only because `selectTier` found `OffscreenCanvas` on the main thread, and
+    // the constructor is exposed to both globals or to neither. No fallback is worth writing: a
+    // worker has no `document`, so without `OffscreenCanvas` it could build no canvas at all.
+    const { atlases, reports } = packSources(decoded, maxDimension);
+    // `transferToImageBitmap` moves the canvas's backing bitmap out instead of copying it, which is
+    // what makes an atlas cheap to return. The canvas is left blank, and this code drops it anyway.
+    const packed = atlases.map((atlas) => ({
+        bitmap: atlas.canvas.transferToImageBitmap(),
+        placements: atlas.placements,
+        resizable: atlas.resizable,
+    }));
+    // The atlases hold the pixels now, so every decoded bitmap is dead. This worker decoded all of
+    // them and owns all of them. Close them rather than leaving a thousand to the collector.
+    closeDecoded(decoded);
+    return { type: 'packed', id, atlases: packed, reports };
+}
+/**
+ * Abandons one pack.
+ *
+ * A pack that has not reached {@link pack} yet is dropped here, because nothing else will ever read
+ * its decodes. A pack that is already running is only marked: it reads the mark at its one yield
+ * point and cleans up there.
+ * @param id - Which pack to abandon.
+ */
+function cancel(id) {
+    const request = requests.get(id);
+    // Already replied, or never started. Either way this worker holds nothing for that pack.
+    if (!request)
+        return;
+    request.canceled = true;
+    if (request.packing)
+        return;
+    requests.delete(id);
+    void Promise.all(request.decoding).then(closeDecoded);
+}
+/**
+ * Frees decoded pixels this worker owns.
+ *
+ * An `ImageBitmap` holds its pixels outside the JavaScript heap, where collection does not reclaim
+ * them promptly. A canceled pack of a thousand logos would otherwise sit on a thousand of them.
+ * @param decoded - What the sources decoded into.
+ */
+function closeDecoded(decoded) {
+    for (const source of decoded)
+        if (source && 'close' in source)
+            source.close();
+}
+/**
+ * Finds a pack's state, starting it on the first batch that arrives.
+ * @param id - Which pack the batch belongs to.
+ * @returns That pack's state.
+ */
+function requestFor(id) {
+    let request = requests.get(id);
+    if (!request) {
+        request = { decoding: [], canceled: false, packing: false };
+        requests.set(id, request);
+    }
+    return request;
+}
+/**
+ * Every pack this worker is working on, by request id.
+ *
+ * The main thread does not terminate this worker once it has returned an atlas, because those
+ * atlases are backed by GPU memory the worker owns. It stops a worker only when that worker broke
+ * before it produced anything. So one worker serves every pack of every layer, for the life of the
+ * page, and each pack's state has to be kept apart from the others'. An entry is deleted as soon
+ * as its pack replies or is canceled.
+ */
+const requests = new Map();
+/** This worker's global scope. */
+const scope = self;
+scope.onmessage = (event) => {
+    const message = event.data;
+    if (message.type === 'sources') {
+        const request = requestFor(message.id);
+        // Null rather than a rejection, so one set of bytes that is not an image drops its own def
+        // instead of failing the whole layer's pack. `packSources` skips it as a source with no pixels.
+        for (const source of message.sources) {
+            request.decoding.push(createImageBitmap(source).catch(() => null));
+        }
+        return;
+    }
+    if (message.type === 'cancel') {
+        cancel(message.id);
+        return;
+    }
+    const { id } = message;
+    pack(id, message.maxDimension).then((response) => {
+        // Nothing is owed for a canceled pack. The main thread has already settled it.
+        if (!response)
+            return;
+        // The bitmaps move rather than copy. After this the worker holds nothing for this pack.
+        scope.postMessage(response, response.atlases.map((atlas) => atlas.bitmap));
+    }, (error) => {
+        requests.delete(id);
+        scope.postMessage({ type: 'failed', id, message: String(error) });
+    });
+};

package/dist/objects/images/worker/client.d.ts

@@ -0,0 +1,62 @@
+import { type SourceReport } from '../pack-sources';
+import { type WorkerAtlas, type WorkerSource } from './atlas-worker';
+/** Options for {@link packInWorker}. */
+export interface PackInWorkerOptions {
+    /** Abandons the pack. The worker is told to drop it, and a reply that still arrives is thrown away. */
+    signal?: AbortSignal;
+    /**
+     * Makes the pooled worker, on the first pack that needs it. Defaults to the bundled atlas worker,
+     * and exists so a spec can drive the protocol against a fake one without a browser. It is ignored
+     * once a worker is pooled.
+     */
+    createWorker?: () => Worker;
+}
+/**
+ * Packs a set of sources in a web worker.
+ *
+ * **One worker serves every pack, and no pack ever stops it.** The atlases come back as
+ * `ImageBitmap`s that `OffscreenCanvas.transferToImageBitmap()` produced, and Chrome backs those
+ * with GPU memory the worker owns. `Images` re-reads an atlas's pixels on every texture-budget
+ * move, and disposing a texture forces a fresh upload, so the producing worker has to outlive every
+ * bitmap it made, not only the first upload of it. Terminating the worker used to run before this
+ * function resolved, which destroyed those pixels and left booth logos blank on real GPUs.
+ *
+ * The one `terminate()` in this file is in `retire`, and it only ever stops a worker that broke
+ * before it handed out an atlas. A worker that has produced pixels is dropped from the pool and
+ * left running. The worker script is inlined into the bundle, so starting one resolves no URL at
+ * runtime, which matters because the SDK is loaded from origins it does not control.
+ *
+ * Each pack carries an `id`, because a shared worker can hold two layers' packs at once and a reply
+ * has to find its own caller. An abandoned pack is settled here and its `id` forgotten, so a reply
+ * that still arrives is discarded — and its atlases are closed, or each superseded pack would leak
+ * a layer's worth of GPU memory.
+ *
+ * The sources go over in batches so the main thread is never blocked for long by one structured
+ * clone, and so the worker can decode the early batches while the later ones are still being sent.
+ * A closing message tells it every source has arrived.
+ * @param sources - The unique sources to pack, in the caller's order; placements address them by
+ *   their index in this array.
+ * @param maxDimension - Largest atlas edge in pixels.
+ * @param options - The abort signal, and the worker factory a spec overrides.
+ * @returns The packed atlases and one report per source.
+ */
+export declare function packInWorker(sources: readonly WorkerSource[], maxDimension: number, options?: PackInWorkerOptions): Promise<{
+    atlases: WorkerAtlas[];
+    reports: SourceReport[];
+}>;
+/**
+ * Forgets the pooled worker without stopping it, and abandons every pack waiting on it.
+ *
+ * Only a spec calls this. Each spec drives its own fake worker, and the pool would otherwise hand
+ * the first spec's fake to every spec after it.
+ */
+export declare function resetAtlasWorkerPool(): void;
+/**
+ * How many sources one `postMessage` carries.
+ *
+ * Sending every source in one message left 18 dropped frames at a thousand logos on a 4x-throttled
+ * CPU; sending them in batches of 25 left one. Chunking is what removes the last stall, so this is
+ * the number that matters most in this file — tune it against the benchmark, not by taste.
+ */
+export declare const SOURCE_CHUNK_SIZE = 25;
+//# sourceMappingURL=client.d.ts.map