@expofp/renderer 3.37.1 → 3.39.0

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

@@ -1,128 +1,129 @@
 import { type ImageDef, type ImageSource } from '../../types/defs';
-/** A canvas an atlas is drawn onto. `OffscreenCanvas` included so packing can move to a worker. */
-export type AtlasCanvas = HTMLCanvasElement | OffscreenCanvas;
+import { type AtlasCanvas, type CreateAtlasCanvas, type SourceRect, type UvRect } from './pack-sources';
+export { type AtlasCanvas, type CreateAtlasCanvas, isResizableSource, type SourceRect, type UvRect, } from './pack-sources';
 /**
- * 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** — the same axes as
- * `ImageDef.bounds`, and literally the `sx, sy, sw, sh` the packer hands to `drawImage`. Kept in
- * pixels rather than normalized so it cannot be mistaken for a {@link UvRect}, whose origin is the
- * other 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, v running down**.
+ * The pixels an atlas can hold: a canvas, or a bitmap transferred out of one.
  *
- * Consumed by a texture uploaded with `flipY = false`, which maps canvas row 0 to `v = 0`, so these
- * numbers feed a uv transform directly with no vertical inversion. That is deliberate: the scene's
- * y axis already points down (SVG coordinates, and the camera is placed to match), so a uv space
- * that also runs down keeps every axis in the pipeline pointing the same way — invert at one end
- * only and images come out upside down.
+ * `AtlasCanvas` stays narrow on purpose. `CreateAtlasCanvas` and `contextOf` both need a type they
+ * can open a 2D context on, and an `ImageBitmap` has no context to open.
  */
-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 image — or one tile of a split image — placed in an atlas. */
+export type AtlasImage = AtlasCanvas | ImageBitmap;
+/** One image, or one tile of a split image, placed in an atlas. */
 export interface PackedImage {
     /**
-     * The def these pixels belong to. Defs whose sources dedupe appear as separate entries sharing
-     * one region, so the list maps one-to-one onto the instances an atlas has to draw.
+     * The def that these pixels belong to. Defs whose sources dedupe appear as separate entries
+     * that share one region, so the list maps one-to-one onto the instances that an atlas must
+     * draw.
      */
     def: ImageDef;
     /** Where the pixels sit in the atlas. */
     uv: UvRect;
     /**
-     * Which part of `def.source` this entry holds. Undefined when the source was small enough to
-     * pack whole, which is the common case; set only on the tiles of a split source, where a
-     * consumer needs it to work out the fraction of `def.bounds` this tile covers.
+     * Which part of `def.source` this entry 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, where a consumer
+     * needs it to work out the fraction of `def.bounds` that this tile covers.
      */
     source?: SourceRect;
+    /**
+     * The intrinsic pixel size of `def.source`. The packer measures this once and carries it on the
+     * placement, because a `Blob` source cannot be measured again later. A tile's consumer reads
+     * this field to find the fraction of the image the tile covers. The field spares that consumer
+     * from decoding the source a second time.
+     */
+    size: {
+        width: number;
+        height: number;
+    };
 }
-/** One packed atlas: a canvas of pixels, and what landed where on it. */
+/** One packed atlas: its pixels, and a record of what landed where on it. */
 export interface Atlas {
-    /** The canvas holding the packed pixels. Its `width`/`height` are the atlas's size. */
-    canvas: AtlasCanvas;
+    /**
+     * The atlas's packed pixels: a canvas, or a bitmap a worker transferred out of one. Its
+     * `width`/`height` are the atlas's size.
+     */
+    image: AtlasImage;
     /** Every def placement on this atlas. */
     images: PackedImage[];
     /**
-     * Whether this atlas's pixels may be downscaled to fit a memory budget. Image and bitmap sources
-     * pack into resizable atlases; canvas sources into fixed ones. An atlas never mixes the two (they
-     * are packed as separate groups), so this one flag speaks for every placement on it — which is
-     * what lets a memory budget scale the whole canvas at once without dragging a canvas source down
-     * with the images. See {@link isResizableSource}.
+     * Whether this atlas's pixels can shrink to fit a memory budget. Image and bitmap sources pack
+     * into resizable atlases. Canvas sources pack into fixed ones. An atlas never mixes the two
+     * kinds, because the code packs them as separate groups. So this one flag applies to every
+     * placement on the atlas. It lets a memory budget scale a whole resizable canvas at once,
+     * without changing a canvas source's pixels. See {@link isResizableSource}.
      */
     resizable: boolean;
 }
 /** Options for {@link packAtlases}. */
 export interface AtlasPackerOptions {
-    /** Creates each atlas canvas. Defaults to a DOM canvas. */
+    /** Creates each atlas canvas. Defaults to {@link createAtlasCanvas}. */
     createCanvas?: CreateAtlasCanvas;
+    /**
+     * Abandons the pack. A repack that supersedes a pack still in flight aborts that pack. The
+     * worker is told to drop it and goes on running, and a result that still arrives is thrown away
+     * instead of mounted.
+     */
+    signal?: AbortSignal;
 }
 /**
- * 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`).
+ * Where a pack draws its atlases.
  *
- * 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.
+ * There are two tiers and not three. Both tiers decode with `createImageBitmap`, because every
+ * build target has it (the plan's Global Constraints hold the compat data). What changes between
+ * the tiers is whether the drawing can leave the main thread. That turns on `OffscreenCanvas`,
+ * which Chrome 66 and Safari 15 do not have. The inline tier is a normal path for those targets
+ * and not an edge case. It is already around five times cheaper than the code it replaces, because
+ * it no longer decodes an `<img>`.
  */
-export declare function isResizableSource(source: ImageSource): boolean;
+export type PackTier = 
+/** `Worker` and `OffscreenCanvas` are present, and every source is a `Blob`: pack off-thread. */
+'worker'
+/** Anything else: decode and pack on the main thread. */
+ | 'inline';
 /**
- * Packs image defs into atlas canvases and reports where every def's pixels landed.
+ * Packs image defs into atlas canvases and reports where each 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.
+ * The code first dedupes the defs. Two defs that point at the same URL, or that hold the same
+ * object, draw once and share one region. The code then decodes every source that is not drawable
+ * yet, which is what makes this function asynchronous: a `Blob` holds bytes and not pixels. The
+ * code then hands the decoded sources to {@link packSources}, which does the pixel work. The
+ * placements come back addressed by source index, and this function expands them into one entry
+ * per def.
  *
- * 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.
+ * 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. A change in
+ * membership is different. This is a batch call with no incremental path, so an added or removed
+ * def needs a fresh call.
+ *
+ * A worker that fails for any reason other than an abort falls back to the inline tier once. The
+ * worker is an optimization, and no host page may cost a layer its images by refusing one.
  * @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.
+ * @param maxDimension - The largest atlas edge, in pixels. The function floors this to a positive
+ *   integer.
+ * @param options - Overrides for how atlas canvases are made, and the signal that abandons the
+ *   pack.
+ * @returns One entry for each atlas, in packing order: resizable atlases first, then fixed ones.
  */
-export declare function packAtlases(defs: readonly ImageDef[], maxDimension: number, options?: AtlasPackerOptions): Atlas[];
+export declare function packAtlases(defs: readonly ImageDef[], maxDimension: number, options?: AtlasPackerOptions): Promise<Atlas[]>;
 /**
- * The pixel size of an image source.
+ * Picks the higher tier when this environment and this set of sources both allow it.
+ *
+ * A layer packs in the worker only when **every** source is a `Blob`. One source of any other kind
+ * keeps the whole layer on the main thread.
+ *
+ * The test names what may cross, never what must stay. A test that only excludes the known-bad
+ * kinds admits every kind nobody thought of, and this code shipped that mistake once: it asked
+ * whether a source was not a DOM canvas, which let an `<img>` through. An `<img>` neither clones
+ * nor moves, so `postMessage` threw on it and the layer drew nothing.
  *
- * 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.
+ * A `Blob` is also the only source the worker can take without taking it from the def that owns it.
+ * Its handle clones, so the def keeps its bytes. Every other kind would have to move, and a moved
+ * source is dead on the main thread, so the next repack would find nothing to draw. Those sources
+ * lose nothing by packing inline. A canvas cannot cross at all — `transferControlToOffscreen` throws
+ * on a canvas that already holds a 2D context, and every floorplan canvas source holds one — and
+ * `createImageBitmap(canvas)` costs more than a pack of that canvas on the main thread (this is
+ * measured, see the design spec).
+ * @param sources - The unique sources that this pack will draw.
+ * @returns The tier to run.
  */
-export declare function imageSourceSize(source: ImageSource): {
-    width: number;
-    height: number;
-};
+export declare function selectTier(sources: readonly ImageSource[]): PackTier;
 //# sourceMappingURL=atlas-packer.d.ts.map