@expofp/renderer 3.2.4 → 3.27.0

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

@@ -0,0 +1,315 @@
+import { MaxRectsPacker } from 'maxrects-packer';
+import { createLogger } from '../../utils/logging';
+const logger = createLogger('atlas-packer');
+// Need to reduce blocking time on the main thread
+// Naive approach of offloading to web worker is not feasible:
+// HTMLImageElement can't be easily transferred, and createImageBitmap() on sources takes more time
+// than actual atlas packing. Needs to be investigated further
+/**
+ * Gap kept between neighboring images in an atlas, so linear filtering at one image's edge can
+ * never reach into the next one's pixels. The packer applies it *between* rects only — atlas edges
+ * stay flush against the pixels — which is also what lets a tile exactly `maxDimension` across
+ * still fit a bin.
+ */
+const PADDING = 1;
+/**
+ * How many source pixels per square unit of `bounds` a def may carry before it is called
+ * over-sampled. Past this the extra resolution cannot reach the screen at any sane zoom, so the
+ * atlas space and texture memory are simply wasted — usually a full-size logo standing in for a
+ * marker icon.
+ */
+const MAX_AREA_RATIO = 1000;
+/**
+ * Whether a source's pixels may be downscaled to fit a memory budget. `true` for decoded images and
+ * bitmaps, `false` for canvases — a canvas's pixels are the caller's, counted at full size but never
+ * compressed (see the scene's `memoryLimit`).
+ *
+ * Detected by the absence of `getContext`: `HTMLCanvasElement` and `OffscreenCanvas` both have it,
+ * `HTMLImageElement` and `ImageBitmap` do not. A property test rather than `instanceof`, because the
+ * SDK runs in WebViews where `OffscreenCanvas`/`ImageBitmap` may be missing as globals and an
+ * `instanceof` against an absent one throws.
+ * @param source - The source to classify.
+ * @returns Whether the source can be downscaled.
+ */
+export function isResizableSource(source) {
+    return !('getContext' in source);
+}
+/**
+ * Packs image defs into atlas canvases and reports where every def's pixels landed.
+ *
+ * Sources are split by kind first — resizable (image/bitmap) from fixed (canvas) — and each kind is
+ * packed on its own, so no atlas ever mixes the two and a memory budget can scale a resizable atlas
+ * whole without touching a canvas's pixels. Within a kind, sources are deduped — two defs pointing
+ * at the same URL, or holding the same canvas object, are drawn once and share one region — and then
+ * offered to the packer whole. Anything too big for an atlas comes back parked in a natural-size bin
+ * of its own, which the packer flags; those are the only sources cut into tiles, and the tiles go
+ * back through the same packer. Letting the packer decide is what keeps the guarantee that no atlas
+ * exceeds `maxDimension` without measuring every image up front.
+ *
+ * Packing reads only the sources' pixel dimensions, never `bounds`, so a def that later moves or
+ * resizes keeps its region: the quad's matrix scales it, and nothing needs repacking. Membership
+ * changes do, though — this is a batch call with no incremental path.
+ * @param defs - The images to pack.
+ * @param maxDimension - Largest atlas edge in pixels, floored to a positive integer.
+ * @param options - Overrides for how atlas canvases are made.
+ * @returns One entry per atlas, in packing order — resizable atlases first, then fixed.
+ */
+export function packAtlases(defs, maxDimension, options = {}) {
+    const startedAt = performance.now();
+    const { createCanvas = createDomCanvas } = options;
+    const limit = Math.max(1, Math.floor(maxDimension));
+    const resizable = [];
+    const fixed = [];
+    for (const def of defs)
+        (isResizableSource(def.source) ? resizable : fixed).push(def);
+    // One packer for both groups, `reset()` between them — the config (size, padding, options) is the
+    // same for each, so reusing it spares an allocation per pack. It cannot be shared across pack calls
+    // though: `limit` is baked in at construction and varies call to call.
+    // `pot: false` because WebGL 2 samples non-power-of-two textures without restriction, so rounding
+    // each atlas up would only waste memory. `smart` stays on (the default), shrinking every bin to
+    // its content — hence reading the size back off the bin rather than assuming `limit`.
+    const packer = new MaxRectsPacker(limit, limit, PADDING, { pot: false });
+    const packedResizable = packGroup(packer, resizable, limit, createCanvas, true);
+    const packedFixed = packGroup(packer, fixed, limit, createCanvas, false);
+    const atlases = [...packedResizable.atlases, ...packedFixed.atlases];
+    const elapsed = (performance.now() - startedAt).toFixed(1);
+    logger.debug('packed defs: %d (%d resizable), sources: %d, tiles: %d, atlases: %d (%sms)', packedResizable.defs + packedFixed.defs, packedResizable.defs, packedResizable.sources + packedFixed.sources, packedResizable.tiles + packedFixed.tiles, atlases.length, elapsed);
+    return atlases;
+}
+/**
+ * Packs one kind of source — all resizable, or all fixed — into atlases, tagging each with the
+ * group's kind. Same pipeline for both: dedup, offer whole, cut whatever the packer parks oversized.
+ * @param packer - The shared packer, reset to empty before this group is added.
+ * @param defs - The defs of this kind; may be empty, which packs to nothing.
+ * @param limit - Largest atlas edge in pixels.
+ * @param createCanvas - Makes each atlas canvas.
+ * @param resizable - The kind, stamped onto every atlas produced.
+ * @returns The atlases and their counts.
+ */
+function packGroup(packer, defs, limit, createCanvas, resizable) {
+    const sources = collectSources(defs);
+    const { rects, skipped } = sourceRects(sources.values());
+    // Clear whatever the previous group left in the packer, keeping its configuration.
+    packer.reset();
+    // `addArray` sorts by longest edge before placing, which packs far tighter than insertion order.
+    packer.addArray(rects);
+    // The packer tags whatever it had to park in an oversized bin, so it — not a measurement of our
+    // own — decides what needs cutting. The tiles are ordinary rects, and pack into the bins the
+    // first pass already opened.
+    const oversized = rects.filter((rect) => rect.oversized);
+    if (oversized.length > 0)
+        packer.addArray(oversized.flatMap((rect) => cutTiles(rect, limit)));
+    // Every oversized bin is now represented by its tiles, so it is dropped rather than returned:
+    // handing back a canvas larger than the caller's limit is the thing this all exists to prevent.
+    const bins = packer.bins.filter((bin) => !bin.rects.some((rect) => rect.oversized));
+    const atlases = bins.map((bin) => ({ ...renderAtlas(bin, createCanvas), resizable }));
+    return {
+        atlases,
+        defs: defs.length - skipped.defs,
+        sources: sources.size - skipped.sources,
+        tiles: bins.reduce((count, bin) => count + bin.rects.length, 0),
+    };
+}
+/**
+ * The pixel size of an image source.
+ *
+ * Duck-typed rather than `instanceof`: the SDK runs in WebViews where `OffscreenCanvas` and
+ * `ImageBitmap` may be missing as globals, and an `instanceof` against an absent global throws.
+ * @param source - The source to measure.
+ * @returns Its intrinsic size, `0 × 0` for an image element that has not decoded yet.
+ */
+export function imageSourceSize(source) {
+    // `naturalWidth` is the decoded size; an `<img>`'s `width` is its layout size, which is 0 for an
+    // element that was never in the document — the usual case for images loaded purely as textures.
+    const image = source;
+    return typeof image.naturalWidth === 'number'
+        ? { width: image.naturalWidth, height: image.naturalHeight }
+        : { width: source.width, height: source.height };
+}
+/**
+ * Groups defs by the source they draw, so identical images are packed once.
+ *
+ * Identity is the URL for an image element and the object itself for a canvas or bitmap — a `Map`
+ * never confuses the two, since a string key cannot collide with an object one. An `<img>` with no
+ * `src` keys on itself instead, so a set of blank images is not collapsed into a single region.
+ * @param defs - The defs to group.
+ * @returns One entry per unique source, in first-seen order.
+ */
+function collectSources(defs) {
+    const sources = new Map();
+    for (const def of defs) {
+        const src = def.source.src;
+        const key = typeof src === 'string' && src !== '' ? src : def.source;
+        let entry = sources.get(key);
+        if (!entry) {
+            entry = {
+                source: def.source,
+                ...imageSourceSize(def.source),
+                defs: [],
+                bounds: { width: 0, height: 0 },
+            };
+            sources.set(key, entry);
+        }
+        entry.defs.push(def);
+        // Copied rather than referenced: `Rect` exposes an in-place `set`, so holding onto its size
+        // vector would let a later bounds change rewrite what was measured here.
+        const { width, height } = def.bounds.size;
+        if (width * height > entry.bounds.width * entry.bounds.height) {
+            entry.bounds = { width, height };
+        }
+    }
+    return sources;
+}
+/**
+ * Turns each unique source into the one rect that offers it to the packer whole, dropping the ones
+ * with no pixels to draw and flagging the ones carrying more resolution than they can show.
+ * @param sources - The unique sources to offer.
+ * @returns The rects to pack, and what was dropped for having no pixels.
+ */
+function sourceRects(sources) {
+    const rects = [];
+    const skipped = { defs: 0, sources: 0 };
+    for (const entry of sources) {
+        // A `drawImage` with a zero-width or zero-height source region throws in some browsers, so an
+        // image that has not decoded (or a canvas sized to nothing) is dropped rather than drawn.
+        if (entry.width <= 0 || entry.height <= 0) {
+            skipped.sources++;
+            skipped.defs += entry.defs.length;
+            logger.warn('skipping source with no pixels (%dx%d) %O', entry.width, entry.height, entry.source);
+            continue;
+        }
+        warnIfOverSampled(entry);
+        rects.push({
+            width: entry.width,
+            height: entry.height,
+            x: 0,
+            y: 0,
+            hash: `${rects.length}`,
+            data: { entry },
+        });
+    }
+    return { rects, skipped };
+}
+/**
+ * Reports a source carrying far more pixels than the bounds it is drawn into can ever show. Once
+ * per source rather than once per def, since deduped defs all share the one texture region.
+ * @param entry - The source to check.
+ */
+function warnIfOverSampled(entry) {
+    const boundsArea = entry.bounds.width * entry.bounds.height;
+    // Degenerate bounds would divide out to Infinity and warn about every such def, which says
+    // nothing about resolution — that is a bounds bug, and not this function's to report.
+    if (boundsArea <= 0)
+        return;
+    const ratio = (entry.width * entry.height) / boundsArea;
+    if (ratio <= MAX_AREA_RATIO)
+        return;
+    logger.warn('over-sampled source: %dx%d px drawn into %sx%s units — %d px per unit², limit %d', entry.width, entry.height, 
+    // At most two decimals, trailing zeros dropped: 4 → 4, 4.1 → 4.1, 4.2999 → 4.3.
+    Number(entry.bounds.width.toFixed(2)), Number(entry.bounds.height.toFixed(2)), Math.round(ratio), MAX_AREA_RATIO);
+}
+/**
+ * Cuts a source the packer could not fit into a grid of tiles no larger than one atlas. Tiles are
+ * exact and non-overlapping — each ends up alone (or beside its own siblings) in an atlas, so
+ * nothing can bleed across the cut and no overlap column is needed to hide it.
+ * @param rect - The oversized rect, holding the source to cut.
+ * @param limit - Largest tile edge in pixels.
+ * @returns The tiles to pack in its place.
+ */
+function cutTiles(rect, limit) {
+    const { entry } = rect.data;
+    const columns = Math.ceil(entry.width / limit);
+    const rows = Math.ceil(entry.height / limit);
+    logger.warn('source %dx%d exceeds the %dpx atlas limit, splitting into %d tiles', entry.width, entry.height, limit, columns * rows);
+    const tiles = [];
+    for (let row = 0; row < rows; row++) {
+        const y = row * limit;
+        const height = Math.min(limit, entry.height - y);
+        for (let column = 0; column < columns; column++) {
+            const x = column * limit;
+            const width = Math.min(limit, entry.width - x);
+            tiles.push({
+                width,
+                height,
+                x: 0,
+                y: 0,
+                hash: `${rect.hash}:${column},${row}`,
+                data: { entry, source: { x, y, width, height } },
+            });
+        }
+    }
+    return tiles;
+}
+/**
+ * Draws one packed bin onto a canvas and maps its rects back onto the defs that wanted them. The
+ * `resizable` flag is not this function's to set — {@link packGroup} stamps it from the group's kind.
+ * @param bin - The packed bin, already sized to its content.
+ * @param createCanvas - Makes the canvas to draw on.
+ * @returns The atlas, less its `resizable` flag.
+ */
+function renderAtlas(bin, createCanvas) {
+    const canvas = createCanvas(bin.width, bin.height);
+    const context = contextOf(canvas);
+    // Nothing downstream can recover from this: every atlas would upload blank, so the images would
+    // silently draw as nothing at all. Better to fail where the cause is still visible.
+    if (!context)
+        throw new Error(`atlas-packer: no 2d context for a ${bin.width}x${bin.height} atlas`);
+    const images = [];
+    for (const rect of bin.rects) {
+        const { entry, source } = rect.data;
+        // The copied region is the tile when there is one and the whole image otherwise — both read
+        // from the source's own axes. It happens to equal the packed rect's size today (tiles are
+        // placed 1:1, unrotated), but taking it from the destination would only be right by accident.
+        // Kept apart from `source` itself, which stays undefined for an unsplit image so the placement
+        // below does not report a region the caller has no use for.
+        const region = source ?? { x: 0, y: 0, width: entry.width, height: entry.height };
+        context.drawImage(entry.source, region.x, region.y, region.width, region.height, rect.x, rect.y, rect.width, rect.height);
+        // The rect is in canvas pixels and uv keeps the canvas's axes, so this is a plain normalization
+        // with no vertical inversion (see {@link UvRect}). Shared by every def on this rect — dedup is
+        // the whole point.
+        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,
+        };
+        for (const def of entry.defs)
+            images.push(source ? { def, uv, source } : { def, uv });
+    }
+    return { canvas, images };
+}
+/**
+ * Makes an atlas canvas in the document, the default when the caller supplies no factory.
+ * @param width - The atlas width in pixels.
+ * @param height - The atlas height in pixels.
+ * @returns The canvas.
+ */
+function createDomCanvas(width, height) {
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    return canvas;
+}
+/**
+ * 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.
+ */
+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/image-container.d.ts

@@ -0,0 +1,51 @@
+import { type InstancedMeshExt, type InstancedMeshExtParams } from '../../core/instanced/InstancedMesh';
+import { type ImageDef } from '../../types/defs';
+import { SlotContainer } from '../containers';
+import { type Atlas, type PackedImage } from './atlas-packer';
+/**
+ * The per-instance uniform each atlas mesh reads its texture region from. The container owns the
+ * name: it writes each slot's region here (`setUniformAt`) and hands it to the mesh's
+ * `TextureMaterial` as the `uvOffset` prop, so the material patches its shader to sample the region
+ * without knowing the name itself. `xy` is the region's origin in uv space and `zw` its size, so
+ * `uv * zw + xy` maps the quad's unit uv onto the region.
+ */
+export declare const UV_OFFSET_UNIFORM = "uvOffset";
+/**
+ * The constructor tuple R3F builds one atlas's mesh from, passed as `<instancedMesh args={…}>`.
+ * R3F diffs `args` element-wise and rebuilds the object when any element changes, so this is
+ * snapshotted once and never mutated.
+ *
+ * Only the options: `InstancedMeshExt` takes no geometry or material, seeding throwaways that the
+ * element's `<planeGeometry>` and `<TextureMaterial>` children replace (R3F creates, attaches, and
+ * disposes those).
+ */
+export type ImageMeshArgs = [params: InstancedMeshExtParams];
+/**
+ * One atlas's mesh bookkeeping.
+ *
+ * Simpler than a shape container, and deliberately so: an atlas draws one shared quad, so there is
+ * no geometry cache and no geometry-id juggling, and `InstancedMeshExt` grows its own buffers, so
+ * there is no capacity pre-scan — the mesh is merely sized to the atlas's packed-image count and
+ * left to resize itself if a claim ever overflows it. What remains is a slot per packed image and
+ * the uv region each one samples, written once at claim since a def's source never changes.
+ *
+ * Paint order is incremental, like the shape container's, because packing is order-independent: a
+ * reorder of the same images keeps this container and only re-labels its slots, never repacking. A
+ * change to the *set* of images is the harder case and still repacks into a fresh container —
+ * packing has no incremental path for that — but a pure reorder does not.
+ */
+export declare class ImageContainer extends SlotContainer<PackedImage, InstancedMeshExt, ImageDef> {
+    /** The constructor args R3F builds the mesh from; a frozen snapshot, never mutated. */
+    readonly args: ImageMeshArgs;
+    /**
+     * Builds one atlas's bookkeeping. The mesh, its quad, and its material are all R3F's — the atlas
+     * component renders `<instancedMesh args={container.args}>` with the geometry and material as
+     * children, and hands the mesh back through {@link SlotContainer.bind} — so R3F owns their
+     * lifetimes, including disposal on unmount and survival across StrictMode's simulated remount.
+     * @param atlas - The packed atlas this container draws; only its image count sizes the mesh.
+     */
+    constructor(atlas: Atlas);
+    protected addInstance(packed: PackedImage): number;
+    protected removeInstance(slot: number): void;
+}
+//# sourceMappingURL=image-container.d.ts.map

package/dist/objects/images/image-container.js

@@ -0,0 +1,70 @@
+import { Vector4 } from 'three';
+import { SlotContainer } from '../containers';
+import { DIM_SCHEMA } from '../materials/dim';
+/**
+ * The per-instance uniform each atlas mesh reads its texture region from. The container owns the
+ * name: it writes each slot's region here (`setUniformAt`) and hands it to the mesh's
+ * `TextureMaterial` as the `uvOffset` prop, so the material patches its shader to sample the region
+ * without knowing the name itself. `xy` is the region's origin in uv space and `zw` its size, so
+ * `uv * zw + xy` maps the quad's unit uv onto the region.
+ */
+export const UV_OFFSET_UNIFORM = 'uvOffset';
+/**
+ * One atlas's mesh bookkeeping.
+ *
+ * Simpler than a shape container, and deliberately so: an atlas draws one shared quad, so there is
+ * no geometry cache and no geometry-id juggling, and `InstancedMeshExt` grows its own buffers, so
+ * there is no capacity pre-scan — the mesh is merely sized to the atlas's packed-image count and
+ * left to resize itself if a claim ever overflows it. What remains is a slot per packed image and
+ * the uv region each one samples, written once at claim since a def's source never changes.
+ *
+ * Paint order is incremental, like the shape container's, because packing is order-independent: a
+ * reorder of the same images keeps this container and only re-labels its slots, never repacking. A
+ * change to the *set* of images is the harder case and still repacks into a fresh container —
+ * packing has no incremental path for that — but a pure reorder does not.
+ */
+export class ImageContainer extends SlotContainer {
+    /** The constructor args R3F builds the mesh from; a frozen snapshot, never mutated. */
+    args;
+    /**
+     * Builds one atlas's bookkeeping. The mesh, its quad, and its material are all R3F's — the atlas
+     * component renders `<instancedMesh args={container.args}>` with the geometry and material as
+     * children, and hands the mesh back through {@link SlotContainer.bind} — so R3F owns their
+     * lifetimes, including disposal on unmount and survival across StrictMode's simulated remount.
+     * @param atlas - The packed atlas this container draws; only its image count sizes the mesh.
+     */
+    constructor(atlas) {
+        super({ schema: IMAGE_SCHEMA });
+        this.args = [{ capacity: Math.max(1, atlas.images.length) }];
+    }
+    addInstance(packed) {
+        // `addInstances` grows the buffers itself if the atlas ever overflows its sized capacity, so
+        // there is nothing to pre-scan; the id is captured from the creation callback.
+        let slot = -1;
+        this.mesh.addInstances(1, (id) => {
+            slot = id;
+        });
+        // The uv region is fixed for the instance's life — a def's source never changes, and a set
+        // change repacks into a fresh container — so it is written once, here, rather than on every
+        // sync.
+        const { u0, v0, u1, v1 } = packed.uv;
+        this.mesh.setUniformAt(slot, UV_OFFSET_UNIFORM, _uvOffset.set(u0, v0, u1 - u0, v1 - v0));
+        return slot;
+    }
+    removeInstance(slot) {
+        this.mesh.removeInstances(slot);
+    }
+}
+/**
+ * The schema the mesh declares (via `addUniforms`) so it can hold a {@link UV_OFFSET_UNIFORM} and a
+ * dim per slot.
+ *
+ * Both in one call although the two come from different places: `InstanceUniforms.add` merges and
+ * rebuilds the backing texture, so declaring them separately would build it twice per bind.
+ */
+const IMAGE_SCHEMA = {
+    vertex: { [UV_OFFSET_UNIFORM]: 'vec4', ...DIM_SCHEMA.vertex },
+};
+// Scratch for the one uv-region upload a claim performs, filled and read within a single
+// synchronous statement.
+const _uvOffset = new Vector4();

package/dist/objects/images/index.d.ts

@@ -0,0 +1,2 @@
+export { Images, type ImagesProps } from './Images';
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/images/index.js

@@ -0,0 +1 @@
+export { Images } from './Images';

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