@woosh/meep-engine 3.64.1 → 3.65.0

package/src/shade/renderer/grass/surface/GRASS_SURFACE.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Grass surfaces on the device: the constants every pass over them shares.
+ *
+ * A grass surface is a group of mesh instances with one frame (a `transforms` row). Its ground is sampled
+ * into **surfels** on a lattice in that frame: columns along the frame's up axis, a spacing apart, each
+ * holding the ground the column meets (`chunk_grass_surfel`). A surface has **levels**, level `l` at
+ * `2^l` times the finest spacing, and each level is cut into square **tiles** of
+ * {@link GRASS_TILE_COLUMNS} columns a side. A column can meet ground more than once (a hilltop over a
+ * cave floor), so a tile has **layers**: layer `k` holds each column's `k`-th ground from the top.
+ *
+ * One layer of one tile is what is baked and kept: {@link GRASS_TILE_SURFELS} surfels in a **slot** of a
+ * pool every surface shares. A slot is a tile of the surfel atlas (a `GPUTileAtlas2D` of tiles
+ * {@link GRASS_TILE_COLUMNS} texels a side) and a record of {@link GRASS_SLOT_WORDS} words saying which
+ * layer of which tile of which surface it holds.
+ *
+ * **A slot's life.** A view's ask takes a free slot for a layer it wants and finds none for
+ * ({@link GRASS_SLOT_STATE_PENDING}), the frame's bake fills it ({@link GRASS_SLOT_STATE_BAKED}), and every
+ * later ask stamps it with the frame. Ground that changes under it makes it
+ * {@link GRASS_SLOT_STATE_STALE} until it is baked again. A slot no view has asked for since the frame
+ * before can be evicted, and is only when the pool is short of free slots, the longest unasked first
+ * (`chunk_age_eviction`); where the slots in use fill the pool, an ask starves and the pool grows.
+ */
+/**
+ * Columns along a side of a tile. A tile's layer is baked by one workgroup, a thread a column, so the
+ * square of this is the workgroup's size.
+ *
+ * @type {number}
+ */
+export const GRASS_TILE_COLUMNS: number;
+/**
+ * Surfels in one layer of one tile, and threads in the workgroup that bakes it.
+ *
+ * @type {number}
+ */
+export const GRASS_TILE_SURFELS: number;
+/**
+ * Faces a column's walk crosses before it stops, kept or not. A thread's loop bound: each crossing is one
+ * walk of the scene's TLAS and of the geometry it lands in. Ground under more faces than this is not
+ * found.
+ *
+ * @type {number}
+ */
+export const GRASS_COLUMN_CROSSINGS: number;
+/**
+ * Words in a slot's record.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_WORDS: number;
+/**
+ * Slot record word: the `transforms` row of the surface the slot's tile belongs to.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_SURFACE: number;
+/**
+ * Slot record word: the tile's level in the low byte, the layer the slot holds in the next.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_LEVEL_LAYER: number;
+/**
+ * Slot record word: the tile's place along the frame's x axis, in tiles of its level; a signed integer's bits.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_TILE_X: number;
+/**
+ * Slot record word: the tile's place along the frame's z axis, in tiles of its level; a signed integer's bits.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_TILE_Z: number;
+/**
+ * Slot record word: one of the `GRASS_SLOT_STATE_*`.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE: number;
+/**
+ * Slot record word: the last frame a view asked for the slot's tile.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_WANTED_FRAME: number;
+/**
+ * Slot record word: the most ground any column of the tile met, counted by the bake. A tile has this
+ * many layers; ones past the slot's own are other slots.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_LAYER_COUNT: number;
+/**
+ * Slot record word: how many of the slot's columns hold a surfel, counted by the bake.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_SURFEL_COUNT: number;
+/**
+ * Slot record word: the lowest height of any of the slot's surfels, as `grass_height_key` orders heights
+ * (`chunk_grass_slot`); the highest key there is while the slot holds none.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_HEIGHT_MIN: number;
+/**
+ * Slot record word: the highest height of any of the slot's surfels, as a `grass_height_key`; zero while
+ * the slot holds none.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_HEIGHT_MAX: number;
+/**
+ * Slot record word: how far the slot's surfels' normals stray from the frame's up axis, the bits of a
+ * `f32`: the greatest length of `normal - up` among them, 0 for level ground and at most 2.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_NORMAL_SPREAD: number;
+/**
+ * The slot holds nothing and is on the free stack.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_FREE: number;
+/**
+ * The slot is taken for a tile's layer that is not baked yet: its surfels are not to be read.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_PENDING: number;
+/**
+ * The slot's surfels are its tile's layer.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_BAKED: number;
+/**
+ * The slot was taken for a tile's layer but could not be listed in the directory: nothing finds it, and
+ * the next retire puts it back on the free stack.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_ORPHAN: number;
+/**
+ * The slot's surfels are its tile's layer as it was, and can be read, but a member of its surface has
+ * come, gone or moved over it since: it is baked again, in place, when a view next asks for it.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_STALE: number;
+/**
+ * Words at the front of the pool's arena, ahead of the slot records: the pool's own counters. Slot `s`'s
+ * record starts at word `GRASS_POOL_HEADER_WORDS + s * GRASS_SLOT_WORDS`.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_HEADER_WORDS: number;
+/**
+ * Pool arena word: how many slots the free stack holds (`chunk_slot_stack`'s count).
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_FREE_COUNT: number;
+/**
+ * Pool arena word: how many asks for a tile's layer have been turned away because no slot was free, since
+ * the pool was made. It only rises; a pool grows when it has.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_STARVED: number;
+/**
+ * Pool arena word: how many layers of tiles have been baked since the pool was made.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_BAKED: number;
+/**
+ * Pool arena word: how many slots the frame's retire has evicted of the bucket its plan takes some of.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_EVICTED: number;
+/**
+ * Pool arena word: the eviction plan's whole buckets (`age_eviction_plan`'s x), written by a frame's
+ * schedule for the next frame's retire.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_EVICT_BUCKETS: number;
+/**
+ * Pool arena word: the eviction plan's count of the bucket below the whole ones (`age_eviction_plan`'s y).
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_EVICT_REMAINING: number;
+/**
+ * Pool arena word: how many records have been removed from the directory since the pool was made. It
+ * only rises; the directory is rebuilt when enough have gone since its last rebuild.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_REMOVED: number;
+/**
+ * Pool arena word: the first of `AGE_EVICTION_BUCKETS` counts, the slots the frame's retire kept and
+ * could have evicted, by the bucket of the frames since a view last asked for them.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_AGES: number;
+//# sourceMappingURL=GRASS_SURFACE.d.ts.map

package/src/shade/renderer/grass/surface/GRASS_SURFACE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GRASS_SURFACE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/grass/surface/GRASS_SURFACE.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;GAKG;AACH,iCAFU,MAAM,CAEqB;AAErC;;;;GAIG;AACH,iCAFU,MAAM,CAE0D;AAE1E;;;;;;GAMG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;;GAIG;AACH,+BAFU,MAAM,CAEmB;AAEnC;;;;GAIG;AACH,iCAFU,MAAM,CAEoB;AAEpC;;;;GAIG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;;GAIG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;GAIG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;GAIG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;GAIG;AACH,sCAFU,MAAM,CAEyB;AAEzC;;;;;GAKG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;;GAIG;AACH,sCAFU,MAAM,CAEyB;AAEzC;;;;;GAKG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;;;GAKG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;;;GAKG;AACH,uCAFU,MAAM,CAE2B;AAE3C;;;;GAIG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;;GAIG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;;GAIG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;;;GAKG;AACH,sCAFU,MAAM,CAEyB;AAEzC;;;;;GAKG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;;;GAKG;AACH,sCAFU,MAAM,CAEgD;AAEhE;;;;GAIG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;;;GAKG;AACH,iCAFU,MAAM,CAEoB;AAEpC;;;;GAIG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;GAIG;AACH,iCAFU,MAAM,CAEoB;AAEpC;;;;;GAKG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;;GAIG;AACH,yCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,iCAFU,MAAM,CAEoB;AAEpC;;;;;GAKG;AACH,8BAFU,MAAM,CAEiB"}

package/src/shade/renderer/grass/surface/GRASS_SURFACE.js

@@ -0,0 +1,241 @@
+import { AGE_EVICTION_BUCKETS } from "../../gpu_primitive/age_eviction/chunk_age_eviction.js";
+
+/**
+ * Grass surfaces on the device: the constants every pass over them shares.
+ *
+ * A grass surface is a group of mesh instances with one frame (a `transforms` row). Its ground is sampled
+ * into **surfels** on a lattice in that frame: columns along the frame's up axis, a spacing apart, each
+ * holding the ground the column meets (`chunk_grass_surfel`). A surface has **levels**, level `l` at
+ * `2^l` times the finest spacing, and each level is cut into square **tiles** of
+ * {@link GRASS_TILE_COLUMNS} columns a side. A column can meet ground more than once (a hilltop over a
+ * cave floor), so a tile has **layers**: layer `k` holds each column's `k`-th ground from the top.
+ *
+ * One layer of one tile is what is baked and kept: {@link GRASS_TILE_SURFELS} surfels in a **slot** of a
+ * pool every surface shares. A slot is a tile of the surfel atlas (a `GPUTileAtlas2D` of tiles
+ * {@link GRASS_TILE_COLUMNS} texels a side) and a record of {@link GRASS_SLOT_WORDS} words saying which
+ * layer of which tile of which surface it holds.
+ *
+ * **A slot's life.** A view's ask takes a free slot for a layer it wants and finds none for
+ * ({@link GRASS_SLOT_STATE_PENDING}), the frame's bake fills it ({@link GRASS_SLOT_STATE_BAKED}), and every
+ * later ask stamps it with the frame. Ground that changes under it makes it
+ * {@link GRASS_SLOT_STATE_STALE} until it is baked again. A slot no view has asked for since the frame
+ * before can be evicted, and is only when the pool is short of free slots, the longest unasked first
+ * (`chunk_age_eviction`); where the slots in use fill the pool, an ask starves and the pool grows.
+ */
+
+/**
+ * Columns along a side of a tile. A tile's layer is baked by one workgroup, a thread a column, so the
+ * square of this is the workgroup's size.
+ *
+ * @type {number}
+ */
+export const GRASS_TILE_COLUMNS = 16;
+
+/**
+ * Surfels in one layer of one tile, and threads in the workgroup that bakes it.
+ *
+ * @type {number}
+ */
+export const GRASS_TILE_SURFELS = GRASS_TILE_COLUMNS * GRASS_TILE_COLUMNS;
+
+/**
+ * Faces a column's walk crosses before it stops, kept or not. A thread's loop bound: each crossing is one
+ * walk of the scene's TLAS and of the geometry it lands in. Ground under more faces than this is not
+ * found.
+ *
+ * @type {number}
+ */
+export const GRASS_COLUMN_CROSSINGS = 8;
+
+/**
+ * Words in a slot's record.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_WORDS = 12;
+
+/**
+ * Slot record word: the `transforms` row of the surface the slot's tile belongs to.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_SURFACE = 0;
+
+/**
+ * Slot record word: the tile's level in the low byte, the layer the slot holds in the next.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_LEVEL_LAYER = 1;
+
+/**
+ * Slot record word: the tile's place along the frame's x axis, in tiles of its level; a signed integer's bits.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_TILE_X = 2;
+
+/**
+ * Slot record word: the tile's place along the frame's z axis, in tiles of its level; a signed integer's bits.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_TILE_Z = 3;
+
+/**
+ * Slot record word: one of the `GRASS_SLOT_STATE_*`.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE = 4;
+
+/**
+ * Slot record word: the last frame a view asked for the slot's tile.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_WANTED_FRAME = 5;
+
+/**
+ * Slot record word: the most ground any column of the tile met, counted by the bake. A tile has this
+ * many layers; ones past the slot's own are other slots.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_LAYER_COUNT = 6;
+
+/**
+ * Slot record word: how many of the slot's columns hold a surfel, counted by the bake.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_SURFEL_COUNT = 7;
+
+/**
+ * Slot record word: the lowest height of any of the slot's surfels, as `grass_height_key` orders heights
+ * (`chunk_grass_slot`); the highest key there is while the slot holds none.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_HEIGHT_MIN = 8;
+
+/**
+ * Slot record word: the highest height of any of the slot's surfels, as a `grass_height_key`; zero while
+ * the slot holds none.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_HEIGHT_MAX = 9;
+
+/**
+ * Slot record word: how far the slot's surfels' normals stray from the frame's up axis, the bits of a
+ * `f32`: the greatest length of `normal - up` among them, 0 for level ground and at most 2.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_NORMAL_SPREAD = 10;
+
+/**
+ * The slot holds nothing and is on the free stack.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_FREE = 0;
+
+/**
+ * The slot is taken for a tile's layer that is not baked yet: its surfels are not to be read.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_PENDING = 1;
+
+/**
+ * The slot's surfels are its tile's layer.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_BAKED = 2;
+
+/**
+ * The slot was taken for a tile's layer but could not be listed in the directory: nothing finds it, and
+ * the next retire puts it back on the free stack.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_ORPHAN = 3;
+
+/**
+ * The slot's surfels are its tile's layer as it was, and can be read, but a member of its surface has
+ * come, gone or moved over it since: it is baked again, in place, when a view next asks for it.
+ *
+ * @type {number}
+ */
+export const GRASS_SLOT_STATE_STALE = 4;
+
+/**
+ * Words at the front of the pool's arena, ahead of the slot records: the pool's own counters. Slot `s`'s
+ * record starts at word `GRASS_POOL_HEADER_WORDS + s * GRASS_SLOT_WORDS`.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_HEADER_WORDS = 8 + AGE_EVICTION_BUCKETS;
+
+/**
+ * Pool arena word: how many slots the free stack holds (`chunk_slot_stack`'s count).
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_FREE_COUNT = 0;
+
+/**
+ * Pool arena word: how many asks for a tile's layer have been turned away because no slot was free, since
+ * the pool was made. It only rises; a pool grows when it has.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_STARVED = 1;
+
+/**
+ * Pool arena word: how many layers of tiles have been baked since the pool was made.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_BAKED = 2;
+
+/**
+ * Pool arena word: how many slots the frame's retire has evicted of the bucket its plan takes some of.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_EVICTED = 3;
+
+/**
+ * Pool arena word: the eviction plan's whole buckets (`age_eviction_plan`'s x), written by a frame's
+ * schedule for the next frame's retire.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_EVICT_BUCKETS = 4;
+
+/**
+ * Pool arena word: the eviction plan's count of the bucket below the whole ones (`age_eviction_plan`'s y).
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_EVICT_REMAINING = 5;
+
+/**
+ * Pool arena word: how many records have been removed from the directory since the pool was made. It
+ * only rises; the directory is rebuilt when enough have gone since its last rebuild.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_REMOVED = 6;
+
+/**
+ * Pool arena word: the first of `AGE_EVICTION_BUCKETS` counts, the slots the frame's retire kept and
+ * could have evicted, by the bucket of the frames since a view last asked for them.
+ *
+ * @type {number}
+ */
+export const GRASS_POOL_AGES = 8;

package/src/shade/renderer/grass/surface/GRASS_SURFACE_VIEW.d.ts

@@ -0,0 +1,82 @@
+/**
+ * How many levels a view asks a surface for: enough that the coarsest in use reaches the distance where
+ * the tallest blade spans `shortest_blade` pixels, each level reaching twice as far as the one below.
+ *
+ * Level 0 reaches `finest_spacing * focal / narrowest_blade` and a blade is drawn out to
+ * `blade_length * focal / shortest_blade`, so the focal length cancels: the count follows the blade, the
+ * spacing and the two pixel tolerances alone.
+ *
+ * @param {number} blade_length the tallest blade of any surface, world units; positive
+ * @param {number} finest_spacing positive
+ * @param {number} narrowest_blade pixels, positive
+ * @param {number} shortest_blade pixels, positive
+ * @returns {number} at least 1
+ */
+export function grass_surface_level_count(blade_length: number, finest_spacing: number, narrowest_blade: number, shortest_blade: number): number;
+/**
+ * A grass surface as the passes that ask for its tiles read it. Records sit packed from 0 in the
+ * `grass_surfaces` buffer, in no order.
+ *
+ * - `node`: the surface's `transforms` row. Its frame is that row's position and rotation; the row's scale
+ *   is not part of the frame, so a frame's units are the world's.
+ * - `blade_length`: the tallest blade that grows on any of its members, in world units. It sets how far
+ *   from a view the surface's tiles are wanted.
+ * - `low`, `high`: a box in the frame that holds every member.
+ *
+ * 48 bytes.
+ *
+ * @type {WebGPUStruct}
+ */
+export const GRASS_SURFACE_RECORD_STRUCT: WebGPUStruct;
+/**
+ * Words in a {@link GRASS_SURFACE_RECORD_STRUCT}, and the words its fields start at.
+ */
+export const GRASS_SURFACE_RECORD_WORDS: 12;
+export const GRASS_SURFACE_RECORD_NODE: 0;
+export const GRASS_SURFACE_RECORD_BLADE_LENGTH: 1;
+export const GRASS_SURFACE_RECORD_LOW: 4;
+export const GRASS_SURFACE_RECORD_HIGH: 8;
+/**
+ * The `grass_surfaces` buffer, as its readers declare it.
+ *
+ * @type {ShaderResourceDescriptor}
+ */
+export const GRASS_SURFACES_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The pool's arena (`GRASS_SURFACE.js`), as the passes that write it declare it: its counters, then a
+ * record a slot.
+ *
+ * @type {ShaderResourceDescriptor}
+ */
+export const GRASS_POOL_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The pool's directory, a `chunk_hash_table_atomic` table at offset 0, as the passes that look tiles up
+ * in it declare it.
+ *
+ * @type {ShaderResourceDescriptor}
+ */
+export const GRASS_DIRECTORY_RESOURCE: ShaderResourceDescriptor;
+/**
+ * What a view asks of the grass surfaces, as an immediate of the passes that ask.
+ *
+ * - `finest_spacing`: the distance between neighbouring columns of level 0, in world units.
+ * - `focal`: the view's focal length in pixels of its render resolution: what a unit at a distance of one
+ *   unit spans.
+ * - `narrowest_blade`: the least width a blade is drawn at, in pixels. A level serves the distances at which
+ *   its spacing spans no more than this.
+ * - `shortest_blade`: the least length a blade is drawn at, in pixels. Past the distance where a surface's
+ *   tallest blade spans less, none of its tiles are wanted.
+ * - `frame`: the frame's number, which a wanted tile is stamped with.
+ * - `level_count`: how many levels a surface is asked for, 0 the finest.
+ * - `surface_count`: how many records `grass_surfaces` holds.
+ * - `job_capacity`: how many layers of tiles may be taken for baking this frame.
+ * - `slot_capacity`: how many slots the pool has.
+ * - `canopy_opacity`: how many blades a view ray may cross before the grass behind them is left out.
+ * - `blade_capacity`: how many blades the frame's blade list has room for.
+ *
+ * @type {WebGPUStruct}
+ */
+export const GRASS_SURFACE_VIEW_SETTINGS: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+//# sourceMappingURL=GRASS_SURFACE_VIEW.d.ts.map

package/src/shade/renderer/grass/surface/GRASS_SURFACE_VIEW.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GRASS_SURFACE_VIEW.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/grass/surface/GRASS_SURFACE_VIEW.js"],"names":[],"mappings":"AA4FA;;;;;;;;;;;;;GAaG;AACH,wDANW,MAAM,kBACN,MAAM,mBACN,MAAM,kBACN,MAAM,GACJ,MAAM,CAMlB;AAzGD;;;;;;;;;;;;;GAaG;AACH,0CAFU,YAAY,CAOG;AAEzB;;GAEG;AACH,4CAA6C;AAC7C,0CAA2C;AAC3C,kDAAmD;AACnD,yCAA0C;AAC1C,0CAA2C;AAE3C;;;;GAIG;AACH,sCAFU,wBAAwB,CAE6G;AAE/I;;;;;GAKG;AACH,kCAFU,wBAAwB,CAE0F;AAE5H;;;;;GAKG;AACH,uCAFU,wBAAwB,CAEoG;AAEtI;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0CAFU,YAAY,CAcS;6BAvFF,mCAAmC;yCAHvB,mDAAmD"}

package/src/shade/renderer/grass/surface/GRASS_SURFACE_VIEW.js

@@ -0,0 +1,111 @@
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { atomic_u32, f32, u32, vec3f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * A grass surface as the passes that ask for its tiles read it. Records sit packed from 0 in the
+ * `grass_surfaces` buffer, in no order.
+ *
+ * - `node`: the surface's `transforms` row. Its frame is that row's position and rotation; the row's scale
+ *   is not part of the frame, so a frame's units are the world's.
+ * - `blade_length`: the tallest blade that grows on any of its members, in world units. It sets how far
+ *   from a view the surface's tiles are wanted.
+ * - `low`, `high`: a box in the frame that holds every member.
+ *
+ * 48 bytes.
+ *
+ * @type {WebGPUStruct}
+ */
+export const GRASS_SURFACE_RECORD_STRUCT = WebGPUStruct.from({
+    node: u32,
+    blade_length: f32,
+    low: vec3f,
+    high: vec3f,
+}, "GrassSurfaceRecord");
+
+/**
+ * Words in a {@link GRASS_SURFACE_RECORD_STRUCT}, and the words its fields start at.
+ */
+export const GRASS_SURFACE_RECORD_WORDS = 12;
+export const GRASS_SURFACE_RECORD_NODE = 0;
+export const GRASS_SURFACE_RECORD_BLADE_LENGTH = 1;
+export const GRASS_SURFACE_RECORD_LOW = 4;
+export const GRASS_SURFACE_RECORD_HIGH = 8;
+
+/**
+ * The `grass_surfaces` buffer, as its readers declare it.
+ *
+ * @type {ShaderResourceDescriptor}
+ */
+export const GRASS_SURFACES_RESOURCE = ShaderResourceDescriptor.storageBuffer("grass_surfaces", WebGPUArray.from(GRASS_SURFACE_RECORD_STRUCT));
+
+/**
+ * The pool's arena (`GRASS_SURFACE.js`), as the passes that write it declare it: its counters, then a
+ * record a slot.
+ *
+ * @type {ShaderResourceDescriptor}
+ */
+export const GRASS_POOL_RESOURCE = ShaderResourceDescriptor.storageBuffer("grass_pool", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * The pool's directory, a `chunk_hash_table_atomic` table at offset 0, as the passes that look tiles up
+ * in it declare it.
+ *
+ * @type {ShaderResourceDescriptor}
+ */
+export const GRASS_DIRECTORY_RESOURCE = ShaderResourceDescriptor.storageBuffer("grass_directory", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * What a view asks of the grass surfaces, as an immediate of the passes that ask.
+ *
+ * - `finest_spacing`: the distance between neighbouring columns of level 0, in world units.
+ * - `focal`: the view's focal length in pixels of its render resolution: what a unit at a distance of one
+ *   unit spans.
+ * - `narrowest_blade`: the least width a blade is drawn at, in pixels. A level serves the distances at which
+ *   its spacing spans no more than this.
+ * - `shortest_blade`: the least length a blade is drawn at, in pixels. Past the distance where a surface's
+ *   tallest blade spans less, none of its tiles are wanted.
+ * - `frame`: the frame's number, which a wanted tile is stamped with.
+ * - `level_count`: how many levels a surface is asked for, 0 the finest.
+ * - `surface_count`: how many records `grass_surfaces` holds.
+ * - `job_capacity`: how many layers of tiles may be taken for baking this frame.
+ * - `slot_capacity`: how many slots the pool has.
+ * - `canopy_opacity`: how many blades a view ray may cross before the grass behind them is left out.
+ * - `blade_capacity`: how many blades the frame's blade list has room for.
+ *
+ * @type {WebGPUStruct}
+ */
+export const GRASS_SURFACE_VIEW_SETTINGS = WebGPUStruct.from({
+    finest_spacing: f32,
+    focal: f32,
+    narrowest_blade: f32,
+    shortest_blade: f32,
+    frame: u32,
+    level_count: u32,
+    surface_count: u32,
+    job_capacity: u32,
+    slot_capacity: u32,
+    canopy_opacity: f32,
+    blade_capacity: u32,
+}, "GrassSurfaceViewSettings");
+
+/**
+ * How many levels a view asks a surface for: enough that the coarsest in use reaches the distance where
+ * the tallest blade spans `shortest_blade` pixels, each level reaching twice as far as the one below.
+ *
+ * Level 0 reaches `finest_spacing * focal / narrowest_blade` and a blade is drawn out to
+ * `blade_length * focal / shortest_blade`, so the focal length cancels: the count follows the blade, the
+ * spacing and the two pixel tolerances alone.
+ *
+ * @param {number} blade_length the tallest blade of any surface, world units; positive
+ * @param {number} finest_spacing positive
+ * @param {number} narrowest_blade pixels, positive
+ * @param {number} shortest_blade pixels, positive
+ * @returns {number} at least 1
+ */
+export function grass_surface_level_count(blade_length, finest_spacing, narrowest_blade, shortest_blade) {
+    const reach_in_finest_reaches = (blade_length * narrowest_blade) / (shortest_blade * finest_spacing);
+
+    return Math.max(1, Math.ceil(Math.log2(reach_in_finest_reaches)) + 1);
+}

package/src/shade/renderer/grass/surface/chunk_grass_column_cross.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Clear height of ground under open sky: the largest finite half float, which is how a surfel stores it.
+ * Any stored clear height at or above this means nothing stands over the surfel.
+ * @type {number}
+ */
+export const GRASS_CLEAR_HEIGHT_OPEN: number;
+/**
+ * One step of a walk down a column of a grass surface, from above the surface's members to below them.
+ *
+ * A column crosses the faces of its surface's members in order of falling height. Each crossing is either
+ * an upward face (ground a blade could stand on) or a downward one (an underside: a ceiling, the bottom of
+ * something resting there). What the column crossed just before a crossing decides what it is:
+ *
+ * - nothing: the crossing is under open sky;
+ * - a downward face: the crossing is in open air under it, and the gap between them is its clear height;
+ * - an upward face: the crossing is inside the member that face tops, where nothing grows.
+ *
+ * ```wgsl
+ * fn grass_column_begin() -> GrassColumnWalk
+ * fn grass_column_cross(walk: GrassColumnWalk, height: f32, faces_up: bool) -> GrassColumnCrossing
+ * ```
+ *
+ * `grass_column_cross` takes the walk as it stood before the crossing and answers with:
+ *
+ * - `keep`: the crossing is ground to keep, an upward face that is not inside a member;
+ * - `clear_height`: for a kept crossing, the height of open air over it, `GRASS_CLEAR_HEIGHT_OPEN` under
+ *   open sky; never negative;
+ * - `walk`: the walk after the crossing, to hand to the next one.
+ *
+ * Heights are along the surface frame's up axis and must not rise from one crossing to the next.
+ *
+ * Which way a face points is read from its winding, so ground under a one-sided sheet reads as inside it:
+ * a cave needs its ceiling modelled.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_grass_column_cross: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_grass_column_cross.d.ts.map