@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,59 +1,59 @@
-import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
-
-/**
- * Does a decal's volume — the unit cube put into the world by its own transform — touch a frustum?
- *
- * **A conservative plane test, deliberately.** meep's own clustered lighting reached this conclusion
- * the expensive way: it used an Arvo nearest-feature test, which is valid only for *axis-aligned*
- * boxes, and so false-excluded lights from oblique froxels — visible as blocky edges — until it was
- * replaced by a plane-only test. A decal is an oriented box by definition, so nearest-feature is
- * wrong for it in exactly the same way.
- *
- * A plane test over-includes: a box can fail to be wholly outside any single plane while still
- * missing the frustum. That costs a froxel an entry it did not need and never loses one it did,
- * which is the correct direction to be wrong in.
- *
- * @type {CodeChunk}
- */
-export const chunk_decal_intersects_frustum = CodeChunk.from(
-    //language=WGSL
-    `
-fn decal_intersects_frustum(
-    transform: mat4x4<f32>,
-    frustum: array<vec4<f32>, 6>,
-) -> bool {
-
-    var corners: array<vec3<f32>, 8>;
-
-    for (var i = 0u; i < 8u; i++) {
-        let local = vec3<f32>(
-            select(-0.5, 0.5, (i & 1u) != 0u),
-            select(-0.5, 0.5, (i & 2u) != 0u),
-            select(-0.5, 0.5, (i & 4u) != 0u)
-        );
-
-        corners[i] = (transform * vec4<f32>(local, 1.0)).xyz;
-    }
-
-    for (var p = 0; p < 6; p++) {
-        let plane = frustum[p];
-
-        var outside = 0u;
-
-        for (var i = 0u; i < 8u; i++) {
-            // the frustum convention is inward normals, so a point is inside when this is positive
-            if (dot(plane.xyz, corners[i]) + plane.w < 0.0) {
-                outside += 1u;
-            }
-        }
-
-        if (outside == 8u) {
-            // wholly beyond one plane, so wholly outside
-            return false;
-        }
-    }
-
-    return true;
-}
-    `, []
-);
+import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
+
+/**
+ * Does a decal's volume — the unit cube put into the world by its own transform — touch a frustum?
+ *
+ * **A conservative plane test, deliberately.** meep's own clustered lighting reached this conclusion
+ * the expensive way: it used an Arvo nearest-feature test, which is valid only for *axis-aligned*
+ * boxes, and so false-excluded lights from oblique froxels — visible as blocky edges — until it was
+ * replaced by a plane-only test. A decal is an oriented box by definition, so nearest-feature is
+ * wrong for it in exactly the same way.
+ *
+ * A plane test over-includes: a box can fail to be wholly outside any single plane while still
+ * missing the frustum. That costs a froxel an entry it did not need and never loses one it did,
+ * which is the correct direction to be wrong in.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_decal_intersects_frustum = CodeChunk.from(
+    //language=WGSL
+    `
+fn decal_intersects_frustum(
+    transform: mat4x4<f32>,
+    frustum: array<vec4<f32>, 6>,
+) -> bool {
+
+    var corners: array<vec3<f32>, 8>;
+
+    for (var i = 0u; i < 8u; i++) {
+        let local = vec3<f32>(
+            select(-0.5, 0.5, (i & 1u) != 0u),
+            select(-0.5, 0.5, (i & 2u) != 0u),
+            select(-0.5, 0.5, (i & 4u) != 0u)
+        );
+
+        corners[i] = (transform * vec4<f32>(local, 1.0)).xyz;
+    }
+
+    for (var p = 0; p < 6; p++) {
+        let plane = frustum[p];
+
+        var outside = 0u;
+
+        for (var i = 0u; i < 8u; i++) {
+            // the frustum convention is inward normals, so a point is inside when this is positive
+            if (dot(plane.xyz, corners[i]) + plane.w < 0.0) {
+                outside += 1u;
+            }
+        }
+
+        if (outside == 8u) {
+            // wholly beyond one plane, so wholly outside
+            return false;
+        }
+    }
+
+    return true;
+}
+    `, []
+);

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

@@ -1,57 +1,57 @@
-import {
-    GRADIENT_SAMPLING_INFO_STRUCT
-} from "../../../shade/renderer/shader/chunk/texture/GRADIENT_SAMPLING_INFO_STRUCT.js";
-import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
-
-/**
- * Where a decal samples its atlas, and how wide a footprint it samples over.
- *
- * The derivatives are the ones the caller worked out from the surface, not the hardware's: a decal
- * is sampled inside a loop over a per-pixel list, which is non-uniform control flow, and WGSL
- * forbids implicit derivatives there. The material pass met the same constraint from the other
- * direction — it shades from a visibility buffer, where a neighbouring pixel may belong to another
- * triangle entirely — and answers it by interpolating gradients off the triangle and sampling
- * through `textureSampleGrad`. This is that same arrangement, with the gradients coming off the
- * surface plane instead of a triangle's barycentrics.
- *
- * **The mip bound is applied as a gradient, not as a level**, because a gradient is what the sampler
- * reads. Halving the gradients lowers the level it picks by one, so scaling them until the implied
- * level meets the bound states the clamp in the units the sampler already speaks — and it composes
- * with anisotropy, which a hard level clamp would flatten.
- *
- * @type {CodeChunk}
- */
-export const chunk_decal_sampling_info = CodeChunk.from(
-    //language=WGSL
-    `
-fn decal_sampling_info(
-    uv: vec2<f32>,
-    duv_dx: vec2<f32>,
-    duv_dy: vec2<f32>,
-    rect: vec4<f32>,
-    max_lod: f32,
-    atlas_size: vec2<f32>
-) -> ${GRADIENT_SAMPLING_INFO_STRUCT.wgsl_ref} {
-
-    // the decal's uv is its own 0..1; the atlas rectangle is where that lands, so the gradient
-    // scales with the rectangle exactly as the coordinate does
-    var ddx = duv_dx * rect.zw;
-    var ddy = duv_dy * rect.zw;
-
-    let texels = max(length(ddx * atlas_size), length(ddy * atlas_size));
-
-    let level = log2(max(texels, 1e-8));
-
-    if (level > max_lod) {
-        let scale = exp2(max_lod - level);
-
-        ddx *= scale;
-        ddy *= scale;
-    }
-
-    return ${GRADIENT_SAMPLING_INFO_STRUCT.wgsl_ref}(rect.xy + uv * rect.zw, ddx, ddy);
-}
-    `, [
-        GRADIENT_SAMPLING_INFO_STRUCT.declaration_chunk
-    ]
-);
+import {
+    GRADIENT_SAMPLING_INFO_STRUCT
+} from "../../../shade/renderer/shader/chunk/texture/GRADIENT_SAMPLING_INFO_STRUCT.js";
+import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
+
+/**
+ * Where a decal samples its atlas, and how wide a footprint it samples over.
+ *
+ * The derivatives are the ones the caller worked out from the surface, not the hardware's: a decal
+ * is sampled inside a loop over a per-pixel list, which is non-uniform control flow, and WGSL
+ * forbids implicit derivatives there. The material pass met the same constraint from the other
+ * direction — it shades from a visibility buffer, where a neighbouring pixel may belong to another
+ * triangle entirely — and answers it by interpolating gradients off the triangle and sampling
+ * through `textureSampleGrad`. This is that same arrangement, with the gradients coming off the
+ * surface plane instead of a triangle's barycentrics.
+ *
+ * **The mip bound is applied as a gradient, not as a level**, because a gradient is what the sampler
+ * reads. Halving the gradients lowers the level it picks by one, so scaling them until the implied
+ * level meets the bound states the clamp in the units the sampler already speaks — and it composes
+ * with anisotropy, which a hard level clamp would flatten.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_decal_sampling_info = CodeChunk.from(
+    //language=WGSL
+    `
+fn decal_sampling_info(
+    uv: vec2<f32>,
+    duv_dx: vec2<f32>,
+    duv_dy: vec2<f32>,
+    rect: vec4<f32>,
+    max_lod: f32,
+    atlas_size: vec2<f32>
+) -> ${GRADIENT_SAMPLING_INFO_STRUCT.wgsl_ref} {
+
+    // the decal's uv is its own 0..1; the atlas rectangle is where that lands, so the gradient
+    // scales with the rectangle exactly as the coordinate does
+    var ddx = duv_dx * rect.zw;
+    var ddy = duv_dy * rect.zw;
+
+    let texels = max(length(ddx * atlas_size), length(ddy * atlas_size));
+
+    let level = log2(max(texels, 1e-8));
+
+    if (level > max_lod) {
+        let scale = exp2(max_lod - level);
+
+        ddx *= scale;
+        ddy *= scale;
+    }
+
+    return ${GRADIENT_SAMPLING_INFO_STRUCT.wgsl_ref}(rect.xy + uv * rect.zw, ddx, ddy);
+}
+    `, [
+        GRADIENT_SAMPLING_INFO_STRUCT.declaration_chunk
+    ]
+);

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

@@ -1,54 +1,54 @@
-import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
-
-/**
- * The frame a decal paints in, and how much of it reaches the surface at this angle.
- *
- * **A decal projects along its own +Z, so the surface it lands on faces the other way.** That is not
- * a choice made here: `CombatUnitEntityDecorator` and `EncounterLossLogic` both build their decal's
- * rotation by looking **down**, and the Forward+ shader this replaces faded a decal in as
- * `dot(decal_z, surface_normal)` approached **-1**. The projection direction and the surface normal
- * are opposites, and getting that sign the other way round is not a subtle difference — it rejects
- * every decal in the game, silently, because the fade reaching zero is also how a decal grazing a
- * wall is skipped.
- *
- * So the sign lives here, once, rather than in the two places the composite needs it: the angle
- * fade, and the frame a tangent-space normal is resolved in. A flat normal map — `(0, 0, 1)`, which
- * is what every decal authoring no normal map shares — must come out as the surface's own outward
- * normal and change nothing, and it only does if both use the same convention.
- *
- * `tangent` and `bitangent` are the decal's own X and Y, which is what its uv already is:
- * `local.xy + 0.5`. The frame is therefore left-handed against the outward normal, which is what a
- * projector seen from in front is, and it is the frame a normal map authored over that uv means.
- *
- * @type {CodeChunk}
- */
-export const chunk_decal_surface_frame = CodeChunk.from(
-    //language=WGSL
-    `
-struct DecalSurfaceFrame {
-    tangent : vec3<f32>,
-    bitangent : vec3<f32>,
-
-    // outward from the surface, which is **opposite** the direction the decal projects
-    normal : vec3<f32>,
-
-    // 1 where the surface faces the decal squarely, 0 where it has turned too far away to take it
-    fade : f32,
-}
-
-fn decal_surface_frame(transform: mat4x4<f32>, face_normal: vec3<f32>) -> DecalSurfaceFrame {
-    let axis_x = normalize(transform[0].xyz);
-    let axis_y = normalize(transform[1].xyz);
-    let axis_z = normalize(transform[2].xyz);
-
-    let outward = -axis_z;
-
-    return DecalSurfaceFrame(
-        axis_x,
-        axis_y,
-        outward,
-        smoothstep(0.35, 0.6, dot(face_normal, outward))
-    );
-}
-    `
-);
+import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
+
+/**
+ * The frame a decal paints in, and how much of it reaches the surface at this angle.
+ *
+ * **A decal projects along its own +Z, so the surface it lands on faces the other way.** That is not
+ * a choice made here: `CombatUnitEntityDecorator` and `EncounterLossLogic` both build their decal's
+ * rotation by looking **down**, and the Forward+ shader this replaces faded a decal in as
+ * `dot(decal_z, surface_normal)` approached **-1**. The projection direction and the surface normal
+ * are opposites, and getting that sign the other way round is not a subtle difference — it rejects
+ * every decal in the game, silently, because the fade reaching zero is also how a decal grazing a
+ * wall is skipped.
+ *
+ * So the sign lives here, once, rather than in the two places the composite needs it: the angle
+ * fade, and the frame a tangent-space normal is resolved in. A flat normal map — `(0, 0, 1)`, which
+ * is what every decal authoring no normal map shares — must come out as the surface's own outward
+ * normal and change nothing, and it only does if both use the same convention.
+ *
+ * `tangent` and `bitangent` are the decal's own X and Y, which is what its uv already is:
+ * `local.xy + 0.5`. The frame is therefore left-handed against the outward normal, which is what a
+ * projector seen from in front is, and it is the frame a normal map authored over that uv means.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_decal_surface_frame = CodeChunk.from(
+    //language=WGSL
+    `
+struct DecalSurfaceFrame {
+    tangent : vec3<f32>,
+    bitangent : vec3<f32>,
+
+    // outward from the surface, which is **opposite** the direction the decal projects
+    normal : vec3<f32>,
+
+    // 1 where the surface faces the decal squarely, 0 where it has turned too far away to take it
+    fade : f32,
+}
+
+fn decal_surface_frame(transform: mat4x4<f32>, face_normal: vec3<f32>) -> DecalSurfaceFrame {
+    let axis_x = normalize(transform[0].xyz);
+    let axis_y = normalize(transform[1].xyz);
+    let axis_z = normalize(transform[2].xyz);
+
+    let outward = -axis_z;
+
+    return DecalSurfaceFrame(
+        axis_x,
+        axis_y,
+        outward,
+        smoothstep(0.35, 0.6, dot(face_normal, outward))
+    );
+}
+    `
+);

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

@@ -1,69 +1,69 @@
-import { assert } from "../../../core/assert.js";
-
-/**
- * How much of a patch's own size is spent on its border.
- *
- * A **proportional** border rather than a fixed one, and that is the point of it: the border is what
- * decides how far a patch can be minified before its neighbours bleed into it, so sizing it in
- * proportion makes that limit the same for every decal whatever its resolution. At 1/64 every patch
- * stops minifying at roughly the same ~64 px screen footprint, for a flat ~6.3% of atlas area.
- *
- * A fixed border does the opposite: generous for small patches and useless for large ones.
- *
- * @type {number}
- */
-export const DECAL_ATLAS_BORDER_RATIO = 1 / 64;
-
-/**
- * The smallest border a patch may have, in texels.
- *
- * One, not more. A 64x64 decal is common and needs four texels at the very most; eight would spend a
- * tenth of the texture on gutter to protect mip levels at which the decal is a handful of pixels on
- * screen. One texel is also not really one — see {@link decal_atlas_max_lod}.
- *
- * @type {number}
- */
-export const DECAL_ATLAS_BORDER_MINIMUM = 1;
-
-/**
- * Border, in texels, for a patch of this size.
- *
- * Driven by the longer side, because one border value protects both axes and the atlas halves both
- * together when it builds its mip chain.
- *
- * @param {number} width
- * @param {number} height
- * @returns {number}
- */
-export function decal_atlas_border(width, height) {
-    assert.isNonNegativeInteger(width, 'width');
-    assert.isNonNegativeInteger(height, 'height');
-
-    return Math.max(
-        DECAL_ATLAS_BORDER_MINIMUM,
-        Math.ceil(Math.max(width, height) * DECAL_ATLAS_BORDER_RATIO)
-    );
-}
-
-/**
- * The deepest mip level a patch with this border can be sampled at without reading a neighbour.
- *
- * **A patch's own border is not the whole guard.** Every patch in the atlas has a border of at least
- * {@link DECAL_ATLAS_BORDER_MINIMUM}, so whatever sits next to this one contributes at least one
- * more texel of separation: content is `border + 1` texels apart at worst. At mip level `L` that
- * separation is `(border + 1) / 2^L` texels, and it has to survive down to one — which is also what
- * pays for patches not landing on power-of-two boundaries, so alignment is not claimed on top of it.
- *
- * Past this level the sampler is clamped rather than allowed to keep minifying, so a decal seen from
- * very far away aliases instead of bleeding. That is the trade, and it is the right way round: a
- * shimmering decal is a decal, a bleeding one is somebody else's texture.
- *
- * @param {number} border
- * @returns {number}
- */
-export function decal_atlas_max_lod(border) {
-    assert.isNonNegativeInteger(border, 'border');
-    assert.greaterThanOrEqual(border, DECAL_ATLAS_BORDER_MINIMUM, 'border');
-
-    return Math.floor(Math.log2(border + 1));
-}
+import { assert } from "../../../core/assert.js";
+
+/**
+ * How much of a patch's own size is spent on its border.
+ *
+ * A **proportional** border rather than a fixed one, and that is the point of it: the border is what
+ * decides how far a patch can be minified before its neighbours bleed into it, so sizing it in
+ * proportion makes that limit the same for every decal whatever its resolution. At 1/64 every patch
+ * stops minifying at roughly the same ~64 px screen footprint, for a flat ~6.3% of atlas area.
+ *
+ * A fixed border does the opposite: generous for small patches and useless for large ones.
+ *
+ * @type {number}
+ */
+export const DECAL_ATLAS_BORDER_RATIO = 1 / 64;
+
+/**
+ * The smallest border a patch may have, in texels.
+ *
+ * One, not more. A 64x64 decal is common and needs four texels at the very most; eight would spend a
+ * tenth of the texture on gutter to protect mip levels at which the decal is a handful of pixels on
+ * screen. One texel is also not really one — see {@link decal_atlas_max_lod}.
+ *
+ * @type {number}
+ */
+export const DECAL_ATLAS_BORDER_MINIMUM = 1;
+
+/**
+ * Border, in texels, for a patch of this size.
+ *
+ * Driven by the longer side, because one border value protects both axes and the atlas halves both
+ * together when it builds its mip chain.
+ *
+ * @param {number} width
+ * @param {number} height
+ * @returns {number}
+ */
+export function decal_atlas_border(width, height) {
+    assert.isNonNegativeInteger(width, 'width');
+    assert.isNonNegativeInteger(height, 'height');
+
+    return Math.max(
+        DECAL_ATLAS_BORDER_MINIMUM,
+        Math.ceil(Math.max(width, height) * DECAL_ATLAS_BORDER_RATIO)
+    );
+}
+
+/**
+ * The deepest mip level a patch with this border can be sampled at without reading a neighbour.
+ *
+ * **A patch's own border is not the whole guard.** Every patch in the atlas has a border of at least
+ * {@link DECAL_ATLAS_BORDER_MINIMUM}, so whatever sits next to this one contributes at least one
+ * more texel of separation: content is `border + 1` texels apart at worst. At mip level `L` that
+ * separation is `(border + 1) / 2^L` texels, and it has to survive down to one — which is also what
+ * pays for patches not landing on power-of-two boundaries, so alignment is not claimed on top of it.
+ *
+ * Past this level the sampler is clamped rather than allowed to keep minifying, so a decal seen from
+ * very far away aliases instead of bleeding. That is the trade, and it is the right way round: a
+ * shimmering decal is a decal, a bleeding one is somebody else's texture.
+ *
+ * @param {number} border
+ * @returns {number}
+ */
+export function decal_atlas_max_lod(border) {
+    assert.isNonNegativeInteger(border, 'border');
+    assert.greaterThanOrEqual(border, DECAL_ATLAS_BORDER_MINIMUM, 'border');
+
+    return Math.floor(Math.log2(border + 1));
+}