@woosh/meep-engine 3.28.0 → 3.30.0

package/src/shade/playground/vgeo_scene/main.js

@@ -1,6 +1,7 @@
 import { Color } from "../../../core/color/Color.js";
 import { m4_linear_determinant } from "../../../core/geom/3d/mat4/m4_linear_determinant.js";
 import Vector3 from "../../../core/geom/Vector3.js";
+import { GIGABYTE } from "../../../core/science/units/memory/GIGABYTE.js";
 import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
 import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
@@ -25,6 +26,12 @@ 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 { ColorSpace } from "../../renderer/texture/ColorSpace.js";
+import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
+import { TextureWrapType } from "../../renderer/texture/TextureWrapType.js";
+import { ShadeImage } from "../../renderer/texture/source/ShadeImage.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
 import {
     RasterizationCollectionType
 } from "../../renderer/rasterize/expand/RasterizationCollectionType.js";
@@ -76,14 +83,35 @@ const element = id => document.getElementById(id);
 /**
  * Where the containers are served from when the page is opened without a `?scene=`.
  *
- * `tools/geometry/virtual/vgeo_serve.js` binds this by default and answers `/scenes.json` with what
- * it holds, so a page with no parameters finds the scene that is there rather than asking for a URL
- * to be pasted. It is a *separate* origin on purpose: vite refuses `/@fs/` outside the workspace,
- * and a forty-gigabyte directory has no business inside one.
+ * Same origin as the page, and that is the point: `tools/dev/vite_test_assets.js` serves this prefix
+ * out of the package's own `test_assets/` **and** out of an asset root outside the checkout, by
+ * range, so a fifty-gigabyte converted scene is reached from the dev server that is already running.
+ * It used to be `http://localhost:5200` — a second server, started by hand, that this page was
+ * useless without.
  *
  * @type {string}
  */
-const DEFAULT_ORIGIN = 'http://localhost:5200';
+const ASSET_PREFIX = '/test_assets';
+
+/**
+ * What a scene manifest is named, and therefore what {@link resolve_scene_url} asks the asset root
+ * for when the page is opened with no parameters at all.
+ *
+ * @type {string}
+ */
+const SCENE_SUFFIX = '.vgeoscene.json';
+
+/**
+ * What the material sidecar beside a scene manifest is named.
+ *
+ * `vgeo_scene_materials.js` writes it: the material each container is, and the constants to shade
+ * that material with. It is a separate file from the scene because it answers to a separate source
+ * — the original project, extracted — and a scene nobody has done that to is still a scene, so the
+ * page opens with or without it.
+ *
+ * @type {string}
+ */
+const MATERIALS_SUFFIX = '.vgeomaterials.json';
 
 /**
  * Head bytes read on the first request of every container.
@@ -233,6 +261,50 @@ class VGeoScenePlayground {
      */
     mirror_material;
 
+    /**
+     * One material per distinct material the source scene used, when a sidecar was found.
+     *
+     * Empty when it was not, and {@link material} then draws everything as before.
+     *
+     * @type {StandardShadeMaterial[]}
+     */
+    materials = [];
+
+    /**
+     * Which of {@link materials} each container is, indexed the same as the scene manifest's
+     * geometries. `-1` for a container the sidecar had no material for.
+     *
+     * @type {number[]}
+     */
+    geometry_material = [];
+
+    /**
+     * Containers drawn with their own material rather than with {@link material}.
+     * @type {number}
+     */
+    materialised = 0;
+
+    /**
+     * Texture slots bound from the sidecar — zero when the scene has no texture coordinates to
+     * sample them with, which is the ordinary case for a converted set.
+     *
+     * @type {number}
+     */
+    textures_bound = 0;
+
+    /**
+     * What a container the sidecar had no material for is drawn with.
+     *
+     * Not {@link material}: that one is a pale grey chosen to read well when it is the *only*
+     * material in the frame, and at 0.72 it is brighter than almost anything the extraction
+     * produces. Six hundred of those among two thousand real surfaces do not look like missing
+     * data, they look like the scene — and they drag the exposure down over everything else. A
+     * neutral dielectric grey sits in the range the real materials occupy.
+     *
+     * @type {StandardShadeMaterial}
+     */
+    unmaterialised;
+
     /**
      * Instances placed with a negative-determinant transform.
      * @type {number}
@@ -428,9 +500,9 @@ class VGeoScenePlayground {
 
         const worker = async () => {
             while (next < geometries.length) {
-                const record = geometries[next++];
+                const index = next++;
 
-                await this.open_one(record, options);
+                await this.open_one(geometries[index], options, index);
             }
         };
 
@@ -457,7 +529,7 @@ class VGeoScenePlayground {
      * @param {VGeoReadOptions} options
      * @returns {Promise<void>}
      */
-    async open_one(record, options) {
+    async open_one(record, options, index = -1) {
         const url = new URL(record.file, this.base).href;
 
         try {
@@ -484,6 +556,19 @@ class VGeoScenePlayground {
 
             const matrices = record.instances;
 
+            /*
+             The container's own material when the sidecar named one. There is no per-instance
+             material here and there is nothing to choose between: a `.vgeo` is one primitive of the
+             source document and a glTF primitive has exactly one material, so the container *is*
+             the material bucket.
+            */
+            const own_material = index < 0 ? undefined : this.materials[this.geometry_material[index]];
+            const material = own_material ?? this.unmaterialised ?? this.material;
+
+            if (own_material !== undefined) {
+                this.materialised++;
+            }
+
             const transform = new Transform64();
 
             for (let i = 0; i < matrices.length; i += 16) {
@@ -512,9 +597,16 @@ class VGeoScenePlayground {
                     this.mirrored++;
                 }
 
+                /*
+                 `?mirrored=` splits reflected instances into a bucket of their own, which is a
+                 diagnostic about winding rather than about materials — so it takes precedence when
+                 it is on, and the container's own material is what draws otherwise.
+                */
                 place_primitive(
                     this.scene_context, geometry,
-                    reflected ? this.mirror_material : this.material,
+                    reflected && this.mirror_material !== this.material
+                        ? this.mirror_material
+                        : material,
                     transform
                 );
 
@@ -612,6 +704,8 @@ class VGeoScenePlayground {
                 refused: this.refused,
                 instances: this.placed,
                 mirrored: this.mirrored,
+                materials: this.materials.length,
+                materialised: this.materialised,
                 faces: this.manifest === undefined ? 0 : scene_faces(this.manifest),
                 bytes: this.manifest?.total_bytes ?? 0,
                 bytes_read,
@@ -952,12 +1046,328 @@ function human_bytes(bytes) {
 }
 
 /**
- * Where the scene manifest is, out of `?scene=` or out of the asset server's own listing.
+ * Build the engine material a sidecar entry describes.
  *
- * The listing is what makes the page turn-key: `vgeo_serve.js` answers `/scenes.json` with the
- * manifests in the directory it is serving, so a page opened with no parameters at all finds the
- * one scene that is there. More than one and it takes the first and says which, because a page
- * that refuses to choose between two is a page that shows nothing.
+ * **What is bound here is the `constant` block, not the textures**, and that is a property of this
+ * asset rather than of the extraction. Zorah's containers carry position, normal and tangent and no
+ * texture coordinates at all — the source document the conversion read is `POSITION` only — so
+ * there is nothing to sample an albedo map *with* until a UV-carrying source is built and the
+ * containers are made again from it. The material's `textures` are in the sidecar and the images
+ * are on disk, waiting for that.
+ *
+ * The constants are not a stand-in for the textures. `albedo` is the extracted base colour map's
+ * own alpha-weighted mean multiplied by the material's authored tint, `roughness` and `metallic`
+ * come from the real ORM, and the draw side and alpha mode are what the material instance actually
+ * overrode. What the surface loses is its detail, not its identity.
+ *
+ * @param {object} definition one entry of the sidecar's `materials`
+ * @param {number} side what `?side=` asked for, which still wins
+ * @returns {StandardShadeMaterial}
+ */
+function make_scene_material(definition, side) {
+    const material = new StandardShadeMaterial();
+
+    material.name = definition.name;
+
+    const constant = definition.constant ?? {};
+    const albedo = constant.albedo ?? [0.72, 0.74, 0.78];
+
+    material.diffuse_color.set(albedo[0], albedo[1], albedo[2], 1);
+
+    /*
+     With no ORM bound the material samples the engine's default white pixel, so every one of these
+     factors is the value itself rather than a multiplier on a map.
+    */
+    material.roughness_factor = constant.roughness ?? 0.55;
+    material.metallic_factor = constant.metallic ?? 0;
+
+    /*
+     `ambient = fma(orm.r, ambient_factors.a, ambient_factors.b)`. `StandardShadeMaterial`
+     constructs with `LinearModifier(1, 1)`, which against the default white ORM pixel is 2 and
+     saturates to 1 in the G-buffer's unorm alpha — a material that has said nothing about occlusion
+     is therefore unoccluded, which is the right answer and the reason the default is that pair.
+
+     This states it rather than reaching it by saturation, because the value here has to survive
+     `bind_scene_textures` switching to (1, 0) when a real ORM arrives: Unreal's red channel *is*
+     ambient occlusion and the conversion wants it applied, which is a decision about the source
+     rather than a correction to the engine.
+    */
+    material.ambient_factors.a = 0;
+    material.ambient_factors.b = 1;
+
+    const emissive = definition.emissive_factor ?? [0, 0, 0];
+
+    material.emissive_factor.set(emissive[0], emissive[1], emissive[2], 1);
+
+    /*
+     A two-sided material is two-sided because the artist said so — foliage cards, cloth, thin
+     stone tracery — and drawing it `Front` loses half of it. `?side=` overrides the lot, because
+     its whole purpose is to ask whether something is missing or merely culled.
+    */
+    material.draw_side = side ?? (definition.draw_side === 'Double'
+        ? ShadeDrawSide.Double
+        : definition.draw_side === 'Back' ? ShadeDrawSide.Back : ShadeDrawSide.Front);
+
+    /*
+     Alpha testing needs an alpha to test and the albedo texture is what carries it, so a masked
+     material with no texture bound would discard by a constant and disappear entirely. Opaque is
+     the honest fallback until the textures can be sampled.
+    */
+    material.transparency_mode = TransparencyMode.Opaque;
+
+    return material;
+}
+
+/**
+ * An environment of one constant radiance, for asking how much of a surface's brightness is its own
+ * colour and how much is the sky.
+ *
+ * The real environment is an HDR sky with a sun in it, and a rough reflection integrates a wide
+ * enough lobe to gather that sun — so comparing a surface against one pixel of the background
+ * proves nothing about whether the image-based lighting is over-contributing. Against a **uniform**
+ * environment the comparison is exact: no reflected direction can return more than the constant, so
+ * a surface brighter than it is being lit by more than it reflects, and by how much.
+ *
+ * Big enough to carry a mip chain rather than 1×1 — `sample_environment_map` reads `lod` and
+ * `lod + 1`, and a texture with one level has nowhere to read the second from. Every level is the
+ * same value, so the roughness the sampler picks its lod from cannot change the answer.
+ *
+ * @param {number} value linear radiance, the same in all three channels
+ * @returns {ShadeTexture}
+ */
+function make_uniform_environment(value) {
+    const size = 64;
+
+    // An environment is half-float; a float32 sampler uploads at twice the pitch the texture was
+    // created with and the whole thing is refused. `Float16Array` converts on assignment, so these
+    // are plain radiances rather than bit patterns — writing the bits instead stores the *number*
+    // 14336 and lights the scene with it.
+    const sampler = Sampler2D.float16(4, size, size);
+
+    for (let i = 0; i < size * size; i++) {
+        sampler.data[i * 4] = value;
+        sampler.data[i * 4 + 1] = value;
+        sampler.data[i * 4 + 2] = value;
+        sampler.data[i * 4 + 3] = 1;
+    }
+
+    const image = ShadeImage.fromSampler2D(sampler);
+
+    image.color_space = ColorSpace.LinearSRGB;
+
+    const texture = ShadeTexture.from(image);
+
+    texture.wrapS = TextureWrapType.ClampToEdge;
+    texture.wrapT = TextureWrapType.ClampToEdge;
+
+    return texture;
+}
+
+/**
+ * Fetch one extracted texture and make a {@link ShadeTexture} of it.
+ *
+ * `createImageBitmap` rather than `ShadeImage.fromArrayBuffer`: these are ordinary PNGs written by
+ * the extraction and the browser's own decoder is what should read them.
+ * `colorSpaceConversion: 'none'` matters — the extraction already wrote the exact bytes Unreal had,
+ * and letting the browser convert them to the display profile on the way in shifts every albedo.
+ *
+ * A UDIM set has no place to go in a fixed material, so its first tile is taken and the caller is
+ * told; composing the grid and rescaling the UVs belongs in the converter, not here.
+ *
+ * @param {object} slot one of a sidecar material's `textures`
+ * @param {string} base where the textures are served from
+ * @returns {Promise<ShadeTexture|null>}
+ */
+async function load_scene_texture(slot, base) {
+    const file = slot.files?.[0]?.file;
+
+    if (file === undefined || base === null) {
+        return null;
+    }
+
+    const url = `${base.replace(/\/$/, '')}/${file}`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+        throw new Error(`${url} answered HTTP ${response.status}`);
+    }
+
+    const bitmap = await createImageBitmap(await response.blob(), {
+        premultiplyAlpha: 'none',
+        colorSpaceConversion: 'none',
+    });
+
+    const image = ShadeImage.fromImageBitmap(bitmap);
+
+    /*
+     A base colour map is sRGB encoded and everything else — normals, and an ORM's occlusion,
+     roughness and metalness — is linear data that must not be decoded on the way in. The extraction
+     read the flag off the Unreal asset and wrote it into the sidecar rather than guessing it from
+     the slot, because the two disagree often enough to matter.
+    */
+    image.color_space = slot.srgb === true ? ColorSpace.SRGB : ColorSpace.None;
+
+    return ShadeTexture.from(image);
+}
+
+/**
+ * Bind the real maps onto the materials, where the scene can sample them.
+ *
+ * Returns what happened rather than throwing: one texture that will not load is one material drawn
+ * from its constants, and the rest of the scene is unaffected.
+ *
+ * @param {object[]} definitions the sidecar's materials
+ * @param {StandardShadeMaterial[]} materials what {@link make_scene_material} built from them
+ * @param {string} base
+ * @returns {Promise<{bound: number, failed: string[], udim: number}>}
+ */
+async function bind_scene_textures(definitions, materials, base) {
+    const cache = new Map();
+    const failed = [];
+
+    let bound = 0;
+    let udim = 0;
+
+    const obtain = async (slot) => {
+        const key = slot.files?.[0]?.file;
+
+        if (key === undefined) {
+            return null;
+        }
+
+        if (!cache.has(key)) {
+            cache.set(key, load_scene_texture(slot, base));
+        }
+
+        return cache.get(key);
+    };
+
+    const SLOTS = [
+        ['albedo', 'texture_albedo'],
+        ['normal', 'texture_normal'],
+        ['orm', 'texture_orm'],
+    ];
+
+    await Promise.all(definitions.map(async (definition, i) => {
+        for (const [name, field] of SLOTS) {
+            const slot = definition.textures?.[name];
+
+            if (slot === undefined || slot.missing === true) {
+                continue;
+            }
+
+            if (slot.udim === true) {
+                udim++;
+            }
+
+            try {
+                const texture = await obtain(slot);
+
+                if (texture !== null) {
+                    materials[i][field] = texture;
+                    bound++;
+                }
+            } catch (error) {
+                failed.push(`${definition.name}.${name}: ${error.message ?? error}`);
+            }
+        }
+
+        /*
+         The tint already multiplied the texture's mean to make the constant. With the texture
+         itself bound, the mean has to come back out or the surface is darkened by its own colour
+         twice.
+        */
+        if (materials[i].texture_albedo !== undefined) {
+            const tint = definition.diffuse_color ?? [1, 1, 1, 1];
+
+            materials[i].diffuse_color.set(tint[0], tint[1], tint[2], 1);
+        }
+
+        /*
+         Every one of these is a **multiplier on the map**, as glTF specifies — `roughness = orm.g *
+         roughness_factor`, `metalness = orm.b * metallic_factor`. The constants that stood in for
+         the map have to give way, or the map is scaled by the mean of itself.
+
+         glTF's default for both factors is 1 and `StandardShadeMaterial`'s own is 0 for metalness,
+         which is right for a bare material with no map to multiply. The extraction wrote that 0
+         through even where it was binding an ORM, and a factor of zero suppressing the map is the
+         specified behaviour rather than a fault in it — so this is the extraction saying which of
+         the two cases it is in.
+        */
+        if (materials[i].texture_orm !== undefined) {
+            materials[i].roughness_factor = definition.roughness_factor ?? 1;
+            materials[i].metallic_factor = definition.metallic_factor ?? 1;
+
+            materials[i].ambient_factors.a = 1;
+            materials[i].ambient_factors.b = 0;
+        }
+    }));
+
+    return { bound, failed, udim };
+}
+
+/**
+ * Read the material sidecar beside a scene, if there is one.
+ *
+ * `?materials=<url>` names one explicitly and `?materials=off` refuses it, which is how the page
+ * still shows what a converted scene looks like with nothing but geometry — the picture this page
+ * had before there was anything to say about its surfaces.
+ *
+ * A sidecar that is absent is not an error. It is the ordinary case for any scene that has not had
+ * its source project extracted.
+ *
+ * @param {string} scene_url
+ * @param {URLSearchParams} parameters
+ * @returns {Promise<object|null>}
+ */
+async function load_scene_materials(scene_url, parameters) {
+    const requested = parameters.get('materials');
+
+    if (requested === 'off') {
+        return null;
+    }
+
+    const url = requested !== null && requested !== ''
+        ? new URL(requested, globalThis.location.href).href
+        : scene_url.replace(new RegExp(`${SCENE_SUFFIX.replace(/\./g, '\\.')}$`), MATERIALS_SUFFIX);
+
+    if (url === scene_url) {
+        return null;
+    }
+
+    let response;
+
+    try {
+        response = await fetch(url);
+    } catch (error) {
+        console.warn(`material sidecar ${url} — ${error.message ?? error}`);
+
+        return null;
+    }
+
+    if (!response.ok) {
+        // the ordinary case: this scene has no sidecar
+        return null;
+    }
+
+    const sidecar = await response.json();
+
+    if (sidecar.format !== 1) {
+        console.warn(`${url} is a format-${sidecar.format} sidecar and this page reads format 1`);
+
+        return null;
+    }
+
+    return sidecar;
+}
+
+/**
+ * Where the scene manifest is, out of `?scene=` or out of the asset root's own listing.
+ *
+ * The listing is what makes the page turn-key: the dev server answers `?find=` with the paths of
+ * every manifest under every root it serves, so a page opened with no parameters at all finds the
+ * one scene that is there. More than one and it takes the first and says which, because a page that
+ * refuses to choose between two is a page that shows nothing.
  *
  * @returns {Promise<string>}
  */
@@ -968,13 +1378,13 @@ async function resolve_scene_url() {
         return new URL(requested, globalThis.location.href).href;
     }
 
-    const listing = await fetch(`${DEFAULT_ORIGIN}/scenes.json`);
+    const listing = await fetch(`${ASSET_PREFIX}/?find=${encodeURIComponent(SCENE_SUFFIX)}`);
 
     if (!listing.ok) {
         throw new Error(
-            `no ?scene= was given and ${DEFAULT_ORIGIN} answered HTTP ${listing.status};`
-            + ` start the asset server with`
-            + ` "node tools/geometry/virtual/vgeo_serve.js <container directory>"`
+            `no ?scene= was given and ${ASSET_PREFIX}/?find= answered HTTP ${listing.status};`
+            + ` that listing is "tools/dev/vite_test_assets.js" under the dev server, so this is a`
+            + ` page being served by something else — pass the manifest as ?scene=<url>`
         );
     }
 
@@ -982,12 +1392,17 @@ async function resolve_scene_url() {
 
     if (scenes.length === 0) {
         throw new Error(
-            `${DEFAULT_ORIGIN} is serving no .vgeoscene.json;`
+            `nothing under ${ASSET_PREFIX}/ is a ${SCENE_SUFFIX};`
             + ` build one with "node tools/geometry/virtual/vgeo_scene.js <manifest.vgeo.json>"`
+            + ` under the asset root the dev server named at startup`
         );
     }
 
-    return `${DEFAULT_ORIGIN}/${scenes[0]}`;
+    // the listing answers with a path, and a path is not a URL: a directory with a space in it is
+    // ordinary on a Windows asset drive and is a 404 if it goes out unencoded
+    const encoded = scenes[0].split('/').map(encodeURIComponent).join('/');
+
+    return new URL(`${ASSET_PREFIX}/${encoded}`, globalThis.location.href).href;
 }
 
 /**
@@ -1079,7 +1494,7 @@ async function start() {
      more, because the cut is a function of the resolution, so it is a URL parameter and `refused`
      is in the panel to say when it was the wrong one.
     */
-    const page_capacity = Number(parameters.get('pages') ?? 12288);
+    const page_capacity = Number(parameters.get('pages') ?? 16384);
 
     const capacities = scene_capacities(manifest, page_capacity);
 
@@ -1125,7 +1540,15 @@ async function start() {
             direction: new Vector3(-manifest.sun[0], -manifest.sun[1], -manifest.sun[2]),
         });
 
-    place_light(scene, sun);
+    /*
+     `?sun=off` leaves the scene to its environment alone. Paired with `?env=uniform:<v>` it is a
+     closed question rather than an argument: the only light is then a constant radiance from every
+     direction, so a surface cannot return more of it than it reflects, and any surface brighter
+     than the environment it is standing in is being lit by something that is not there.
+    */
+    if (parameters.get('sun') !== 'off') {
+        place_light(scene, sun);
+    }
 
     /*
      Image-based lighting, and for the geometry rather than for the picture: a sun alone puts every
@@ -1133,7 +1556,23 @@ async function start() {
      cut is worth looking at. Not awaited — `test_assets/` is gitignored, so a checkout without it
      gets the sun alone and still draws every triangle the cut selected.
     */
-    load_default_environment(scene);
+    /*
+     `?env=off` leaves it out, and it is a **diagnostic about the shading rather than about the
+     geometry**: the environment is the only wide, neutral light in the scene, so it is the term to
+     remove when a surface reads paler than its own albedo and the question is whether that colour
+     is coming from the material at all. The renderer already treats a missing environment as an
+     ordinary state — a checkout without `test_assets/` renders by the sun alone — so this needs
+     nothing but skipping the load.
+    */
+    const environment = parameters.get('env');
+
+    if (environment === 'off') {
+        // nothing: the sun alone
+    } else if (environment !== null && environment.startsWith('uniform')) {
+        scene.lights.environment = make_uniform_environment(Number(environment.split(':')[1] ?? 0.5));
+    } else {
+        load_default_environment(scene);
+    }
 
     const camera = new PerspectiveCamera();
 
@@ -1162,7 +1601,7 @@ async function start() {
     */
     const residency = new VGeoResidencyOptions();
 
-    residency.ram_budget_bytes = 1024 * 1024 * 1024;
+    residency.ram_budget_bytes = 2 * GIGABYTE;
 
     /*
      VRAM is a strict subset of RAM, so the RAM tier has to be able to hold the whole VRAM tier and
@@ -1279,6 +1718,61 @@ async function start() {
 
     page.mirror_material = mirrored_mode === null ? material : mirror_material;
 
+    /*
+     The scene's own materials, when the source project has been extracted beside it. 3,163
+     containers resolve to a few hundred distinct materials — a `.vgeo` is one glTF primitive and a
+     primitive has one material — so this is a few hundred buckets in the draw path rather than one,
+     which is the scene's real shape rather than a cost this page is choosing to pay.
+    */
+    const sidecar = await load_scene_materials(scene_url, parameters);
+
+    if (sidecar !== null) {
+        const side = DRAW_SIDES[parameters.get('side')];
+
+        page.materials = sidecar.materials.map(definition => make_scene_material(definition, side));
+        page.geometry_material = sidecar.geometry_material;
+
+        page.unmaterialised = make_scene_material({
+            name: 'unmaterialised',
+            constant: { albedo: [0.18, 0.18, 0.18], roughness: 0.7, metallic: 0 },
+        }, side);
+
+        const noted = sidecar.materials.filter(m => (m.unsupported ?? []).length > 0).length;
+
+        page.status(
+            `${sidecar.material_count} materials, `
+            + `${noted} with something the standard material cannot carry`
+        );
+
+        /*
+         The maps themselves, but only when the containers can sample them. `uv0` is the sidecar
+         saying the source document carried `TEXCOORD_0`; for a scene converted from a
+         `POSITION`-only document there is nothing to sample *with*, and binding an albedo map would
+         put one texel across every surface in the frame.
+
+         `?textures=off` refuses them, which is how the two halves are compared on the same scene.
+        */
+        if (sidecar.uv0 === true && parameters.get('textures') !== 'off') {
+            page.status(`${sidecar.material_count} materials — loading textures…`);
+
+            const bound = await bind_scene_textures(
+                sidecar.materials, page.materials, sidecar.texture_base,
+            );
+
+            page.textures_bound = bound.bound;
+
+            for (const failure of bound.failed) {
+                console.warn(`texture — ${failure}`);
+            }
+
+            page.status(
+                `${sidecar.material_count} materials, ${bound.bound} textures`
+                + (bound.udim > 0 ? ` (${bound.udim} UDIM sets took their first tile)` : '')
+                + (bound.failed.length > 0 ? `, ${bound.failed.length} failed` : '')
+            );
+        }
+    }
+
     globalThis.addEventListener('pagehide', () => page.feedback.destroy());
 
     renderer.add_extension(new VGeoFrameStart(page));
@@ -1605,6 +2099,13 @@ function paint(page, capacities, state) {
         ['containers', `${scene.containers.toLocaleString()} / ${scene.declared.toLocaleString()}`],
         ['instances', scene.instances.toLocaleString()],
         ['reflected', scene.mirrored.toLocaleString()],
+        [
+            'materials',
+            scene.materials === 0
+                ? 'one — no sidecar'
+                : `${scene.materials.toLocaleString()} over `
+                    + `${scene.materialised.toLocaleString()} containers`,
+        ],
         ['source triangles', scene.faces.toLocaleString()],
         ['on the server', human_bytes(scene.bytes)],
         ['read', human_bytes(scene.bytes_read)],