@woosh/meep-engine 3.68.0 → 3.69.0

package/src/shade/renderer/trails/shaders/shader_trail_update.js

@@ -0,0 +1,101 @@
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { TRAIL_DESCRIPTOR, TRAIL_STATE_DESCRIPTOR } from "../data/TRAIL_DATABASE_SPEC.js";
+import { chunk_trail_update } from "./chunk_trail_update.js";
+
+/**
+ * Threads per workgroup; one trail row each. The page iterator wants a multiple of 32.
+ * @type {number}
+ */
+export const TRAIL_UPDATE_WORKGROUP_SIZE = 64;
+
+const PG = TRAIL_DESCRIPTOR.page_iterator_symbol_prefix(TRAIL_UPDATE_WORKGROUP_SIZE, true);
+const STATE = TRAIL_STATE_DESCRIPTOR;
+
+export const TRAIL_UPDATE_SETTINGS = WebGPUStruct.from({
+    /** the clock, in ticks */
+    now: u32,
+    /** element capacity of the trail table: the length of the counts list the scan reads */
+    capacity: u32,
+}, "Trail3DUpdateSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", TRAIL_UPDATE_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("trail_database", WebGPUArray.u32, true)
+    .addStorageBuffer("scene_database", WebGPUArray.u32, false)
+    .addStorageBuffer("knots", WebGPUArray.u32, true)
+    .addStorageBuffer("live_segments", COLLECTION_U32_STRUCT_READ, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${TRAIL_UPDATE_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg_id : vec3<u32>,
+    @builtin(local_invocation_index) local_id : u32,
+) {
+    // the scan reads exactly this many counts; written before the page test so it lands even when the
+    // first page is unallocated
+    if (wg_id.x == 0u && local_id == 0u) {
+        live_segments.count = settings.capacity;
+    }
+
+    if (!${PG}_setup(&trail_database, wg_id.x, local_id)) {
+        return;
+    }
+
+    let slot = ${PG}_slot_in_page(local_id);
+
+    if (slot >= ${PG}_ELEMENTS_PER_PAGE || !${PG}_is_occupied(slot)) {
+        return;
+    }
+
+    let record = ${PG}_read(&trail_database, slot);
+    let row = ${PG}_slot_to_index(slot);
+
+    var state = ${STATE.marshalling_method_read_rw}(&trail_database, row);
+
+    if (state.seeded_epoch != record.seed_epoch) {
+        // a seed has been asked for and not run yet: nothing to draw until it has
+        live_segments.elements[row] = 0u;
+        return;
+    }
+
+    let head = trail_head_world(scene_read_node(&scene_database, record.node).global, record.offset);
+
+    live_segments.elements[row] = trail_update(record, &state, head, settings.now);
+
+    ${STATE.marshalling_method_write}(&trail_database, row, state);
+}
+`, [
+    TRAIL_DESCRIPTOR.chunk_iterate(TRAIL_UPDATE_WORKGROUP_SIZE, true),
+    STATE.chunk_read_rw,
+    STATE.chunk_write,
+    chunk_scene_database_access,
+    chunk_trail_update,
+]);
+
+/**
+ * One frame of every trail: a thread per row of the trail table, through the table's page iterator.
+ * Each reads its entity's world matrix from the scene database — the hierarchy has composed this
+ * frame's — runs `trail_update`, writes its state back, and writes how many of its segments can be
+ * visible into `live_segments`, the list the scan sums.
+ *
+ * A row whose state has not been seeded for its record's epoch writes zero and waits for its seed.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_trail_update = ComputeShader.from({
+    label: "Trail Update",
+    resources,
+    body,
+});

package/src/engine/graphics/ecs/trail3d/advance_trail.d.ts

@@ -1,18 +0,0 @@
-/**
- * Age a trail by one frame and put its head where the entity is.
- *
- * **Renderer-neutral**, like {@link seed_trail_tube}: what a backend does afterwards is turn the
- * knots into vertices, and the knots themselves are the same either way.
- *
- * {@link Trail3DFlags.BoundsNeedUpdate} is left set for the caller, because what wants bounds
- * differs by renderer — the legacy path keeps a CPU BVH of trails and Shade culls on the GPU.
- *
- * @param {Trail3D} trail
- * @param {Transform} transform
- * @param {number} timeDelta seconds
- * @param {TubeXFixedPhysicsSimulator} simulator ages the knots and fades them; stateless, so whose
- * it is does not matter, only that the caller owns one
- * @returns {void}
- */
-export function advance_trail(trail: Trail3D, transform: Transform, timeDelta: number, simulator: TubeXFixedPhysicsSimulator): void;
-//# sourceMappingURL=advance_trail.d.ts.map

package/src/engine/graphics/ecs/trail3d/advance_trail.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"advance_trail.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/advance_trail.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;GAeG;AACH,+EALW,MAAM,0CAGJ,IAAI,CAiBhB"}

package/src/engine/graphics/ecs/trail3d/advance_trail.js

@@ -1,42 +0,0 @@
-import Vector3 from "../../../../core/geom/Vector3.js";
-import { max2 } from "../../../../core/math/max2.js";
-import { compute_trail_head_position } from "./trail_head_position.js";
-import { Trail3DFlags } from "./Trail3DFlags.js";
-
-/**
- * @type {Vector3}
- */
-const v3_head = new Vector3();
-
-/**
- * Age a trail by one frame and put its head where the entity is.
- *
- * **Renderer-neutral**, like {@link seed_trail_tube}: what a backend does afterwards is turn the
- * knots into vertices, and the knots themselves are the same either way.
- *
- * {@link Trail3DFlags.BoundsNeedUpdate} is left set for the caller, because what wants bounds
- * differs by renderer — the legacy path keeps a CPU BVH of trails and Shade culls on the GPU.
- *
- * @param {Trail3D} trail
- * @param {Transform} transform
- * @param {number} timeDelta seconds
- * @param {TubeXFixedPhysicsSimulator} simulator ages the knots and fades them; stateless, so whose
- * it is does not matter, only that the caller owns one
- * @returns {void}
- */
-export function advance_trail(trail, transform, timeDelta, simulator) {
-    const tube = trail.tube;
-
-    compute_trail_head_position(v3_head, trail, transform);
-
-    trail.timeSinceLastUpdate += timeDelta;
-    trail.time += timeDelta;
-
-    const age_offset = max2(0, trail.maxAge - trail.time);
-
-    simulator.update(tube, trail.maxAge, timeDelta, trail.color.w, trail.fade);
-
-    if (trail.getFlag(Trail3DFlags.Spawning)) {
-        trail.updateHead(v3_head.x, v3_head.y, v3_head.z, age_offset);
-    }
-}

package/src/engine/graphics/ecs/trail3d/seed_trail_tube.d.ts

@@ -1,14 +0,0 @@
-/**
- * Build a trail's knots and collapse them onto the head, ready to be drawn by whichever renderer
- * owns the entity.
- *
- * **Renderer-neutral on purpose.** A trail is a simulation with a picture attached, and the
- * simulation is the same one under either backend — what differs is only what the knots are turned
- * into. Two copies of this would be two trails that age differently.
- *
- * @param {Trail3D} trail
- * @param {Transform} transform
- * @returns {void}
- */
-export function seed_trail_tube(trail: Trail3D, transform: Transform): void;
-//# sourceMappingURL=seed_trail_tube.d.ts.map

package/src/engine/graphics/ecs/trail3d/seed_trail_tube.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"seed_trail_tube.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/seed_trail_tube.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;GAWG;AACH,uEAFa,IAAI,CAwChB"}

package/src/engine/graphics/ecs/trail3d/seed_trail_tube.js

@@ -1,75 +0,0 @@
-import Vector3 from "../../../../core/geom/Vector3.js";
-import { clamp } from "../../../../core/math/clamp.js";
-import { TUBE_ATTRIBUTE_ADDRESS_AGE, TUBE_ATTRIBUTE_ADDRESS_UV_V } from "../../trail/tube/tube_attributes_spec.js";
-import { compute_trail_head_position } from "./trail_head_position.js";
-import { Trail3DFlags } from "./Trail3DFlags.js";
-
-/**
- * Knots laid down per second of trail life. The tube is a fixed-capacity ring, so this is what
- * turns an age into a length.
- *
- * @type {number}
- */
-const SEGMENTS_PER_SECOND = 60;
-
-/**
- * @type {number}
- */
-const MAX_SEGMENTS = 1024;
-
-/**
- * @type {Vector3}
- */
-const v3_head = new Vector3();
-
-/**
- * Build a trail's knots and collapse them onto the head, ready to be drawn by whichever renderer
- * owns the entity.
- *
- * **Renderer-neutral on purpose.** A trail is a simulation with a picture attached, and the
- * simulation is the same one under either backend — what differs is only what the knots are turned
- * into. Two copies of this would be two trails that age differently.
- *
- * @param {Trail3D} trail
- * @param {Transform} transform
- * @returns {void}
- */
-export function seed_trail_tube(trail, transform) {
-    const segment_count = Math.ceil(clamp(trail.maxAge * SEGMENTS_PER_SECOND, 2, MAX_SEGMENTS));
-
-    trail.build(segment_count);
-
-    const tube = trail.tube;
-
-    trail.time = 0;
-    trail.trailingIndex = 0;
-    trail.timeSinceLastUpdate = 0;
-    trail.distanceSinceLastUpdate = 0;
-
-    // seed exactly where the per-frame update will place the head, or the first head move bridges
-    // the gap with a visible segment
-    compute_trail_head_position(v3_head, trail, transform);
-
-    const position_x = v3_head.x;
-    const position_y = v3_head.y;
-    const position_z = v3_head.z;
-
-    const color = trail.color;
-
-    // initialize knots. setCount has already seeded a valid default frame on every knot, so the
-    // freshly built (collapsed) tube is well-formed — a zero-length, invisible point — until the
-    // head starts moving and supplies real tangents.
-    for (let i = 0; i < segment_count; i++) {
-        const f = i / (segment_count - 1);
-
-        tube.setKnotColor(i, color.x, color.y, color.z);
-        tube.setKnotPosition(i, position_x, position_y, position_z);
-        tube.setKnotThickness(i, trail.width);
-        tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, f);
-        // seeded age = maxAge means "already expired", so alpha follows the fade law: 0
-        tube.setKnotAlpha(i, 0);
-        tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_AGE, trail.maxAge);
-    }
-
-    trail.setFlag(Trail3DFlags.Built);
-}

package/src/engine/graphics/ecs/trail3d/trail_head_position.d.ts

@@ -1,17 +0,0 @@
-/**
- * World point the trail's head tracks: the component's {@link Trail3D#offset}, which lives in the
- * entity's LOCAL frame, carried through the entity's full transform — so it rides the entity's
- * rotation and scales with it.
- *
- * Seeding and the per-frame head update must agree on this, whichever renderer is drawing. If they
- * disagree, the freshly built tube sits collapsed somewhere the head never visits, and the head's
- * first move draws a segment bridging the two — a one-frame streak as long as the disagreement, in
- * a direction fixed by the offset rather than by travel.
- *
- * @param {Vector3} result
- * @param {Trail3D} trail
- * @param {Transform} transform
- * @returns {void}
- */
-export function compute_trail_head_position(result: Vector3, trail: Trail3D, transform: Transform): void;
-//# sourceMappingURL=trail_head_position.d.ts.map

package/src/engine/graphics/ecs/trail3d/trail_head_position.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"trail_head_position.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/trail3d/trail_head_position.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,oGAFa,IAAI,CAKhB"}

package/src/engine/graphics/ecs/trail3d/trail_head_position.js

@@ -1,19 +0,0 @@
-/**
- * World point the trail's head tracks: the component's {@link Trail3D#offset}, which lives in the
- * entity's LOCAL frame, carried through the entity's full transform — so it rides the entity's
- * rotation and scales with it.
- *
- * Seeding and the per-frame head update must agree on this, whichever renderer is drawing. If they
- * disagree, the freshly built tube sits collapsed somewhere the head never visits, and the head's
- * first move draws a segment bridging the two — a one-frame streak as long as the disagreement, in
- * a direction fixed by the offset rather than by travel.
- *
- * @param {Vector3} result
- * @param {Trail3D} trail
- * @param {Transform} transform
- * @returns {void}
- */
-export function compute_trail_head_position(result, trail, transform) {
-    result.copy(trail.offset);
-    result.applyMatrix4(transform.matrix);
-}

package/src/engine/graphics/trail/tube/TubeX.d.ts

@@ -1,186 +0,0 @@
-/**
- * Dynamic, non-allocating 3D tube geometry — the volumetric analogue of
- * {@link RibbonX}.
- *
- * A tube is a ring buffer of `count` KNOTS along a centre-line. Each knot owns a
- * ring of `radial + 1` vertices: the extra vertex duplicates vertex 0 so the UV
- * seam (u = 0 meeting u = 1) closes cleanly when the texture wraps the tube.
- * Vertices are extruded in the vertex shader from the knot's stored tangent
- * frame, so the CPU only ever writes per-knot data (centre, frame, colour, …) —
- * never per-triangle.
- *
- * Like {@link RibbonX} the geometry is a fixed-capacity ring: {@link rotate}
- * recycles the oldest knot as the new head and rewrites a single segment's worth
- * of indices, so steady-state updates allocate nothing.
- *
- * **The knots are the tube; a drawable is what a renderer makes of them.** Nothing
- * here belongs to a renderer: {@link TubeXGeometry} wraps this data in three
- * attribute views for the legacy path, and the Shade path extrudes the same rows
- * into dynamic-mesh vertices. The three versions below are what tells either one
- * that its copy is stale.
- */
-export class TubeX {
-    /**
-     * The knot rows, interleaved per {@link tube_attributes_spec} — `vertex_count`
-     * records of `bytes_per_vertex` bytes, one per ring vertex.
-     *
-     * @returns {RowFirstTable}
-     */
-    get table(): RowFirstTable;
-    /**
-     * Triangle indices over the ring vertices, sized by {@link setCount} and
-     * rewritten one segment at a time by {@link rotate}.
-     *
-     * @returns {Uint32Array}
-     */
-    get indices(): Uint32Array;
-    /**
-     * @returns {number} bytes one ring vertex occupies in {@link table}
-     */
-    get bytes_per_vertex(): number;
-    /**
-     * @returns {number} ring vertices across the whole tube — `count * (radial + 1)`
-     */
-    get vertex_count(): number;
-    /**
-     * @returns {number}
-     */
-    get data_version(): number;
-    /**
-     * @returns {number}
-     */
-    get index_version(): number;
-    /**
-     * @returns {number}
-     */
-    get layout_version(): number;
-    /**
-     * @returns {number} number of knots
-     */
-    getCount(): number;
-    /**
-     * @returns {number} radial subdivisions
-     */
-    getRadialSegments(): number;
-    getHeadIndex(): number;
-    getTailIndex(): number;
-    /**
-     * @param {number[]|Float32Array|Float64Array} result
-     * @param {number} knot_index
-     */
-    getKnotPosition(result: number[] | Float32Array | Float64Array, knot_index: number): void;
-    /**
-     * Read the stored ring normal of a knot. Used by the head to parallel-transport
-     * its frame from the previous knot.
-     * @param {number[]|Float32Array|Float64Array} result
-     * @param {number} knot_index
-     */
-    getKnotNormal(result: number[] | Float32Array | Float64Array, knot_index: number): void;
-    /**
-     * Read the stored ring binormal of a knot.
-     * @param {number[]|Float32Array|Float64Array} result
-     * @param {number} knot_index
-     */
-    getKnotBinormal(result: number[] | Float32Array | Float64Array, knot_index: number): void;
-    /**
-     * Read a scalar attribute of a knot. Every vertex of the ring carries the same
-     * value, so the first one answers for the knot.
-     *
-     * @param {number} knot_index
-     * @param {number} attribute_index
-     * @returns {number}
-     */
-    getKnotAttribute_Scalar(knot_index: number, attribute_index: number): number;
-    /**
-     * Write a vec3 attribute to all ring vertices of a knot.
-     * @param {number} knot_index
-     * @param {number} attribute_index
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     */
-    setKnotAttribute_Vector3(knot_index: number, attribute_index: number, x: number, y: number, z: number): void;
-    /**
-     * Write a scalar attribute to all ring vertices of a knot.
-     * @param {number} knot_index
-     * @param {number} attribute_index
-     * @param {number} value
-     */
-    setKnotAttribute_Scalar(knot_index: number, attribute_index: number, value: number): void;
-    /**
-     * Add `delta` to a scalar attribute on every ring vertex of a knot.
-     * @param {number} knot_index
-     * @param {number} attribute_index
-     * @param {number} delta
-     * @returns {number} incremented value
-     */
-    incrementKnotAttribute_Scalar(knot_index: number, attribute_index: number, delta: number): number;
-    /**
-     * @param {number} knot_index
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     */
-    setKnotPosition(knot_index: number, x: number, y: number, z: number): void;
-    /**
-     * Set the orienting tangent frame of a knot. `nx,ny,nz` and `bx,by,bz` must be
-     * unit vectors, mutually orthogonal and perpendicular to the local tangent.
-     * @param {number} knot_index
-     * @param {number} nx
-     * @param {number} ny
-     * @param {number} nz
-     * @param {number} bx
-     * @param {number} by
-     * @param {number} bz
-     */
-    setKnotFrame(knot_index: number, nx: number, ny: number, nz: number, bx: number, by: number, bz: number): void;
-    /**
-     * Linear colour, stored at half precision. Not limited to 0..1: values above 1 are HDR.
-     *
-     * @param {number} knot_index
-     * @param {number} r
-     * @param {number} g
-     * @param {number} b
-     */
-    setKnotColor(knot_index: number, r: number, g: number, b: number): void;
-    /**
-     * @param {number} knot_index
-     * @param {number} value
-     */
-    setKnotAlpha(knot_index: number, value: number): void;
-    /**
-     * @param {number} knot_index
-     * @param {number} value tube diameter
-     */
-    setKnotThickness(knot_index: number, value: number): void;
-    /**
-     * @param {number} count number of knots (>= 2)
-     * @param {number} [radial] radial subdivisions (>= 3)
-     */
-    setCount(count: number, radial?: number): void;
-    /**
-     * NOTE: takes tube thickness into account.
-     * @param {AABB3|ArrayLike<number>} result
-     */
-    computeBoundingBox(result: AABB3 | ArrayLike<number>): void;
-    /**
-     * Recycle the oldest knot as the new head, in O(radial). Mirrors
-     * {@link RibbonX#rotate}: the head/tail pointers decrement together (preserving
-     * `head === (tail + 1) mod count`), and the single tail segment's indices are
-     * rewritten to bridge the previous head's ring to the recycled (new head) ring.
-     */
-    rotate(): void;
-    #private;
-}
-export namespace TubeX {
-    export { DEFAULT_RADIAL_SEGMENTS };
-}
-import { RowFirstTable } from "../../../../core/collection/table/RowFirstTable.js";
-/**
- * Default number of radial subdivisions around the tube. Overridable per-tube
- * via {@link TubeX#setCount}; never hard-coded into the geometry.
- * @type {number}
- */
-declare const DEFAULT_RADIAL_SEGMENTS: number;
-export {};
-//# sourceMappingURL=TubeX.d.ts.map

package/src/engine/graphics/trail/tube/TubeX.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"TubeX.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/TubeX.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAoEI;;;;;OAKG;IACH,2BAEC;IAED;;;;;OAKG;IACH,2BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,YAFa,MAAM,CAIlB;IAED;;OAEG;IACH,qBAFa,MAAM,CAIlB;IAED,uBAEC;IAED,uBAEC;IAiGD;;;OAGG;IACH,wBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,QAShB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,QAShB;IAED;;;;OAIG;IACH,wBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,QAShB;IAED;;;;;;;OAOG;IACH,oCAJW,MAAM,mBACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,qCANW,MAAM,mBACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAehB;IAED;;;;;OAKG;IACH,oCAJW,MAAM,mBACN,MAAM,SACN,MAAM,QAYhB;IAED;;;;;;OAMG;IACH,0CALW,MAAM,mBACN,MAAM,SACN,MAAM,GACJ,MAAM,CAgBlB;IAED;;;;;OAKG;IACH,4BALW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAMhB;IAED;;;;;;;;;;OAUG;IACH,yBARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAKhB;IAED;;;;;;;OAOG;IACH,yBALW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAMhB;IAED;;;OAGG;IACH,yBAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;OAGG;IACH,6BAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;OAGG;IACH,gBAHW,MAAM,WACN,MAAM,QAuChB;IAED;;;OAGG;IACH,2BAFW,QAAM,UAAU,MAAM,CAAC,QA4BjC;IAED;;;;;OAKG;IACH,eAsBC;;CACJ;;;;8BA3jB6B,oDAAoD;AAgBlF;;;;GAIG;AACH,uCAFU,MAAM,CAEkB"}