three-realtime-rt 0.6.1 → 0.7.0

package/src/SceneCompiler.js

@@ -16,6 +16,39 @@ const MAX_LIGHTS = 32; // stage-1 cap; a data-texture light list is future work
 // from the light list with a warning.
 const MAX_EMISSIVE_TRIS = 256;
 
+// ---- usage diagnostics (warn-once) -----------------------------------------
+// Silent "it looks wrong but nothing errored" mistakes are the expensive kind:
+// a flag that is ignored, an object type that never reaches the BVH, a mesh
+// edited after compileScene(). Each one below is detected at compile time and
+// reported ONCE per object (never per frame, never per recompile) with the exact
+// fix. The message text is also pushed onto the CompiledScene as
+// `warnings: [{ code, message }]` so RealtimeRaytracer can mirror it into
+// `status.warnings` for a UI / an automated check.
+//
+// Warn-once state is keyed by the OBJECT (a WeakMap of code sets), so recompiling
+// the same scene does not re-spam the console; the returned `warnings` array is
+// still rebuilt on every compile so the status surface stays complete.
+const _warnedObjects = new WeakMap();
+function _firstTime(obj, code) {
+  let set = _warnedObjects.get(obj);
+  if (!set) { set = new Set(); _warnedObjects.set(obj, set); }
+  if (set.has(code)) return false;
+  set.add(code);
+  return true;
+}
+
+// Human-readable identifier for a scene object in a diagnostic message.
+function describeObject(obj) {
+  if (!obj) return "(null)";
+  return obj.name ? `"${obj.name}"` : `(unnamed ${obj.type || "Object3D"})`;
+}
+
+// Join up to `max` object names for a message that covers a whole category.
+function describeList(objs, max = 4) {
+  const head = objs.slice(0, max).map(describeObject).join(", ");
+  return objs.length > max ? `${head} and ${objs.length - max} more` : head;
+}
+
 /**
  * A two-level BVH scene. Static geometry lives in one BVH uploaded to the GPU
  * ONCE; dynamic (moving) meshes live in a second, small BVH that is re-baked and
@@ -49,8 +82,24 @@ export class CompiledScene {
     // (shape changes each frame, so it forces a per-frame normal upload too).
     this.hasSkinned = false;
 
+    // Usage diagnostics raised while compiling THIS scene: [{ code, message }].
+    // Console output happens once per offending object at collection time;
+    // RealtimeRaytracer mirrors this array into status.warnings.
+    this.warnings = [];
+    // Per-static-mesh fingerprints ({ ref: WeakRef, name, version, matrix,
+    // warned }) used to detect a static mesh edited after compile time. Only the
+    // WeakRef points at the app's mesh, so this never keeps a scene alive.
+    this.staticSources = [];
+
     this.materialsTex = null;
     this.materials = [];
+    // World-space 3D-texture albedo (see collectVolumeAlbedo). null when no
+    // material opted in via userData.rtVolumeAlbedo. v1 is single-volume: the
+    // FIRST opted-in material wins for the traced-bounce path (the lighting
+    // megakernel takes one sampler3D + one material index). Primary visibility
+    // (the G-buffer) can carry any number of distinct volumes; only the traced
+    // secondary rays are limited to one in v1.
+    this.volumeAlbedo = null;
     this.lightPosType = [];
     this.lightColorRadius = [];
     this.lightDirCone = []; // spot direction.xyz + cos(outer angle)
@@ -328,6 +377,8 @@ export class CompiledScene {
     if (this.materialsTex) this.materialsTex.dispose();
     if (this.staticBvh) this.staticBvh.geometry.dispose();
     if (this.dynamicMerged) this.dynamicMerged.dispose();
+    // Drop the staleness fingerprints (WeakRefs + a 16-float matrix each).
+    this.staticSources = [];
   }
 }
 
@@ -488,6 +539,65 @@ function emissiveColor(mat) {
   return [mat.emissive.r * i, mat.emissive.g * i, mat.emissive.b * i];
 }
 
+// World-space 3D-texture albedo ("volumetric surface albedo"). A material opts
+// in with `material.userData.rtVolumeAlbedo = { texture, origin, size }`:
+//   texture — a THREE.Data3DTexture, ALREADY colour-mapped to RGB(A); the tracer
+//             samples its .rgb at the hit point (no colormap logic in the library)
+//   origin  — THREE.Vector3, world position of the texel-(0,0,0) corner
+//   size    — THREE.Vector3, world extent of the full volume along each axis
+// The hit point p maps to uvw = clamp((p - origin) / size, 0, 1) and the trilinear
+// sample replaces the material's base albedo. Everything else (roughness, metalness,
+// emissive) composes normally. Returns { matIndex, texture, origin, size, material }
+// for the FIRST opted-in material (v1 single-volume for the traced-bounce path), or
+// null. `materials` is the deduped table, so matIndex is the exact index the BVH
+// per-vertex attribute stores and the lighting pass reads via fetchMaterial().
+function collectVolumeAlbedo(materials) {
+  let found = null;
+  let extra = 0;
+  for (let i = 0; i < materials.length; i++) {
+    const desc = materials[i] && materials[i].userData && materials[i].userData.rtVolumeAlbedo;
+    if (!desc) continue;
+    if (found) { extra++; continue; }
+    const texture = desc.texture;
+    const is3D = texture && (texture.isData3DTexture || texture.isDataArrayTexture ||
+      (texture.image && texture.image.depth > 0));
+    if (!texture || !is3D) {
+      console.warn(
+        "three-realtime-rt: userData.rtVolumeAlbedo.texture must be a THREE.Data3DTexture " +
+        "(RGB[A], pre-colormapped) — ignoring this material's volume albedo."
+      );
+      continue;
+    }
+    const origin = new THREE.Vector3().copy(desc.origin ?? new THREE.Vector3(0, 0, 0));
+    // Guard a zero extent (would divide by zero in the shader) — fall back to 1.
+    const size = new THREE.Vector3().copy(desc.size ?? new THREE.Vector3(1, 1, 1));
+    if (size.x === 0) size.x = 1;
+    if (size.y === 0) size.y = 1;
+    if (size.z === 0) size.z = 1;
+    // Trilinear + clamp-to-edge is what "sample the field on the surface" means;
+    // set it here so callers don't have to remember (the shader also clamps uvw,
+    // so wrapping only matters for the edge texel's interpolation). We only touch
+    // filtering/wrapping, never the caller's data or colour space.
+    let changed = false;
+    if (texture.magFilter !== THREE.LinearFilter) { texture.magFilter = THREE.LinearFilter; changed = true; }
+    if (texture.minFilter !== THREE.LinearFilter) { texture.minFilter = THREE.LinearFilter; changed = true; }
+    if (texture.wrapS !== THREE.ClampToEdgeWrapping) { texture.wrapS = THREE.ClampToEdgeWrapping; changed = true; }
+    if (texture.wrapT !== THREE.ClampToEdgeWrapping) { texture.wrapT = THREE.ClampToEdgeWrapping; changed = true; }
+    if (texture.wrapR !== THREE.ClampToEdgeWrapping) { texture.wrapR = THREE.ClampToEdgeWrapping; changed = true; }
+    if (changed) texture.needsUpdate = true;
+    found = { matIndex: i, texture, origin, size, material: materials[i] };
+  }
+  if (extra > 0) {
+    console.warn(
+      `three-realtime-rt: ${extra + 1} materials set userData.rtVolumeAlbedo, but v1 samples ` +
+      `only ONE volume in the traced-bounce (GI/reflection) path — keeping the first. The other ` +
+      `volumes still render correctly in primary visibility (the G-buffer); multi-volume bounces ` +
+      `are future work.`
+    );
+  }
+  return found;
+}
+
 // Row 0: materials, 2 texels each (albedo+rough, emissive+metal).
 // Row 1: emissive triangles for NEE, 4 texels each:
 //   [v0.xyz | area] [e1.xyz | emit.r] [e2.xyz | emit.g] [n.xyz | emit.b]
@@ -650,6 +760,22 @@ export function compileScene(scene, options = {}) {
   let dynVertexOffset = 0;
   const tmpGeoms = []; // to dispose after merge
 
+  // Usage diagnostics collected during the traverse (see _warnedObjects above).
+  // Each category is reported as ONE aggregated message after the traverse, so a
+  // scene with fifty offenders costs one console line, not fifty.
+  const warnings = [];
+  const diag = {
+    "rtdeforming-not-dynamic": [],
+    "untraceable-object": [],
+    "instanced-mesh": [],
+    "transparent-dynamic": [],
+  };
+  // Per-static-mesh fingerprints for the post-compile staleness check (see
+  // RealtimeRaytracer._checkStale). WeakRef so a mesh removed from the scene
+  // can still be collected — the compiled scene must never keep it alive.
+  const staticSources = [];
+  const canTrack = typeof WeakRef === "function";
+
   const registerMaterial = (m) => {
     let i = materials.indexOf(m);
     if (i < 0) { i = materials.length; materials.push(m); }
@@ -657,7 +783,19 @@ export function compileScene(scene, options = {}) {
   };
 
   scene.traverse((obj) => {
+    // Object types the tracer cannot represent: they are not triangles in a BVH,
+    // and their ESSL1 materials cannot write the 4-attachment G-buffer either, so
+    // GBufferPass hides them for the traced frame. Say so once. An explicit
+    // rtExclude means the app already knows — stay quiet for those.
+    if ((obj.isSprite || obj.isLine || obj.isPoints) && obj.visible && !obj.userData.rtExclude) {
+      diag["untraceable-object"].push(obj);
+      return;
+    }
     if (!obj.isMesh || !obj.geometry || !obj.visible || obj.userData.rtExclude) return;
+    // An InstancedMesh is traversed as ONE mesh: its per-instance matrices are a
+    // GPU attribute the compiler never reads, so every instance past the first
+    // silently vanishes from the traced world (and from the G-buffer).
+    if (obj.isInstancedMesh) diag["instanced-mesh"].push(obj);
     const isArray = Array.isArray(obj.material);
     const rep = isArray ? obj.material[0] : obj.material;
     // Transparent surfaces must not act as opaque occluders — e.g.
@@ -665,9 +803,22 @@ export function compileScene(scene, options = {}) {
     // the whole model in shadow. Alpha-textured glass can't be cheaply tested,
     // so ANY transparent material is skipped like rtExclude (still
     // rasterized). alphaTest cut-outs (transparent: false) stay occluders.
-    if (rep.transparent) return;
+    if (rep.transparent) {
+      // Listing a transparent mesh in dynamicMeshes does nothing at all — it is
+      // dropped here, BEFORE the dynamic registration below, so it is never
+      // BVH-traced and updateDynamic() never touches it.
+      if (dynamicSet && dynamicSet.has(obj)) diag["transparent-dynamic"].push(obj);
+      return;
+    }
 
     const isDynamic = dynamicSet && dynamicSet.has(obj);
+    // rtDeforming alone does nothing: the flag is only read for meshes that are
+    // ALSO in dynamicMeshes (there is no dynamic segment to re-bake otherwise).
+    // Without this warning the mesh compiles static and its traced shadow keeps
+    // the compile-time shape forever, silently.
+    if (obj.userData.rtDeforming === true && !isDynamic) {
+      diag["rtdeforming-not-dynamic"].push(obj);
+    }
     // Opt-in CPU deformation: the mesh must be BOTH in dynamicMeshes AND carry
     // userData.rtDeforming, and its live geometry is read every frame.
     const deforming = isDynamic && obj.userData.rtDeforming === true;
@@ -736,9 +887,65 @@ export function compileScene(scene, options = {}) {
         const emit = emissiveColor(r.material);
         if (emit) collectEmissiveTriangles(extracted.geo, emit, emissiveTris, r.start, r.vcount);
       }
+      // Fingerprint this static source so a later edit (vertices moved, mesh
+      // moved) can be DETECTED instead of quietly tracing the old shape. Two
+      // cheap comparands: the position attribute's version counter and a copy of
+      // matrixWorld. Held via WeakRef — never a strong reference.
+      if (canTrack) {
+        const pos = obj.geometry.getAttribute("position");
+        staticSources.push({
+          ref: new WeakRef(obj),
+          name: describeObject(obj),
+          version: pos ? pos.version : -1,
+          // Float64Array, NOT Float32Array: three's Matrix4.elements holds
+          // doubles, so a float32 snapshot rounds every element by up to ~1e-7
+          // and EVERY static mesh then compares as "moved" (measured: the demo
+          // scene reported 36 of 41 sources stale on the first run of this scan).
+          matrix: new Float64Array(obj.matrixWorld.elements),
+          warned: false,
+        });
+      }
     }
   });
 
+  // ---- report the collected usage diagnostics (one line per category) -------
+  const note = (code, message) => {
+    warnings.push({ code, message });
+  };
+  const report = (code, objs, build) => {
+    if (objs.length === 0) return;
+    const fresh = objs.filter((o) => _firstTime(o, code));
+    const message = build(objs);
+    note(code, message);
+    if (fresh.length > 0) console.warn(message);
+  };
+  report("rtdeforming-not-dynamic", diag["rtdeforming-not-dynamic"], (objs) =>
+    `three-realtime-rt: userData.rtDeforming is set on a mesh that is NOT in ` +
+    `compileScene(scene, {dynamicMeshes:[...]}) — the flag is IGNORED, the mesh ` +
+    `compiles STATIC, and traced shadows/GI keep its compile-time shape forever: ` +
+    `${describeList(objs)}. Add it to dynamicMeshes and call updateDynamic() each ` +
+    `frame to make it actually deform.`
+  );
+  report("untraceable-object", diag["untraceable-object"], (objs) =>
+    `three-realtime-rt: Sprite/Line/Points objects are not traceable geometry and ` +
+    `are auto-hidden from the traced frame (their materials cannot write the ` +
+    `4-attachment G-buffer): ${describeList(objs)}. Draw them in your own overlay ` +
+    `pass on top of rt.render(), or set userData.rtExclude = true to silence this.`
+  );
+  report("instanced-mesh", diag["instanced-mesh"], (objs) =>
+    `three-realtime-rt: InstancedMesh is NOT supported — it collapses to a single ` +
+    `instance in the traced output and in the G-buffer: ${describeList(objs)}. ` +
+    `Expand it to individual meshes, or set userData.rtExclude = true to exclude it.`
+  );
+  report("transparent-dynamic", diag["transparent-dynamic"], (objs) =>
+    `three-realtime-rt: a transparent mesh listed in dynamicMeshes does nothing — ` +
+    `transparent meshes are composited via the blend path and are never BVH-traced ` +
+    `or dynamic-registered: ${describeList(objs)}. Remove it from dynamicMeshes, or ` +
+    `make the material opaque (transparent: false) if it should cast traced shadows.`
+  );
+  compiled.warnings = warnings;
+  compiled.staticSources = staticSources;
+
   if (staticGeoms.length === 0 && dynamicGeoms.length === 0) {
     throw new Error("three-realtime-rt: no meshes found in scene");
   }
@@ -796,6 +1003,10 @@ export function compileScene(scene, options = {}) {
   }
   compiled.hasDynamicEmissive = compiled._dynamicEmissive.length > 0;
   compiled.materialsTex = buildSceneDataTexture(materials, emissiveTris);
+  // World-space 3D-texture albedo opt-in (userData.rtVolumeAlbedo). Resolved from
+  // the deduped material table so the recorded matIndex matches what the BVH
+  // per-vertex attribute stores and the lighting pass reads.
+  compiled.volumeAlbedo = collectVolumeAlbedo(materials);
   syncLights(scene, compiled);
 
   // Static merged geometry is owned by its BVH (disposed with it); dynamic

package/src/index.d.ts

@@ -5,11 +5,56 @@ import type {
   Color,
   Vector3,
   Object3D,
+  Data3DTexture,
 } from "three";
 
 /** Capability tier used to pick sensible defaults. */
 export type Tier = "none" | "mid" | "high";
 
+/**
+ * World-space 3D-texture albedo ("volumetric surface albedo"). Set it on a
+ * material's `userData.rtVolumeAlbedo` to make the tracer sample a 3D texture at
+ * the world-space HIT POINT for that surface's albedo — colouring a mesh by a
+ * volumetric data field (stress, temperature, density) instead of a flat colour
+ * or a 2D UV map. The colour replaces the base albedo in BOTH primary visibility
+ * (the G-buffer, so the raster/hybrid view agrees) and the traced GI / reflection
+ * bounces (so the field's colours bleed correctly through global illumination).
+ * Roughness, metalness and emissive still compose normally.
+ *
+ * ```js
+ * material.userData.rtVolumeAlbedo = {
+ *   texture,                      // THREE.Data3DTexture, RGB(A), already colour-mapped
+ *   origin: new THREE.Vector3(),  // world position of the texel-(0,0,0) corner
+ *   size:   new THREE.Vector3(1,1,1), // world extent of the full volume
+ * };
+ * rt.compileScene(scene);         // (re)compile after adding/changing it
+ * ```
+ *
+ * The hit point `p` maps to `uvw = clamp((p - origin) / size, 0, 1)` and is
+ * sampled trilinearly (the library sets Linear filtering + ClampToEdge on the
+ * texture at compile time). The texture must be **already colour-mapped to RGB** —
+ * the library samples `.rgb` directly and contains no colormap logic. Changing the
+ * texture DATA later needs only `texture.needsUpdate = true` (no recompile);
+ * changing which material carries the field, or its `origin` / `size`, needs a
+ * `compileScene()`.
+ *
+ * **v1 is single-volume for the traced-bounce path.** Any number of materials may
+ * carry distinct volumes and each renders correctly in primary visibility, but the
+ * GI / reflection bounce samples only the FIRST registered volume (the lighting
+ * megakernel is at the WebGL2 16-sampler minimum; the feature adds one sampler3D,
+ * enabled only when the GPU exposes ≥ 17 fragment texture units — on a bare-minimum
+ * 16-unit device the bounces fall back to the material's flat base colour while
+ * primary visibility still shows the full field). Multi-volume bounces are future work.
+ */
+export interface VolumeAlbedo {
+  /** A THREE.Data3DTexture, RGB(A) and already colour-mapped; `.rgb` is sampled. */
+  texture: Data3DTexture;
+  /** World position of the texel-(0,0,0) corner of the volume. */
+  origin: Vector3;
+  /** World extent of the full texture volume along each axis (non-zero). */
+  size: Vector3;
+}
+
 /** Result of {@link RealtimeRaytracer.probeGPUTier}. */
 export interface GPUTierProbe {
   /** Chosen capability tier. */
@@ -299,6 +344,36 @@ export interface DisabledPass {
  * with a reason instead of guessing. Populated over the first several rendered
  * frames (link status is checked lazily / can be deferred by the driver).
  */
+/**
+ * A **usage** diagnostic on {@link RaytracerStatus.warnings} (since 0.7.0). Unlike
+ * {@link DisabledPass}, nothing is broken in the pipeline — the SCENE SETUP is
+ * not what the app probably intended (a flag that is being ignored, an object
+ * type that cannot be traced, a static mesh edited after `compileScene()`). Each
+ * one is also `console.warn`ed once, with the exact fix in the text.
+ */
+export interface RaytracerWarning {
+  /**
+   * Stable machine-readable identifier:
+   * - `"stale-geometry"` — a static mesh's `position` buffer changed after `compileScene()`.
+   * - `"stale-transform"` — a static mesh was moved after `compileScene()`.
+   * - `"rtdeforming-not-dynamic"` — `userData.rtDeforming` set on a mesh that is not in `dynamicMeshes` (ignored).
+   * - `"implicit-compile"` — `render()` compiled the scene itself, so it was compiled with no options.
+   * - `"untraceable-object"` — a visible `Sprite` / `Line` / `Points` was auto-hidden from the traced frame.
+   * - `"instanced-mesh"` — an `InstancedMesh` collapses to a single instance.
+   * - `"transparent-dynamic"` — a transparent mesh listed in `dynamicMeshes` (the entry does nothing).
+   */
+  code:
+    | "stale-geometry"
+    | "stale-transform"
+    | "rtdeforming-not-dynamic"
+    | "implicit-compile"
+    | "untraceable-object"
+    | "instanced-mesh"
+    | "transparent-dynamic";
+  /** Full human-readable message (names the object, the consequence and the fix). */
+  message: string;
+}
+
 export interface RaytracerStatus {
   /**
    * True while every ray tracing pass is running as intended. Flips to false the
@@ -314,6 +389,13 @@ export interface RaytracerStatus {
    * is a `"rt:<pass>: <driver log>"` summary; null when no core pass has failed.
    */
   coreFailure: string | null;
+  /**
+   * Usage diagnostics raised for this scene (**since 0.7.0**) — see
+   * {@link RaytracerWarning}. Deduplicated by `code` + `message`, and each one is
+   * also `console.warn`ed once. **`ok` is NOT affected by warnings**: the
+   * pipeline is compiling and running fine, the scene setup is what looks wrong.
+   */
+  warnings: RaytracerWarning[];
 }
 
 /** Options accepted by {@link RealtimeRaytracer.compileScene} and {@link compileScene}. */
@@ -359,8 +441,24 @@ export class CompiledScene {
   sceneDiagonal: number;
   /** True when any dynamic emitter contributes NEE rows refreshed each frame. */
   hasDynamicEmissive: boolean;
+  /**
+   * The resolved world-space 3D-texture albedo for the traced-bounce path (see
+   * {@link VolumeAlbedo}), or `null` when no material opted in via
+   * `userData.rtVolumeAlbedo`. `matIndex` is the material's index in the compiled
+   * table (v1 keeps the first opted-in material for the GI/reflection path).
+   */
+  volumeAlbedo:
+    | { matIndex: number; texture: Data3DTexture; origin: Vector3; size: Vector3; material: unknown }
+    | null;
   /** CPU cost (ms) of the most recent dynamic-emissive refresh (0 if none). */
   lastEmissiveRefreshMs: number;
+  /**
+   * Usage diagnostics raised while compiling this scene (**since 0.7.0**). The
+   * standalone {@link compileScene} reports these to the console; going through
+   * {@link RealtimeRaytracer.compileScene} additionally mirrors them onto
+   * {@link RaytracerStatus.warnings}.
+   */
+  warnings: RaytracerWarning[];
   /**
    * Re-bake moving meshes' current world transforms and refit the dynamic BVH.
    * Also refreshes any dynamic emitters' NEE area-light rows + power CDF from the
@@ -422,7 +520,8 @@ export class RealtimeRaytracer {
    * link; `status.disabled` lists auto-disabled optional features; and
    * `status.coreFailure` names an unrecoverable core-pass failure. Populated over
    * the first several rendered frames. When `supported` is false, `status.ok` is
-   * false too (the RT pipeline is not operational).
+   * false too (the RT pipeline is not operational). `status.warnings` (since
+   * 0.7.0) carries USAGE diagnostics and never changes `status.ok`.
    */
   status: RaytracerStatus;
   /** Accumulated frame counter. */