@expofp/renderer 3.38.0 → 3.39.1

package/dist/objects/images/ImageInstance.js

@@ -1,5 +1,7 @@
 import { memo } from 'react';
-import { Matrix4 } from 'three';
+import { Matrix4, Vector2, Vector3 } from 'three';
+import { isBatchedSprites } from '../../core/sprites/BatchedSprites';
+import { Y_DOWN_FLIP } from '../../space/Space';
 import { shapeToMatrix, useDefSync, writeMatrixIfChanged } from '../containers';
 /**
  * Keeps one image placement current: claims a slot on mount (where the container writes the fixed
@@ -18,66 +20,132 @@ import { shapeToMatrix, useDefSync, writeMatrixIfChanged } from '../containers';
  */
 export const ImageInstance = memo(function ImageInstance(props) {
     const { def, packed, container } = props;
-    useDefSync(container, def, packed, (slot) => {
-        writeImageMatrix(container.mesh, slot, def, packed);
+    useDefSync(container, def, () => packed, (slot) => {
+        const tile = tileRect(packed);
+        writeImageMatrix(container, slot, def, tile);
+        writeImageAnchor(container, slot, def, tile);
+        // Checked on every sync rather than behind the write, because screenSpace is an ordinary def
+        // field. Flipping it reaches this instance and stops there, so this is where a mesh learns that
+        // it holds something it should not. The atlas re-filters, which never touches the packing.
+        if (!!def.screenSpace !== container.facesCamera)
+            container.reportKindMismatch();
     });
     return null;
 });
 /**
- * Writes an image placement's transform into its instance, skipping the write when nothing moved.
+ * Composes an image placement's instance matrix, and skips the write when nothing moved.
  *
- * `bounds` is a rect, so the quad's placement composes exactly as a rect shape's does; the image's
- * own offsets are then post-multiplied onto it, innermost last. The origin shifts the quad within
- * its own unit square so the anchor — not the quad's center — lands on `bounds.center`, which also
- * makes the anchor the point rotation pivots about. A split source draws as several instances, so
- * this instance's quad is finally shrunk onto the fraction of the image its tile covers.
- * @param mesh - The mesh holding the instance.
+ * `bounds` is a rect, so the quad's placement composes exactly as a rect shape's does. The two
+ * kinds part over the anchor and the tile.
+ *
+ * A flat quad folds the anchor into the matrix. That shifts the quad within its own unit square so
+ * the anchor, not the quad's center, lands on the bounds center, which also makes the anchor the
+ * point rotation pivots about. A tile then shrinks the quad onto the fraction of the image it covers.
+ *
+ * A sprite cannot fold the anchor in. It pivots about its anchor, so the matrix translation has to
+ * be the bounds center and stay there for every tile of a split source. Only the tile's scale and
+ * the plan-to-view y mirror stay in the matrix here. The anchor itself is
+ * {@link writeImageAnchor}'s write, not this one's.
+ * @param container - The container holding the instance, which says which kind it draws.
  * @param slot - The instance's slot.
  * @param def - The image def supplying the transform.
- * @param packed - This instance's placement, whose `source` region marks it as a tile.
+ * @param tile - This instance's tile within the source, or `undefined` for an unsplit image.
  */
-function writeImageMatrix(mesh, slot, def, packed) {
-    // The shared scratch `shapeToMatrix` returns, adjusted in place below and uploaded before any
-    // other write can claim it.
+function writeImageMatrix(container, slot, def, tile) {
     const matrix = shapeToMatrix(def.bounds);
-    // Unit-plane axes run the same way as image axes — x right, y down, matching the atlas uv and the
-    // scene's y-down coordinates — so an origin of `[0, 0]` (top-left) shifts the quad by a positive
-    // half in both, putting its top-left corner on the bounds' center.
+    if (container.facesCamera) {
+        if (tile)
+            matrix.scale(_tileScale.set(tile.width, tile.height, 1));
+        // Y_DOWN_FLIP is the plan-to-view y mirror for this quad's own 2D linear map. Order does not
+        // matter against the tile scale above: the flip lands on the left of the whole linear map
+        // either way. Premultiplying also flips the translation, so save it and put it back. The
+        // translation is the bounds center the sprite pivots about and must not move.
+        const centerY = matrix.elements[13];
+        matrix.premultiply(Y_DOWN_FLIP);
+        matrix.elements[13] = centerY;
+    }
+    else {
+        const [originX, originY] = def.origin ?? DEFAULT_ORIGIN;
+        // The anchor as an offset from the quad's middle, which is the convention both paths use.
+        const anchorX = originX - 0.5;
+        const anchorY = originY - 0.5;
+        // Unit-plane axes run the same way as image axes, x right and y down, matching the atlas uv and
+        // the scene's y-down coordinates. So an origin of [0, 0], the top-left corner, shifts the quad
+        // by a positive half in both and puts its top-left corner on the bounds center.
+        matrix.multiply(_anchor.makeTranslation(-anchorX, -anchorY, 0));
+        if (tile) {
+            matrix.multiply(_tile.makeScale(tile.width, tile.height, 1).setPosition(tile.x, tile.y, 0));
+        }
+    }
+    writeMatrixIfChanged(container.mesh, slot, matrix);
+}
+/**
+ * Writes an image placement's anchor uniform, for the one kind that has one, skipping the write when
+ * it did not move.
+ *
+ * Only a sprite pivots about its anchor. The flat path folds the anchor into the matrix instead (see
+ * {@link writeImageMatrix}) and has no anchor uniform to write. The mesh is narrowed here rather
+ * than asked through `facesCamera`, which answers the same question but cannot narrow the mesh's
+ * type for the two anchor calls. A tile shifts the anchor by the tile's own offset from the image's
+ * middle and rescales it into the tile's unit square, so the result still reads as an offset from
+ * the tile's own middle.
+ *
+ * `setAnchorAt` invalidates the mesh's bounds on every call, so the compare-and-skip is what keeps
+ * a def whose anchor did not move from paying for that invalidation on every sync, the same way
+ * `writeMatrixIfChanged` does for the matrix.
+ * @param container - The container holding the instance.
+ * @param slot - The instance's slot.
+ * @param def - The image def supplying the origin.
+ * @param tile - This instance's tile within the source, or `undefined` for an unsplit image.
+ */
+function writeImageAnchor(container, slot, def, tile) {
+    const mesh = container.mesh;
+    if (!isBatchedSprites(mesh))
+        return;
     const [originX, originY] = def.origin ?? DEFAULT_ORIGIN;
-    matrix.multiply(_origin.makeTranslation(0.5 - originX, 0.5 - originY, 0));
-    if (packed.source)
-        applyTile(matrix, packed);
-    writeMatrixIfChanged(mesh, slot, matrix);
+    // The anchor as an offset from the quad's middle, which is the convention both paths use.
+    let x = originX - 0.5;
+    let y = originY - 0.5;
+    if (tile) {
+        x = (x - tile.x) / tile.width;
+        y = (y - tile.y) / tile.height;
+    }
+    mesh.getAnchorAt(slot, _previousAnchor);
+    if (_previousAnchor.x === x && _previousAnchor.y === y)
+        return;
+    mesh.setAnchorAt(slot, x, y);
 }
 /**
- * Post-multiplies the image transform by the local sub-quad a tile occupies, so a split source's
- * tiles reassemble into the whole image. The tile's fraction of the source, in source pixels, is
- * also its fraction of the image. So the sub-quad is that same fraction of the unit plane. The
- * code scales the sub-quad to the tile's size, then moves it so its center lands on that
- * fraction's center point, in unit-plane coordinates.
- * @param matrix - The image transform, multiplied in place.
+ * Where one tile sits inside the whole image, in unit-quad lengths.
  * @param packed - This instance's placement, with the tile's region and the source size to divide
  *   by.
+ * @returns The tile's size and the offset of its center from the image's middle, or `undefined` for
+ *   an unsplit placement or a source that has no size to measure against.
  */
-function applyTile(matrix, packed) {
+function tileRect(packed) {
     const { source, size } = packed;
     if (!source || size.width <= 0 || size.height <= 0)
-        return;
+        return undefined;
     const fx0 = source.x / size.width;
     const fy0 = source.y / size.height;
     const fx1 = (source.x + source.width) / size.width;
     const fy1 = (source.y + source.height) / size.height;
-    _tile
-        .makeScale(fx1 - fx0, fy1 - fy0, 1)
-        .setPosition((fx0 + fx1) / 2 - 0.5, (fy0 + fy1) / 2 - 0.5, 0);
-    matrix.multiply(_tile);
+    return {
+        width: fx1 - fx0,
+        height: fy1 - fy0,
+        x: (fx0 + fx1) / 2 - 0.5,
+        y: (fy0 + fy1) / 2 - 0.5,
+    };
 }
 /**
  * The anchor a def leaves unset: the image's center, so `bounds.center` is where the middle of the
  * image sits. Matches {@link ImageDef.origin}'s documented default.
  */
 const DEFAULT_ORIGIN = [0.5, 0.5];
-// Scratch shared by every instance and every write: filled and uploaded within a single
-// synchronous statement, so an instance costs a texture write and no allocation.
-const _origin = new Matrix4();
+// Scratch shared by every instance and every write. Each is filled and uploaded within a single
+// synchronous statement, so an instance costs a texture write and no allocation. `_previousAnchor`
+// is only ever read back and compared, so a caller still holding the matrix never collides with it.
+const _anchor = new Matrix4();
 const _tile = new Matrix4();
+const _tileScale = new Vector3();
+const _previousAnchor = new Vector2();

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

@@ -17,15 +17,16 @@ export interface ImagesProps extends DefsProps<ImageDef> {
     createCanvas?: CreateAtlasCanvas;
 }
 /**
- * Draws a collection of images as textured quads, packing their pixels into one or more atlases and
- * drawing each atlas as a single `InstancedMesh` — so a layer of many images costs a handful of
- * draw calls, not one per image.
+ * Draws a collection of images as textured quads, packing their pixels into one or more atlases.
+ * Each atlas draws through up to two meshes that share its texture, so a layer of many images still
+ * costs a handful of draw calls, not one per image.
  *
  * Unlike a shape layer, an image layer can span **several meshes**: bin-packing splits the images
- * across as many atlases as their pixels need, and each atlas gets its own mesh, batch, and
- * texture (an {@link ImageAtlas}). A def whose source is too big for one atlas is cut into tiles
- * that may land on different atlases, so one def can drive several instances — the atlas iterates
- * its packed placements, not the defs.
+ * across as many atlases as their pixels need, and each atlas gets its own texture drawn through up
+ * to two meshes, a flat `InstancedMesh` and a camera-facing `BatchedSprites` (an
+ * {@link ImageAtlas}). An unmixed layer still mounts only one mesh. A def whose source is too big
+ * for one atlas is cut into tiles that may land on different atlases, so one def can drive several
+ * instances. The atlas iterates its packed placements, not the defs.
  *
  * Packing has no incremental path, so a change to the **set** of images **repacks from scratch**: a
  * fresh atlas set under fresh keys, remounting every mesh and instance. A **reorder** of the same

package/dist/objects/images/Images.js

@@ -3,25 +3,27 @@ import { useThree } from '@react-three/fiber';
 import { use, useEffect, useRef, useState } from 'react';
 import { CanvasTexture, SRGBColorSpace } from 'three';
 import { InstancedMesh } from '../../core/instanced/InstancedMesh';
+import { BatchedSprites } from '../../core/sprites/BatchedSprites';
 import { createLogger } from '../../utils/logging';
 import { defKey, useContainer } from '../containers';
 import { TextureMaterial } from '../materials/TextureMaterial';
-import { packAtlases } from './atlas-packer';
+import { packAtlases, } from './atlas-packer';
 import { ImageContainer, UV_OFFSET_UNIFORM } from './image-container';
 import { ImageInstance } from './ImageInstance';
 import { contextOf, createAtlasCanvas } from './pack-sources';
 import { TextureBudgetContext, useResizeFactor } from './texture-budget';
 const logger = createLogger('images');
 /**
- * Draws a collection of images as textured quads, packing their pixels into one or more atlases and
- * drawing each atlas as a single `InstancedMesh` — so a layer of many images costs a handful of
- * draw calls, not one per image.
+ * Draws a collection of images as textured quads, packing their pixels into one or more atlases.
+ * Each atlas draws through up to two meshes that share its texture, so a layer of many images still
+ * costs a handful of draw calls, not one per image.
  *
  * Unlike a shape layer, an image layer can span **several meshes**: bin-packing splits the images
- * across as many atlases as their pixels need, and each atlas gets its own mesh, batch, and
- * texture (an {@link ImageAtlas}). A def whose source is too big for one atlas is cut into tiles
- * that may land on different atlases, so one def can drive several instances — the atlas iterates
- * its packed placements, not the defs.
+ * across as many atlases as their pixels need, and each atlas gets its own texture drawn through up
+ * to two meshes, a flat `InstancedMesh` and a camera-facing `BatchedSprites` (an
+ * {@link ImageAtlas}). An unmixed layer still mounts only one mesh. A def whose source is too big
+ * for one atlas is cut into tiles that may land on different atlases, so one def can drive several
+ * instances. The atlas iterates its packed placements, not the defs.
  *
  * Packing has no incremental path, so a change to the **set** of images **repacks from scratch**: a
  * fresh atlas set under fresh keys, remounting every mesh and instance. A **reorder** of the same
@@ -107,26 +109,26 @@ export function Images(props) {
     return (_jsx(_Fragment, { children: packed.atlases.map((atlas) => (_jsx(ImageAtlas, { atlas: atlas, defs: defs, mounted: mounted }, atlasKey(atlas, packed.generation)))) }));
 }
 /**
- * Draws one atlas as an `InstancedMesh`: the R3F-owned mesh with the atlas texture as its
- * `TextureMaterial`, plus one {@link ImageInstance} per placement on the atlas. Its set of images is
- * fixed for its lifetime — a repack remounts the whole component — so the batch and texture are
- * built once from state and released together on unmount. Paint order is not fixed: a reorder keeps
- * this atlas and re-labels its instances through the effect below.
+ * Owns one atlas's texture and its flat/sprite split, and draws each non-empty side as its own
+ * `AtlasMesh`. The atlas's set of images is fixed for its lifetime. A repack remounts the whole
+ * component, so the texture is built once from state and released on unmount.
  *
- * The uploaded texture is not fixed either: a resizable atlas registers with the scene's texture
- * budget and re-derives a downscaled copy of its canvas whenever the shared resize factor moves (see
- * {@link resizeTexture}). That is a texture re-upload, not a repack — the mesh, container,
- * instances, and their normalized uv regions all stand, since uv is invariant to the canvas's pixel
- * size.
+ * The uploaded texture is not fixed. A resizable atlas registers with the scene's texture budget and
+ * re-derives a downscaled copy of its canvas whenever the shared resize factor moves (see
+ * {@link resizeTexture}). That is a texture re-upload, not a repack. The meshes, their containers,
+ * their instances, and their normalized uv regions all stand, because uv does not depend on the
+ * canvas's pixel size.
+ *
+ * The flat/sprite split is a second kind of state, held here rather than derived every render. A
+ * def's `screenSpace` is an ordinary slot write that never re-renders this component, so an
+ * `AtlasMesh` calls `repartition` when it finds a member that no longer matches its kind.
  * @param props - The atlas and the layer's images in paint order.
- * @returns The mesh and one instance component per placement.
+ * @returns One `AtlasMesh` per non-empty kind, sharing this atlas's texture.
  */
 function ImageAtlas(props) {
     const { atlas, defs } = props;
-    // Only the placements are staged; the container and the texture are built from the whole atlas.
     const mounted = props.mounted ?? atlas.images.length;
     const [texture] = useState(() => makeAtlasTexture(atlas.image));
-    const container = useContainer(() => new ImageContainer(atlas), defs);
     const invalidate = useThree((state) => state.invalidate);
     const budget = use(TextureBudgetContext);
     const factor = useResizeFactor(budget, atlas);
@@ -157,15 +159,79 @@ function ImageAtlas(props) {
         const scaled = scaledRef.current;
         return () => closeScaled(scaled);
     }, []);
-    // `args` is a frozen snapshot so R3F never rebuilds the mesh; the `ref` arrow (not
-    // `ref={container.bind}`) keeps the React Compiler from inferring `container` itself as a ref and
+    // Held in state rather than derived each render, which is the shape `Shapes` uses for its own
+    // split. screenSpace is an ordinary slot write that never re-renders this component, so a def
+    // crossing the orientation boundary would otherwise stay in a mesh that no longer suits it.
+    // repartition is what an instance's reportKindMismatch runs. The atlas's placements never change
+    // identity, because a repack remounts this whole component, so nothing else triggers a re-split.
+    const [partition, setPartition] = useState(() => partitionImages(atlas.images));
+    /** Re-splits the atlas's placements, for a mesh that found a member of the wrong kind. */
+    function repartition() {
+        setPartition(() => partitionImages(atlas.images));
+    }
+    // One mesh per kind, keyed so React never reconciles a flat mesh element against a sprite one
+    // when the first kind empties out. An empty subset renders nothing, so an unmixed layer costs
+    // exactly what it costs today and a mixed layer costs one extra draw call per atlas.
+    //
+    // renderOrder is the kind's place in IMAGE_KINDS, which makes "flats, then sprites" an explicit
+    // rule within a layer. Today the atlas meshes carry no order at all and it falls out of
+    // material.id, which is mount order. What that costs is that a flat def and a sprite def in one
+    // layer can no longer interleave in array order. `overlay` is there for a caller who needs strict
+    // separation, and a camera-facing pin is generally meant to be on top anyway.
+    return (_jsx(_Fragment, { children: IMAGE_KINDS.map((kind, renderOrder) => {
+            const placements = partition[kind];
+            if (placements.length === 0)
+                return null;
+            return (_jsx(AtlasMesh, { kind: kind, placements: placements, defs: defs, mounted: mounted, capacity: atlas.images.length, texture: texture, renderOrder: renderOrder, onKindMismatch: repartition }, kind));
+        }) }));
+}
+/**
+ * One atlas mesh and its instances: the atlas's flat images or its camera-facing ones, never both.
+ *
+ * The material is a child and is genuinely per mesh. `InstancedMeshImpl` wraps whatever it draws with
+ * in a closure over its own textures, and two instanced meshes on one material would both render
+ * against the first one's. The texture is shared, and that is the whole of the two-mesh split: an
+ * atlas is a texture packing and a mesh is a draw call, and nothing forces them to be one thing.
+ *
+ * The sprite mesh mounts no plane geometry child. `BatchedSpritesImpl` seeds the shared quad
+ * itself, and not rendering a replacement is what makes the seeded one stand.
+ * @param props - The kind, its placements, and the shared texture.
+ * @returns The mesh and one instance component per placement.
+ */
+function AtlasMesh(props) {
+    const { kind, placements, defs, capacity, texture, renderOrder, onKindMismatch } = props;
+    // Handed to this mesh as a prefix of its own placements rather than apportioned between the two,
+    // as Shapes does for its batches. A slice can overshoot the scheduler's budget by a factor of two
+    // at worst, and the scheduler measures what a slice actually cost and sizes the next one from it.
+    const mounted = props.mounted ?? placements.length;
+    // Sized from the atlas's whole placement count, not this subset's, so a re-split never resizes a
+    // buffer. The container is bookkeeping only, so the copy StrictMode's double-invoked initializer
+    // discards is plain garbage.
+    const container = useContainer(() => new ImageContainer(capacity), defs, onKindMismatch);
+    // args is a frozen snapshot, so R3F never rebuilds the mesh. The ref arrow, rather than
+    // ref={container.bind}, keeps the React Compiler from inferring container itself as a ref and
     // rejecting its render reads.
-    // The quad and the material are children so R3F creates, attaches, and disposes both — the args
-    // pair are placeholders the constructor demands (see `ImageMeshArgs`). The material has to be per
-    // mesh: `InstancedMeshImpl` wraps whatever it draws with in a closure over its own textures, and two
-    // instanced meshes on one material would both render against the first one's.
-    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => container.bind(mesh), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }), atlas.images.slice(0, mounted).map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
+    const mesh = kind === 'sprite' ? (_jsx(BatchedSprites, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM }) })) : (_jsxs(InstancedMesh, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }));
+    return (_jsxs(_Fragment, { children: [mesh, placements.slice(0, mounted).map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
+}
+/**
+ * Splits an atlas's placements by orientation.
+ *
+ * A filter over an array the component already holds. The packing, the canvas, the uv regions and the
+ * texture budget are all untouched, so nothing repacks. That is what makes flipping a def's
+ * screenSpace cheaper here than a shape's kind change, where a re-split rebuilds partitions.
+ * @param images - The atlas's placements, in packing order.
+ * @returns The two subsets, each still in packing order.
+ */
+function partitionImages(images) {
+    const flat = [];
+    const sprite = [];
+    for (const packed of images)
+        (packed.def.screenSpace === true ? sprite : flat).push(packed);
+    return { flat, sprite };
 }
+/** The atlas's two meshes, in draw order: flats first, then the camera-facing ones. */
+const IMAGE_KINDS = ['flat', 'sprite'];
 /**
  * Whether two snapshots hold the same *set* of images, order aside — the question "does this need a
  * repack". Order is excluded on purpose: packing reads only pixels, so a reorder produces the same

package/dist/objects/images/image-container.d.ts

@@ -1,7 +1,7 @@
 import { type InstancedMeshImpl, type InstancedMeshImplParams } from '../../core/instanced/InstancedMesh';
 import { type ImageDef } from '../../types/defs';
 import { SlotContainer } from '../containers';
-import { type Atlas, type PackedImage } from './atlas-packer';
+import { 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
@@ -42,9 +42,20 @@ export declare class ImageContainer extends SlotContainer<PackedImage, Instanced
      * 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.
+     * @param capacity - How many instances to size the mesh for. This is the atlas's whole placement
+     *   count, not one kind's share of it, so moving a def between the two meshes never resizes a
+     *   buffer. The mesh grows past it on demand in any case.
      */
-    constructor(atlas: Atlas);
+    constructor(capacity: number);
+    /**
+     * Whether the bound mesh draws its members facing the camera.
+     *
+     * Read off the mesh rather than stored, so one field cannot disagree with another. `screenSpace` is
+     * an ordinary def field, so flipping it re-renders nothing and only an instance can notice that it
+     * is drawing from the wrong mesh.
+     * @returns Whether this container holds a sprite batch.
+     */
+    get facesCamera(): boolean;
     protected addInstance(packed: PackedImage): number;
     protected removeInstance(slot: number): void;
 }

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

@@ -1,4 +1,5 @@
 import { Vector4 } from 'three';
+import { isBatchedSprites } from '../../core/sprites/BatchedSprites';
 import { SlotContainer } from '../containers';
 import { DIM_SCHEMA } from '../materials/effects/color-dim';
 /**
@@ -31,11 +32,24 @@ export class ImageContainer extends SlotContainer {
      * 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.
+     * @param capacity - How many instances to size the mesh for. This is the atlas's whole placement
+     *   count, not one kind's share of it, so moving a def between the two meshes never resizes a
+     *   buffer. The mesh grows past it on demand in any case.
      */
-    constructor(atlas) {
+    constructor(capacity) {
         super({ schema: IMAGE_SCHEMA });
-        this.args = [{ capacity: Math.max(1, atlas.images.length) }];
+        this.args = [{ capacity: Math.max(1, capacity) }];
+    }
+    /**
+     * Whether the bound mesh draws its members facing the camera.
+     *
+     * Read off the mesh rather than stored, so one field cannot disagree with another. `screenSpace` is
+     * an ordinary def field, so flipping it re-renders nothing and only an instance can notice that it
+     * is drawing from the wrong mesh.
+     * @returns Whether this container holds a sprite batch.
+     */
+    get facesCamera() {
+        return isBatchedSprites(this.mesh);
     }
     addInstance(packed) {
         // `addInstances` grows the buffers itself if the atlas ever overflows its sized capacity, so
@@ -65,6 +79,6 @@ export class ImageContainer extends SlotContainer {
 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.
+// 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/layer/Layer.d.ts

@@ -5,10 +5,10 @@ export interface LayerProps {
     /** The layer definition to render, together with its descendants. */
     layer: LayerDef;
     /**
-     * Rendered inside the root group, before the tree's own content — under the root layer's dim
-     * provider, which is what the scene's background quad mounts here for: the root's dim reaches it
-     * like any layer's, and its material exists before every layer's, which its draw order relies
-     * on.
+     * Rendered inside the root group, before the tree's own content. This sits under the root
+     * layer's dim and overlay providers. The scene's background quad mounts here for that reason:
+     * the root's dim reaches it like any layer's, and its material exists before every layer's,
+     * which its draw order relies on.
      */
     children?: ReactNode;
 }
@@ -18,8 +18,9 @@ export interface LayerProps {
  * This root component owns the tree-wide concerns — in debug mode the layer-visibility GUI, a
  * "Main layers" folder for its direct child layers and a "Content layers" folder mirroring the
  * scheduler's leaf queue (see `visibility-gui.ts`) — and seeds the recursion {@link LayerNode}
- * carries: nothing above the root can hide it, and the whole tree's draw order lives inside
- * `[0, 1)`.
+ * carries with `hidden`, at `false`. Dim and overlay need no seed: `LayerDimContext` and
+ * `LayerOverlayContext` already default to undimmed and plan tier, which is what "no layer above
+ * me" means for either one. The whole tree's draw order lives inside `[0, 1)`.
  * @param props - The layer props.
  * @returns The tree's root group.
  */