@woosh/meep-engine 3.47.0 → 3.49.0

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

@@ -0,0 +1,48 @@
+/**
+ * Build one of the scenes.
+ *
+ * @param {import("../../renderer/Renderer.js").Renderer} renderer
+ * @param {string} name one of {@link CONTACT_SCENE_NAMES}
+ * @returns {Promise<ContactScene>}
+ */
+export function create_contact_scene(renderer: import("../../renderer/Renderer.js").Renderer, name: string): Promise<ContactScene>;
+/**
+ * The scenes' names, in the order the panel lists them.
+ * @type {string[]}
+ */
+export const CONTACT_SCENE_NAMES: string[];
+export type ContactScene = {
+    name: string;
+    title: string;
+    /**
+     * what this scene is built to show
+     */
+    failure: string;
+    scene: Scene;
+    /**
+     * unit vector toward the sun
+     */
+    to_light: Float32Array;
+    /**
+     * camera framings, [from, to]
+     */
+    presets: {
+        [x: string]: number[][];
+    };
+    /**
+     * camera at time t (seconds of path), into from and to
+     */
+    path: (arg0: number, arg1: number[], arg2: number[]) => void;
+    /**
+     * movers at time t
+     */
+    update: (arg0: number) => void;
+    /**
+     * controls the scene asks for when it is opened
+     */
+    defaults: {
+        taa?: boolean;
+    };
+};
+import { Scene } from "../../renderer/scene/Scene.js";
+//# sourceMappingURL=scenes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scenes.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/contact_shadows/scenes.js"],"names":[],"mappings":"AA4lBA;;;;;;GAMG;AACH,+CAJW,OAAO,4BAA4B,EAAE,QAAQ,QAC7C,MAAM,GACJ,QAAQ,YAAY,CAAC,CAUjC;AArBD;;;GAGG;AACH,kCAFU,MAAM,EAAE,CAEqC;;UArkBzC,MAAM;WACN,MAAM;;;;aACN,MAAM;WACN,KAAK;;;;cACL,YAAY;;;;;YACL,MAAM,GAAE,MAAM,EAAE,EAAE;;;;;iBAChB,MAAM,QAAE,MAAM,EAAE,QAAE,MAAM,EAAE,KAAG,IAAI;;;;mBACjC,MAAM,KAAG,IAAI;;;;cACtB;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAC;;sBAdP,+BAA+B"}

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

@@ -0,0 +1,620 @@
+import { Color } from "../../../core/color/Color.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { BoxGeometry } from "../../renderer/geometry/BoxGeometry.js";
+import { CylinderGeometry } from "../../renderer/geometry/CylinderGeometry.js";
+import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { UVSphereGeometry } from "../../renderer/geometry/UVSphereGeometry.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { TransparencyMode } from "../../renderer/material/TransparencyMode.js";
+import { move_primitive, place_primitive } from "../../renderer/scene/rows/place_primitive.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { make_flat_environment } from "../skinned_blas_refit/flat_environment.js";
+import { make_bump_normal_texture, make_leaf_texture } from "./textures.js";
+
+/**
+ * @typedef {Object} ContactScene
+ * @property {string} name
+ * @property {string} title
+ * @property {string} failure what this scene is built to show
+ * @property {Scene} scene
+ * @property {Float32Array} to_light unit vector toward the sun
+ * @property {Object<string, number[][]>} presets camera framings, [from, to]
+ * @property {function(number, number[], number[]): void} path camera at time t (seconds of path), into from and to
+ * @property {function(number): void} update movers at time t
+ * @property {{taa?: boolean}} defaults controls the scene asks for when it is opened
+ */
+
+const DEG = Math.PI / 180;
+
+/**
+ * Everything a scene shares: a scene with a dataset, a box placer, materials, a flat sky and a sun.
+ *
+ * @param {import("../../renderer/Renderer.js").Renderer} renderer
+ * @param {number} elevation of the sun, degrees
+ * @param {number} azimuth of the sun about +y from +z, degrees
+ */
+async function scene_base(renderer, elevation, azimuth) {
+    await MeshoptClusterizer.ready;
+
+    const scene = new Scene();
+
+    scene.dataset = new EntityComponentDataset();
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const cube = new BoxGeometry();
+
+    /**
+     * @param {number[]} rgb
+     * @param {number} [roughness]
+     */
+    const material = (rgb, roughness = 0.8) => {
+        const result = new StandardShadeMaterial();
+
+        result.diffuse_color.copy(new Color(...rgb));
+        result.roughness_factor = roughness;
+        result.metallic_factor = 0;
+
+        return result;
+    };
+
+    /**
+     * @param {import("../../renderer/geometry/MeshletGeometry.js").MeshletGeometry} geometry
+     * @param {StandardShadeMaterial} mat
+     * @param {number[]} position
+     * @param {number[]} [scale]
+     * @param {number[]} [rotation] quaternion
+     * @param {string} [name]
+     */
+    const place = (geometry, mat, position, scale = [1, 1, 1], rotation = [0, 0, 0, 1], name = '') => {
+        const transform = new Transform64();
+
+        transform.setTranslation(position[0], position[1], position[2]);
+        transform.setScale(scale[0], scale[1], scale[2]);
+        transform.setRotation(rotation[0], rotation[1], rotation[2], rotation[3]);
+        transform.updateMatrix();
+
+        return { entity: place_primitive(scene_context, geometry, mat, transform, { name }), transform };
+    };
+
+    /**
+     * A box from its base centre: [x, y of the base, z], [width, height, depth].
+     */
+    const box = (mat, base, size, rotation, name = 'box') => place(
+        cube, mat, [base[0], base[1] + size[1] * 0.5, base[2]], size, rotation, name
+    );
+
+    scene.lights.environment = make_flat_environment([0.05, 0.065, 0.09]);
+
+    const to_light = new Float32Array([
+        Math.cos(elevation * DEG) * Math.sin(azimuth * DEG),
+        Math.sin(elevation * DEG),
+        Math.cos(elevation * DEG) * Math.cos(azimuth * DEG),
+    ]);
+
+    const sun = make_sunlight({
+        intensity: 3,
+        temperature: 5800,
+        direction: new Vector3(-to_light[0], -to_light[1], -to_light[2]),
+    });
+
+    place_light(scene, sun);
+
+    const ground = material([0.5, 0.48, 0.45], 0.9);
+
+    box(ground, [0, -0.2, -40], [200, 0.2, 200], undefined, 'ground');
+
+    return { scene, scene_context, material, place, box, cube, sun, to_light };
+}
+
+/**
+ * Write a camera on a circle about `centre` into from/to.
+ */
+function orbit(from, to, centre, radius, height, angle) {
+    from[0] = centre[0] + Math.sin(angle) * radius;
+    from[1] = height;
+    from[2] = centre[2] + Math.cos(angle) * radius;
+
+    to[0] = centre[0];
+    to[1] = centre[1];
+    to[2] = centre[2];
+}
+
+/**
+ * Half a turn about an axis, as a quaternion.
+ * @param {number[]} axis unit
+ * @param {number} angle radians
+ */
+function rotation(axis, angle) {
+    const q = new Quaternion();
+
+    q.fromAxisAngle(new Vector3(...axis), angle);
+
+    return [q.x, q.y, q.z, q.w];
+}
+
+const scenes = {
+    /**
+     * The depth buffer is a heightfield: it holds each caster's front and nothing behind it, so a
+     * contact pass guesses how thick every pixel is. Thin poles and a thin floating plank get the
+     * guess too thick (shadow smeared and lengthened behind them); a block two and a half metres deep
+     * gets it too thin (a ray passing behind its front face reads as passing behind it).
+     */
+    async thickness(renderer) {
+        const base = await scene_base(renderer, 28, -70);
+        const { material, box, place } = base;
+
+        const light = material([0.75, 0.72, 0.66]);
+        const dark = material([0.32, 0.34, 0.38]);
+
+        for (const [i, radius] of [0.01, 0.025, 0.05].entries()) {
+            place(new CylinderGeometry(radius, radius, 1.5, 12), dark, [-2.6 + i * 0.5, 0.75, 0.2], undefined, undefined, 'pole');
+        }
+
+        // a 2 cm plank 25 cm off the ground on two thin legs
+        box(light, [-0.7, 0.25, 0.4], [1.2, 0.02, 0.4], undefined, 'plank');
+        box(dark, [-1.2, 0, 0.4], [0.02, 0.25, 0.02], undefined, 'leg');
+        box(dark, [-0.2, 0, 0.4], [0.02, 0.25, 0.02], undefined, 'leg');
+
+        box(light, [0.6, 0, 0.2], [0.5, 0.5, 0.5], undefined, 'cube');
+
+        // deep along the view, so rays behind its front face are inside it
+        box(light, [2.0, 0, -0.8], [1.0, 1.2, 2.5], undefined, 'block');
+
+        return {
+            ...base,
+            name: 'thickness',
+            title: 'Thickness: thin poles, a floating plank, a deep block',
+            failure: 'The depth buffer is a heightfield: thin casters smear, thick ones leak.',
+            presets: { default: [[0, 1.6, 5.2], [0, 0.4, 0]] },
+            path(t, from, to) {
+                orbit(from, to, [0, 0.4, 0], 5.2, 1.6, Math.sin(t * 0.25) * 40 * DEG);
+            },
+            update() {
+            },
+            defaults: {},
+        };
+    },
+
+    /**
+     * Receivers the sun grazes at 8°: a flat ground the camera also grazes, a low-poly sphere and
+     * cylinder whose smooth shading normals disagree with their faceted depth, a ramp, and a slab whose
+     * bumps exist only in its normal map. A ray leaving such a surface runs almost along it, so the
+     * surface's own neighbouring depths sit just in front of the ray.
+     */
+    async grazing(renderer) {
+        const base = await scene_base(renderer, 8, -60);
+        const { material, box, place } = base;
+
+        const light = material([0.75, 0.72, 0.66]);
+
+        place(new UVSphereGeometry(0.6, 8, 6), light, [-1.6, 0.6, -0.5], undefined, undefined, 'low-poly sphere');
+        place(new CylinderGeometry(0.4, 0.4, 1.2, 6), light, [0, 0.6, -1.2], undefined, undefined, 'hexagonal column');
+
+        box(light, [1.8, 0, -0.5], [1.6, 0.05, 2.4], rotation([1, 0, 0], -12 * DEG), 'ramp');
+
+        const bumpy = material([0.62, 0.6, 0.56], 0.7);
+
+        bumpy.texture_normal = make_bump_normal_texture();
+
+        box(bumpy, [-0.4, 0, 1.4], [2.4, 0.02, 1.6], undefined, 'normal-mapped slab');
+
+        return {
+            ...base,
+            name: 'grazing',
+            title: 'Grazing sun: flat ground, facets, a ramp, a normal map',
+            failure: 'Self-shadowing where the sun or the view grazes a surface.',
+            presets: { default: [[0, 0.7, 6], [0, 0.3, -2]] },
+            path(t, from, to) {
+                const s = Math.sin(t * 0.3);
+
+                from[0] = s * 1.5;
+                from[1] = 0.7 + 0.3 * Math.sin(t * 0.21);
+                from[2] = 6 - 2 * (0.5 + 0.5 * s);
+
+                to[0] = 0;
+                to[1] = 0.3;
+                to[2] = -2;
+            },
+            update() {
+            },
+            defaults: {},
+        };
+    },
+
+    /**
+     * Small casters seen from every side: a table, a sphere and a cube on the ground, and a post that
+     * hides the cube from part of the orbit. A screen-space shadow exists only where its caster is on
+     * screen and in front, and its reach is counted in pixels, so the same contact changes as the
+     * camera goes round.
+     */
+    async view(renderer) {
+        const base = await scene_base(renderer, 35, -40);
+        const { material, box, place } = base;
+
+        const light = material([0.75, 0.72, 0.66]);
+        const wood = material([0.55, 0.38, 0.22]);
+
+        box(wood, [0, 0.72, 0], [1.2, 0.04, 0.8], undefined, 'table top');
+
+        for (const [x, z] of [[-0.55, -0.35], [0.55, -0.35], [-0.55, 0.35], [0.55, 0.35]]) {
+            box(wood, [x, 0, z], [0.05, 0.72, 0.05], undefined, 'table leg');
+        }
+
+        place(new UVSphereGeometry(0.3, 32, 16), light, [1.4, 0.3, 0.6], undefined, undefined, 'sphere');
+        box(light, [-1.5, 0, 0.8], [0.4, 0.4, 0.4], undefined, 'cube');
+        box(material([0.3, 0.32, 0.36]), [-1.5, 0, 1.6], [0.15, 1.8, 0.15], undefined, 'post');
+
+        return {
+            ...base,
+            name: 'view',
+            title: 'View dependence: an orbit round small casters',
+            failure: 'Shadows that change as the camera moves: occluded casters, reach in pixels.',
+            presets: { default: [[0, 1.8, 4], [0, 0.35, 0]], far: [[0, 4, 11], [0, 0.35, 0]] },
+            path(t, from, to) {
+                orbit(from, to, [0, 0.35, 0], 4 + Math.sin(t * 0.17) * 1.5, 1.4 + 0.6 * Math.sin(t * 0.23), t * 0.35);
+            },
+            update() {
+            },
+            defaults: {},
+        };
+    },
+
+    /**
+     * Fine detail under a moving camera: a grating of 2 cm slats a hand's width off the ground, a picket
+     * fence and a patch of thin blades. Every sub-pixel step of the camera, and every TAA jitter,
+     * changes which slats the depth buffer holds.
+     */
+    async noise(renderer) {
+        const base = await scene_base(renderer, 40, -55);
+        const { material, box } = base;
+
+        const metal = material([0.6, 0.6, 0.62], 0.5);
+        const wood = material([0.55, 0.38, 0.22]);
+        const grass = material([0.25, 0.42, 0.15]);
+
+        for (let i = 0; i < 40; i++) {
+            box(metal, [-1.5 + i * 0.06, 0.1, 0.5], [0.02, 0.02, 1.4], undefined, 'grating slat');
+        }
+
+        box(metal, [-0.3, 0, 0.0], [2.4, 0.1, 0.03], undefined, 'grating support');
+        box(metal, [-0.3, 0, 1.0], [2.4, 0.1, 0.03], undefined, 'grating support');
+
+        for (let i = 0; i < 30; i++) {
+            box(wood, [-2 + i * 0.12, 0, -1.2], [0.03, 0.9, 0.03], undefined, 'picket');
+        }
+
+        box(wood, [-0.25, 0.75, -1.2], [3.7, 0.05, 0.03], undefined, 'rail');
+
+        // a deterministic scatter of blades
+        let seed = 12345;
+        const random = () => {
+            seed = (seed * 1664525 + 1013904223) >>> 0;
+            return seed / 4294967296;
+        };
+
+        for (let i = 0; i < 300; i++) {
+            box(grass, [1.5 + random() * 1.5, 0, 0.5 + random() * 1.5], [0.01, 0.15 + random() * 0.15, 0.01], undefined, 'blade');
+        }
+
+        return {
+            ...base,
+            name: 'noise',
+            title: 'Fine detail: a grating, pickets and blades, camera moving',
+            failure: 'Noise and TAA instability: sub-pixel detail flickering in and out of the depth buffer.',
+            presets: { default: [[0.2, 1.3, 3.6], [0.2, 0.2, 0.2]] },
+            path(t, from, to) {
+                const s = Math.sin(t * 0.4);
+
+                from[0] = 0.2 + s * 1.2;
+                from[1] = 1.3 + 0.15 * Math.sin(t * 0.7);
+                from[2] = 3.6 - 0.4 * Math.cos(t * 0.4);
+
+                to[0] = 0.2 + s * 0.6;
+                to[1] = 0.2;
+                to[2] = 0.2;
+            },
+            update() {
+            },
+            defaults: { taa: true },
+        };
+    },
+
+    /**
+     * Casters that move, and ground that the camera's pan uncovers from behind pillars: a box circling
+     * close to the ground, a plank sliding back and forth, a sphere rolling across. The contact pass
+     * keeps no history of its own; what trails is whatever TAA keeps.
+     */
+    async disocclusion(renderer) {
+        const base = await scene_base(renderer, 45, -35);
+        const { material, box, place, scene_context } = base;
+
+        const light = material([0.75, 0.72, 0.66]);
+        const red = material([0.8, 0.25, 0.15], 0.5);
+
+        for (let i = 0; i < 4; i++) {
+            box(light, [-2.25 + i * 1.5, 0, -0.2], [0.3, 2, 0.3], undefined, 'pillar');
+        }
+
+        const orbiter = box(red, [0, 0.05, 1], [0.4, 0.4, 0.4], undefined, 'orbiter');
+        const plank = box(red, [0, 0.12, 1.8], [0.8, 0.03, 0.3], undefined, 'sliding plank');
+        const ball = place(new UVSphereGeometry(0.25, 32, 16), red, [0, 0.25, 0.4], undefined, undefined, 'rolling ball');
+
+        return {
+            ...base,
+            name: 'disocclusion',
+            title: 'Movers and revealed ground: a circling box, a plank, a ball',
+            failure: 'Disocclusion: shadows of moving casters, and ground the camera uncovers.',
+            presets: { default: [[0, 1.5, 4.5], [0, 0.3, 0.6]] },
+            path(t, from, to) {
+                from[0] = Math.sin(t * 0.35) * 2.5;
+                from[1] = 1.5;
+                from[2] = 4.5;
+
+                to[0] = from[0] * 0.4;
+                to[1] = 0.3;
+                to[2] = 0.6;
+            },
+            update(t) {
+                const o = orbiter.transform;
+
+                o.setTranslation(Math.cos(t * 0.9) * 1.2, 0.2 + 0.05 + 0.04 * Math.sin(t * 2.3), 1 + Math.sin(t * 0.9) * 0.6);
+                o.updateMatrix();
+                move_primitive(scene_context, orbiter.entity, o);
+
+                const p = plank.transform;
+
+                p.setTranslation(Math.sin(t * 0.6) * 1.5, 0.12 + 0.015, 1.8);
+                p.updateMatrix();
+                move_primitive(scene_context, plank.entity, p);
+
+                const b = ball.transform;
+
+                b.setTranslation(-2 + ((t * 0.5) % 4), 0.25, 0.4);
+                b.updateMatrix();
+                move_primitive(scene_context, ball.entity, b);
+            },
+            defaults: { taa: true },
+        };
+    },
+
+    /**
+     * Posts whose shadows fall into the view from the left while the camera pans them off the screen,
+     * and a beam above the top edge. Off-screen depth reads as the far plane, which shadows nothing.
+     */
+    async screen_edge(renderer) {
+        const base = await scene_base(renderer, 25, -100);
+        const { material, box } = base;
+
+        const light = material([0.75, 0.72, 0.66]);
+
+        for (let i = 0; i < 5; i++) {
+            box(light, [-3 + i * 0.45, 0, -0.5 + i * 0.6], [0.2, 3, 0.2], undefined, 'post');
+        }
+
+        box(light, [0, 2.4, -1.5], [6, 0.15, 0.15], undefined, 'beam');
+        box(light, [-3.2, 0, -1.5], [0.15, 2.4, 0.15], undefined, 'beam post');
+        box(light, [3.2, 0, -1.5], [0.15, 2.4, 0.15], undefined, 'beam post');
+
+        return {
+            ...base,
+            name: 'screen_edge',
+            title: 'Screen edges: posts panned off the left edge',
+            failure: 'Casters that leave the screen take their contact shadows with them.',
+            presets: { default: [[-0.5, 1.4, 4.5], [-0.5, 0.6, 0]] },
+            path(t, from, to) {
+                const x = -0.5 + 2.5 * (0.5 - 0.5 * Math.cos(t * 0.3));
+
+                from[0] = x;
+                from[1] = 1.4;
+                from[2] = 4.5;
+
+                to[0] = x;
+                to[1] = 0.6;
+                to[2] = 0;
+            },
+            update() {
+            },
+            defaults: {},
+        };
+    },
+
+    /**
+     * One cube and pole pair at 2, 5, 10, 20, 50, 100 and 200 metres down an avenue. The pass reaches
+     * 60 pixels and takes a thickness proportional to depth, so the same contact is short and thin near
+     * the camera and long and fat in world terms far away.
+     */
+    async distance(renderer) {
+        const base = await scene_base(renderer, 30, -60);
+        const { material, box } = base;
+
+        const light = material([0.75, 0.72, 0.66]);
+        const dark = material([0.32, 0.34, 0.38]);
+
+        for (const [i, d] of [2, 5, 10, 20, 50, 100, 200].entries()) {
+            const x = (i % 2 === 0 ? -1 : 1) * (0.6 + d * 0.06);
+
+            box(light, [x, 0, -d], [0.5, 0.5, 0.5], undefined, `cube ${d} m`);
+            box(dark, [x + 0.7, 0, -d], [0.05, 1.5, 0.05], undefined, `pole ${d} m`);
+        }
+
+        return {
+            ...base,
+            name: 'distance',
+            title: 'Distance: the same contact from 2 m to 200 m',
+            failure: 'Scale with distance: a reach in pixels and a thickness in proportion to depth.',
+            presets: { default: [[0, 1.7, 2], [0, 0.6, -60]] },
+            path(t, from, to) {
+                const z = 2 - 18 * (0.5 - 0.5 * Math.cos(t * 0.2));
+
+                from[0] = 0;
+                from[1] = 1.7;
+                from[2] = z;
+
+                to[0] = 0;
+                to[1] = 0.6;
+                to[2] = z - 60;
+            },
+            update() {
+            },
+            defaults: {},
+        };
+    },
+
+    /**
+     * Alpha-tested foliage: plants of crossed leaf cards, a low hedge of them, and grass cards. Cards
+     * are a few millimetres thick in the depth buffer and their cut-outs alias per texel; they are
+     * two-sided, so a back-lit card is also a receiver whose own depth sits in front of its rays.
+     */
+    async foliage(renderer) {
+        const base = await scene_base(renderer, 35, -50);
+        const { material, box } = base;
+
+        const leaves = material([0.22, 0.45, 0.14], 0.8);
+
+        leaves.texture_albedo = make_leaf_texture();
+        leaves.transparency_mode = TransparencyMode.AlphaTested;
+        leaves.draw_side = ShadeDrawSide.Double;
+
+        const card = (base_xyz, size, angle, name) => box(leaves, base_xyz, [size, size, 0.004], rotation([0, 1, 0], angle), name);
+
+        for (const [x, z, s] of [[-1.2, 0, 1.1], [0.4, -0.6, 1.4], [1.6, 0.5, 0.9]]) {
+            for (let k = 0; k < 3; k++) {
+                card([x, 0, z], s, k * 60 * DEG, 'plant card');
+            }
+        }
+
+        for (let i = 0; i < 12; i++) {
+            card([-2 + i * 0.35, 0, 1.6], 0.5, (i % 2) * 90 * DEG + 20 * DEG, 'hedge card');
+        }
+
+        let seed = 777;
+        const random = () => {
+            seed = (seed * 1664525 + 1013904223) >>> 0;
+            return seed / 4294967296;
+        };
+
+        for (let i = 0; i < 80; i++) {
+            card([-2.5 + random() * 5, 0, -1.5 + random() * 2.5], 0.25, random() * Math.PI, 'grass card');
+        }
+
+        return {
+            ...base,
+            name: 'foliage',
+            title: 'Foliage: alpha-tested leaf cards, a hedge, grass',
+            failure: 'Alpha-tested foliage: thin, two-sided, aliasing cut-outs.',
+            presets: { default: [[0, 1.6, 4.6], [0, 0.4, 0]] },
+            path(t, from, to) {
+                orbit(from, to, [0, 0.4, 0], 4.6, 1.6, Math.sin(t * 0.2) * 50 * DEG);
+            },
+            update() {
+            },
+            defaults: { taa: true },
+        };
+    },
+
+    /**
+     * Where the contact term meets the shadow map: a box, a sphere and a column at the sun's angle that
+     * leaves the cascades' bias gap at their bases, and a slab on low supports under a soft shadow-map
+     * penumbra. Multiply darkens where both terms are partial; min does not.
+     */
+    async combine(renderer) {
+        const base = await scene_base(renderer, 35, -45);
+        const { material, box, place } = base;
+
+        const light = material([0.75, 0.72, 0.66]);
+
+        box(light, [-1.2, 0, 0], [1, 0.6, 1], undefined, 'box');
+        place(new UVSphereGeometry(0.4, 48, 24), light, [0.4, 0.4, 0.3], undefined, undefined, 'sphere');
+        place(new CylinderGeometry(0.15, 0.15, 2, 24), light, [1.5, 1, -0.3], undefined, undefined, 'column');
+
+        box(light, [-0.2, 0.08, 1.4], [1.6, 0.04, 0.6], undefined, 'low slab');
+        box(light, [-0.9, 0, 1.4], [0.05, 0.08, 0.5], undefined, 'slab support');
+        box(light, [0.5, 0, 1.4], [0.05, 0.08, 0.5], undefined, 'slab support');
+
+        return {
+            ...base,
+            name: 'combine',
+            title: 'Combining: bias gaps at caster bases, penumbrae, double darkening',
+            failure: 'Double darkening against the shadow map term and its bias.',
+            presets: { default: [[0.3, 1.5, 3.8], [0, 0.2, 0.4]], close: [[0.6, 0.6, 1.6], [0.4, 0.05, 0.3]] },
+            path(t, from, to) {
+                orbit(from, to, [0, 0.2, 0.4], 3.8 - 1.2 * (0.5 - 0.5 * Math.cos(t * 0.3)), 1.5, Math.sin(t * 0.25) * 35 * DEG);
+            },
+            update() {
+            },
+            defaults: {},
+        };
+    },
+
+    /**
+     * A field of posts and boxes with a low sun, and a camera turning on the spot, so the sun's point on
+     * screen crosses the view (rays converge on it) and then lies behind the camera (they leave the
+     * point opposite). Near the sun's point every ray is a few pixels long.
+     */
+    async sun_in_view(renderer) {
+        const base = await scene_base(renderer, 15, 0);
+        const { material, box } = base;
+
+        const light = material([0.75, 0.72, 0.66]);
+
+        for (let i = 0; i < 24; i++) {
+            const a = i / 24 * Math.PI * 2;
+            const r = 3 + (i % 3);
+
+            box(light, [Math.sin(a) * r, 0, Math.cos(a) * r], [0.15, 1.5, 0.15], undefined, 'post');
+            box(light, [Math.sin(a + 0.1) * r * 0.6, 0, Math.cos(a + 0.1) * r * 0.6], [0.4, 0.4, 0.4], undefined, 'cube');
+        }
+
+        return {
+            ...base,
+            name: 'sun_in_view',
+            title: 'Sun in view: turning toward and away from the sun',
+            failure: 'Rays converge on the sun\'s point on screen and are a few pixels long near it.',
+            presets: { toward: [[0, 1.6, 0], [0, 1.0, 8]], away: [[0, 1.6, 0], [0, 1.0, -8]] },
+            path(t, from, to) {
+                const a = t * 0.25;
+
+                from[0] = 0;
+                from[1] = 1.6;
+                from[2] = 0;
+
+                to[0] = Math.sin(a) * 8;
+                to[1] = 1.0;
+                to[2] = Math.cos(a) * 8;
+            },
+            update() {
+            },
+            defaults: {},
+        };
+    },
+};
+
+/**
+ * The scenes' names, in the order the panel lists them.
+ * @type {string[]}
+ */
+export const CONTACT_SCENE_NAMES = Object.keys(scenes);
+
+/**
+ * Build one of the scenes.
+ *
+ * @param {import("../../renderer/Renderer.js").Renderer} renderer
+ * @param {string} name one of {@link CONTACT_SCENE_NAMES}
+ * @returns {Promise<ContactScene>}
+ */
+export function create_contact_scene(renderer, name) {
+    const make = scenes[name];
+
+    if (make === undefined) {
+        throw new Error(`no scene '${name}'; there are ${CONTACT_SCENE_NAMES.join(', ')}`);
+    }
+
+    return make(renderer);
+}