@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/playground/ground_seam/make_grid_texture.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The albedo the ground plane wears.
+ *
+ * A grid rather than a photograph, because what is being measured is a *per-texel* instability: the
+ * signal only exists if the texture carries energy at the texel scale, and a smooth image would
+ * hide a mip level or an anisotropy ratio that moved by a fraction. A one-texel line on a flat
+ * field is the highest-contrast thing a 256² texture can hold at its own Nyquist limit, so it is
+ * the loudest possible witness to a sampler that is not landing in the same place twice.
+ *
+ * Every filter stays {@link TextureFilterType.Linear} deliberately —
+ * `sampler_descriptor_from_shade_texture` grants 16× anisotropy only when min, mag *and* mip are
+ * all linear, and the anisotropic path is one of the quantities under suspicion. Dropping any one
+ * of them to Nearest would quietly take the sampler down to 1× and change what is being observed.
+ *
+ * An `ImageBitmap` rather than the raw `ImageData` buffer: it is the path every glTF albedo takes,
+ * so the decode, the premultiplication rule and the `rgba8unorm-srgb` format selection are the ones
+ * a real asset gets rather than a second set reached only from here.
+ *
+ * @param {number} [size] edge length in texels; a power of two so the mip chain reaches 1×1 exactly
+ * @param {boolean} [anisotropic] when false, the mip filter drops to Nearest, which is the only
+ *      handle {@link ShadeTexture} offers on anisotropy — `sampler_descriptor_from_shade_texture`
+ *      grants 16× only while min, mag *and* mip are all Linear, and 1× otherwise. Not a
+ *      single-variable control, and the trilinear blend goes with it; what it is good for is asking
+ *      whether a difference depends on the gradient-derived footprint at all.
+ * @returns {Promise<ShadeTexture>}
+ */
+export function make_grid_texture(size?: number, anisotropic?: boolean): Promise<ShadeTexture>;
+import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
+//# sourceMappingURL=make_grid_texture.d.ts.map

package/src/shade/playground/ground_seam/make_grid_texture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_grid_texture.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ground_seam/make_grid_texture.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,yCARW,MAAM,gBACN,OAAO,GAKL,QAAQ,YAAY,CAAC,CA0EjC;6BAvG4B,wCAAwC"}

package/src/shade/playground/ground_seam/make_grid_texture.js

@@ -0,0 +1,105 @@
+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";
+
+/**
+ * The albedo the ground plane wears.
+ *
+ * A grid rather than a photograph, because what is being measured is a *per-texel* instability: the
+ * signal only exists if the texture carries energy at the texel scale, and a smooth image would
+ * hide a mip level or an anisotropy ratio that moved by a fraction. A one-texel line on a flat
+ * field is the highest-contrast thing a 256² texture can hold at its own Nyquist limit, so it is
+ * the loudest possible witness to a sampler that is not landing in the same place twice.
+ *
+ * Every filter stays {@link TextureFilterType.Linear} deliberately —
+ * `sampler_descriptor_from_shade_texture` grants 16× anisotropy only when min, mag *and* mip are
+ * all linear, and the anisotropic path is one of the quantities under suspicion. Dropping any one
+ * of them to Nearest would quietly take the sampler down to 1× and change what is being observed.
+ *
+ * An `ImageBitmap` rather than the raw `ImageData` buffer: it is the path every glTF albedo takes,
+ * so the decode, the premultiplication rule and the `rgba8unorm-srgb` format selection are the ones
+ * a real asset gets rather than a second set reached only from here.
+ *
+ * @param {number} [size] edge length in texels; a power of two so the mip chain reaches 1×1 exactly
+ * @param {boolean} [anisotropic] when false, the mip filter drops to Nearest, which is the only
+ *      handle {@link ShadeTexture} offers on anisotropy — `sampler_descriptor_from_shade_texture`
+ *      grants 16× only while min, mag *and* mip are all Linear, and 1× otherwise. Not a
+ *      single-variable control, and the trilinear blend goes with it; what it is good for is asking
+ *      whether a difference depends on the gradient-derived footprint at all.
+ * @returns {Promise<ShadeTexture>}
+ */
+export async function make_grid_texture(size = 256, anisotropic = true) {
+    const canvas = document.createElement('canvas');
+
+    canvas.width = size;
+    canvas.height = size;
+
+    const ctx = canvas.getContext('2d');
+
+    // olive base — dark enough that the grid is the only high-frequency content in the image
+    ctx.fillStyle = '#3c4838';
+    ctx.fillRect(0, 0, size, size);
+
+    /**
+     * Cell pitch, in texels. 32 divides 256 exactly, so the pattern is continuous across the wrap
+     * seam and a tile boundary is not itself a feature.
+     */
+    const CELL = 32;
+
+    ctx.strokeStyle = '#ffffff';
+
+    /**
+     * A half-texel offset puts a 1px stroke on a texel centre rather than straddling two, which
+     * keeps the line a genuine one-texel impulse instead of a two-texel ramp.
+     *
+     * @param {number} width
+     * @param {number} pitch
+     */
+    function rule(width, pitch) {
+        ctx.lineWidth = width;
+
+        for (let i = 0; i <= size; i += pitch) {
+            ctx.beginPath();
+            ctx.moveTo(i + 0.5, 0);
+            ctx.lineTo(i + 0.5, size);
+            ctx.stroke();
+
+            ctx.beginPath();
+            ctx.moveTo(0, i + 0.5);
+            ctx.lineTo(size, i + 0.5);
+            ctx.stroke();
+        }
+    }
+
+    rule(1, CELL);
+
+    // every fourth cell is heavier, so the pattern has structure at two scales and a mip slip reads
+    // as a change in which of the two dominates rather than as uniform blur
+    rule(1.5, CELL * 4);
+
+    const bitmap = await createImageBitmap(canvas, {
+        // premultiplication happens during texture upload
+        premultiplyAlpha: 'none'
+    });
+
+    const image = ShadeImage.fromImageBitmap(bitmap);
+
+    // assigned after construction, exactly as `gltf_create_material` does it — this is what selects
+    // `rgba8unorm-srgb` and therefore the free sRGB decode on sample
+    image.color_space = ColorSpace.SRGB;
+
+    const texture = ShadeTexture.from(image);
+
+    texture.label = 'ground_seam/grid';
+
+    texture.wrapS = TextureWrapType.Repeat;
+    texture.wrapT = TextureWrapType.Repeat;
+
+    texture.minFilter = TextureFilterType.Linear;
+    texture.magFilter = TextureFilterType.Linear;
+    texture.mipmapFilter = anisotropic ? TextureFilterType.Linear : TextureFilterType.Nearest;
+
+    return texture;
+}

package/src/shade/playground/ground_seam/make_ground.d.ts

@@ -0,0 +1,70 @@
+/**
+ * How many times the grid texture repeats across the quad.
+ *
+ * extent/16 — one texture tile every 16 world units, which puts the 256² grid somewhere around one
+ * texel per screen pixel in the middle distance of the view this page sets up. That is the band
+ * where mip selection and anisotropy actually have to make a decision, and therefore the band where
+ * an unstable decision is visible.
+ *
+ * @param {number} extent
+ * @returns {number}
+ */
+export function uv_scale_for(extent: number): number;
+/**
+ * The ground plane, and nothing else — the brief's scene reproduces with this alone.
+ *
+ * @param {object} options
+ * @param {ShadeTexture} options.albedo
+ * @param {number} [options.extent] edge length of the quad in world units. Bigger is worse
+ *      conditioned: at a fixed camera height a wider quad puts its far corner closer to the eye
+ *      plane, so |w| there shrinks and everything derived from it grows. The UV scale is derived
+ *      from the extent, so world-space texel density — and therefore the image in the middle
+ *      distance — is the same at every size, which is what makes two extents comparable at all.
+ * @param {number} [options.segments] subdivision per axis; 1 is the default two-triangle quad
+ * @param {number[]} [options.indices] index buffer override, only meaningful when `segments === 1`
+ * @param {number} [options.yaw_degrees] rotation about +Y, applied after the quad is laid flat
+ * @param {number} [options.roughness]
+ * @param {number} [options.metallic]
+ * @returns {Mesh}
+ */
+export function make_ground({ albedo, segments, indices, extent, yaw_degrees, roughness, metallic, }: {
+    albedo: ShadeTexture;
+    extent?: number;
+    segments?: number;
+    indices?: number[];
+    yaw_degrees?: number;
+    roughness?: number;
+    metallic?: number;
+}): Mesh;
+/**
+ * Edge length of the ground quad, in world units.
+ * @type {number}
+ */
+export const GROUND_EXTENT: number;
+/**
+ * How `make_plane_geometry` triangulates its default 1×1 quad, and the other way it could have.
+ *
+ * The vertices it emits, in the plane's own XY (before the −90° X rotation that lays it flat):
+ *
+ * ```
+ *   v0 (−212.5, +212.5)      v1 (+212.5, +212.5)
+ *   v2 (−212.5, −212.5)      v3 (+212.5, −212.5)
+ * ```
+ *
+ * The default is `(0,2,1)` and `(2,3,1)`, whose shared edge is v2→v1 — the diagonal that becomes
+ * the world line **x = −z** once the quad is laid flat. {@link GROUND_TRIANGULATION.flipped } is the
+ * same four vertices, the same UVs and the same winding across the *other* diagonal, v0→v3, which
+ * is the world line **x = z**.
+ *
+ * Both windings were checked by hand: every triangle in both lists has a positive Z cross product
+ * in plane-local XY, so nothing here changes which face is front.
+ */
+export type GROUND_TRIANGULATION = number[];
+export namespace GROUND_TRIANGULATION {
+    let _default: number[];
+    export { _default as default };
+    export let flipped: number[];
+    export let rotated: number[];
+}
+import { Mesh } from "../../renderer/scene/Mesh.js";
+//# sourceMappingURL=make_ground.d.ts.map

package/src/shade/playground/ground_seam/make_ground.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_ground.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ground_seam/make_ground.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;GAUG;AACH,qCAHW,MAAM,GACJ,MAAM,CAIlB;AAyCD;;;;;;;;;;;;;;;;GAgBG;AACH;IAbiC,MAAM;IACX,MAAM,GAAvB,MAAM;IAKW,QAAQ,GAAzB,MAAM;IACa,OAAO,GAA1B,MAAM,EAAE;IACS,WAAW,GAA5B,MAAM;IACW,SAAS,GAA1B,MAAM;IACW,QAAQ,GAAzB,MAAM;IACJ,IAAI,CA2EhB;AAtJD;;;GAGG;AACH,4BAFU,MAAM,CAEiB;;;;;;;;;;;;;;;;;;;mCAmCvB,MAAM,EAAE;;;;;;;qBAzCG,8BAA8B"}

package/src/shade/playground/ground_seam/make_ground.js

@@ -0,0 +1,161 @@
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { Attribute } from "../../renderer/geometry/Attribute.js";
+import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "../../renderer/geometry/MeshletGeometry.js";
+import { make_plane_geometry } from "../../renderer/geometry/primitives/make_plane_geometry.js";
+import { StandardAttributes } from "../../renderer/geometry/StandardAttributes.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../../renderer/scene/Mesh.js";
+
+/**
+ * Edge length of the ground quad, in world units.
+ * @type {number}
+ */
+export const GROUND_EXTENT = 425;
+
+/**
+ * How many times the grid texture repeats across the quad.
+ *
+ * extent/16 — one texture tile every 16 world units, which puts the 256² grid somewhere around one
+ * texel per screen pixel in the middle distance of the view this page sets up. That is the band
+ * where mip selection and anisotropy actually have to make a decision, and therefore the band where
+ * an unstable decision is visible.
+ *
+ * @param {number} extent
+ * @returns {number}
+ */
+export function uv_scale_for(extent) {
+    return extent / 16;
+}
+
+/**
+ * How `make_plane_geometry` triangulates its default 1×1 quad, and the other way it could have.
+ *
+ * The vertices it emits, in the plane's own XY (before the −90° X rotation that lays it flat):
+ *
+ * ```
+ *   v0 (−212.5, +212.5)      v1 (+212.5, +212.5)
+ *   v2 (−212.5, −212.5)      v3 (+212.5, −212.5)
+ * ```
+ *
+ * The default is `(0,2,1)` and `(2,3,1)`, whose shared edge is v2→v1 — the diagonal that becomes
+ * the world line **x = −z** once the quad is laid flat. {@link GROUND_TRIANGULATION.flipped} is the
+ * same four vertices, the same UVs and the same winding across the *other* diagonal, v0→v3, which
+ * is the world line **x = z**.
+ *
+ * Both windings were checked by hand: every triangle in both lists has a positive Z cross product
+ * in plane-local XY, so nothing here changes which face is front.
+ *
+ * @enum {number[]}
+ */
+export const GROUND_TRIANGULATION = {
+    default: [0, 2, 1, 2, 3, 1],
+    flipped: [0, 2, 3, 0, 3, 1],
+
+    /**
+     * The **same two triangles** as `default`, each cyclically rotated so a different corner is
+     * first. Same diagonal, same winding, same three vertices per face — only which one the
+     * reconstruction anchors on changes.
+     *
+     * `chunk_barycentric_full` builds every pixel's barycentric from `pixel - ndc0` and divides by
+     * `determinant(mat2x2(ndc2 - ndc1, ndc0 - ndc1))`, so vertex 0 is the origin the whole
+     * reconstruction is measured from and the other two set the scale. In exact arithmetic a
+     * rotation changes nothing. In f32 it changes which differences are formed and therefore how
+     * they round — which is exactly the quantity a per-triangle instability would be made of, and
+     * the one thing that can be varied without varying the geometry, the UVs or the coverage.
+     */
+    rotated: [2, 1, 0, 3, 1, 2],
+};
+
+/**
+ * The ground plane, and nothing else — the brief's scene reproduces with this alone.
+ *
+ * @param {object} options
+ * @param {ShadeTexture} options.albedo
+ * @param {number} [options.extent] edge length of the quad in world units. Bigger is worse
+ *      conditioned: at a fixed camera height a wider quad puts its far corner closer to the eye
+ *      plane, so |w| there shrinks and everything derived from it grows. The UV scale is derived
+ *      from the extent, so world-space texel density — and therefore the image in the middle
+ *      distance — is the same at every size, which is what makes two extents comparable at all.
+ * @param {number} [options.segments] subdivision per axis; 1 is the default two-triangle quad
+ * @param {number[]} [options.indices] index buffer override, only meaningful when `segments === 1`
+ * @param {number} [options.yaw_degrees] rotation about +Y, applied after the quad is laid flat
+ * @param {number} [options.roughness]
+ * @param {number} [options.metallic]
+ * @returns {Mesh}
+ */
+export function make_ground({
+                                albedo,
+                                segments = 1,
+                                indices = GROUND_TRIANGULATION.default,
+                                extent = GROUND_EXTENT,
+                                yaw_degrees = 0,
+                                roughness = 0.95,
+                                metallic = 0,
+                            }) {
+
+    const geometry = make_plane_geometry(extent, extent, segments, segments);
+
+    // The texture has to tile, and it has to tile by exactly the same amount however the quad is
+    // cut up — a subdivided plane that sampled the texture differently would confound "subdivision
+    // fixes it" with "subdivision changed the shading".
+    const uv = geometry.getAttribute(StandardAttributes.TextureCoordinates0);
+
+    for (let i = 0; i < uv.data.length; i++) {
+        uv.data[i] *= uv_scale_for(extent);
+    }
+
+    if (segments === 1) {
+        /*
+         Same vertices, same UVs, same winding. Which pairs of corners are joined is the A/B the
+         brief calls its first positive result; which corner comes first within a face is the
+         finer one, and both are just this index buffer.
+        */
+        geometry.index = Attribute.from(new Uint32Array(indices), 1, StandardAttributes.Index);
+    }
+
+    const mesh = new Mesh();
+
+    mesh.name = 'ground';
+    mesh.geometry = new MeshletGeometry();
+
+    meshlet_geometry_build_from_geometry(geometry, mesh.geometry);
+
+    const material = new StandardShadeMaterial();
+
+    material.texture_albedo = albedo;
+    material.roughness_factor = roughness;
+    material.metallic_factor = metallic;
+
+    mesh.material = material;
+
+    /*
+     −90° about X lays the plane flat with its normal pointing at +Y.
+
+     A yaw on top of that is the control that separates *which diagonal the seam lies on* from
+     *which of the two triangles is which*. 180° is a symmetry of both the quad and the shared edge
+     — the world line x = −z maps to itself — but it exchanges the triangles' corners: the one whose
+     odd vertex sat behind the eye plane now has two there, and the other way round. So the seam
+     stays exactly where it was on screen while the two triangles swap roles, which is the one
+     experiment that can tell a property of the *edge* from a property of a *triangle*.
+
+     `Transform64` keeps its matrix by hand, so the write is only real after `updateMatrix`, and the
+     world bounds the `meshes` table publishes only exist after `updateMatrices` — a mesh added on
+     its own is never reached by the scene's hierarchy walk.
+    */
+    const rotation = Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2);
+
+    if (yaw_degrees !== 0) {
+        const yaw = Quaternion.fromAxisAngle(Vector3.up, yaw_degrees * Math.PI / 180);
+
+        rotation.multiplyQuaternions(yaw, rotation);
+        rotation.normalize();
+    }
+
+    mesh.transform_local.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+    mesh.transform_local.updateMatrix();
+    mesh.updateMatrices();
+
+    return mesh;
+}

package/src/shade/playground/ground_seam/measure_flicker.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Which of the ground quad's two triangles covers each pixel, and where on the plane it lands.
+ *
+ * The classification is `sign(x + z)`: the default triangulation's shared edge is the world line
+ * `x = −z` (v2→v1 of `make_plane_geometry`'s 1×1 quad, laid flat by the −90° X rotation), so the
+ * two triangles are exactly the two sides of `x + z = 0`. For the flipped index buffer the shared
+ * edge is `x = z` instead, so `side_flipped` carries `sign(x − z)` alongside it and a caller can
+ * ask about whichever diagonal is currently in the mesh.
+ *
+ * @param {PerspectiveCamera} camera must already have had `update_matrices` run for this frame
+ * @param {number} width in pixels
+ * @param {number} height in pixels
+ * @param {number} [extent] half-width of the quad; pixels outside it are not ground
+ * @returns {{side: Int8Array, side_flipped: Int8Array, round_trip_error_px: number, covered: number}}
+ * `side` is −1, +1 or 0 (not ground). `round_trip_error_px` is the worst error, in pixels, from
+ * projecting a recovered world point back through the forward matrix — a sanity check on the whole
+ * convention, which should be a small fraction of a pixel.
+ */
+export function classify_ground(camera: PerspectiveCamera, width: number, height: number, extent?: number): {
+    side: Int8Array;
+    side_flipped: Int8Array;
+    round_trip_error_px: number;
+    covered: number;
+};
+/**
+ * Owns the render target, the readback buffer, and the frame-driving loop.
+ *
+ * @param {object} context
+ * @param {Renderer} context.renderer
+ * @param {Scene} context.scene
+ * @param {PerspectiveCamera} context.camera
+ */
+export function attach_measurement({ renderer, scene, camera }: {
+    renderer: Renderer;
+    scene: Scene;
+    camera: PerspectiveCamera;
+}): {
+    frame: (time_delta_s?: number) => void;
+    settle: (n: number) => Promise<void>;
+    burst: ({ settle_frames, frames }?: {
+        settle_frames?: number;
+        frames?: number;
+    }) => Promise<{
+        spread: Float32Array;
+        mean: Float32Array;
+        width: number;
+        height: number;
+    }>;
+    read_depth: () => Promise<{
+        depth: Float32Array;
+        width: number;
+        height: number;
+    }>;
+    readonly capture: any;
+};
+/**
+ * Where a world-space line on the ground plane lands on screen, as a signed-distance function.
+ *
+ * A projective map takes a straight line to a straight line, so two projected points are the whole
+ * of it. This exists so a profile can be taken *across* the seam in pixels: the half-plane means a
+ * split reports cannot tell a step at the boundary from a smooth gradient over the whole frame, and
+ * that is exactly the difference between "a seam" and "one half of the view is more oblique".
+ *
+ * @param {PerspectiveCamera} camera
+ * @param {number} width
+ * @param {number} height
+ * @param {number[]} direction unit direction of the line in the XZ plane
+ * @returns {function(number, number): number} pixel → signed perpendicular distance, in pixels
+ */
+export function screen_line_distance(camera: PerspectiveCamera, width: number, height: number, direction: number[]): (arg0: number, arg1: number) => number;
+//# sourceMappingURL=measure_flicker.d.ts.map

package/src/shade/playground/ground_seam/measure_flicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure_flicker.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ground_seam/measure_flicker.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;GAiBG;AACH,kEARW,MAAM,UACN,MAAM,WACN,MAAM;UACG,SAAS;kBAAgB,SAAS;yBAAuB,MAAM;aAAW,MAAM;EAmHnG;AAED;;;;;;;GAOG;AACH;IAJ6B,QAAQ;IACX,KAAK;IACO,MAAM;;2BAqE7B,MAAM;gBAQN,MAAM;;QAoFW,aAAa,GAA9B,MAAM;QACW,MAAM,GAAvB,MAAM;;gBACa,YAAY;cAAQ,YAAY;eAAS,MAAM;gBAAU,MAAM;;;eA4DhE,YAAY;eAAS,MAAM;gBAAU,MAAM;;;EAkE3E;AAED;;;;;;;;;;;;;GAaG;AACH,uEALW,MAAM,UACN,MAAM,aACN,MAAM,EAAE,UACG,MAAM,QAAE,MAAM,KAAG,MAAM,CAyC5C"}