@woosh/meep-engine 3.67.0 → 3.69.0

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

@@ -0,0 +1,111 @@
+import { ANIMATION_CURVE_KEYFRAME_STRUCT } from "../../animation/ANIMATION_CURVE_KEYFRAME_STRUCT.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_avboit_unlit_varyings } from "../../rasterize/native/avboit/chunk_avboit_unlit_varyings.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.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 { TRAIL_STRUCT } from "../data/TRAIL_RECORD.js";
+import { chunk_trail_knot_alpha } from "./chunk_trail_knot_alpha.js";
+
+/**
+ * The frame uniform: the clock the knots' ages are counted against.
+ */
+export const TRAIL_FRAME_STRUCT = WebGPUStruct.from({
+    now: u32,
+}, "Trail3DFrame");
+
+/**
+ * What the trails' vertex stage reads, the same group in the splat and the draw: the camera, the
+ * clock, the frame's segment list, the knots, the trail and state tables and the fade keys.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
+export const TRAIL_VERTEX_GROUP = new ShaderResourceGroupDescriptor();
+
+TRAIL_VERTEX_GROUP
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addUniform("trail_frame", TRAIL_FRAME_STRUCT)
+    .addStorageBuffer("segment_list", WebGPUArray.u32, false)
+    .addStorageBuffer("knots", WebGPUArray.u32, false)
+    .addStorageBuffer("trail_database", WebGPUArray.u32, false)
+    .addStorageBuffer("fade_keys", WebGPUArray.from(ANIMATION_CURVE_KEYFRAME_STRUCT), false);
+
+/**
+ * `trail_vertex(vertex_index, instance_index) -> AVBOITUnlitVaryings`: one vertex of one segment of a
+ * trail's tube, extruded where the vertex shader runs instead of on the CPU.
+ *
+ * The instance is the segment: `segment_list[instance_index]` is its head-ward knot, and the knot
+ * names its trail, whose record and state it reads. `trail_ring_vertex(record, head, live, head_ward,
+ * vertex_index, now)` is the vertex itself: `vertex_index` runs over the two rings of `radial + 1`
+ * vertices, the head-ward ring first; the seam vertex closes each ring on its first.
+ *
+ * A ring vertex sits at its knot's centre displaced by `cos θ · normal + sin θ · binormal`, half the
+ * knot's thickness out, at `θ = 2π · r / radial`. Its colour is the trail's; its alpha is the knot's (`trail_knot_alpha`), clamped to 0..1 and
+ * split between the tube's two faces as `1 - √(1 - α)`, because a line of sight through the closed tube
+ * crosses two faces and the two together must cover `α`.
+ *
+ * The enclosing shader binds {@link TRAIL_VERTEX_GROUP}.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_trail_vertex = CodeChunk.from(
+    //language=WGSL
+    `
+const TRAIL_TWO_PI : f32 = 6.283185307179586;
+
+fn trail_vertex(vertex_index : u32, instance_index : u32) -> AVBOITUnlitVaryings {
+    let head_ward = segment_list[instance_index];
+    let row = trail_knot_read(head_ward).trail;
+
+    let record = ${TRAIL_DESCRIPTOR.marshalling_method_read}(&trail_database, row);
+    let state = ${TRAIL_STATE_DESCRIPTOR.marshalling_method_read}(&trail_database, row);
+
+    return trail_ring_vertex(record, state.head, state.live, head_ward, vertex_index, trail_frame.now);
+}
+
+fn trail_ring_vertex(
+    record : ${TRAIL_STRUCT.wgsl_ref},
+    head : u32,
+    live : u32,
+    head_ward : u32,
+    vertex_index : u32,
+    now : u32,
+) -> AVBOITUnlitVaryings {
+    let ring_size = record.radial + 1u;
+    let ring = vertex_index / ring_size;
+    let around = vertex_index % ring_size;
+
+    var address = head_ward;
+
+    if (ring != 0u) {
+        address = record.knot_base + (head_ward - record.knot_base + 1u) % record.knot_count;
+    }
+
+    let knot = trail_knot_read(address);
+
+    let alpha = clamp(trail_knot_alpha(record, head, live, address, now), 0.0, 1.0);
+
+    let angle = f32(around) / f32(record.radial) * TRAIL_TWO_PI;
+    let radial = cos(angle) * knot.normal + sin(angle) * knot.binormal;
+    let world = vec4<f32>(knot.position + radial * (knot.thickness * 0.5), 1.0);
+
+    var out : AVBOITUnlitVaryings;
+
+    out.clip = camera.view_projection_matrix * world;
+    // half the optical depth: the face behind this one carries the other half
+    out.color = vec4<f32>(record.color.rgb, 1.0 - sqrt(1.0 - alpha));
+    // the camera looks down -Z, so depth is -z
+    out.view_depth = -(camera.view_matrix * world).z;
+
+    return out;
+}
+`, [
+        chunk_avboit_unlit_varyings,
+        TRAIL_DESCRIPTOR.chunk_read,
+        TRAIL_STATE_DESCRIPTOR.chunk_read,
+        chunk_trail_knot_alpha,
+    ]
+);

package/src/shade/renderer/trails/shaders/shader_trail_avboit.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Bind group of {@link TRAIL_VERTEX_GROUP} in both trail pipelines.
+ * @type {number}
+ */
+export const TRAIL_AVBOIT_BIND_GROUP_VERTEX: number;
+/**
+ * The trails' AVBOIT splat: the tube extruded in the vertex stage (`chunk_trail_vertex`), into the unlit
+ * splat's fragment stage, the one the dynamic meshes splat through.
+ */
+export const TRAIL_AVBOIT_SPLAT_PIPELINE: import("../../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+export const TRAIL_AVBOIT_SPLAT_RESOURCES: ShaderResourceSetDescriptor;
+/** The assembled splat shader, for the validity tier. */
+export const shader_trail_avboit_splat: ShaderDescriptor;
+/**
+ * The trails' AVBOIT draw: the tube extruded in the vertex stage, into the unlit draw's fragment stage,
+ * the one the dynamic meshes draw through.
+ */
+export const TRAIL_AVBOIT_DRAW_PIPELINE: import("../../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+export const TRAIL_AVBOIT_DRAW_RESOURCES: ShaderResourceSetDescriptor;
+/** The assembled draw shader, for the validity tier. */
+export const shader_trail_avboit_draw: ShaderDescriptor;
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
+//# sourceMappingURL=shader_trail_avboit.d.ts.map

package/src/shade/renderer/trails/shaders/shader_trail_avboit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_trail_avboit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/trails/shaders/shader_trail_avboit.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,6CAFU,MAAM,CAEgC;AA0BhD;;;GAGG;AACH,6IAIG;AAEH,uEAA4D;AAE5D,yDAAyD;AACzD,yDAA0D;AAa1D;;;GAGG;AACH,4IAIG;AAEH,sEAA0D;AAE1D,wDAAwD;AACxD,wDAAwD;4CAzEZ,sDAAsD;iCACjE,kCAAkC"}

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

@@ -0,0 +1,78 @@
+import { avboit_unlit_draw_pipeline, AVBOIT_UNLIT_DRAW_PASS_GROUP, chunk_avboit_unlit_draw_fragment } from "../../rasterize/native/avboit/avboit_unlit_draw.js";
+import { avboit_unlit_splat_pipeline, AVBOIT_UNLIT_SPLAT_PASS_GROUP, chunk_avboit_unlit_splat_fragment } from "../../rasterize/native/avboit/avboit_unlit_splat.js";
+import { AVBOIT_SPLAT_VOLUME_GROUP } from "../../rasterize/native/avboit/shader_avboit_splat.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
+import { chunk_trail_vertex, TRAIL_VERTEX_GROUP } from "./chunk_trail_vertex.js";
+
+/**
+ * Bind group of {@link TRAIL_VERTEX_GROUP} in both trail pipelines.
+ * @type {number}
+ */
+export const TRAIL_AVBOIT_BIND_GROUP_VERTEX = 0;
+
+const vertex_stage = CodeChunk.from(
+    //language=WGSL
+    `
+@vertex
+fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32) -> AVBOITUnlitVaryings {
+    return trail_vertex(vi, ii);
+}
+`, [
+        chunk_trail_vertex,
+    ]
+);
+
+const splat_resources = new ShaderResourceSetDescriptor();
+
+splat_resources.addGroup(TRAIL_VERTEX_GROUP);
+splat_resources.addGroup(AVBOIT_UNLIT_SPLAT_PASS_GROUP);
+splat_resources.addGroup(AVBOIT_SPLAT_VOLUME_GROUP);
+
+const splat_descriptor = ShaderDescriptor.from({
+    label: "Trail AVBOIT Splat",
+    body: CodeChunk.from("", [vertex_stage, chunk_avboit_unlit_splat_fragment]),
+    resources: splat_resources,
+});
+
+/**
+ * The trails' AVBOIT splat: the tube extruded in the vertex stage (`chunk_trail_vertex`), into the unlit
+ * splat's fragment stage, the one the dynamic meshes splat through.
+ */
+export const TRAIL_AVBOIT_SPLAT_PIPELINE = avboit_unlit_splat_pipeline({
+    label: "Trail AVBOIT Splat",
+    resources: splat_resources,
+    source: splat_descriptor.source,
+});
+
+export const TRAIL_AVBOIT_SPLAT_RESOURCES = splat_resources;
+
+/** The assembled splat shader, for the validity tier. */
+export const shader_trail_avboit_splat = splat_descriptor;
+
+const draw_resources = new ShaderResourceSetDescriptor();
+
+draw_resources.addGroup(TRAIL_VERTEX_GROUP);
+draw_resources.addGroup(AVBOIT_UNLIT_DRAW_PASS_GROUP);
+
+const draw_descriptor = ShaderDescriptor.from({
+    label: "Trail AVBOIT Draw",
+    body: CodeChunk.from("", [vertex_stage, chunk_avboit_unlit_draw_fragment]),
+    resources: draw_resources,
+});
+
+/**
+ * The trails' AVBOIT draw: the tube extruded in the vertex stage, into the unlit draw's fragment stage,
+ * the one the dynamic meshes draw through.
+ */
+export const TRAIL_AVBOIT_DRAW_PIPELINE = avboit_unlit_draw_pipeline({
+    label: "Trail AVBOIT Draw",
+    resources: draw_resources,
+    source: draw_descriptor.source,
+});
+
+export const TRAIL_AVBOIT_DRAW_RESOURCES = draw_resources;
+
+/** The assembled draw shader, for the validity tier. */
+export const shader_trail_avboit_draw = draw_descriptor;

package/src/shade/renderer/trails/shaders/shader_trail_avboit_segments.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Threads per workgroup: the group size `shader_prefix_sum_to_command` sizes the dispatch for.
+ * @type {number}
+ */
+export const TRAIL_SEGMENTS_WORKGROUP_SIZE: number;
+export const TRAIL_SEGMENTS_SETTINGS: WebGPUStruct;
+/**
+ * The trails' AVBOIT occupancy and their draw lists, per view: a thread per live segment of every
+ * trail, its trail found by lower bound over the frame's sums of live segments.
+ *
+ * A segment whose two knots have both faded, or whose capsule — the two centres, padded by the wider
+ * ring's radius — misses the view frustum, does nothing (`trail_segment_bounds`). A visible one marks the depth slices its box
+ * spans (`aabb3_view_depth_range`, `avboit_occupancy_mark`, the arithmetic the other channels' boxes
+ * go through), and appends its head-ward knot's address to its trail's draw class's list
+ * (`subgroup_keyed_append`, one atomic per class a subgroup holds). `class_counts` starts each class's
+ * counter at the class's region of `segment_list`, so the place handed back is where to write.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_trail_avboit_segments: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_trail_avboit_segments.d.ts.map

package/src/shade/renderer/trails/shaders/shader_trail_avboit_segments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_trail_avboit_segments.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/trails/shaders/shader_trail_avboit_segments.js"],"names":[],"mappings":"AAwBA;;;GAGG;AACH,4CAFU,MAAM,CAE+D;AAE/E,mDAK8B;AA6E9B;;;;;;;;;;;;GAYG;AACH,2CAFU,aAAa,CAMpB;6BA7G0B,mCAAmC;8BAJlC,+BAA+B"}

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

@@ -0,0 +1,130 @@
+import { ANIMATION_CURVE_KEYFRAME_STRUCT } from "../../animation/ANIMATION_CURVE_KEYFRAME_STRUCT.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { AVBOIT_OCCUPANCY_WORDS } from "../../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
+import { chunk_avboit_occupancy_mark } from "../../rasterize/native/avboit/chunk_avboit_occupancy_mark.js";
+import { AABB3_STRUCT } from "../../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
+import { chunk_aabb3_intersects_frustum } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_intersects_frustum.js";
+import { chunk_aabb3_view_depth_range } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_view_depth_range.js";
+import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_lower_bound_branchless } from "../../shader/chunk/math/chunk_lower_bound_branchless.js";
+import {
+    chunk_subgroup_keyed_append,
+    SUBGROUP_KEYED_APPEND_NONE
+} from "../../shader/chunk/subgroup/chunk_subgroup_keyed_append.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32, vec3f } 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_segment } from "./chunk_trail_segment.js";
+
+/**
+ * Threads per workgroup: the group size `shader_prefix_sum_to_command` sizes the dispatch for.
+ * @type {number}
+ */
+export const TRAIL_SEGMENTS_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
+
+export const TRAIL_SEGMENTS_SETTINGS = WebGPUStruct.from({
+    /** the frame's AVBOIT depth curve */
+    cluster_parameters: vec3f,
+    /** the clock, in ticks */
+    now: u32,
+}, "Trail3DSegmentsSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", TRAIL_SEGMENTS_SETTINGS);
+
+resources.createGroup()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer("trail_database", WebGPUArray.u32, false)
+    .addStorageBuffer("knots", WebGPUArray.u32, false)
+    .addStorageBuffer("fade_keys", WebGPUArray.from(ANIMATION_CURVE_KEYFRAME_STRUCT), false)
+    .addStorageBuffer("segment_sums", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("class_counts", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("segment_list", WebGPUArray.u32, true)
+    .addStorageBuffer("occupancy", WebGPUArray.from(atomic_u32, AVBOIT_OCCUPANCY_WORDS), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${TRAIL_SEGMENTS_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg_id : vec3<u32>,
+    @builtin(local_invocation_index) local_id : u32,
+) {
+    let i = folded_workgroup_index(wg_id) * ${TRAIL_SEGMENTS_WORKGROUP_SIZE}u + local_id;
+    let rows = segment_sums.count;
+
+    // every lane reaches the append below; one with no visible segment appends nothing
+    var key = ${SUBGROUP_KEYED_APPEND_NONE}u;
+    var address = 0u;
+
+    if (rows > 0u && i < segment_sums.elements[rows - 1u]) {
+        let row = lower_bound_branchless(&segment_sums.elements, i + 1u, rows);
+
+        var first = 0u;
+
+        if (row > 0u) {
+            first = segment_sums.elements[row - 1u];
+        }
+
+        let segment = i - first;
+
+        let record = ${TRAIL_DESCRIPTOR.marshalling_method_read}(&trail_database, row);
+        let state = ${TRAIL_STATE_DESCRIPTOR.marshalling_method_read}(&trail_database, row);
+
+        var box : ${AABB3_STRUCT.wgsl_ref};
+
+        if (trail_segment_bounds(record, state.head, state.live, segment, settings.now, &box)
+            && aabb3_intersects_frustum(box, camera.frustum)) {
+            let range = aabb3_view_depth_range(box, camera.view_matrix);
+
+            avboit_occupancy_mark(range.x, range.y, camera.clip_near_far.x, settings.cluster_parameters);
+
+            key = record.draw_class;
+            address = trail_knot_address(record, state.head, segment);
+        }
+    }
+
+    let place = subgroup_keyed_append(&class_counts, key);
+
+    if (key != ${SUBGROUP_KEYED_APPEND_NONE}u) {
+        segment_list[place] = address;
+    }
+}
+`, [
+    TRAIL_DESCRIPTOR.chunk_read,
+    TRAIL_STATE_DESCRIPTOR.chunk_read,
+    AABB3_STRUCT.declaration_chunk,
+    chunk_aabb3_intersects_frustum,
+    chunk_aabb3_view_depth_range,
+    chunk_avboit_occupancy_mark,
+    chunk_folded_workgroup_index,
+    chunk_lower_bound_branchless,
+    chunk_subgroup_keyed_append,
+    chunk_trail_segment,
+]);
+
+/**
+ * The trails' AVBOIT occupancy and their draw lists, per view: a thread per live segment of every
+ * trail, its trail found by lower bound over the frame's sums of live segments.
+ *
+ * A segment whose two knots have both faded, or whose capsule — the two centres, padded by the wider
+ * ring's radius — misses the view frustum, does nothing (`trail_segment_bounds`). A visible one marks the depth slices its box
+ * spans (`aabb3_view_depth_range`, `avboit_occupancy_mark`, the arithmetic the other channels' boxes
+ * go through), and appends its head-ward knot's address to its trail's draw class's list
+ * (`subgroup_keyed_append`, one atomic per class a subgroup holds). `class_counts` starts each class's
+ * counter at the class's region of `segment_list`, so the place handed back is where to write.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_trail_avboit_segments = ComputeShader.from({
+    label: "Trail AVBOIT Segments",
+    resources,
+    body,
+});

package/src/shade/renderer/trails/shaders/shader_trail_draw_args.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Words of one indexed indirect draw: index count, instance count, first index, base vertex, first
+ * instance — `drawIndexedIndirect`'s layout.
+ * @type {number}
+ */
+export const TRAIL_DRAW_ARGS_WORDS: number;
+/**
+ * Threads per workgroup; one draw class each.
+ * @type {number}
+ */
+export const TRAIL_DRAW_ARGS_WORKGROUP_SIZE: number;
+/**
+ * One draw class as the args pass reads it: its radial count and where its region of the segment list
+ * starts.
+ */
+export const TRAIL_DRAW_CLASS_STRUCT: WebGPUStruct;
+export const TRAIL_DRAW_ARGS_SETTINGS: WebGPUStruct;
+/**
+ * The trails' indexed indirect draws, one per draw class: `6 × radial` indices from the class's static
+ * index buffer, an instance per segment the segments pass appended to the class's list, and the
+ * instances starting at the class's region of that list (`first_instance`). Written by a pass of its
+ * own, so the render passes that draw through it bind it read-only.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_trail_draw_args: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_trail_draw_args.d.ts.map

package/src/shade/renderer/trails/shaders/shader_trail_draw_args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_trail_draw_args.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/trails/shaders/shader_trail_draw_args.js"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,mDAGuB;AAEvB,oDAE8B;AAkC9B;;;;;;;GAOG;AACH,qCAFU,aAAa,CAMpB;6BAxE0B,mCAAmC;8BAJlC,+BAA+B"}

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

@@ -0,0 +1,78 @@
+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";
+
+/**
+ * Words of one indexed indirect draw: index count, instance count, first index, base vertex, first
+ * instance — `drawIndexedIndirect`'s layout.
+ * @type {number}
+ */
+export const TRAIL_DRAW_ARGS_WORDS = 5;
+
+/**
+ * Threads per workgroup; one draw class each.
+ * @type {number}
+ */
+export const TRAIL_DRAW_ARGS_WORKGROUP_SIZE = 64;
+
+/**
+ * One draw class as the args pass reads it: its radial count and where its region of the segment list
+ * starts.
+ */
+export const TRAIL_DRAW_CLASS_STRUCT = WebGPUStruct.from({
+    radial: u32,
+    region: u32,
+}, "Trail3DDrawClass");
+
+export const TRAIL_DRAW_ARGS_SETTINGS = WebGPUStruct.from({
+    class_count: u32,
+}, "Trail3DDrawArgsSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", TRAIL_DRAW_ARGS_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("class_counts", WebGPUArray.u32, false)
+    .addStorageBuffer("classes", WebGPUArray.from(TRAIL_DRAW_CLASS_STRUCT), false)
+    .addStorageBuffer("args", WebGPUArray.u32, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${TRAIL_DRAW_ARGS_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) id : vec3<u32>) {
+    let c = id.x;
+
+    if (c >= settings.class_count) {
+        return;
+    }
+
+    let draw_class = classes[c];
+    let at = c * ${TRAIL_DRAW_ARGS_WORDS}u;
+
+    // a segment is an instance: the indices of two rings, the instances the segments pass appended
+    args[at] = 6u * draw_class.radial;
+    args[at + 1u] = class_counts[c] - draw_class.region;
+    args[at + 2u] = 0u;
+    args[at + 3u] = 0u;
+    args[at + 4u] = draw_class.region;
+}
+`);
+
+/**
+ * The trails' indexed indirect draws, one per draw class: `6 × radial` indices from the class's static
+ * index buffer, an instance per segment the segments pass appended to the class's list, and the
+ * instances starting at the class's region of that list (`first_instance`). Written by a pass of its
+ * own, so the render passes that draw through it bind it read-only.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_trail_draw_args = ComputeShader.from({
+    label: "Trail Draw Args",
+    resources,
+    body,
+});

package/src/shade/renderer/trails/shaders/shader_trail_seed.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Threads per workgroup; a workgroup seeds one trail, each thread a stride of its knots. A ring of
+ * 1,024 knots is 16 a thread.
+ * @type {number}
+ */
+export const TRAIL_SEED_WORKGROUP_SIZE: number;
+export const TRAIL_SEED_SETTINGS: WebGPUStruct;
+/**
+ * Seed the trails asked for this frame: a workgroup per row of `seeds`, each thread a stride of the
+ * trail's knots (`trail_seed_knot`), then its state (`trail_seed_state`), every knot collapsed onto the
+ * head where the first update will put it (`trail_head_world`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_trail_seed: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_trail_seed.d.ts.map

package/src/shade/renderer/trails/shaders/shader_trail_seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_trail_seed.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/trails/shaders/shader_trail_seed.js"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,wCAFU,MAAM,CAE4B;AAE5C,+CAG0B;AA+C1B;;;;;;GAMG;AACH,gCAFU,aAAa,CAMpB;6BAxE0B,mCAAmC;8BAJlC,+BAA+B"}

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

@@ -0,0 +1,79 @@
+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_seed } from "./chunk_trail_seed.js";
+
+/**
+ * Threads per workgroup; a workgroup seeds one trail, each thread a stride of its knots. A ring of
+ * 1,024 knots is 16 a thread.
+ * @type {number}
+ */
+export const TRAIL_SEED_WORKGROUP_SIZE = 64;
+
+export const TRAIL_SEED_SETTINGS = WebGPUStruct.from({
+    /** the clock, in ticks */
+    now: u32,
+}, "Trail3DSeedSettings");
+
+const STATE = TRAIL_STATE_DESCRIPTOR;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", TRAIL_SEED_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("trail_database", WebGPUArray.u32, true)
+    .addStorageBuffer("scene_database", WebGPUArray.u32, false)
+    .addStorageBuffer("knots", WebGPUArray.u32, true)
+    .addStorageBuffer("seeds", WebGPUArray.u32, false);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${TRAIL_SEED_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg_id : vec3<u32>,
+    @builtin(local_invocation_index) local_id : u32,
+) {
+    let row = seeds[wg_id.x];
+    let record = ${TRAIL_DESCRIPTOR.marshalling_method_read_rw}(&trail_database, row);
+
+    let head = trail_head_world(scene_read_node(&scene_database, record.node).global, record.offset);
+
+    for (var i = local_id; i < record.knot_count; i = i + ${TRAIL_SEED_WORKGROUP_SIZE}u) {
+        trail_seed_knot(record, row, i, head, settings.now);
+    }
+
+    if (local_id == 0u) {
+        var state = ${STATE.marshalling_method_read_rw}(&trail_database, row);
+
+        trail_seed_state(record, &state, settings.now);
+
+        ${STATE.marshalling_method_write}(&trail_database, row, state);
+    }
+}
+`, [
+    TRAIL_DESCRIPTOR.chunk_read_rw,
+    STATE.chunk_read_rw,
+    STATE.chunk_write,
+    chunk_scene_database_access,
+    chunk_trail_seed,
+]);
+
+/**
+ * Seed the trails asked for this frame: a workgroup per row of `seeds`, each thread a stride of the
+ * trail's knots (`trail_seed_knot`), then its state (`trail_seed_state`), every knot collapsed onto the
+ * head where the first update will put it (`trail_head_world`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_trail_seed = ComputeShader.from({
+    label: "Trail Seed",
+    resources,
+    body,
+});

package/src/shade/renderer/trails/shaders/shader_trail_update.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Threads per workgroup; one trail row each. The page iterator wants a multiple of 32.
+ * @type {number}
+ */
+export const TRAIL_UPDATE_WORKGROUP_SIZE: number;
+export const TRAIL_UPDATE_SETTINGS: WebGPUStruct;
+/**
+ * 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;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_trail_update.d.ts.map

package/src/shade/renderer/trails/shaders/shader_trail_update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_trail_update.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/trails/shaders/shader_trail_update.js"],"names":[],"mappings":"AAWA;;;GAGG;AACH,0CAFU,MAAM,CAE8B;AAK9C,iDAK4B;AA6D5B;;;;;;;;;GASG;AACH,kCAFU,aAAa,CAMpB;6BA7F0B,mCAAmC;8BAJlC,+BAA+B"}