@woosh/meep-engine 3.60.3 → 3.60.5

package/src/engine/graphics3/decal/graph_gather_decal_tiles.js

@@ -0,0 +1,70 @@
+import { assert } from "../../../core/assert.js";
+import { BufferResourceDescriptor } from "../../../shade/device/graph/BufferResourceDescriptor.js";
+import { STRUCT_UNINDEXED_DRAW_COMMAND } from "../../../shade/renderer/gpu_primitive/indirect/STRUCT_UNINDEXED_DRAW_COMMAND.js";
+import { build_indirect_draw_command } from "../../../shade/renderer/gpu_primitive/indirect/build_indirect_draw_command.js";
+import { u32 } from "../../../shade/renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { DECAL_CLUSTER_TILE_RESOLUTION } from "./DECAL_CLUSTER.js";
+import { shader_gather_decal_tiles } from "./shader_gather_decal_tiles.js";
+
+/**
+ * Two triangles per tile, one instance per tile, the instance count read off the tile list's head.
+ *
+ * @type {string}
+ */
+const DRAW_COMMAND_PATTERN = "6u, input, 0u, 0u";
+
+/**
+ * List the screen tiles that hold a decal, and the draw command a `DecalTileShader` draws them with.
+ *
+ * The list holds every tile of the screen at worst, so it never drops one; what it costs to draw
+ * follows the count the gather wrote, through the command. The command has a buffer of its own, as
+ * an indirect argument may not be bound writable in the scope it is used in.
+ *
+ * @param {object} args
+ * @param {FrameGraph} args.graph
+ * @param {number} args.cluster_lookup handle of the decal froxels' lookup
+ * @param {number[]} args.resolution
+ * @returns {{tiles: number, command: number}}
+ */
+export function graph_gather_decal_tiles({ graph, cluster_lookup, resolution }) {
+    assert.isNonNegativeInteger(cluster_lookup, 'cluster_lookup');
+    assert.isArrayLike(resolution, 'resolution');
+
+    const tile_count_x = Math.ceil(resolution[0] / DECAL_CLUSTER_TILE_RESOLUTION);
+    const tile_count_y = Math.ceil(resolution[1] / DECAL_CLUSTER_TILE_RESOLUTION);
+
+    const data = {};
+
+    const pass = graph.add("decal tiles / gather", data, (data, resources, context) => {
+        const encoder = context.encoder;
+        const tiles = resources.get(data.tiles);
+
+        shader_gather_decal_tiles.dispatchThreads({
+            encoder,
+            bindings: {
+                settings: { screen_resolution: resolution },
+                cluster_lookup: resources.get(data.cluster_lookup),
+                decal_tiles: tiles,
+            },
+            thread_count_x: tile_count_x,
+            thread_count_y: tile_count_y,
+        });
+
+        build_indirect_draw_command(encoder.device, DRAW_COMMAND_PATTERN, encoder, tiles, resources.get(data.command));
+    });
+
+    data.cluster_lookup = pass.read(cluster_lookup);
+
+    data.tiles = pass.create("decal tiles", BufferResourceDescriptor.from(
+        u32.size * (1 + tile_count_x * tile_count_y),
+        GPUBufferUsage.STORAGE,
+        0, u32.size, // clear the count
+    ));
+
+    data.command = pass.create("decal tiles / draw command", BufferResourceDescriptor.from(
+        STRUCT_UNINDEXED_DRAW_COMMAND.aligned_size,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+    ));
+
+    return { tiles: data.tiles, command: data.command };
+}

package/src/engine/graphics3/decal/shader_decal_composite.d.ts

@@ -1,18 +1,20 @@
 export const DECAL_COMPOSITE_SETTINGS: WebGPUStruct;
 /**
- * Reads the G-buffer, paints this frame's decals into it, and writes a new one.
+ * Paints this frame's decals into the G-buffer, in place, over the screen tiles that hold one.
  *
  * **Every channel is composited exactly, in registers.** Nothing is blended by hardware and nothing
  * is approximated: two of the four targets are integer formats that cannot blend at all, and the
  * previous shading normal and the ambient in the albedo's alpha both have to survive — which they
- * only can if the pass reads one texture and writes another (D23).
+ * only can if the pass reads one texture and writes another (D23). The one it reads is
+ * `shader_decal_tile_copy`'s copy of the same tiles, so only the covered part of the screen
+ * is read and written twice, rather than all of it once.
  *
  * The face normal is carried through untouched. A decal changes what a surface looks like, not which
  * way it is turned, and the face normal is what the fade and everything downstream reason about.
  *
- * @type {ImageShader}
+ * @type {DecalTileShader}
  */
-export const shader_decal_composite: ImageShader;
+export const shader_decal_composite: DecalTileShader;
 import { WebGPUStruct } from "../../../shade/renderer/shader/type/WebGPUStruct.js";
-import { ImageShader } from "../../../shade/renderer/shader/ImageShader.js";
+import { DecalTileShader } from "./DecalTileShader.js";
 //# sourceMappingURL=shader_decal_composite.d.ts.map

package/src/engine/graphics3/decal/shader_decal_composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_decal_composite.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_decal_composite.js"],"names":[],"mappings":"AAgEA,oDAKG;AAySH;;;;;;;;;;;;GAYG;AACH,qCAFU,WAAW,CAclB;6BA1V0B,qDAAqD;4BAPtD,+CAA+C"}
+{"version":3,"file":"shader_decal_composite.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_decal_composite.js"],"names":[],"mappings":"AAgEA,oDAKG;AA2SH;;;;;;;;;;;;;;GAcG;AACH,qCAFU,eAAe,CActB;6BA9V0B,qDAAqD;gCARlD,sBAAsB"}

package/src/engine/graphics3/decal/shader_decal_composite.js

@@ -1,5 +1,5 @@
-import { CAMERA_UNIFORM_STRUCT } from "../../../shade/renderer/camera/CAMERA_UNIFORM_STRUCT.js";
-import { VIEW_UNIFORM_STRUCT } from "../../../shade/renderer/view/VIEW_UNIFORM_STRUCT.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../../shade/renderer/camera/CAMERA_UNIFORM_STRUCT.js";
+import { VIEW_UNIFORM_STRUCT } from "../../../shade/renderer/view/VIEW_UNIFORM_STRUCT.js";
 import { chunk_view_mip_bias } from "../../../shade/renderer/view/chunk_view_mip_bias.js";
 import { G_BUFFER_ALBEDO_FORMAT } from "../../../shade/renderer/gbuffer/G_BUFFER_ALBEDO_FORMAT.js";
 import {
@@ -35,8 +35,8 @@ import {
 } from "../../../shade/renderer/shader/chunk/texture/GRADIENT_SAMPLING_INFO_STRUCT.js";
 import { chunk_decal_sampling_info } from "./chunk_decal_sampling_info.js";
 import { chunk_decal_surface_frame } from "./chunk_decal_surface_frame.js";
+import { DecalTileShader } from "./DecalTileShader.js";
 import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
-import { ImageShader } from "../../../shade/renderer/shader/ImageShader.js";
 import {
     ShaderResourceSetDescriptor
 } from "../../../shade/renderer/shader/resource/ShaderResourceSetDescriptor.js";
@@ -75,7 +75,7 @@ const resources = new ShaderResourceSetDescriptor();
 resources.setImmediate("settings", DECAL_COMPOSITE_SETTINGS);
 
 resources.createGroup()
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
     .addUniform("view", VIEW_UNIFORM_STRUCT);
 
 /*
@@ -93,7 +93,8 @@ resources.createGroup()
 resources.createGroup()
     .addStorageBuffer("decal_data", WebGPUArray.f32)
     .addStorageBuffer("cluster_lookup", WebGPUArray.from(DECAL_CLUSTER_METADATA))
-    .addStorageBuffer("cluster_data", WebGPUArray.u32);
+    .addStorageBuffer("cluster_data", WebGPUArray.u32)
+    .addStorageBuffer("decal_tiles", WebGPUArray.u32);
 
 /*
  The three atlases are **filterable**, which is not the default a texture binding gets. Every one of
@@ -153,10 +154,11 @@ fn main(
     let old_emissive = textureLoad(gBufferEmissive, i_coord, 0).r;
 
     /*
-     Every pixel is written, covered or not. The targets are fresh textures this pass hands
-     downstream in place of the ones it read, so a pixel left alone here is not "unchanged" — it is
-     undefined. Reading and writing the whole frame is the price of being able to composite exactly
-     rather than through a blend the integer targets cannot do.
+     Every pixel this pass is drawn over is written, covered or not: the draw replaces what the
+     target held, and what it held is exactly what was read, so a pixel no decal touches is written
+     back unchanged. The inputs are a copy of the same texels taken by the pass before — one texture
+     cannot be attached and sampled at once — which is what lets the composite be exact rather than
+     a blend the integer targets cannot do.
     */
     var out : DecalCompositeOut;
 
@@ -179,34 +181,6 @@ fn main(
 
     let position = project_position_from_depth(uv, depth, camera.view_projection_matrix_inverse);
 
-    let shading_normal = decode_g_buffer_normal(old_normal.xy);
-    let face_normal = decode_g_buffer_normal(old_normal.zw);
-
-    /*
-     Screen-space world gradients, taken analytically off the surface rather than from 'dpdx'.
-
-     Two reasons, and the first is that there is no choice: sampling inside a loop over a per-pixel
-     decal list is non-uniform control flow, where WGSL forbids implicit derivatives — the same
-     constraint that made the material pass interpolate its own from barycentrics. The second is
-     that it is better anyway. A hardware derivative reads whatever the neighbouring pixel hit, so
-     it lies across every silhouette; intersecting the neighbouring pixel's ray with *this* surface's
-     plane answers the question actually being asked, which is how fast the decal's texture moves
-     across the surface it is painted on.
-    */
-    let ray_here = normalize(project_position_from_depth(uv, 0.5, camera.view_projection_matrix_inverse) - camera_position);
-    let ray_x = normalize(project_position_from_depth(uv + vec2<f32>(1.0 / resolution.x, 0.0), 0.5, camera.view_projection_matrix_inverse) - camera_position);
-    let ray_y = normalize(project_position_from_depth(uv + vec2<f32>(0.0, 1.0 / resolution.y), 0.5, camera.view_projection_matrix_inverse) - camera_position);
-
-    let plane_distance = dot(position - camera_position, face_normal);
-
-    let denominator_x = dot(ray_x, face_normal);
-    let denominator_y = dot(ray_y, face_normal);
-
-    // grazing angles send these toward zero and the gradient toward infinity; the per-decal LOD
-    // clamp is what keeps that finite, so nothing here needs to guard it
-    let position_x = camera_position + ray_x * (plane_distance / denominator_x);
-    let position_y = camera_position + ray_y * (plane_distance / denominator_y);
-
     let view_forward = -normalize(camera.view_matrix_inverse[2].xyz);
     let view_depth = dot(position - camera_position, view_forward);
 
@@ -232,10 +206,38 @@ fn main(
 
     let metadata = cluster_lookup[cluster_index];
 
+    // most pixels of a tile sit in a slice with no decal; they leave before any of the work below
     if (metadata.count == 0u) {
         return out;
     }
 
+    let shading_normal = decode_g_buffer_normal(old_normal.xy);
+    let face_normal = decode_g_buffer_normal(old_normal.zw);
+
+    /*
+     Screen-space world gradients, taken analytically off the surface rather than from 'dpdx'.
+
+     Two reasons, and the first is that there is no choice: sampling inside a loop over a per-pixel
+     decal list is non-uniform control flow, where WGSL forbids implicit derivatives — the same
+     constraint that made the material pass interpolate its own from barycentrics. The second is
+     that it is better anyway. A hardware derivative reads whatever the neighbouring pixel hit, so
+     it lies across every silhouette; intersecting the neighbouring pixel's ray with *this* surface's
+     plane answers the question actually being asked, which is how fast the decal's texture moves
+     across the surface it is painted on.
+    */
+    let ray_x = normalize(project_position_from_depth(uv + vec2<f32>(1.0 / resolution.x, 0.0), 0.5, camera.view_projection_matrix_inverse) - camera_position);
+    let ray_y = normalize(project_position_from_depth(uv + vec2<f32>(0.0, 1.0 / resolution.y), 0.5, camera.view_projection_matrix_inverse) - camera_position);
+
+    let plane_distance = dot(position - camera_position, face_normal);
+
+    let denominator_x = dot(ray_x, face_normal);
+    let denominator_y = dot(ray_y, face_normal);
+
+    // grazing angles send these toward zero and the gradient toward infinity; the per-decal LOD
+    // clamp is what keeps that finite, so nothing here needs to guard it
+    let position_x = camera_position + ray_x * (plane_distance / denominator_x);
+    let position_y = camera_position + ray_y * (plane_distance / denominator_y);
+
     let atlas_albedo_size = vec2<f32>(textureDimensions(atlas_albedo, 0));
     let atlas_normal_size = vec2<f32>(textureDimensions(atlas_normal, 0));
     let atlas_orm_size = vec2<f32>(textureDimensions(atlas_orm, 0));
@@ -246,8 +248,8 @@ fn main(
     var normal = shading_normal;
     var emissive = rgbe9995_decode(old_emissive);
 
-    let uv_bias = view_uv_derivative_bias(view.upscale_ratio);
-
+    let uv_bias = view_uv_derivative_bias(view.upscale_ratio);
+
     for (var i = 0u; i < metadata.count; i++) {
         let decal_index = cluster_data[metadata.offset + i];
 
@@ -359,25 +361,27 @@ fn main(
         chunk_rgbe9995_encode,
         chunk_light_cluster_resolution_xy_from_screen,
         chunk_cluster_depth_to_z_slice,
-        chunk_grid3d_to_index,
+        chunk_grid3d_to_index,
         chunk_view_mip_bias
     ]
 );
 
 /**
- * Reads the G-buffer, paints this frame's decals into it, and writes a new one.
+ * Paints this frame's decals into the G-buffer, in place, over the screen tiles that hold one.
  *
  * **Every channel is composited exactly, in registers.** Nothing is blended by hardware and nothing
  * is approximated: two of the four targets are integer formats that cannot blend at all, and the
  * previous shading normal and the ambient in the albedo's alpha both have to survive — which they
- * only can if the pass reads one texture and writes another (D23).
+ * only can if the pass reads one texture and writes another (D23). The one it reads is
+ * `shader_decal_tile_copy`'s copy of the same tiles, so only the covered part of the screen
+ * is read and written twice, rather than all of it once.
  *
  * The face normal is carried through untouched. A decal changes what a surface looks like, not which
  * way it is turned, and the face normal is what the fade and everything downstream reason about.
  *
- * @type {ImageShader}
+ * @type {DecalTileShader}
  */
-export const shader_decal_composite = ImageShader.from({
+export const shader_decal_composite = new DecalTileShader({
     descriptor: ShaderDescriptor.from({
         label: "Decal composite",
         resources,

package/src/engine/graphics3/decal/shader_decal_tile_copy.d.ts

@@ -0,0 +1,12 @@
+export const DECAL_TILE_COPY_SETTINGS: WebGPUStruct;
+/**
+ * Copies the G-buffer under the tiles that hold a decal, so the composite can read a surface as it
+ * was while writing the same texels in place — one texture cannot be a render attachment and a
+ * sampled source in one pass, and two of the four targets are integers that cannot blend.
+ *
+ * @type {DecalTileShader}
+ */
+export const shader_decal_tile_copy: DecalTileShader;
+import { WebGPUStruct } from "../../../shade/renderer/shader/type/WebGPUStruct.js";
+import { DecalTileShader } from "./DecalTileShader.js";
+//# sourceMappingURL=shader_decal_tile_copy.d.ts.map

package/src/engine/graphics3/decal/shader_decal_tile_copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_decal_tile_copy.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_decal_tile_copy.js"],"names":[],"mappings":"AAWA,oDAEG;AA6CH;;;;;;GAMG;AACH,qCAFU,eAAe,CActB;6BArE0B,qDAAqD;gCAClD,sBAAsB"}

package/src/engine/graphics3/decal/shader_decal_tile_copy.js

@@ -0,0 +1,78 @@
+import { G_BUFFER_ALBEDO_FORMAT } from "../../../shade/renderer/gbuffer/G_BUFFER_ALBEDO_FORMAT.js";
+import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
+import {
+    ShaderResourceSetDescriptor
+} from "../../../shade/renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../../shade/renderer/shader/ShaderDescriptor.js";
+import { vec2u } from "../../../shade/renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shade/renderer/shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shade/renderer/shader/type/WebGPUStruct.js";
+import { DecalTileShader } from "./DecalTileShader.js";
+
+export const DECAL_TILE_COPY_SETTINGS = WebGPUStruct.from({
+    screen_resolution: vec2u,
+});
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", DECAL_TILE_COPY_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("decal_tiles", WebGPUArray.u32);
+
+// integer targets are read as integer textures, as the composite reads them — see its note
+resources.createGroup()
+    .addTexture("gBufferPBR")
+    .addTexture("gBufferNormal", "uint")
+    .addTexture("gBufferAlbedo")
+    .addTexture("gBufferEmissive", "uint");
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+struct DecalTileCopyOut {
+    @location(0) pbr : vec2<f32>,
+    @location(1) normal : vec4<u32>,
+    @location(2) albedo : vec4<f32>,
+    @location(3) emissive : u32,
+}
+
+@fragment
+fn main(
+    @builtin(position) coord : vec4<f32>,
+) -> DecalTileCopyOut {
+    let i_coord = vec2<i32>(coord.xy);
+
+    var out : DecalTileCopyOut;
+
+    // the two unorm targets round-trip exactly: k/255 written back is k
+    out.pbr = textureLoad(gBufferPBR, i_coord, 0).rg;
+    out.normal = textureLoad(gBufferNormal, i_coord, 0);
+    out.albedo = textureLoad(gBufferAlbedo, i_coord, 0);
+    out.emissive = textureLoad(gBufferEmissive, i_coord, 0).r;
+
+    return out;
+}
+`
+);
+
+/**
+ * Copies the G-buffer under the tiles that hold a decal, so the composite can read a surface as it
+ * was while writing the same texels in place — one texture cannot be a render attachment and a
+ * sampled source in one pass, and two of the four targets are integers that cannot blend.
+ *
+ * @type {DecalTileShader}
+ */
+export const shader_decal_tile_copy = new DecalTileShader({
+    descriptor: ShaderDescriptor.from({
+        label: "Decal tiles / copy",
+        resources,
+        body
+    }),
+    targets: [
+        { format: "rg8unorm" },
+        { format: "rgba16uint" },
+        { format: G_BUFFER_ALBEDO_FORMAT },
+        { format: "r32uint" },
+    ]
+});

package/src/engine/graphics3/decal/shader_gather_decal_tiles.d.ts

@@ -0,0 +1,11 @@
+export const DECAL_TILE_GATHER_SETTINGS: WebGPUStruct;
+/**
+ * Lists the screen tiles whose froxel column holds at least one decal — the only part of the screen
+ * the decal passes draw. The list's first word is its length, and is zero when the pass starts.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_gather_decal_tiles: ComputeShader;
+import { WebGPUStruct } from "../../../shade/renderer/shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shade/renderer/shader/ComputeShader.js";
+//# sourceMappingURL=shader_gather_decal_tiles.d.ts.map

package/src/engine/graphics3/decal/shader_gather_decal_tiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_gather_decal_tiles.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_gather_decal_tiles.js"],"names":[],"mappings":"AAcA,sDAEG;AAqDH;;;;;GAKG;AACH,wCAFU,aAAa,CAMpB;6BApE0B,qDAAqD;8BANpD,iDAAiD"}

package/src/engine/graphics3/decal/shader_gather_decal_tiles.js

@@ -0,0 +1,80 @@
+import {
+    chunk_light_cluster_resolution_xy_from_screen
+} from "../../../shade/renderer/light/cluster/chunk_light_cluster_resolution_xy_from_screen.js";
+import { chunk_grid3d_to_index } from "../../../shade/renderer/shader/chunk/grid/chunk_grid3d_to_index.js";
+import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shade/renderer/shader/ComputeShader.js";
+import {
+    ShaderResourceSetDescriptor
+} from "../../../shade/renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, vec2u } from "../../../shade/renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shade/renderer/shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shade/renderer/shader/type/WebGPUStruct.js";
+import { DECAL_CLUSTER_METADATA, DECAL_CLUSTER_RESOLUTION_Z } from "./DECAL_CLUSTER.js";
+
+export const DECAL_TILE_GATHER_SETTINGS = WebGPUStruct.from({
+    screen_resolution: vec2u,
+});
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", DECAL_TILE_GATHER_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("cluster_lookup", WebGPUArray.from(DECAL_CLUSTER_METADATA))
+    .addStorageBuffer("decal_tiles", WebGPUArray.from(atomic_u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(8, 8, 1)
+fn main(
+    @builtin(global_invocation_id) tile : vec3<u32>
+) {
+    let resolution = light_cluster_resolution_xy_from_screen(settings.screen_resolution);
+
+    if (any(tile.xy >= resolution)) {
+        return;
+    }
+
+    /*
+     Gathered per tile, down its own column, rather than scattered by the froxels that hold a decal:
+     a tile is listed once however many of its slices are occupied, with no flag to clear and no
+     second pass to compact one.
+    */
+    var occupied = false;
+
+    for (var z = 0u; z < ${DECAL_CLUSTER_RESOLUTION_Z}u; z++) {
+        if (cluster_lookup[grid3d_to_index(vec3<u32>(tile.xy, z), resolution)].count > 0u) {
+            occupied = true;
+            break;
+        }
+    }
+
+    if (!occupied) {
+        return;
+    }
+
+    // the count leads the list; the list is sized for every tile, so the append cannot overrun
+    let slot = atomicAdd(&decal_tiles[0], 1u);
+
+    atomicStore(&decal_tiles[1u + slot], tile.x | (tile.y << 16u));
+}
+`,
+    [
+        chunk_light_cluster_resolution_xy_from_screen,
+        chunk_grid3d_to_index,
+    ]
+);
+
+/**
+ * Lists the screen tiles whose froxel column holds at least one decal — the only part of the screen
+ * the decal passes draw. The list's first word is its length, and is zero when the pass starts.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_gather_decal_tiles = ComputeShader.from({
+    label: "decal tiles / gather",
+    resources,
+    body
+});

package/src/engine/graphics3/trail/trail_tube_write_geometry.d.ts

@@ -20,6 +20,16 @@
  * base opacity — as the fourth channel. A knot that has aged out is written transparent rather than
  * dropped, which is what the index buffer expects, and blending takes it out of the picture.
  *
+ * **A knot's alpha is the opacity of the tube as seen, not of one face of it.** The tube is a closed
+ * hull drawn from both sides, so a line of sight through it crosses two faces, and the transparency
+ * pipeline composes their transmittances: written as is, an alpha of 0.5 would cover 0.75, and a
+ * linear fade would hold near solid for most of the trail's life and collapse at its tail. Each face
+ * therefore takes half the optical depth, `1 - √(1 - α)`, and the two together cover exactly `α`.
+ * This is the one place that knows the hull is crossed twice, so it is the one place that splits it;
+ * a ray through a bend crosses the tube twice over, and that overlap is real and reads denser. The
+ * alpha is clamped to `0..1` first, the range an opacity has — an authored fade curve may overshoot
+ * it, and the square root has no answer above one.
+ *
  * @param {Geometry} geometry
  * @param {TubeX} tube
  * @returns {void}

package/src/engine/graphics3/trail/trail_tube_write_geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trail_tube_write_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/trail/trail_tube_write_geometry.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,4EAFa,IAAI,CAgEhB"}
+{"version":3,"file":"trail_tube_write_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/trail/trail_tube_write_geometry.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,4EAFa,IAAI,CAiEhB"}

package/src/engine/graphics3/trail/trail_tube_write_geometry.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import { clamp01 } from "../../../core/math/clamp01.js";
 import {
     geometry_obtain_attribute,
     geometry_obtain_index
@@ -38,6 +39,16 @@ const TWO_PI = Math.PI * 2;
  * base opacity — as the fourth channel. A knot that has aged out is written transparent rather than
  * dropped, which is what the index buffer expects, and blending takes it out of the picture.
  *
+ * **A knot's alpha is the opacity of the tube as seen, not of one face of it.** The tube is a closed
+ * hull drawn from both sides, so a line of sight through it crosses two faces, and the transparency
+ * pipeline composes their transmittances: written as is, an alpha of 0.5 would cover 0.75, and a
+ * linear fade would hold near solid for most of the trail's life and collapse at its tail. Each face
+ * therefore takes half the optical depth, `1 - √(1 - α)`, and the two together cover exactly `α`.
+ * This is the one place that knows the hull is crossed twice, so it is the one place that splits it;
+ * a ray through a bend crosses the tube twice over, and that overlap is real and reads denser. The
+ * alpha is clamped to `0..1` first, the range an opacity has — an authored fade curve may overshoot
+ * it, and the square root has no answer above one.
+ *
  * @param {Geometry} geometry
  * @param {TubeX} tube
  * @returns {void}
@@ -94,7 +105,8 @@ export function trail_tube_write_geometry(geometry, tube) {
         colors[o] = halves[h];
         colors[o + 1] = halves[h + 1];
         colors[o + 2] = halves[h + 2];
-        colors[o + 3] = floats[f + TUBE_ATTRIBUTE_ADDRESS_ALPHA];
+        // half the optical depth: the face behind this one carries the other half
+        colors[o + 3] = 1 - Math.sqrt(1 - clamp01(floats[f + TUBE_ATTRIBUTE_ADDRESS_ALPHA]));
     }
 
     const source_indices = tube.indices;

package/src/engine/input/devices/mouse/MouseEventButtons.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bits of {@link MouseEvent.buttons }, the set of buttons held during an event.
+ *
+ * NOTE: not the {@link MouseButtons } ordinals, which index a single button by {@link MouseEvent.button }
+ * and put the middle button before the right one. Here the right button is 2 and the middle one 4.
+ */
+export type MouseEventButtons = number;
+export namespace MouseEventButtons {
+    let primary: number;
+    let secondary: number;
+    let auxiliary: number;
+}
+//# sourceMappingURL=MouseEventButtons.d.ts.map

package/src/engine/input/devices/mouse/MouseEventButtons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MouseEventButtons.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/mouse/MouseEventButtons.js"],"names":[],"mappings":";;;;;;gCAOU,MAAM"}

package/src/engine/input/devices/mouse/MouseEventButtons.js

@@ -0,0 +1,23 @@
+/**
+ * Bits of {@link MouseEvent.buttons}, the set of buttons held during an event.
+ *
+ * NOTE: not the {@link MouseButtons} ordinals, which index a single button by {@link MouseEvent.button}
+ * and put the middle button before the right one. Here the right button is 2 and the middle one 4.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const MouseEventButtons = {
+    /**
+     * usually the left button, and a touch or pen in contact
+     */
+    primary: 1,
+    /**
+     * usually the right button
+     */
+    secondary: 2,
+    /**
+     * usually the middle button or the wheel
+     */
+    auxiliary: 4,
+};

package/src/engine/input/ecs/controllers/KeyboardCameraController.d.ts

@@ -1,4 +1,8 @@
 export default KeyboardCameraController;
+/**
+ * WASD and the arrow keys move a top-down camera's orbit target across the ground, along the way the
+ * view is turned, at a fixed speed in world units a second.
+ */
 declare class KeyboardCameraController {
     /**
      *

package/src/engine/input/ecs/controllers/KeyboardCameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KeyboardCameraController.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/ecs/controllers/KeyboardCameraController.js"],"names":[],"mappings":";AAaA;IACI;;;;;OAKG;IACH,8BAHW;QAAC,SAAS,0BAAyB;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,+BAqG7D;IALG,gBAIgB;IAGpB;;OAEG;IACH,0CAEC;CACJ;mBAvHkB,wBAAwB"}
+{"version":3,"file":"KeyboardCameraController.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/ecs/controllers/KeyboardCameraController.js"],"names":[],"mappings":";AAQA;;;GAGG;AACH;IACI;;;;;OAKG;IACH,8BAHW;QAAC,SAAS,0BAAyB;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,+BAkE7D;IALG,gBAIgB;IAGpB;;OAEG;IACH,0CAEC;CACJ;mBAtFkB,wBAAwB"}