@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/objects/images/pack-sources.d.ts

@@ -0,0 +1,190 @@
+/**
+ * A source that the packer can draw from without decoding it further. It is already decoded, and
+ * it reports its own pixel size. A `Blob` is the one image source that meets neither condition, so
+ * code decodes each `Blob` into one of these types before it reaches this module.
+ */
+export type DecodedSource = ImageBitmap | HTMLCanvasElement | OffscreenCanvas;
+/**
+ * A canvas that one atlas is drawn onto. This type includes `OffscreenCanvas`, so packing can
+ * later move into a worker.
+ */
+export type AtlasCanvas = HTMLCanvasElement | OffscreenCanvas;
+/**
+ * Creates the backing canvas for one atlas, sized to that atlas exactly.
+ * @param width - The atlas width in pixels.
+ * @param height - The atlas height in pixels.
+ * @returns The canvas to draw on.
+ */
+export type CreateAtlasCanvas = (width: number, height: number) => AtlasCanvas;
+/**
+ * A region of a source image, in **source pixels with a top-left origin**. These are the same axes
+ * as `ImageDef.bounds`, and they are the exact `sx, sy, sw, sh` values that the packer passes to
+ * `drawImage`. This type keeps pixels instead of normalized values, so code cannot mistake it for
+ * a {@link UvRect}, whose origin is the opposite corner.
+ */
+export interface SourceRect {
+    /** Distance from the source's left edge, in pixels. */
+    x: number;
+    /** Distance from the source's top edge, in pixels. */
+    y: number;
+    /** Region width in pixels. */
+    width: number;
+    /** Region height in pixels. */
+    height: number;
+}
+/**
+ * A region of an atlas, **normalized in the canvas's own axes: a top-left origin, with v running
+ * down**.
+ *
+ * A texture with `flipY = false` consumes these values. That setting maps canvas row 0 to `v = 0`,
+ * so these numbers feed a uv transform directly, with no vertical inversion. This is deliberate.
+ * The scene already uses a y axis that points down, because it follows SVG coordinates and the
+ * camera matches them. A uv space that also runs down keeps every axis in the pipeline pointing
+ * the same way. If only one end inverts, images come out upside down.
+ */
+export interface UvRect {
+    /** Left edge, `0` at the atlas's left. */
+    u0: number;
+    /** Top edge, `0` at the atlas's top. */
+    v0: number;
+    /** Right edge. */
+    u1: number;
+    /** Bottom edge. */
+    v1: number;
+}
+/**
+ * One source, or one tile of a split source, placed on an atlas. Each placement carries an array
+ * index instead of the source object as its address, because this data crosses a `postMessage`
+ * boundary, and object identity does not survive that boundary.
+ */
+export interface Placement {
+    /** Index into the `sources` array that the caller gave {@link packSources}. */
+    index: number;
+    /** Where the pixels sit on the atlas. */
+    uv: UvRect;
+    /**
+     * Which part of the source this placement holds. This is undefined when the source packs
+     * whole, which is the common case. It is set only on the tiles of a split source.
+     */
+    source?: SourceRect;
+}
+/** One packed atlas, before its placements are mapped back onto the defs that wanted them. */
+export interface SourceAtlas {
+    /** The canvas holding the packed pixels. Its `width`/`height` are the atlas's size. */
+    canvas: AtlasCanvas;
+    /** Every placement on this atlas. */
+    placements: Placement[];
+    /**
+     * Whether this atlas's pixels can shrink to fit a memory budget. Bitmaps pack into resizable
+     * atlases, canvases pack into fixed ones, and an atlas never mixes the two.
+     */
+    resizable: boolean;
+}
+/**
+ * What one source contributed to a pack. The caller holds the defs, so only the caller can warn
+ * about them. This report gives the caller the measurements it needs to do that.
+ */
+export interface SourceReport {
+    /** The source's intrinsic width in pixels. */
+    width: number;
+    /** The source's intrinsic height in pixels. */
+    height: number;
+    /**
+     * How many rects this source packed into. It is `0` when the source had no pixels and code
+     * dropped it. It is `1` when the source packed whole. Otherwise it is the tile count, for a
+     * source too big for one atlas that code had to cut.
+     */
+    tiles: number;
+}
+/**
+ * Whether a source is a `Blob`, which is also true of a `File`.
+ *
+ * The test looks for `slice`, and it must keep looking for `slice`. `slice` is Chrome 21, Chrome
+ * Android 25, Safari 7 and iOS Safari 7, so every build target has it. `arrayBuffer` reads better
+ * and is wrong: it is Chrome 76 and Chrome Android 76, above this package's `chrome66` floor, so on
+ * the old Android WebViews it is `undefined` and every real `Blob` would fail this test and reach
+ * the packer undecoded (`packages/floorplan/src/components/Maplibre/utils/pmtiles-range-fallback.ts`
+ * works around the same floor). No other image source carries either method: not an `<img>`, a
+ * canvas, an offscreen canvas or a bitmap.
+ *
+ * A property test rather than `instanceof`, so this never reaches for a global that can be absent.
+ *
+ * This is the one home of the test. It decides both what needs a decode and what may cross to the
+ * atlas worker, so a second copy could drift from this one, and the drift would only show on the
+ * oldest targets.
+ * @param source - The source to classify.
+ * @returns Whether the source needs a decode.
+ */
+export declare function isBlob(source: object): source is Blob;
+/**
+ * Whether a source's pixels can shrink to fit a memory budget. This is `true` for decoded images
+ * and bitmaps. It is `false` for canvases, because a canvas's pixels belong to the caller. The
+ * code counts a canvas at full size and never compresses it (see the scene's `memoryLimit`).
+ *
+ * The check looks for the absence of `getContext`. `HTMLCanvasElement` and `OffscreenCanvas` both
+ * have it. `ImageBitmap` and `Blob` do not. This is a property test, not an
+ * `instanceof` check, because the SDK runs in WebViews. There, `OffscreenCanvas` and `ImageBitmap`
+ * can be missing as globals, and an `instanceof` check against a missing global throws an error.
+ * @param source - The source to classify.
+ * @returns Whether the source can shrink.
+ */
+export declare function isResizableSource(source: object): boolean;
+/**
+ * Makes the canvas that one atlas draws onto. The function returns an `OffscreenCanvas` where one
+ * exists, and a DOM canvas otherwise.
+ *
+ * This is the only place in the package that builds an atlas canvas, so the `OffscreenCanvas`
+ * guard lives here alone. The guard uses this plain form because `eslint-plugin-compat`
+ * understands it and flags only an unguarded construction. Nothing here needs hiding from the
+ * linter.
+ * @param width - The canvas width in pixels.
+ * @param height - The canvas height in pixels.
+ * @returns The canvas.
+ */
+export declare function createAtlasCanvas(width: number, height: number): AtlasCanvas;
+/**
+ * Packs decoded sources into atlas canvases and reports where each one landed.
+ *
+ * The code splits sources by kind first: resizable ones (bitmaps and images) apart from fixed ones
+ * (canvases). Each kind packs on its own, so no atlas ever mixes the two kinds. This lets a memory
+ * budget scale a whole resizable atlas without touching a canvas's pixels. Within one kind, the
+ * code offers each source to the packer whole. Anything too big for an atlas comes back parked in
+ * a bin of its own natural size, and the packer flags that bin. Those are the only sources that get
+ * cut into tiles, and the tiles go back through the same packer. Letting the packer decide keeps
+ * the guarantee that no atlas exceeds `maxDimension`, with no need to measure every image up
+ * front.
+ *
+ * This function does **not** deduplicate sources. The caller must collect unique sources before it
+ * decodes them, so every entry in `sources` is already distinct.
+ *
+ * This module runs unchanged on the main thread and inside the atlas worker. It must not use
+ * `document`, the def types, or the logger.
+ * @param sources - The decoded sources to pack, in the order the caller gives them.
+ * @param maxDimension - The largest atlas edge in pixels. The function floors this to a positive
+ *   integer.
+ * @param createCanvas - Makes each atlas canvas. Defaults to {@link createAtlasCanvas}.
+ * @returns The atlases in packing order (resizable first, then fixed), and one report for each
+ *   source, aligned by index with `sources`.
+ */
+export declare function packSources(sources: readonly (DecodedSource | null)[], maxDimension: number, createCanvas?: CreateAtlasCanvas): {
+    atlases: SourceAtlas[];
+    reports: SourceReport[];
+};
+/**
+ * Resolves an atlas canvas's 2D context, asking one canvas kind at a time.
+ *
+ * Deliberately not `canvas.getContext('2d')` on the union. The two kinds' overload lists disagree
+ * at the end — `HTMLCanvasElement` closes with `getContext(id: string): RenderingContext | null`,
+ * `OffscreenCanvas` with an `OffscreenRenderingContextId` one — and resolving across the union can
+ * combine one kind's `"2d"` overload with the other's catch-all, yielding
+ * `OffscreenCanvasRenderingContext2D | RenderingContext`: a type covering bitmap and WebGL contexts
+ * that have no `drawImage`. It surfaces only on incremental rebuilds (any compile error in this
+ * file leaves the bad resolution cached in `.tsbuildinfo`, where it outlives the error that caused
+ * it), so a clean build hides it and a working tree quietly breaks. Narrowed first, each branch has
+ * one concrete type whose `"2d"` overload is the only candidate, and the result is stable either
+ * way.
+ * @param canvas - The atlas canvas.
+ * @returns Its 2D context, or `null` when the canvas cannot provide one.
+ */
+export declare function contextOf(canvas: AtlasCanvas): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;
+//# sourceMappingURL=pack-sources.d.ts.map

package/dist/objects/images/pack-sources.js

@@ -0,0 +1,272 @@
+import { MaxRectsPacker } from 'maxrects-packer';
+/**
+ * Whether a source is a `Blob`, which is also true of a `File`.
+ *
+ * The test looks for `slice`, and it must keep looking for `slice`. `slice` is Chrome 21, Chrome
+ * Android 25, Safari 7 and iOS Safari 7, so every build target has it. `arrayBuffer` reads better
+ * and is wrong: it is Chrome 76 and Chrome Android 76, above this package's `chrome66` floor, so on
+ * the old Android WebViews it is `undefined` and every real `Blob` would fail this test and reach
+ * the packer undecoded (`packages/floorplan/src/components/Maplibre/utils/pmtiles-range-fallback.ts`
+ * works around the same floor). No other image source carries either method: not an `<img>`, a
+ * canvas, an offscreen canvas or a bitmap.
+ *
+ * A property test rather than `instanceof`, so this never reaches for a global that can be absent.
+ *
+ * This is the one home of the test. It decides both what needs a decode and what may cross to the
+ * atlas worker, so a second copy could drift from this one, and the drift would only show on the
+ * oldest targets.
+ * @param source - The source to classify.
+ * @returns Whether the source needs a decode.
+ */
+export function isBlob(source) {
+    return typeof source.slice === 'function';
+}
+/**
+ * Whether a source's pixels can shrink to fit a memory budget. This is `true` for decoded images
+ * and bitmaps. It is `false` for canvases, because a canvas's pixels belong to the caller. The
+ * code counts a canvas at full size and never compresses it (see the scene's `memoryLimit`).
+ *
+ * The check looks for the absence of `getContext`. `HTMLCanvasElement` and `OffscreenCanvas` both
+ * have it. `ImageBitmap` and `Blob` do not. This is a property test, not an
+ * `instanceof` check, because the SDK runs in WebViews. There, `OffscreenCanvas` and `ImageBitmap`
+ * can be missing as globals, and an `instanceof` check against a missing global throws an error.
+ * @param source - The source to classify.
+ * @returns Whether the source can shrink.
+ */
+export function isResizableSource(source) {
+    return !('getContext' in source);
+}
+/**
+ * Makes the canvas that one atlas draws onto. The function returns an `OffscreenCanvas` where one
+ * exists, and a DOM canvas otherwise.
+ *
+ * This is the only place in the package that builds an atlas canvas, so the `OffscreenCanvas`
+ * guard lives here alone. The guard uses this plain form because `eslint-plugin-compat`
+ * understands it and flags only an unguarded construction. Nothing here needs hiding from the
+ * linter.
+ * @param width - The canvas width in pixels.
+ * @param height - The canvas height in pixels.
+ * @returns The canvas.
+ */
+export function createAtlasCanvas(width, height) {
+    if (typeof OffscreenCanvas !== 'undefined')
+        return new OffscreenCanvas(width, height);
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    return canvas;
+}
+/**
+ * Packs decoded sources into atlas canvases and reports where each one landed.
+ *
+ * The code splits sources by kind first: resizable ones (bitmaps and images) apart from fixed ones
+ * (canvases). Each kind packs on its own, so no atlas ever mixes the two kinds. This lets a memory
+ * budget scale a whole resizable atlas without touching a canvas's pixels. Within one kind, the
+ * code offers each source to the packer whole. Anything too big for an atlas comes back parked in
+ * a bin of its own natural size, and the packer flags that bin. Those are the only sources that get
+ * cut into tiles, and the tiles go back through the same packer. Letting the packer decide keeps
+ * the guarantee that no atlas exceeds `maxDimension`, with no need to measure every image up
+ * front.
+ *
+ * This function does **not** deduplicate sources. The caller must collect unique sources before it
+ * decodes them, so every entry in `sources` is already distinct.
+ *
+ * This module runs unchanged on the main thread and inside the atlas worker. It must not use
+ * `document`, the def types, or the logger.
+ * @param sources - The decoded sources to pack, in the order the caller gives them.
+ * @param maxDimension - The largest atlas edge in pixels. The function floors this to a positive
+ *   integer.
+ * @param createCanvas - Makes each atlas canvas. Defaults to {@link createAtlasCanvas}.
+ * @returns The atlases in packing order (resizable first, then fixed), and one report for each
+ *   source, aligned by index with `sources`.
+ */
+export function packSources(sources, maxDimension, createCanvas = createAtlasCanvas) {
+    const limit = Math.max(1, Math.floor(maxDimension));
+    // Every member of `DecodedSource` reports its own pixel size, so nothing here needs to duck-type
+    // a size. That was only ever needed because an `<img>` reports its layout size as `width`. A
+    // source that fails to decode arrives as `null` and reports `0 x 0`. Code skips that source the
+    // same way it skips a zero-sized canvas.
+    const reports = sources.map((source) => source
+        ? { width: source.width, height: source.height, tiles: 0 }
+        : { width: 0, height: 0, tiles: 0 });
+    const resizable = [];
+    const fixed = [];
+    for (let index = 0; index < sources.length; index++) {
+        const source = sources[index];
+        // A source that failed to decode is dropped later by the size check in `packGroup`. Code
+        // groups it with the resizable sources, so it never lands in an atlas of canvases on its way
+        // to being skipped.
+        (!source || isResizableSource(source) ? resizable : fixed).push(index);
+    }
+    // One packer serves both groups, reset between them. The configuration (size, padding, options)
+    // is the same for each, so reusing the packer spares an allocation per pack. The packer cannot
+    // carry over across pack calls, though, because `limit` is fixed at construction and changes
+    // from call to call.
+    // `pot: false`, because WebGL 2 samples non-power-of-two textures without restriction. Rounding
+    // each atlas up only wastes memory. `smart` stays on (the default), which shrinks every bin to
+    // its content. That is why the code reads the size back off the bin instead of assuming
+    // `limit`.
+    const packer = new MaxRectsPacker(limit, limit, PADDING, { pot: false });
+    const atlases = [
+        ...packGroup(packer, sources, resizable, reports, limit, createCanvas, true),
+        ...packGroup(packer, sources, fixed, reports, limit, createCanvas, false),
+    ];
+    return { atlases, reports };
+}
+/**
+ * The gap between neighboring images on an atlas. This gap stops linear filtering at one image's
+ * edge from reaching into the next image's pixels. The packer applies this gap *between* rects
+ * only, so atlas edges stay flush against the pixels. This is also why a tile exactly
+ * `maxDimension` across still fits in a bin.
+ */
+const PADDING = 1;
+/**
+ * Packs one kind of source, either all resizable or all fixed, into atlases. The function tags
+ * each atlas with the group's kind and records each source's tile count in `reports`.
+ * @param packer - The shared packer. It is reset to empty before this group is added.
+ * @param sources - Every source, indexed by the entries in `indices`.
+ * @param indices - The indices of this kind. This list can be empty, and then nothing packs.
+ * @param reports - Per-source reports. This function fills in each report's `tiles` count.
+ * @param limit - The largest atlas edge, in pixels.
+ * @param createCanvas - Makes each atlas canvas.
+ * @param resizable - The kind, stamped onto every atlas that this call produces.
+ * @returns The atlases this group produced.
+ */
+function packGroup(packer, sources, indices, reports, limit, createCanvas, resizable) {
+    const rects = [];
+    for (const index of indices) {
+        const { width, height } = reports[index];
+        // A `drawImage` call throws in some browsers when the source region has zero width or zero
+        // height. So code drops an image that has not decoded, or a canvas sized to nothing, instead
+        // of drawing it. Its report keeps `tiles: 0`, and that value tells the caller to warn about
+        // it.
+        if (width <= 0 || height <= 0)
+            continue;
+        rects.push({ width, height, x: 0, y: 0, hash: `${index}`, data: { index } });
+    }
+    // Clear whatever the previous group left in the packer, keeping its configuration.
+    packer.reset();
+    // `addArray` sorts by longest edge before it places rects, which packs far tighter than
+    // insertion order.
+    packer.addArray(rects);
+    // The packer tags whatever it must park in an oversized bin. The packer decides what needs
+    // cutting, not a separate measurement in this code. The tiles are ordinary rects, and they pack
+    // into the bins that the first pass already opened.
+    const oversized = rects.filter((rect) => rect.oversized);
+    if (oversized.length > 0) {
+        packer.addArray(oversized.flatMap((rect) => cutTiles(rect, reports[rect.data.index], limit)));
+    }
+    // Every oversized bin now has its tiles standing in for it, so the code drops the bin instead of
+    // returning it. Handing back a canvas larger than the caller's limit is the exact problem this
+    // code exists to prevent.
+    const bins = packer.bins.filter((bin) => !bin.rects.some((rect) => rect.oversized));
+    const atlases = bins.map((bin) => ({
+        ...renderAtlas(bin, sources, reports, createCanvas),
+        resizable,
+    }));
+    // Count what actually landed. This lets code tell a dropped source apart from a split one.
+    for (const bin of bins)
+        for (const rect of bin.rects)
+            reports[rect.data.index].tiles++;
+    return atlases;
+}
+/**
+ * Cuts a source that did not fit in the packer into a grid of tiles. No tile is larger than one
+ * atlas. Tiles are exact and do not overlap. Each tile ends up alone, or beside its own sibling
+ * tiles, in an atlas. Nothing can bleed across the cut, so the code needs no overlap column to
+ * hide a seam.
+ * @param rect - The oversized rect that names the source to cut.
+ * @param report - That source's measured size.
+ * @param limit - The largest tile edge, in pixels.
+ * @returns The tiles to pack in its place.
+ */
+function cutTiles(rect, report, limit) {
+    const columns = Math.ceil(report.width / limit);
+    const rows = Math.ceil(report.height / limit);
+    const tiles = [];
+    for (let row = 0; row < rows; row++) {
+        const y = row * limit;
+        const height = Math.min(limit, report.height - y);
+        for (let column = 0; column < columns; column++) {
+            const x = column * limit;
+            const width = Math.min(limit, report.width - x);
+            tiles.push({
+                width,
+                height,
+                x: 0,
+                y: 0,
+                hash: `${rect.hash}:${column},${row}`,
+                data: { index: rect.data.index, source: { x, y, width, height } },
+            });
+        }
+    }
+    return tiles;
+}
+/**
+ * Draws one packed bin onto a canvas and records where each rect landed.
+ * @param bin - The packed bin, already sized to its content.
+ * @param sources - Every source, indexed by each rect's tile.
+ * @param reports - Per-source sizes, for the whole-image draw region.
+ * @param createCanvas - Makes the canvas to draw on.
+ * @returns The atlas, less its `resizable` flag.
+ */
+function renderAtlas(bin, sources, reports, createCanvas) {
+    const canvas = createCanvas(bin.width, bin.height);
+    const context = contextOf(canvas);
+    // Nothing downstream can recover from a missing context. Every atlas then uploads blank, and
+    // the images silently draw as nothing at all. It is better to fail here, where the cause stays
+    // visible.
+    if (!context)
+        throw new Error(`pack-sources: no 2d context for a ${bin.width}x${bin.height} atlas`);
+    const placements = [];
+    for (const rect of bin.rects) {
+        const { index, source } = rect.data;
+        // The copied region is the tile when the rect has one, and the whole image otherwise. Both
+        // read from the source's own axes. This region happens to match the packed rect's size today,
+        // because tiles are placed 1:1 and unrotated. Reading the size from the destination instead
+        // is correct only by accident, not by design. The code keeps this region apart from `source`
+        // itself, which stays undefined for an unsplit image, so the placement below does not report
+        // a region that the caller has no use for.
+        const { width, height } = reports[index];
+        const region = source ?? { x: 0, y: 0, width, height };
+        // This value is never null, by construction. A source that fails to decode reports `0 x 0`
+        // and never reaches the packer, so every rect in a bin has a drawable source behind it.
+        const decoded = sources[index];
+        if (!decoded)
+            continue;
+        context.drawImage(decoded, region.x, region.y, region.width, region.height, rect.x, rect.y, rect.width, rect.height);
+        // The rect uses canvas pixels, and uv keeps the canvas's axes, so this is a plain
+        // normalization with no vertical inversion (see {@link UvRect}).
+        const uv = {
+            u0: rect.x / bin.width,
+            v0: rect.y / bin.height,
+            u1: (rect.x + rect.width) / bin.width,
+            v1: (rect.y + rect.height) / bin.height,
+        };
+        placements.push(source ? { index, uv, source } : { index, uv });
+    }
+    return { canvas, placements };
+}
+/**
+ * Resolves an atlas canvas's 2D context, asking one canvas kind at a time.
+ *
+ * Deliberately not `canvas.getContext('2d')` on the union. The two kinds' overload lists disagree
+ * at the end — `HTMLCanvasElement` closes with `getContext(id: string): RenderingContext | null`,
+ * `OffscreenCanvas` with an `OffscreenRenderingContextId` one — and resolving across the union can
+ * combine one kind's `"2d"` overload with the other's catch-all, yielding
+ * `OffscreenCanvasRenderingContext2D | RenderingContext`: a type covering bitmap and WebGL contexts
+ * that have no `drawImage`. It surfaces only on incremental rebuilds (any compile error in this
+ * file leaves the bad resolution cached in `.tsbuildinfo`, where it outlives the error that caused
+ * it), so a clean build hides it and a working tree quietly breaks. Narrowed first, each branch has
+ * one concrete type whose `"2d"` overload is the only candidate, and the result is stable either
+ * way.
+ * @param canvas - The atlas canvas.
+ * @returns Its 2D context, or `null` when the canvas cannot provide one.
+ */
+export function contextOf(canvas) {
+    // `in` rather than `instanceof`: in a worker there is no `HTMLCanvasElement` global to test
+    // against, and an `instanceof` against a missing global throws.
+    if ('convertToBlob' in canvas)
+        return canvas.getContext('2d');
+    return canvas.getContext('2d');
+}

package/dist/objects/images/texture-budget.d.ts

@@ -0,0 +1,120 @@
+import { type Atlas } from './atlas-packer';
+/**
+ * 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 declare function getAtlasSizeBytes(width: number, height: number): number;
+/**
+ * One atlas's contribution to the budget: its full size, and whether it may be scaled to fit. The
+ * object doubles as its own registration handle — {@link TextureBudget.unregister} takes the very
+ * object {@link TextureBudget.register} was given, so identity alone distinguishes two atlases of
+ * equal size and no separate key is needed.
+ */
+interface AtlasBudgetEntry {
+    /** Full atlas width in pixels. */
+    width: number;
+    /** Full atlas height in pixels. */
+    height: number;
+    /** Whether this atlas's bytes shrink with the resize factor, or count at full size always. */
+    resizable: boolean;
+}
+/**
+ * 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 declare class TextureBudget {
+    /** The cap in megabytes, or undefined/`0` for no cap — a falsy value scales nothing. */
+    private memoryLimitMb;
+    /** Every registered atlas; the entry object is its own handle. */
+    private readonly atlases;
+    /** Subscribers to the resize factor — the mounted resizable atlases. */
+    private readonly listeners;
+    /** The current shared linear resize factor; `1` means no scaling. */
+    private factor;
+    /**
+     * @param memoryLimitMb - The cap in megabytes, or undefined/`0` for no cap.
+     */
+    constructor(memoryLimitMb?: number);
+    /**
+     * 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(): boolean;
+    /**
+     * 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: number | undefined): void;
+    /**
+     * 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: AtlasBudgetEntry): void;
+    /**
+     * Drops an atlas's contribution, recomputing the factor.
+     * @param entry - The object {@link register} was given.
+     */
+    unregister(entry: AtlasBudgetEntry): void;
+    /**
+     * The current shared resize factor.
+     * @returns The factor in `(0, 1]`.
+     */
+    getResizeFactor(): number;
+    /**
+     * 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: () => void): () => void;
+    /** Recomputes the factor and, if it moved materially, notifies subscribers. */
+    private recompute;
+    /** Notifies every subscriber. */
+    private notify;
+    /**
+     * 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]`.
+     */
+    private computeResizeFactor;
+}
+/**
+ * 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 declare const TextureBudgetContext: import("react").Context<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 declare function useResizeFactor(budget: TextureBudget, atlas: Atlas): number;
+export {};
+//# sourceMappingURL=texture-budget.d.ts.map