@woosh/meep-engine 3.47.0 → 3.49.0

package/src/shade/renderer/texture/atlas/GPUTileAtlas3D.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Grid cell of a slot under a footprint: x fastest, then y, then z.
+ *
+ * @param {number} slot
+ * @param {number} slots_x
+ * @param {number} slots_y
+ * @param {number[]|Uint32Array} out receives x, y, z in tiles
+ * @returns {number[]|Uint32Array} out
+ */
+export function tile_atlas_slot_cell(slot: number, slots_x: number, slots_y: number, out: number[] | Uint32Array): number[] | Uint32Array;
+/**
+ * The footprint a full atlas widens to: the smaller of x and y doubles, x on a tie, capped at
+ * `axis_limit`. The smaller side reaches the limit only when both have, which is when the atlas is
+ * full.
+ *
+ * @param {number} slots_x
+ * @param {number} slots_y
+ * @param {number} axis_limit tiles that fit along an axis
+ * @param {number[]} out receives the new slots_x, slots_y
+ * @returns {boolean} false when both sides are at the limit, and nothing can widen
+ */
+export function tile_atlas_widened_footprint(slots_x: number, slots_y: number, axis_limit: number, out: number[]): boolean;
+/**
+ * A tile's full block from its content: the content in the middle, and around it a skirt of
+ * `border` texels holding the content's opposite edge, so the block tiles with itself under a
+ * linear filter.
+ *
+ * Pure, and the one place the wrap is defined — a device-side producer has to agree with it.
+ *
+ * @param {Uint8Array} content `content_size³ · bytes_per_texel` bytes, x fastest
+ * @param {number} content_size
+ * @param {number} border at most `content_size`
+ * @param {number} bytes_per_texel
+ * @param {Uint8Array} out `(content_size + 2·border)³ · bytes_per_texel` bytes, x fastest
+ * @returns {Uint8Array} out
+ */
+export function tile_atlas_bordered_block(content: Uint8Array, content_size: number, border: number, bytes_per_texel: number, out: Uint8Array): Uint8Array;
+/**
+ * One 3-D texture cut into equal tiles, each tile a `content_size³` block of texels wrapped in a
+ * `border`-texel skirt, handed out one slot at a time.
+ *
+ * **What the border is for.** A tile sampled with a linear filter reads half a texel past its
+ * content on every side. The skirt holds the texels a *wrapping* tile would find there — the
+ * opposite edge of the same content — so a trilinear tap at the tile's edge blends with the tile's
+ * other side and never with the neighbouring slot. {@link tile_atlas_bordered_block} builds that
+ * skirt on the host; a producer writing on the device (a compute bake copying in through
+ * {@link copy_from_buffer}, or storing into the texture from a shader) writes the whole
+ * `tile_size³` block, skirt included, itself. One texel of border is what a linear filter needs; a
+ * wider one is for a consumer that steps further (a distance field marched across a tile), which is
+ * why it is a parameter. A consumer that never reads past its tile — loads clamped to the content —
+ * wants none.
+ *
+ * **Slots are linear, and grow two ways.** Slot `s` sits at grid cell
+ * `(s mod slots_x, floor(s / slots_x) mod slots_y, floor(s / (slots_x · slots_y)))`, x fastest and
+ * z slowest. When none is free, {@link allocate}:
+ * - **adds a layer** of `slots_x · slots_y` slots at the end of z. Nothing already placed moves, so
+ *   the old extent is copied across as it was. This is the common grow.
+ * - **widens the layer** once z is at the device's `maxTextureDimension3D`: the smaller of x and y
+ *   doubles (x on a tie, capped at the device), the layers halve, and every tile is copied to where
+ *   its slot sits under the new footprint ({@link tile_atlas_widened_footprint}). A slot keeps its
+ *   index and its texels; its *origin* changes. Rare, and as costly as a full copy.
+ *
+ * {@link capacity_limit} is where both run out: the device's limit in tiles along every axis.
+ *
+ * **Allocation reallocates the texture.** A grow replaces {@link texture}'s `GPUTexture` (the
+ * `GPUTextureContext` stays; its views are re-made), and a widen moves every tile. Take the
+ * texture, a view, the footprint or a {@link slot_origin} *after* allocating every slot a frame
+ * needs, never across an `allocate` — a frame graph that imports the texture per frame, and a
+ * shader that takes the footprint from `textureDimensions`, do this on their own.
+ *
+ * Free slots are reused most-recently-freed first; a freed slot's texels are left as they were, and
+ * move with it.
+ *
+ * Clients: the volumetrics noise atlas (`r8unorm`, 128³ + 1, sampled) and the per-geometry SDF
+ * atlas of `GPUGeometrySDFManager` (`r32float`, 50³ + 0, stored into by its build shader). Built
+ * general — format, tile size, border, footprint and usage are all constructor arguments — so a
+ * brick SDF atlas can be another instance rather than another class.
+ */
+export class GPUTileAtlas3D {
+    /**
+     * Every argument is required: an atlas is declared, not configured.
+     *
+     * @param {object} options
+     * @param {GPUDevice} options.device
+     * @param {GPUTextureFormat} options.format an uncompressed, copyable format — what a 3-D texture
+     * allows, and what {@link write} sizes its block by
+     * @param {number} options.content_size texels of content along each axis of a tile
+     * @param {number} options.border texels of skirt on each side of the content, at least 1 for a
+     * linear filter
+     * @param {number} options.slots_x tiles along x to start with; it changes only when the atlas
+     * widens
+     * @param {number} options.slots_y tiles along y to start with; it changes only when the atlas
+     * widens
+     * @param {number} options.capacity slots to allocate up front, rounded up to whole z layers of
+     * the starting footprint
+     * @param {GPUTextureUsageFlags} options.usage how the clients use the texture on the device —
+     * `TEXTURE_BINDING` to sample or load it, `STORAGE_BINDING` to store a tile from a shader. The
+     * atlas adds `COPY_DST` and `COPY_SRC` itself: {@link write}, {@link copy_from_buffer} and a grow
+     * are copies
+     * @param {string} options.label the texture's label
+     */
+    constructor({ device, format, content_size, border, slots_x, slots_y, capacity, usage, label }: {
+        device: GPUDevice;
+        format: GPUTextureFormat;
+        content_size: number;
+        border: number;
+        slots_x: number;
+        slots_y: number;
+        capacity: number;
+        usage: GPUTextureUsageFlags;
+        label: string;
+    });
+    /**
+     * @returns {GPUTextureContext}
+     */
+    get texture(): GPUTextureContext;
+    /**
+     * @returns {GPUTextureFormat}
+     */
+    get format(): GPUTextureFormat;
+    /**
+     * @returns {number}
+     */
+    get bytes_per_texel(): number;
+    /**
+     * @returns {number}
+     */
+    get content_size(): number;
+    /**
+     * @returns {number}
+     */
+    get border(): number;
+    /**
+     * Texels along each axis of a tile, skirt included.
+     * @returns {number}
+     */
+    get tile_size(): number;
+    /**
+     * Tiles along x now; a widen may double it.
+     * @returns {number}
+     */
+    get slots_x(): number;
+    /**
+     * Tiles along y now; a widen may double it.
+     * @returns {number}
+     */
+    get slots_y(): number;
+    /**
+     * Layers of slots along z: one more on each grow, halved by a widen.
+     * @returns {number}
+     */
+    get slots_z(): number;
+    /**
+     * Slots the texture holds now, live or not.
+     * @returns {number}
+     */
+    get capacity(): number;
+    /**
+     * The most slots this atlas can ever hold on this device: as many tiles along each of x, y and z
+     * as fit under `maxTextureDimension3D`, x and y reached by widening. A limit of texture
+     * dimensions, not of memory — a device may refuse the texture long before.
+     * @returns {number}
+     */
+    get capacity_limit(): number;
+    /**
+     * @returns {number}
+     */
+    get live_count(): number;
+    /**
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    is_live(slot: number): boolean;
+    /**
+     * Hand out a slot. When none is free the texture grows by a layer, or widens when z is full —
+     * after which every tile's origin may have moved.
+     *
+     * @returns {number} the slot
+     */
+    allocate(): number;
+    /**
+     * @param {number} slot
+     */
+    free(slot: number): void;
+    /**
+     * Texel origin of a slot's tile — the corner of its skirt, not of its content — under the
+     * footprint as it is now.
+     *
+     * @param {number} slot
+     * @param {number[]|Uint32Array} out receives x, y, z
+     * @returns {number[]|Uint32Array} out
+     */
+    slot_origin(slot: number, out: number[] | Uint32Array): number[] | Uint32Array;
+    /**
+     * Put content into a slot from the host: the skirt is built here and the whole tile is sent in
+     * one `writeTexture`.
+     *
+     * @param {number} slot a live slot
+     * @param {Uint8Array} content `content_size³ · bytes_per_texel` bytes, x fastest, then y, then z
+     */
+    write(slot: number, content: Uint8Array): void;
+    /**
+     * Put a whole tile, skirt included, into a slot from a buffer on the device — the way a compute
+     * bake lands: it writes the `tile_size³` block into a storage buffer, rows padded to the copy
+     * alignment, and this copies it across in the same command stream.
+     *
+     * @param {GPUCommandEncoder} encoder
+     * @param {number} slot a live slot
+     * @param {GPUBuffer} buffer
+     * @param {number} byte_offset where the block starts in the buffer
+     * @param {number} bytes_per_row stride of a row of `tile_size` texels, a multiple of
+     * `COPY_BYTES_PER_ROW_ALIGNMENT`; rows per image is the tile size
+     */
+    copy_from_buffer(encoder: GPUCommandEncoder, slot: number, buffer: GPUBuffer, byte_offset: number, bytes_per_row: number): void;
+    destroy(): void;
+    #private;
+}
+import { GPUTextureContext } from "../GPUTextureContext.js";
+//# sourceMappingURL=GPUTileAtlas3D.d.ts.map

package/src/shade/renderer/texture/atlas/GPUTileAtlas3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUTileAtlas3D.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/atlas/GPUTileAtlas3D.js"],"names":[],"mappings":"AAijBA;;;;;;;;GAQG;AACH,2CANW,MAAM,WACN,MAAM,WACN,MAAM,OACN,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,EAAE,GAAC,WAAW,CAchC;AAED;;;;;;;;;;GAUG;AACH,sDANW,MAAM,WACN,MAAM,cACN,MAAM,OACN,MAAM,EAAE,GACN,OAAO,CAuBnB;AAED;;;;;;;;;;;;;GAaG;AACH,mDAPW,UAAU,gBACV,MAAM,UACN,MAAM,mBACN,MAAM,OACN,UAAU,GACR,UAAU,CAwCtB;AA1pBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;IA0EI;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QAlB8B,MAAM;QACC,MAAM;QAEhB,YAAY,EAA5B,MAAM;QACU,MAAM,EAAtB,MAAM;QAEU,OAAO,EAAvB,MAAM;QAEU,OAAO,EAAvB,MAAM;QAEU,QAAQ,EAAxB,MAAM;QAEwB,KAAK;QAInB,KAAK,EAArB,MAAM;OA4DhB;IAED;;OAEG;IACH,iCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,qBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;OAKG;IACH,6BAIC;IAED;;OAEG;IACH,yBAEC;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;;OAKG;IACH,YAFa,MAAM,CAkBlB;IAED;;OAEG;IACH,WAFW,MAAM,QAOhB;IAED;;;;;;;OAOG;IACH,kBAJW,MAAM,OACN,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,EAAE,GAAC,WAAW,CAehC;IAED;;;;;;OAMG;IACH,YAHW,MAAM,WACN,UAAU,QA4BpB;IAED;;;;;;;;;;;OAWG;IACH,mDANW,MAAM,kCAEN,MAAM,iBACN,MAAM,QA2BhB;IAED,gBAEC;;CA0HJ;kCA7iBiC,yBAAyB"}