@volter/blender-engine 0.1.5 → 0.1.7

package/browser/three/blender-runtime-view.ts

@@ -4,11 +4,13 @@
  */
 import * as THREE from 'three';
 import { z } from 'zod';
+import { onPresenterChange, presenterChanged } from './blender-presenter-change';
 import { bytesFromBase64 } from './blender-base64';
 import { ArmatureOverlay, armatureSchema } from './blender-runtime-armature';
 import { UNKNOWN_GEOMETRY, UNKNOWN_IMAGE } from './blender-runtime-frame';
 import {
   drawArraysFromColumns,
+  graphAttributeName,
   drawRuntimeGeometry,
   geometryFromDrawArrays,
 } from './blender-runtime-geometry';
@@ -24,6 +26,11 @@ import {
 } from './blender-runtime-lighting';
 import { fitModelDirectionalShadow, visibleShadowReceivers } from './blender-runtime-shadows';
 import { volumeMesh, volumeSchema } from './blender-runtime-volume';
+import { applyPhysicalMaterial, applyWorldExtinction, physicalMaterialSchema } from './blender-physical-material';
+import { prepareGraphGeometry, setMaterialGraph } from './blender-graph-material';
+import { type CompiledGraph, compileMaterialGraph, graphSeeThrough, materialGraphSchema } from './blender-node-graph';
+import {worldMedium, WorldVolumePass} from './blender-world-volume';
+import { BlenderTextureSamplers } from './blender-texture-samplers';
 import { WeightOverlay, weightsSchema } from './blender-runtime-weights';
 
 const scalar = z.number().finite();
@@ -103,6 +110,9 @@ const drawArraysSchema = z
     positions: z.instanceof(Float32Array),
     normals: z.instanceof(Float32Array).nullable(),
     uv: z.instanceof(Float32Array).nullable(),
+    uvLayers: z.array(z.object({name: z.string(), data: z.instanceof(Float32Array)}).strict()).optional(),
+    attributeLayers: z.array(z.object({name: z.string(), data: z.instanceof(Float32Array)}).strict()).optional(),
+    orco: z.instanceof(Float32Array).nullable().optional(),
     indices: z.instanceof(Uint32Array),
     groups: z.array(
       z
@@ -158,6 +168,8 @@ const unchangedMeshSchema = z
 const columnsSchema = z
   .object({
     co: z.instanceof(Float64Array),
+    cornerNormal: z.instanceof(Float32Array).optional(),
+    orco: z.instanceof(Float32Array).optional(),
     faceStart: z.instanceof(Uint32Array),
     corner: z.instanceof(Uint32Array),
     cornerEdge: z.instanceof(Int32Array),
@@ -251,6 +263,7 @@ function loadPngTexture(png: Uint8Array): { texture: THREE.Texture; ready: Promi
       }
       texture.image = bitmap;
       texture.needsUpdate = true;
+      presenterChanged();
     })
     .finally(() => {
       pendingTextures.delete(decoding);
@@ -289,6 +302,47 @@ function rasterTexture(
   return texture;
 }
 
+/**
+ * A UDIM IMAGE AS A GRAPH SAMPLES IT: every tile a layer of one array texture
+ * (each at its layer's origin, the layer as large as the largest tile), and
+ * the tile map `blender_tile_lookup` reads -- row 0 each tile's layer (-1 for
+ * none), row 1 its offset and scale within the layer, Blender's
+ * `GPU_image_tiled` layout.
+ */
+function udimTextures(
+  name: string,
+  frame: NonNullable<z.infer<typeof rasterImageSchema>['tiles']>,
+  colorspace: 'sRGB' | 'data',
+): {tiles: THREE.DataArrayTexture; map: THREE.DataTexture; frame: typeof frame} {
+  if (frame.length === 0) throw new Error(`Runtime image ${name} is tiled with no tiles`);
+  const width = Math.max(...frame.map(t => t.width));
+  const height = Math.max(...frame.map(t => t.height));
+  const layers = new Uint8Array(width * height * 4 * frame.length);
+  const count = Math.max(...frame.map(t => t.number - 1001)) + 1;
+  const map = new Float32Array(count * 2 * 4);
+  for (let i = 0; i < count; i++) map[i * 4] = -1;
+  frame.forEach((tile, layer) => {
+    const rgba = tile.rgba ?? (tile.rgbaBase64 ? bytesFromBase64(tile.rgbaBase64) : undefined);
+    if (!rgba) throw new Error(`Runtime image ${name} tile ${tile.number} carries no raster`);
+    for (let row = 0; row < tile.height; row++)
+      layers.set(rgba.subarray(row * tile.width * 4, (row + 1) * tile.width * 4),
+        ((layer * height + row) * width) * 4);
+    const index = tile.number - 1001;
+    map[index * 4] = layer;
+    map.set([0, 0, tile.width / width, tile.height / height], (count + index) * 4);
+  });
+  const tiles = new THREE.DataArrayTexture(layers, width, height, frame.length);
+  tiles.colorSpace = colorspace === 'data' ? THREE.NoColorSpace : THREE.SRGBColorSpace;
+  tiles.magFilter = THREE.LinearFilter;
+  tiles.minFilter = THREE.LinearMipmapLinearFilter;
+  tiles.generateMipmaps = true;
+  tiles.needsUpdate = true;
+  const mapTexture = new THREE.DataTexture(map, count, 2, THREE.RGBAFormat, THREE.FloatType);
+  mapTexture.magFilter = mapTexture.minFilter = THREE.NearestFilter;
+  mapTexture.needsUpdate = true;
+  return {tiles, map: mapTexture, frame};
+}
+
 /** One image the frame carries in full, in the only two shapes it comes in.
  *
  * A RASTER states its size, because a `DataTexture` cannot be built without
@@ -307,6 +361,14 @@ const rasterImageSchema = z
     /** Blender's `colorspace_settings.name`, reduced to the two the sampler
      *  tells apart. Absent means sRGB. */
     colorspace: z.enum(['sRGB', 'data']).optional(),
+    /** A UDIM image's tiles, by tile number (the door's `write_image`). */
+    tiles: z.array(z.object({
+      number: z.number().int().min(1001),
+      width: z.number().int().positive(),
+      height: z.number().int().positive(),
+      rgba: z.instanceof(Uint8Array).optional(),
+      rgbaBase64: z.string().optional(),
+    }).strict()).optional(),
   })
   .strict();
 const pngImageSchema = z
@@ -321,8 +383,8 @@ const frameImageSchema = z.union([rasterImageSchema, pngImageSchema]);
 const textureReferenceSchema = z
   .object({
     image: z.object({ name: z.string(), revision: z.number().int().nonnegative() }).strict(),
-    /** Blender's `extension`; CLIP never arrives -- the reducer refuses it. */
-    extension: z.enum(['REPEAT', 'EXTEND', 'MIRROR']).default('REPEAT'),
+    /** CLIP is transparent black outside the image, applied in the shader. */
+    extension: z.enum(['REPEAT', 'EXTEND', 'MIRROR', 'CLIP']).default('REPEAT'),
     uv: z.string(),
     /** A constant the texture is multiplied by -- Blender's MULTIPLY mix at
      *  full factor, which is what `map * color` already is. */
@@ -337,6 +399,11 @@ const materialSchema = z
     metallic: scalar,
     transmission: scalar,
     ior: scalar,
+    physical: physicalMaterialSchema.optional(),
+    normal_texture: textureReferenceSchema.optional(),
+    normal_strength: scalar.default(1),
+    normal_space: z.enum(['TANGENT', 'OBJECT']).default('TANGENT'),
+    normal_directx: z.boolean().default(false),
     /** A Base Color image, NAMED. Its bytes travel in the frame's `images`
      *  map, once per `(name, revision)`. */
     texture: textureReferenceSchema.optional(),
@@ -350,6 +417,11 @@ const materialSchema = z
       .object({ color: z.tuple([scalar, scalar, scalar]), strength: scalar })
       .strict()
       .optional(),
+    /** The node graph driving a Principled BSDF's or Emission's linked
+     *  inputs (`session.py`'s `material_graph`), compiled by
+     *  `blender-node-graph.ts`. The constants above still apply to every
+     *  input the graph does not carry. */
+    graph: materialGraphSchema.optional(),
   })
   .strict();
 /** THE FRAME CONTRACT, and the reason it is exported: the C++ export door
@@ -400,6 +472,11 @@ export const frameSchema = z
           render_visible: z.boolean().default(true),
           selected: z.boolean(),
           parent: z.string().nullable(),
+          /** A manual texture space (`[location, size]`), which Generated
+           *  coordinates map through; absent means Blender's automatic one,
+           *  the evaluated bounds (`blender-graph-material.ts`'s orco). */
+          texspace: z.tuple([z.tuple([scalar, scalar, scalar]), z.tuple([scalar, scalar, scalar])]).optional(),
+          default_color: z.string().optional(),
         })
         .strict(),
     ),
@@ -480,7 +557,7 @@ export class BlenderRuntimeView {
   private readonly armatureRoot = new THREE.Group();
   private readonly weightRoot = new THREE.Group();
   private rendered = false;
-  private readonly fallback = new THREE.MeshStandardMaterial({ color: 0xb9bec6, roughness: 0.72 });
+  private readonly fallback = new THREE.MeshPhysicalMaterial({ color: 0xb9bec6, roughness: 0.72 });
   /** Base Color images, by image name -- ONE texture per image however many
    *  materials read it, and the cache OWNS it: a material points at one and
    *  never disposes it. Held with the size and revision the resident bytes
@@ -495,12 +572,33 @@ export class BlenderRuntimeView {
       revision: number;
       png?: Uint8Array;
       ready?: Promise<void>;
+      /** A UDIM image's tiles as a graph samples them (`udimTextures`). */
+      udim?: {tiles: THREE.DataArrayTexture; map: THREE.DataTexture; frame: NonNullable<z.infer<typeof rasterImageSchema>['tiles']>};
     }
   >();
   /** Which image each material's `map` is currently pointing at. */
   private readonly textureNames = new Map<string, string>();
   /** Which runtime image each material's roughness map is, by material id. */
   private readonly roughnessTextureNames = new Map<string, string>();
+  private readonly textureSamplers = new BlenderTextureSamplers();
+  /** Each material's graph image samplers, by sampler key. */
+  private readonly graphSamplers = new Map<string, Set<string>>();
+  /** A view built for one photograph: its graph programs compile before its
+   *  one draw rather than off it (`setMaterialGraph`'s `immediate`). */
+  private photograph = false;
+  /** Compiled graphs by their JSON: a frame re-sends every material. */
+  private readonly graphs = new Map<string, CompiledGraph>();
+
+  private compiledGraph(graph: z.infer<typeof materialGraphSchema>): CompiledGraph {
+    const text = JSON.stringify(graph);
+    let compiled = this.graphs.get(text);
+    if (!compiled) {
+      compiled = compileMaterialGraph(graph);
+      if (this.graphs.size > 256) this.graphs.clear();
+      this.graphs.set(text, compiled);
+    }
+    return compiled;
+  }
   private frame: Frame | null = null;
   private readonly retiredSessions = new Set<string>();
   private geometryBuilds = 0;
@@ -539,6 +637,18 @@ export class BlenderRuntimeView {
     };
   }
 
+  /** EVERY CHANGE TO WHAT THIS VIEW DRAWS: each applied frame, and each piece
+   *  of work that finishes after one (`blender-presenter-change.ts`). A stage
+   *  that subscribes may draw only when this fires. */
+  onChange(listener: () => void): () => void {
+    const stopFrames = this.subscribeFrames(listener);
+    const stopWork = onPresenterChange(listener);
+    return () => {
+      stopFrames();
+      stopWork();
+    };
+  }
+
   /** The Blender datablock NAME of a presented object, or null when this
    *  object is not one of the engine's (an editor helper, a light three.js
    *  parents under one). It is a lookup by IDENTITY, never by `object.name`:
@@ -706,6 +816,8 @@ export class BlenderRuntimeView {
    * distinction Blender draws between its solid viewport and a render.
    */
   async setRendered(rendered: boolean, camera?: THREE.Camera): Promise<void> {
+    const extinction = (rendered ? worldMedium(this.frame?.world)?.extinction : null) ?? new THREE.Vector3();
+    for (const material of [...this.materials.values(), this.fallback]) applyWorldExtinction(material, extinction);
     // An area light cannot be DRAWN until its lookup tables are uploaded, and a
     // render is one photograph with no second chance at it.
     // A sky is derived off the main thread now, so a render waits for it the
@@ -974,6 +1086,12 @@ export class BlenderRuntimeView {
       if ('width' in data) {
         const rgba = data.rgba ?? (data.rgbaBase64 ? bytesFromBase64(data.rgbaBase64) : undefined);
         if (!rgba) throw new Error(`Runtime image ${name} carries no raster`);
+        const udim = data.tiles ? udimTextures(name, data.tiles, data.colorspace ?? 'sRGB') : undefined;
+        if (held?.udim) {
+          held.udim.tiles.dispose();
+          held.udim.map.dispose();
+          delete held.udim;
+        }
         // A REPAINT AT THE SAME SIZE IS AN UPLOAD, not a new texture: the
         // bytes go into the resident image and three re-uploads it, so every
         // material pointing at it keeps pointing at it. Native does exactly
@@ -984,6 +1102,7 @@ export class BlenderRuntimeView {
             image.data.set(rgba);
             held.texture.needsUpdate = true;
             held.revision = data.revision;
+            if (udim) held.udim = udim;
             continue;
           }
         }
@@ -993,6 +1112,7 @@ export class BlenderRuntimeView {
           width: data.width,
           height: data.height,
           revision: data.revision,
+          ...(udim ? {udim} : {}),
         });
         continue;
       }
@@ -1003,6 +1123,8 @@ export class BlenderRuntimeView {
       const png = data.png ?? (data.pngBase64 ? bytesFromBase64(data.pngBase64) : undefined);
       if (!png) throw new Error(`Runtime image ${name} carries no bytes`);
       held?.texture.dispose();
+      held?.udim?.tiles.dispose();
+      held?.udim?.map.dispose();
       const { texture, ready } = loadPngTexture(png);
       texture.colorSpace = THREE.SRGBColorSpace;
       this.textures.set(name, {
@@ -1050,7 +1172,10 @@ export class BlenderRuntimeView {
       // carries no alpha on a texture, and Blender's Alpha is a separate
       // Principled socket.
       material.opacity = data.color[3];
-      const transparent = material.opacity < 1;
+      // A graph-driven Alpha, or a Transparent BSDF in a shader mix, is per
+      // pixel; the constant cannot say whether the surface is see-through, so
+      // such a graph is.
+      const transparent = material.opacity < 1 || (data.graph !== undefined && graphSeeThrough(data.graph));
       if (material.transparent !== transparent) {
         material.transparent = transparent;
         material.needsUpdate = true;
@@ -1059,6 +1184,33 @@ export class BlenderRuntimeView {
       material.metalness = data.metallic;
       material.transmission = data.transmission;
       material.ior = data.ior;
+      applyPhysicalMaterial(material, data.physical, {
+        map: data.texture?.extension === 'CLIP',
+        roughness: data.roughness_texture?.extension === 'CLIP',
+        normal: data.normal_texture?.extension === 'CLIP',
+      });
+      const normalName = data.normal_texture?.image.name;
+      if (normalName === undefined) {
+        if (material.normalMap) {
+          this.textureSamplers.delete(`${id}:normal`);
+          material.normalMap = null;
+          material.needsUpdate = true;
+        }
+      } else {
+        const held = this.textures.get(normalName);
+        if (!held) throw new Error(`${UNKNOWN_IMAGE}: missing normal image ${normalName}`);
+        const normalMap = this.textureSamplers.get(`${id}:normal`, held.texture, data.normal_texture!.extension, held.ready, data.normal_texture!.uv);
+        if (material.normalMap !== normalMap) {
+          material.normalMap = normalMap;
+          material.needsUpdate = true;
+        }
+        const normalType = data.normal_space === 'OBJECT' ? THREE.ObjectSpaceNormalMap : THREE.TangentSpaceNormalMap;
+        if (material.normalMapType !== normalType) {
+          material.normalMapType = normalType;
+          material.needsUpdate = true;
+        }
+        material.normalScale.set(data.normal_strength, data.normal_strength * (data.normal_directx ? -1 : 1));
+      }
       if (data.emission) {
         material.emissive.setRGB(
           data.emission.color[0],
@@ -1077,6 +1229,7 @@ export class BlenderRuntimeView {
       const roughnessWanted = data.roughness_texture?.image.name ?? null;
       if (roughnessWanted === null) {
         if (this.roughnessTextureNames.has(id)) {
+          this.textureSamplers.delete(`${id}:roughness`);
           material.roughnessMap = null;
           this.roughnessTextureNames.delete(id);
           material.needsUpdate = true;
@@ -1088,18 +1241,8 @@ export class BlenderRuntimeView {
             `${UNKNOWN_IMAGE}: the presenter does not hold runtime image ${roughnessWanted} ` +
               `(revision ${data.roughness_texture!.image.revision})`,
           );
-        const roughnessMap = heldRoughness.texture;
-        const roughnessWrap =
-          data.roughness_texture!.extension === 'EXTEND'
-            ? THREE.ClampToEdgeWrapping
-            : data.roughness_texture!.extension === 'MIRROR'
-              ? THREE.MirroredRepeatWrapping
-              : THREE.RepeatWrapping;
-        if (roughnessMap.wrapS !== roughnessWrap || roughnessMap.wrapT !== roughnessWrap) {
-          roughnessMap.wrapS = roughnessWrap;
-          roughnessMap.wrapT = roughnessWrap;
-          if (roughnessMap.image) roughnessMap.needsUpdate = true;
-        }
+        const roughnessMap = this.textureSamplers.get(`${id}:roughness`, heldRoughness.texture,
+          data.roughness_texture!.extension, heldRoughness.ready, data.roughness_texture!.uv);
         if (material.roughnessMap !== roughnessMap) {
           material.roughnessMap = roughnessMap;
           this.roughnessTextureNames.set(id, roughnessWanted);
@@ -1113,6 +1256,7 @@ export class BlenderRuntimeView {
       const wanted = data.texture?.image.name ?? null;
       if (wanted === null) {
         if (this.textureNames.has(id)) {
+          this.textureSamplers.delete(`${id}:color`);
           material.map = null;
           this.textureNames.delete(id);
           material.needsUpdate = true;
@@ -1129,35 +1273,7 @@ export class BlenderRuntimeView {
             `${UNKNOWN_IMAGE}: the presenter does not hold runtime image ${wanted} ` +
               `(revision ${data.texture!.image.revision})`,
           );
-        const map = held.texture;
-        // REPEAT, because that is what Blender's Image Texture node does:
-        // its `extension` defaults to REPEAT (asked the oracle), while
-        // three's wrapping defaults to ClampToEdge. Any UV outside [0,1]
-        // then smears the edge pixel across the whole surface, which is the
-        // "weirdly stretched" texture the owner saw on the courtyard.
-        //
-        // `extension`, as the description carries it. CLIP never arrives:
-        // the reducer refuses it by name, which is why three modes are
-        // mapped here and not four.
-        const wrap =
-          data.texture!.extension === 'EXTEND'
-            ? THREE.ClampToEdgeWrapping
-            : data.texture!.extension === 'MIRROR'
-              ? THREE.MirroredRepeatWrapping
-              : THREE.RepeatWrapping;
-        if (map.wrapS !== wrap || map.wrapT !== wrap) {
-          map.wrapS = wrap;
-          map.wrapT = wrap;
-          // ONLY IF THERE IS AN IMAGE TO RE-UPLOAD. A wrap change is a sampler
-          // parameter and three re-reads it when the texture's version moves,
-          // so an already-resident map needs the bump -- but bumping one whose
-          // `createImageBitmap` is still in flight is exactly what three warns
-          // about, and it did, 34 times on one courtyard replay:
-          // `THREE.WebGLRenderer: Texture marked for update but no image data
-          // found`. The decode sets `needsUpdate` itself when the bitmap
-          // lands, and it carries whatever wrap is on the texture by then.
-          if (map.image) map.needsUpdate = true;
-        }
+        const map = this.textureSamplers.get(`${id}:color`, held.texture, data.texture!.extension, held.ready, data.texture!.uv);
         // RE-POINTED WHENEVER THE TEXTURE OBJECT CHANGED, which is how a
         // RESIZED image reaches a material: the cache disposes the old texture
         // and builds a new one. A repaint at the same size keeps this exact
@@ -1168,6 +1284,37 @@ export class BlenderRuntimeView {
           material.needsUpdate = true;
         }
       }
+      // THE NODE GRAPH, when the session shipped one: compiled once per
+      // distinct graph, its images through the same cache and per-input
+      // sampler ownership as the maps above.
+      const graph = data.graph ? this.compiledGraph(data.graph) : null;
+      const graphSamplers = new Set<string>();
+      setMaterialGraph(material, graph, (image) => {
+        const held = this.textures.get(image.name);
+        if (!held)
+          throw new Error(
+            `${UNKNOWN_IMAGE}: the presenter does not hold runtime image ${image.name} ` +
+              `(revision ${image.revision})`,
+          );
+        if (image.tiled) {
+          if (!held.udim) throw new Error(`${UNKNOWN_IMAGE}: runtime image ${image.name} arrived without its UDIM tiles`);
+          return held.udim;
+        }
+        const key = `${id}:graph:${image.node}`;
+        graphSamplers.add(key);
+        const texture = this.textureSamplers.get(key, held.texture, image.extension, held.ready);
+        const filter = image.closest ? THREE.NearestFilter : THREE.LinearFilter;
+        const minFilter = image.closest ? THREE.NearestFilter
+          : image.mipmap ? THREE.LinearMipmapLinearFilter : THREE.LinearFilter;
+        if (texture.magFilter !== filter || texture.minFilter !== minFilter) {
+          texture.magFilter = filter;
+          texture.minFilter = minFilter;
+          texture.needsUpdate = true;
+        }
+        return texture;
+      }, this.photograph);
+      for (const key of this.graphSamplers.get(id) ?? []) if (!graphSamplers.has(key)) this.textureSamplers.delete(key);
+      this.graphSamplers.set(id, graphSamplers);
       this.materials.set(id, material);
     }
     for (const obj of next.objects) {
@@ -1197,12 +1344,17 @@ export class BlenderRuntimeView {
         object.matrix.premultiply(parent.invert());
       }
       object.matrix.decompose(object.position, object.quaternion, object.scale);
+      if (obj.texspace) object.userData['blenderTexspace'] = obj.texspace;
+      else delete object.userData['blenderTexspace'];
+      if (obj.default_color !== undefined) object.userData['blenderDefaultColor'] = obj.default_color;
+      else delete object.userData['blenderDefaultColor'];
       if (obj.mesh !== null) {
         const mesh = object as THREE.Mesh;
         mesh.geometry = this.meshes.get(obj.mesh)!.geometry;
         mesh.material = obj.materials.length
           ? obj.materials.map((id) => (id === null ? this.fallback : this.materials.get(id)!))
           : this.fallback;
+        prepareGraphGeometry(mesh);
       }
       if (obj.light) {
         // The light hangs on its object's own node, so the object's matrix
@@ -1242,6 +1394,9 @@ export class BlenderRuntimeView {
       }
     for (const [id, material] of this.materials)
       if (!next.materials[id]) {
+        for (const slot of ['normal', 'roughness', 'color']) this.textureSamplers.delete(`${id}:${slot}`);
+        for (const key of this.graphSamplers.get(id) ?? []) this.textureSamplers.delete(key);
+        this.graphSamplers.delete(id);
         material.dispose();
         this.materials.delete(id);
       }
@@ -1323,6 +1478,17 @@ export class BlenderRuntimeView {
         positions,
         normals: attribute('normal'),
         uv: attribute('uv'),
+        uvLayers: Object.entries(geometry.userData['blenderUvChannels'] as Record<string, number> ?? {}).map(([name, channel]) => {
+          const data = attribute(`uv${channel}`);
+          if (!data) throw new Error(`Blender capture mesh ${id} is missing UV layer ${name}`);
+          return {name, data};
+        }),
+        orco: geometry.userData['blenderOrcoFromDoor'] ? attribute('blenderOrco') : null,
+        attributeLayers: (geometry.userData['blenderAttributes'] as string[] | undefined ?? []).map(name => {
+          const data = attribute(graphAttributeName(name));
+          if (!data) throw new Error(`Blender capture mesh ${id} is missing attribute ${name}`);
+          return {name, data};
+        }),
         indices: index
           ? new Uint32Array(index.array)
           : Uint32Array.from({ length: positions.length / 3 }, (_, i) => i),
@@ -1337,9 +1503,15 @@ export class BlenderRuntimeView {
       frame.volumes[id] = volumeSchema.parse(JSON.parse(signature));
     const images = new Set(
       Object.values(frame.materials).flatMap((material) =>
-        [material.texture?.image.name, material.roughness_texture?.image.name].filter(
-          (name): name is string => name !== undefined,
-        ),
+        [
+          material.texture?.image.name,
+          material.roughness_texture?.image.name,
+          material.normal_texture?.image.name,
+          // The images a material's node graph samples.
+          ...Object.values(material.graph?.nodes ?? {}).map(
+            (node) => (node.props['image'] as { name?: string } | null | undefined)?.name,
+          ),
+        ].filter((name): name is string => name !== undefined),
       ),
     );
     for (const name of images) {
@@ -1357,14 +1529,18 @@ export class BlenderRuntimeView {
           height: held.height,
           rgba: data.slice(),
           colorspace: held.texture.colorSpace === THREE.NoColorSpace ? 'data' : 'sRGB',
+          ...(held.udim ? {tiles: held.udim.frame} : {}),
         };
       }
     }
+    const effect = this.createWorldVolumePass();
     const detached = new BlenderRuntimeView();
+    detached.photograph = true;
     let disposed = false;
     const dispose = () => {
       if (disposed) return;
       disposed = true;
+      effect?.dispose();
       detached.dispose();
       detached.root.removeFromParent();
     };
@@ -1378,6 +1554,7 @@ export class BlenderRuntimeView {
       throw error;
     }
     return {
+      effect,
       root: detached.root,
       session: source.session,
       revision: source.revision,
@@ -1389,6 +1566,11 @@ export class BlenderRuntimeView {
     };
   }
 
+  createWorldVolumePass(): WorldVolumePass | undefined {
+    const medium = worldMedium(this.frame?.world);
+    return medium ? new WorldVolumePass(medium) : undefined;
+  }
+
   /** Keep the description that arrived with this frame. Called by the tab's
    *  Blender host right after `applyFrame`, so a refused frame records
    *  nothing: the record must describe what is DISPLAYED. */
@@ -1443,9 +1625,15 @@ export class BlenderRuntimeView {
     // The pictures go with the session that sent them: the cache OWNS every
     // texture in it (a material only points at one), so this is the one place
     // they are disposed, beside the meshes for the same reason.
-    for (const { texture } of this.textures.values()) texture.dispose();
+    for (const { texture, udim } of this.textures.values()) {
+      texture.dispose();
+      udim?.tiles.dispose();
+      udim?.map.dispose();
+    }
     this.textures.clear();
     this.textureNames.clear();
+    this.roughnessTextureNames.clear();
+    this.textureSamplers.clear();
     this.volumes.clear();
     this.objects.clear();
     this.meshes.clear();

package/browser/three/blender-texture-samplers.ts

@@ -0,0 +1,79 @@
+import * as THREE from 'three';
+import {presenterChanged} from './blender-presenter-change';
+
+export type TextureExtension = 'REPEAT' | 'EXTEND' | 'MIRROR' | 'CLIP';
+
+/** A shared material may draw meshes whose named layers have different
+ * channel positions. Resolve at Three's per-draw hook, before program choice. */
+export function bindNamedUvChannels(material: THREE.MeshPhysicalMaterial, geometry: THREE.BufferGeometry): void {
+  const channels = geometry.userData['blenderUvChannels'] as Record<string, number> | undefined;
+  for (const texture of [material.map, material.roughnessMap, material.normalMap]) {
+    if (!texture) continue;
+    const name = texture.userData['blenderUvName'] as string | undefined;
+    let channel = name ? channels?.[name] : 0;
+    if (channel === undefined) {
+      // Blender's missing named surface attribute is zero, not the active UV
+      // map and not an error. Shared materials routinely cover meshes without
+      // that layer. Reserve a separate zero channel so other slots retain UV0.
+      channel = 9;
+      const count = geometry.getAttribute('position')?.count;
+      if (count === undefined) throw new Error('A textured Blender draw has no positions');
+      if (geometry.getAttribute('uv9')?.count !== count)
+        geometry.setAttribute('uv9', new THREE.BufferAttribute(new Float32Array(count*2),2));
+    }
+    if (texture.channel !== channel) {
+      texture.channel = channel;
+      material.needsUpdate = true;
+    }
+  }
+}
+
+/** Image pixels are shared; sampler state belongs to each material input.
+ * Clones share Three's Source, including asynchronous PNG decoding, but their
+ * upload versions are independent and must follow repaints explicitly. */
+export class BlenderTextureSamplers {
+  private readonly bindings = new Map<string, {
+    source: THREE.Texture; texture: THREE.Texture; version: number; disposed: boolean;
+  }>();
+
+  get(key: string, source: THREE.Texture, extension: TextureExtension, ready?: Promise<void>, uv = ''): THREE.Texture {
+    let binding = this.bindings.get(key);
+    if (!binding || binding.source !== source) {
+      this.delete(key);
+      binding = {source, texture: source.clone(), version: -1, disposed: false};
+      this.bindings.set(key, binding);
+      const held = binding;
+      // The owner awaits and reports decode failures. Avoid an unhandled
+      // rejection here, and never upload a clone removed during the decode.
+      if (ready) void ready.then(() => {
+        if (!held.disposed) {
+          held.texture.needsUpdate = true;
+          held.version = source.version;
+          presenterChanged();
+        }
+      }, () => {});
+    }
+    const wrap = extension === 'REPEAT' ? THREE.RepeatWrapping :
+      extension === 'MIRROR' ? THREE.MirroredRepeatWrapping : THREE.ClampToEdgeWrapping;
+    const changed = binding.texture.wrapS !== wrap || binding.texture.wrapT !== wrap;
+    binding.texture.wrapS = binding.texture.wrapT = wrap;
+    binding.texture.userData['blenderUvName'] = uv;
+    if (source.image && (changed || binding.version !== source.version)) {
+      binding.texture.needsUpdate = true;
+      binding.version = source.version;
+    }
+    return binding.texture;
+  }
+
+  delete(key: string): void {
+    const binding = this.bindings.get(key);
+    if (!binding) return;
+    binding.disposed = true;
+    binding.texture.dispose();
+    this.bindings.delete(key);
+  }
+
+  clear(): void {
+    for (const key of this.bindings.keys()) this.delete(key);
+  }
+}