@woosh/meep-engine 3.46.0 → 3.49.0

package/src/shade/playground/contact_shadows/shader_contact_lab_stats.js

@@ -0,0 +1,216 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../renderer/camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_get_view_space_depth } from "../../renderer/shader/chunk/depth/chunk_get_view_space_depth.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32 } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+
+/**
+ * What each counter of the stats buffer counts, over one frame's pixels, before TAA. "Shadowed" means
+ * a visibility under ½; the reference is the ray-traced sun visibility of the pixel's own G-buffer
+ * position.
+ *
+ * @enum {number}
+ */
+export const ContactStat = {
+    /** the reference shadows it: the pixels any shadow term ought to darken */
+    ReferenceShadowed: 0,
+    /** the reference shadows it, the shadow map leaves it lit: the gaps contact shadows exist for */
+    ShadowMapMissed: 1,
+    /** of those, the ones the combined term shadows */
+    Fixed: 2,
+    /** the reference shadows it, the combined term leaves it lit */
+    Missed: 3,
+    /** the reference lights it, the shadow map shadows it */
+    ShadowMapFalse: 4,
+    /** the reference lights it, the combined term shadows it */
+    False: 5,
+    /** the reference and the shadow map light it, the combined term shadows it: what the contact term added */
+    AddedFalse: 6,
+    /** the combined term crossed ½ since the last frame where the reference did not */
+    SpuriousFlips: 7,
+    /** the shadow map's term crossed ½ since the last frame where the reference did not */
+    ShadowMapSpuriousFlips: 8,
+    /** the reference crossed ½ since the last frame */
+    ReferenceFlips: 9,
+    /** pixels counted */
+    Pixels: 10,
+    /** the contact term alone shadows it */
+    ContactShadowed: 11,
+    /** Σ |combined − reference| × 255 */
+    CombinedError: 12,
+    /** Σ |shadow map − reference| × 255 */
+    ShadowMapError: 13,
+    /** the combined term is darker than both terms by more than 0.1: double darkening */
+    DarkerThanBoth: 14,
+    /** Σ |combined − last frame's| × 255 over pixels whose reference did not cross ½: flicker */
+    CombinedChange: 15,
+    /** Σ |shadow map − last frame's| × 255 over the same pixels */
+    ShadowMapChange: 16,
+};
+
+/**
+ * Counters before the depth bands.
+ * @type {number}
+ */
+export const CONTACT_STAT_BAND_BASE = 20;
+
+/**
+ * Depth bands the band counters split by, in metres of view depth: [0, 2), [2, 4), [4, 8), … doubling,
+ * the last open-ended.
+ * @type {number}
+ */
+export const CONTACT_STAT_BAND_COUNT = 8;
+
+/**
+ * Per band, at CONTACT_STAT_BAND_BASE + band × 4: reference shadowed, shadow map missed, fixed,
+ * added false.
+ * @type {number}
+ */
+export const CONTACT_STAT_BAND_STRIDE = 4;
+
+/**
+ * @type {number}
+ */
+export const CONTACT_STAT_COUNT = CONTACT_STAT_BAND_BASE + CONTACT_STAT_BAND_COUNT * CONTACT_STAT_BAND_STRIDE;
+
+const SETTINGS = WebGPUStruct.from({
+    has_previous: u32,
+}, "ContactStatsSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", SETTINGS);
+
+resources.createGroup()
+    .addTexture("tVisibility")
+    .addTexture("tVisibilityPrevious")
+    .addTexture("gBufferDepth")
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer("stats", WebGPUArray.from(atomic_u32, CONTACT_STAT_COUNT), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const STAT_COUNT = ${CONTACT_STAT_COUNT}u;
+const BAND_BASE = ${CONTACT_STAT_BAND_BASE}u;
+const BAND_COUNT = ${CONTACT_STAT_BAND_COUNT}u;
+const BAND_STRIDE = ${CONTACT_STAT_BAND_STRIDE}u;
+
+var<workgroup> local_stats: array<atomic<u32>, ${CONTACT_STAT_COUNT}>;
+
+fn shadowed(visibility: f32) -> bool {
+    return visibility < 0.5;
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn main(
+    @builtin(global_invocation_id) id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let size = textureDimensions(tVisibility);
+
+    if (all(id.xy < size)) {
+        let v = textureLoad(tVisibility, id.xy, 0);
+
+        let shadow_map = v.x;
+        let contact = v.y;
+        let combined = v.z;
+        let reference = v.w;
+
+        atomicAdd(&local_stats[${ContactStat.Pixels}], 1u);
+
+        let depth = textureLoad(gBufferDepth, id.xy, 0).r;
+        let metres = select(1.0, get_view_space_depth(depth, camera), depth > 0.0);
+        let band = u32(clamp(floor(log2(max(metres, 1.0))), 0.0, f32(BAND_COUNT - 1u)));
+        let band_base = BAND_BASE + band * BAND_STRIDE;
+
+        if (shadowed(reference)) {
+            atomicAdd(&local_stats[${ContactStat.ReferenceShadowed}], 1u);
+            atomicAdd(&local_stats[band_base], 1u);
+
+            if (!shadowed(shadow_map)) {
+                atomicAdd(&local_stats[${ContactStat.ShadowMapMissed}], 1u);
+                atomicAdd(&local_stats[band_base + 1u], 1u);
+
+                if (shadowed(combined)) {
+                    atomicAdd(&local_stats[${ContactStat.Fixed}], 1u);
+                    atomicAdd(&local_stats[band_base + 2u], 1u);
+                }
+            }
+
+            if (!shadowed(combined)) {
+                atomicAdd(&local_stats[${ContactStat.Missed}], 1u);
+            }
+        } else {
+            if (shadowed(shadow_map)) {
+                atomicAdd(&local_stats[${ContactStat.ShadowMapFalse}], 1u);
+            }
+
+            if (shadowed(combined)) {
+                atomicAdd(&local_stats[${ContactStat.False}], 1u);
+
+                if (!shadowed(shadow_map)) {
+                    atomicAdd(&local_stats[${ContactStat.AddedFalse}], 1u);
+                    atomicAdd(&local_stats[band_base + 3u], 1u);
+                }
+            }
+        }
+
+        if (shadowed(contact)) {
+            atomicAdd(&local_stats[${ContactStat.ContactShadowed}], 1u);
+        }
+
+        if (combined < min(shadow_map, contact) - 0.1) {
+            atomicAdd(&local_stats[${ContactStat.DarkerThanBoth}], 1u);
+        }
+
+        atomicAdd(&local_stats[${ContactStat.CombinedError}], u32(round(abs(combined - reference) * 255.0)));
+        atomicAdd(&local_stats[${ContactStat.ShadowMapError}], u32(round(abs(shadow_map - reference) * 255.0)));
+
+        if (settings.has_previous != 0u) {
+            let p = textureLoad(tVisibilityPrevious, id.xy, 0);
+
+            if (shadowed(reference) != shadowed(p.w)) {
+                atomicAdd(&local_stats[${ContactStat.ReferenceFlips}], 1u);
+            } else {
+                atomicAdd(&local_stats[${ContactStat.CombinedChange}], u32(round(abs(combined - p.z) * 255.0)));
+                atomicAdd(&local_stats[${ContactStat.ShadowMapChange}], u32(round(abs(shadow_map - p.x) * 255.0)));
+
+                if (shadowed(combined) != shadowed(p.z)) {
+                    atomicAdd(&local_stats[${ContactStat.SpuriousFlips}], 1u);
+                }
+
+                if (shadowed(shadow_map) != shadowed(p.x)) {
+                    atomicAdd(&local_stats[${ContactStat.ShadowMapSpuriousFlips}], 1u);
+                }
+            }
+        }
+    }
+
+    workgroupBarrier();
+
+    // 64 lanes, STAT_COUNT counters: at most one pass round
+    for (var i = lane; i < STAT_COUNT; i += 64u) {
+        let value = atomicLoad(&local_stats[i]);
+
+        if (value != 0u) {
+            atomicAdd(&stats[i], value);
+        }
+    }
+}
+`, [SETTINGS.declaration_chunk, chunk_get_view_space_depth]);
+
+/**
+ * The playground's counters: one frame's pixels classified against the ray-traced reference, overall
+ * and by depth band, and against the previous frame's record for flips the reference does not share.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_contact_lab_stats = ComputeShader.from({
+    label: "Contact lab / stats",
+    resources,
+    body,
+});

package/src/shade/playground/contact_shadows/shader_contact_lab_view.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What the screen shows.
+ */
+export type ContactLabView = number;
+export namespace ContactLabView {
+    let Final: number;
+    let Combined: number;
+    let Contact: number;
+    let ShadowMap: number;
+    let Reference: number;
+    let Error: number;
+}
+/**
+ * Draws the chosen {@link ContactLabView} over the frame before it is tonemapped.
+ *
+ * @type {ImageShader}
+ */
+export const shader_contact_lab_view: ImageShader;
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+//# sourceMappingURL=shader_contact_lab_view.d.ts.map

package/src/shade/playground/contact_shadows/shader_contact_lab_view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_contact_lab_view.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/contact_shadows/shader_contact_lab_view.js"],"names":[],"mappings":";;;6BAUU,MAAM;;;;;;;;;AAsFhB;;;;GAIG;AACH,sCAFU,WAAW,CAclB;4BA/GyB,sCAAsC"}

package/src/shade/playground/contact_shadows/shader_contact_lab_view.js

@@ -0,0 +1,114 @@
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { chunk_rgb_to_luminance } from "../../renderer/shader/chunk/color/chunk_rgb_to_luminance.js";
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
+import { u32 } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+
+/**
+ * What the screen shows.
+ * @enum {number}
+ */
+export const ContactLabView = {
+    /** the lit frame, with the contact term in the sun's shadow */
+    Final: 0,
+    /** the sun's visibility as the frame used it: shadow map and contact combined */
+    Combined: 1,
+    /** the contact term alone */
+    Contact: 2,
+    /** the shadow map's term alone */
+    ShadowMap: 3,
+    /** the ray-traced sun visibility */
+    Reference: 4,
+    /**
+     * Each pixel against the reference: green, a gap the contact term closed; blue, shadowed in the
+     * reference and lit in the frame; red, a false shadow the contact term added; amber, a false shadow
+     * the shadow map already had.
+     */
+    Error: 5,
+};
+
+const SETTINGS = WebGPUStruct.from({
+    mode: u32,
+}, "ContactLabViewSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", SETTINGS);
+
+resources.createGroup()
+    .addTexture("tScene")
+    .addTexture("tVisibility");
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@fragment
+fn main(
+    @builtin(position) coord: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+) -> @location(0) vec4<f32> {
+    let scene = textureLoad(tScene, vec2<u32>(coord.xy), 0);
+
+    // the record is at the internal resolution, which the upscale may have left behind
+    let record_size = vec2<f32>(textureDimensions(tVisibility));
+    let record_xy = min(vec2<u32>(uv * record_size), vec2<u32>(record_size) - 1u);
+
+    let v = textureLoad(tVisibility, record_xy, 0);
+
+    switch (settings.mode) {
+        case ${ContactLabView.Combined}u: { return vec4<f32>(vec3<f32>(v.z), 1.0); }
+        case ${ContactLabView.Contact}u: { return vec4<f32>(vec3<f32>(v.y), 1.0); }
+        case ${ContactLabView.ShadowMap}u: { return vec4<f32>(vec3<f32>(v.x), 1.0); }
+        case ${ContactLabView.Reference}u: { return vec4<f32>(vec3<f32>(v.w), 1.0); }
+        case ${ContactLabView.Error}u: {
+            let base = vec3<f32>(rgb_to_luminance(scene.rgb) * 0.35);
+
+            let reference_shadowed = v.w < 0.5;
+            let map_shadowed = v.x < 0.5;
+            let combined_shadowed = v.z < 0.5;
+
+            if (reference_shadowed && !combined_shadowed) {
+                return vec4<f32>(0.1, 0.35, 1.0, 1.0);
+            }
+
+            if (reference_shadowed && combined_shadowed && !map_shadowed) {
+                return vec4<f32>(0.1, 0.9, 0.2, 1.0);
+            }
+
+            if (!reference_shadowed && combined_shadowed) {
+                if (map_shadowed) {
+                    return vec4<f32>(1.0, 0.6, 0.05, 1.0);
+                }
+
+                return vec4<f32>(1.0, 0.08, 0.08, 1.0);
+            }
+
+            return vec4<f32>(base, 1.0);
+        }
+        default: {
+            return scene;
+        }
+    }
+}
+`, [SETTINGS.declaration_chunk, chunk_rgb_to_luminance]);
+
+/**
+ * Draws the chosen {@link ContactLabView} over the frame before it is tonemapped.
+ *
+ * @type {ImageShader}
+ */
+export const shader_contact_lab_view = new ImageShader({
+    descriptor: ShaderDescriptor.from({
+        label: "Contact lab / view",
+        resources,
+        body,
+    }),
+    targets: [
+        {
+            label: "contact lab view",
+            format: "rgba16float",
+        },
+    ],
+});

package/src/shade/playground/contact_shadows/shader_contact_shadow_march.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A/B arm: the engine's unwired per-pixel march, `ss_trace_pixel_occlusion` from
+ * `deferred/chunk_ss_trace_contact_shadow_soft.js`, as it stands — one DDA step per pixel along the
+ * longer screen axis, a view-space thickness test, and hit confidence from the hit's normal. Given the
+ * wavefront pass's sample budget and thickness window, so what differs between the two is the method.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_contact_shadow_march: ComputeShader;
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+//# sourceMappingURL=shader_contact_shadow_march.d.ts.map

package/src/shade/playground/contact_shadows/shader_contact_shadow_march.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_contact_shadow_march.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/contact_shadows/shader_contact_shadow_march.js"],"names":[],"mappings":"AA6EA;;;;;;;GAOG;AACH,0CAFU,aAAa,CAMpB;8BAjF2B,wCAAwC"}

package/src/shade/playground/contact_shadows/shader_contact_shadow_march.js

@@ -0,0 +1,90 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../renderer/camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_ss_trace_pixel_occlusion } from "../../renderer/deferred/chunk_ss_trace_contact_shadow_soft.js";
+import { chunk_project_position_from_depth } from "../../renderer/shader/chunk/camera/chunk_project_position_from_depth.js";
+import { chunk_get_view_space_depth } from "../../renderer/shader/chunk/depth/chunk_get_view_space_depth.js";
+import { chunk_is_background } from "../../renderer/shader/chunk/depth/chunk_is_background.js";
+import { chunk_decode_g_buffer_normal } from "../../renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
+import { chunk_texel_coordinate_to_uv } from "../../renderer/shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32, vec3f } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+
+const SETTINGS = WebGPUStruct.from({
+    to_light: vec3f,
+    surface_thickness: f32,
+    step_count: u32,
+}, "ContactMarchSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", SETTINGS);
+
+resources.createGroup()
+    .addTexture("gBufferDepth")
+    .addTexture("gBufferNormal", "uint")
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageTexture("tContactShadow", "r32float", "2d", "write-only");
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(8, 8, 1)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let size = textureDimensions(gBufferDepth);
+
+    if (any(id.xy >= size)) {
+        return;
+    }
+
+    let depth = textureLoad(gBufferDepth, id.xy, 0).r;
+
+    if (is_background(depth)) {
+        textureStore(tContactShadow, id.xy, vec4<f32>(1.0));
+        return;
+    }
+
+    let uv = texel_coordinate_to_uv(vec2<f32>(id.xy), size);
+    let position_ws = project_position_from_depth(uv, depth, camera.view_projection_matrix_inverse);
+    let geometric_normal = decode_g_buffer_normal(textureLoad(gBufferNormal, id.xy, 0).zw);
+
+    // the same window as the wavefront pass: an occluder may sit up to 2 × thickness × its distance in front
+    let thickness = 2.0 * settings.surface_thickness * get_view_space_depth(depth, camera);
+
+    let visibility = ss_trace_pixel_occlusion(
+        position_ws,
+        settings.to_light,
+        geometric_normal,
+        camera.view_projection_matrix,
+        gBufferDepth,
+        settings.step_count,
+        thickness,
+    );
+
+    textureStore(tContactShadow, id.xy, vec4<f32>(visibility));
+}
+`, [
+        SETTINGS.declaration_chunk,
+        chunk_is_background,
+        chunk_texel_coordinate_to_uv,
+        chunk_project_position_from_depth,
+        chunk_get_view_space_depth,
+        chunk_decode_g_buffer_normal,
+        chunk_ss_trace_pixel_occlusion,
+    ]
+);
+
+/**
+ * A/B arm: the engine's unwired per-pixel march, `ss_trace_pixel_occlusion` from
+ * `deferred/chunk_ss_trace_contact_shadow_soft.js`, as it stands — one DDA step per pixel along the
+ * longer screen axis, a view-space thickness test, and hit confidence from the hit's normal. Given the
+ * wavefront pass's sample budget and thickness window, so what differs between the two is the method.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_contact_shadow_march = ComputeShader.from({
+    label: "Contact lab / per-pixel march",
+    resources,
+    body,
+});

package/src/shade/playground/contact_shadows/textures.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Leaves for alpha-tested cards: green ellipses fanned about a stem, opaque inside and wholly
+ * transparent between, so the alpha test cuts real holes.
+ *
+ * @returns {ShadeTexture}
+ */
+export function make_leaf_texture(): ShadeTexture;
+/**
+ * A tangent-space normal map of round bumps, 16 to a side: detail a normal map shades and a depth
+ * buffer never sees.
+ *
+ * @returns {ShadeTexture}
+ */
+export function make_bump_normal_texture(): ShadeTexture;
+import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
+//# sourceMappingURL=textures.d.ts.map

package/src/shade/playground/contact_shadows/textures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textures.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/contact_shadows/textures.js"],"names":[],"mappings":"AAgCA;;;;;GAKG;AACH,qCAFa,YAAY,CA6CxB;AAED;;;;;GAKG;AACH,4CAFa,YAAY,CAmCxB;6BAxH4B,wCAAwC"}

package/src/shade/playground/contact_shadows/textures.js

@@ -0,0 +1,123 @@
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { ColorSpace } from "../../renderer/texture/ColorSpace.js";
+import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
+import { ShadeImage } from "../../renderer/texture/source/ShadeImage.js";
+import { TextureFilterType } from "../../renderer/texture/TextureFilterType.js";
+import { TextureWrapType } from "../../renderer/texture/TextureWrapType.js";
+
+/**
+ * @param {Uint8Array} rgba
+ * @param {number} size
+ * @param {string} label
+ * @param {boolean} srgb
+ */
+function texture_from_rgba(rgba, size, label, srgb) {
+    const image = ShadeImage.fromSampler2D(new Sampler2D(rgba, 4, size, size));
+
+    if (srgb) {
+        image.color_space = ColorSpace.SRGB;
+    }
+
+    const texture = ShadeTexture.from(image);
+
+    texture.label = label;
+    texture.wrapS = TextureWrapType.Repeat;
+    texture.wrapT = TextureWrapType.Repeat;
+    texture.minFilter = TextureFilterType.Linear;
+    texture.magFilter = TextureFilterType.Linear;
+    texture.mipmapFilter = TextureFilterType.Linear;
+
+    return texture;
+}
+
+/**
+ * Leaves for alpha-tested cards: green ellipses fanned about a stem, opaque inside and wholly
+ * transparent between, so the alpha test cuts real holes.
+ *
+ * @returns {ShadeTexture}
+ */
+export function make_leaf_texture() {
+    const size = 256;
+    const rgba = new Uint8Array(size * size * 4);
+
+    // leaf centres in [0, 1]², with their angles
+    const leaves = [];
+
+    for (let i = 0; i < 9; i++) {
+        const t = (i + 0.5) / 9;
+        const side = i % 2 === 0 ? -1 : 1;
+
+        leaves.push([0.5 + side * 0.17, 0.08 + t * 0.84, side * 0.7]);
+    }
+
+    for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+            const u = (x + 0.5) / size;
+            const v = (y + 0.5) / size;
+
+            let inside = Math.abs(u - 0.5) < 0.012 && v > 0.04;
+
+            for (const [cu, cv, angle] of leaves) {
+                const du = u - cu;
+                const dv = v - cv;
+                const a = du * Math.cos(angle) + dv * Math.sin(angle);
+                const b = -du * Math.sin(angle) + dv * Math.cos(angle);
+
+                if ((a / 0.17) ** 2 + (b / 0.065) ** 2 < 1) {
+                    inside = true;
+                }
+            }
+
+            const i = (y * size + x) * 4;
+            const shade = 0.8 + 0.2 * Math.sin(u * 40) * Math.sin(v * 31);
+
+            rgba[i] = Math.round(255 * shade);
+            rgba[i + 1] = Math.round(255 * shade);
+            rgba[i + 2] = Math.round(255 * shade);
+            rgba[i + 3] = inside ? 255 : 0;
+        }
+    }
+
+    return texture_from_rgba(rgba, size, 'contact lab / leaves', true);
+}
+
+/**
+ * A tangent-space normal map of round bumps, 16 to a side: detail a normal map shades and a depth
+ * buffer never sees.
+ *
+ * @returns {ShadeTexture}
+ */
+export function make_bump_normal_texture() {
+    const size = 512;
+    const cells = 16;
+    const rgba = new Uint8Array(size * size * 4);
+
+    // a dome per cell, of this slope at its edge
+    const steepness = 2.2;
+
+    for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+            const cx = ((x + 0.5) / size * cells) % 1 - 0.5;
+            const cy = ((y + 0.5) / size * cells) % 1 - 0.5;
+            const r = Math.hypot(cx, cy);
+
+            let nx = 0;
+            let ny = 0;
+
+            if (r < 0.45) {
+                nx = -cx / 0.45 * steepness;
+                ny = -cy / 0.45 * steepness;
+            }
+
+            const length = Math.hypot(nx, ny, 1);
+            const i = (y * size + x) * 4;
+
+            rgba[i] = Math.round((nx / length * 0.5 + 0.5) * 255);
+            rgba[i + 1] = Math.round((ny / length * 0.5 + 0.5) * 255);
+            rgba[i + 2] = Math.round((1 / length * 0.5 + 0.5) * 255);
+            rgba[i + 3] = 255;
+        }
+    }
+
+    return texture_from_rgba(rgba, size, 'contact lab / bumps', false);
+}

package/src/shade/playground/particle_ecs/README.md

@@ -43,7 +43,7 @@ reported no adapter at all since 2026-09-02.
 | flame | `ParticleEffect` | additive billboards, short-lived, stirred by noise and pinched inward so the column narrows |
 | smoke | `ParticleEffect` | alpha, soft-depth, expanding, firelit at the base and moonlit above it |
 | embers | `ParticleEffect` | small additive motes, buoyant then falling, flickering on their own clock |
-| soot | `ParticleEffect` | dark tumbling flakes that ride the plume and fall back through the firelight |
+| soot | `ParticleEffect` | dark flakes that ride the plume and fall back through the firelight, tumbling in the world: a `FACING_WORLD` quad turned by its own `orientation`, born at a `sampleRotation` and advanced by `quatIntegrate` |
 | ground, logs, stones | `ShadedGeometry` | something for the fire to light, and for the smoke to fade against |
 | moon | `Light` (directional) | the cool half of the lighting, aimed at the moon in the environment map |
 | firelight | `Light` (point) | the warm half, flickered every frame by writing the component |