@tinypoly/gpu-renderer 0.2.5 → 0.3.0

package/src/texturePack.ts

@@ -1,12 +1,14 @@
-import type { SerializedScene, SerializedTexture } from "./upstream.js";
+import type { ShaderPrograms } from "./shaderProgram.js";
+import type { SerializedMaterial, SerializedScene, SerializedTexture } from "./upstream.js";
 
 /**
  * Every texture of a scene in one storage buffer, led by a table saying where each one lives. Core WebGPU has no binding
  * arrays and `texture_2d_array` wants one size and one format for every layer, which a Three.js scene does not provide,
  * so the texels are read by hand. See the decision in ARCHITECTURE.md.
  *
- * Byte textures keep their eight bits per channel, four to a word, and are decoded from sRGB as they are read. Float
- * textures keep all four, because their range is the reason they are float at all.
+ * Byte textures keep their eight bits per channel, four to a word, and are decoded from sRGB as they are read. A byte
+ * texture of which only one channel is ever read (a roughness or a bump map) keeps that channel alone, four texels to a
+ * word. Float textures keep all four, because their range is the reason they are float at all.
  */
 export interface PackedTextures {
   /**
@@ -97,6 +99,8 @@ const TEXTURE_NEAREST = 4;
 const TEXTURE_FLIP_Y = 8;
 /** An environment map whose mapping bends the view ray instead of mirroring it. */
 const TEXTURE_REFRACTION = 16;
+/** One byte a texel: the only channel the scene reads of it, which the shader hands back in every channel. */
+const TEXTURE_SINGLE = 32;
 
 /** Three's own wrap constants, which the shader compares against. */
 const REPEAT = 1000;
@@ -118,6 +122,139 @@ const isFloat = (texture: SerializedTexture) => texture.data instanceof Float32A
  */
 const isEncoded = (texture: SerializedTexture) => !isFloat(texture) && texture.colorSpace === "srgb";
 
+/**
+ * The channels the kernel reads from each material map slot, as the WGSL reads them: roughness from green, metalness
+ * from blue, and so on. A slot missing here counts as reading all four.
+ */
+export const SLOT_CHANNELS: Readonly<Record<string, string>> = {
+  map: "rgba", emissiveMap: "rgb", roughnessMap: "g", metalnessMap: "b", normalMap: "rgb", clearcoatNormalMap: "rgb",
+  alphaMap: "g", transmissionMap: "r", thicknessMap: "g", clearcoatMap: "r", clearcoatRoughnessMap: "g",
+  sheenColorMap: "rgb", sheenRoughnessMap: "a", iridescenceMap: "r", iridescenceThicknessMap: "g", anisotropyMap: "rgb",
+  specularMap: "r", specularIntensityMap: "a", specularColorMap: "rgb", bumpMap: "r", displacementMap: "r",
+  lightMap: "rgb", gradientMap: "r", matcap: "rgb", envMap: "rgb",
+};
+
+/** Every string inside a value, with the first path it was found at, without walking into typed arrays. */
+function collectStrings(value: unknown, path: string, into: Map<string, string>, seen = new Set<unknown>()) {
+  if (typeof value === "string") {
+    if (!into.has(value)) into.set(value, path);
+
+    return;
+  }
+
+  if (!value || typeof value !== "object" || seen.has(value) || ArrayBuffer.isView(value)) return;
+
+  seen.add(value);
+
+  for (const [key, entry] of Object.entries(value)) collectStrings(entry, `${path}.${key}`, into, seen);
+}
+
+/** How each texture of a scene is stored: one channel, or all four and why. */
+export interface TextureChannels {
+  /** The channel kept (0 for red to 3 for alpha) of each texture stored one byte a texel. */
+  single: Map<string, number>;
+  /** Why every other texture keeps all four. */
+  whole: Map<string, string>;
+}
+
+/** Texture indices no table reaches, one per texture, which a program's packed uniforms give back where it reads one. */
+const PROBE = 0x7f000000;
+
+/**
+ * The textures a material's translated programs read: their uniforms are packed with a probe index for every texture,
+ * and the probes that come back are the textures the programs declare. A texture a hook's uniforms name but its
+ * program never declares (Three hands a patched material's every map to its shader) is not read by it.
+ */
+function programTextures(material: SerializedMaterial, programs: Pick<ShaderPrograms, "fragment" | "after">,
+  textures: readonly SerializedTexture[]): Set<string> {
+  const probes = new Map(textures.map((texture, index) => [texture.id, PROBE + index]));
+  const uniforms = { ...material.shader?.uniforms, ...material.time !== undefined ? { time: material.time } : {} };
+  const read = new Set<string>();
+
+  for (const program of [programs.fragment(material), programs.after(material)]) {
+    if (!program) continue;
+
+    for (const word of program.packUniforms(uniforms, probes))
+      if (word >= PROBE && word < PROBE + textures.length) read.add(textures[word - PROBE].id);
+  }
+
+  return read;
+}
+
+/**
+ * Which byte textures of a scene are read through one channel only: every reference to the texture is a material map
+ * slot, and every such slot reads the same channel. A texture named anywhere else (a light's projected map, the sky, a
+ * planar capture) is read in ways this cannot see, and keeps all four. With the scene's translated programs, a
+ * shader's uniforms count only for the textures its program reads; without them, any texture they name keeps all four.
+ */
+export function textureChannels(scene: SerializedScene,
+  programs?: Pick<ShaderPrograms, "fragment" | "after">): TextureChannels {
+  const read = new Map<string, Set<string>>();
+  const elsewhere = new Map<string, string>();
+  const materials = new Set(scene.meshes.flatMap(mesh => mesh.materials));
+
+  for (const material of materials) {
+    if (!material) continue;
+
+    const { maps, ...everything } = material;
+    const name = `material "${material.name || material.type}"`;
+    // The shader's uniforms are read only through its translated programs, which say what they sample.
+    const { shader, ...rest } = everything;
+
+    if (programs && shader) {
+      for (const id of programTextures(material, programs, scene.textures ?? []))
+        if (!elsewhere.has(id)) elsewhere.set(id, `the shader of ${name}`);
+    } else if (shader) {
+      collectStrings(shader, `${name}.shader`, elsewhere);
+    }
+
+    for (const [slot, id] of Object.entries(maps ?? {})) {
+      if (typeof id !== "string") continue;
+
+      let channels = read.get(id);
+
+      if (!channels) read.set(id, channels = new Set());
+
+      for (const channel of SLOT_CHANNELS[slot] ?? "rgba") channels.add(channel);
+    }
+
+    collectStrings(rest, name, elsewhere);
+  }
+
+  // The rest of the scene: its lights, its sky and whatever else names a texture.
+  for (const [key, value] of Object.entries(scene))
+    if (key !== "meshes" && key !== "textures") collectStrings(value, key, elsewhere);
+
+  const single = new Map<string, number>();
+  const whole = new Map<string, string>();
+
+  for (const texture of scene.textures ?? []) {
+    const channels = read.get(texture.id);
+    const named = elsewhere.get(texture.id);
+
+    if (isFloat(texture)) whole.set(texture.id, "float");
+    else if (!channels) whole.set(texture.id, named ? `named by ${named}` : "not read by any map");
+    else if (channels.size !== 1) whole.set(texture.id, `reads ${[...channels].join("")}`);
+    else if (named) whole.set(texture.id, `named by ${named}`);
+    else single.set(texture.id, "rgba".indexOf([...channels][0]));
+  }
+
+  return { single, whole };
+}
+
+/** The byte textures of a scene read through one channel only, with that channel: see `textureChannels`. */
+export function singleChannelTextures(scene: SerializedScene,
+  programs?: Pick<ShaderPrograms, "fragment" | "after">): Map<string, number> {
+  return textureChannels(scene, programs).single;
+}
+
+/** Words a texture's texels take in the buffer. */
+function texelWords(texture: SerializedTexture, single: boolean): number {
+  const texels = texelCount(texture);
+
+  return isFloat(texture) ? texels * 4 : single ? Math.ceil(texels / 4) : texels;
+}
+
 /**
  * Where everything will go, before anything is written: which index each texture gets and where the words after the
  * texels begin. Materials and lights point into that tail by absolute offset, so they need it before the buffer exists.
@@ -125,13 +262,16 @@ const isEncoded = (texture: SerializedTexture) => !isFloat(texture) && texture.c
 export interface TexturePlan {
   textures: SerializedTexture[];
   indexOf: Map<string, number>;
+  /** The channel kept of each texture stored one byte a texel, by id. */
+  channelOf: ReadonlyMap<string, number>;
   /** The lookup tables and the texture table together: where the texels begin. */
   tableWords: number;
   /** Where the words appended after the texels begin. */
   extraOffset: number;
 }
 
-export function planTextures(scene: SerializedScene, extraTextures: readonly SerializedTexture[] = []): TexturePlan {
+export function planTextures(scene: SerializedScene, extraTextures: readonly SerializedTexture[] = [],
+  channelOf: ReadonlyMap<string, number> = singleChannelTextures(scene)): TexturePlan {
   const seen = new Set<string>();
 
   // A texture id appears once, whoever refers to it; the first copy wins.
@@ -141,40 +281,43 @@ export function planTextures(scene: SerializedScene, extraTextures: readonly Ser
 
   const indexOf = new Map(textures.map((texture, index) => [texture.id, index]));
   const tableWords = TEXTURE_TABLE + Math.max(1, textures.length) * TEXTURE_WORDS;
-  const texelWords = textures.reduce((sum, texture) => sum + texelCount(texture) * (isFloat(texture) ? 4 : 1), 0);
+  const kept = new Map([...channelOf].filter(([id]) => indexOf.has(id)));
+  const words = textures.reduce((sum, texture) => sum + texelWords(texture, kept.has(texture.id)), 0);
 
-  return { textures, indexOf, tableWords, extraOffset: tableWords + texelWords };
+  return { textures, indexOf, channelOf: kept, tableWords, extraOffset: tableWords + words };
 }
 
 export function packTextures(scene: SerializedScene, extras: TextureExtras = {}): PackedTextures {
   return writeTextures(planTextures(scene, extras.textures), extras.words ?? new Uint32Array(0));
 }
 
-/** The buffer a plan describes, with `extraWords` appended at its `extraOffset`. */
-export function writeTextures(plan: TexturePlan, extraWords: Uint32Array): PackedTextures {
-  const { textures, indexOf, tableWords } = plan;
-
-  // WebGPU rejects an empty binding, and a scene with no textures at all is ordinary.
-  const data = new Uint32Array(Math.max(4, plan.extraOffset + extraWords.length));
-  const words = data;
-  const floats = new Float32Array(data.buffer);
-  let texelAt = tableWords;
+/**
+ * The lookup tables and the texture table a plan describes, written at the head of `words`. Returns where each
+ * texture's texels start, in words.
+ */
+function writeTable(words: Uint32Array, plan: TexturePlan): number[] {
+  const floats = new Float32Array(words.buffer, words.byteOffset, words.length);
+  const offsets: number[] = [];
+  let texelAt = plan.tableWords;
 
-  data.set(LOOKUP, 0);
+  words.set(LOOKUP, 0);
 
-  textures.forEach((texture, index) => {
+  plan.textures.forEach((texture, index) => {
     const at = textureEntry(index);
-    const texels = texelCount(texture);
     const float = isFloat(texture);
 
+    offsets.push(texelAt);
     words[at] = texture.width;
     words[at + 1] = texture.height;
     words[at + 2] = texelAt;
+
     words[at + 3] = (float ? TEXTURE_FLOAT : 0)
       | (isEncoded(texture) ? TEXTURE_SRGB : 0)
       | (texture.nearest ? TEXTURE_NEAREST : 0)
       | (texture.flipY ? TEXTURE_FLIP_Y : 0)
-      | (texture.refraction ? TEXTURE_REFRACTION : 0);
+      | (texture.refraction ? TEXTURE_REFRACTION : 0)
+      | (plan.channelOf.has(texture.id) ? TEXTURE_SINGLE : 0);
+
     words[at + 4] = texture.wrapS;
     words[at + 5] = texture.wrapT;
     words[at + 6] = Math.min(Math.max(0, texture.channel | 0), UV_CHANNELS - 1);
@@ -185,35 +328,123 @@ export function writeTextures(plan: TexturePlan, extraWords: Uint32Array): Packe
 
     floats.set([matrix[0], matrix[3], matrix[6], 0], at + 8);
     floats.set([matrix[1], matrix[4], matrix[7], 0], at + 12);
+    texelAt += texelWords(texture, plan.channelOf.has(texture.id));
+  });
+
+  return offsets;
+}
+
+/**
+ * A texture's texels as the buffer holds them: viewed straight from the snapshot where the bytes already agree, the one
+ * channel kept copied out four texels to a word, or null for a byte texture a big endian page has to turn around.
+ */
+function texelView(texture: SerializedTexture, channel: number | undefined): ArrayBufferView | null {
+  const texels = texelCount(texture);
+
+  if (isFloat(texture)) return (texture.data as Float32Array).subarray(0, texels * 4);
+
+  if (channel !== undefined) {
+    const source = texture.data as Uint8Array;
+    // Bytes in the order the device reads a word's, lowest first, so this needs no turning around on any page.
+    const kept = new Uint8Array(Math.ceil(texels / 4) * 4);
+
+    for (let texel = 0; texel < texels; texel++) kept[texel] = source[texel * 4 + channel];
+
+    return kept;
+  }
+
+  return LITTLE_ENDIAN ? (texture.data as Uint8Array).subarray(0, texels * 4) : null;
+}
+
+/** The buffer a plan describes, with `extraWords` appended at its `extraOffset`. */
+export function writeTextures(plan: TexturePlan, extraWords: Uint32Array): PackedTextures {
+  const { textures, indexOf } = plan;
+  // WebGPU rejects an empty binding, and a scene with no textures at all is ordinary.
+  const data = new Uint32Array(Math.max(4, plan.extraOffset + extraWords.length));
+  const offsets = writeTable(data, plan);
+
+  textures.forEach((texture, index) => {
+    const texelAt = offsets[index];
+    const view = texelView(texture, plan.channelOf.get(texture.id));
+
+    if (view) {
+      // The channels keep their bits, and bytes already sit in the order the words want them: copied whole.
+      new Uint8Array(data.buffer, texelAt * 4, view.byteLength)
+        .set(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+
+      return;
+    }
 
-    if (float) {
-      // The channels keep their bits and the shader reads them back as floats.
-      floats.set((texture.data as Float32Array).subarray(0, texels * 4), texelAt);
-      texelAt += texels * 4;
-    } else {
-      const source = texture.data as Uint8Array;
-
-      if (LITTLE_ENDIAN) {
-        // The bytes already sit in the order the words want them: copied whole, as the GPU reads them.
-        new Uint8Array(data.buffer, texelAt * 4, texels * 4).set(source.subarray(0, texels * 4));
-      } else {
-        for (let texel = 0; texel < texels; texel++) {
-          const offset = texel * 4;
-
-          words[texelAt + texel] = source[offset]
-            | (source[offset + 1] << 8)
-            | (source[offset + 2] << 16)
-            | (source[offset + 3] << 24);
-        }
-      }
-
-      texelAt += texels;
+    const source = texture.data as Uint8Array;
+
+    for (let texel = 0; texel < texelCount(texture); texel++) {
+      const offset = texel * 4;
+
+      data[texelAt + texel] = source[offset]
+        | (source[offset + 1] << 8)
+        | (source[offset + 2] << 16)
+        | (source[offset + 3] << 24);
     }
   });
 
-  data.set(extraWords, texelAt);
+  data.set(extraWords, plan.extraOffset);
+
+  return { data, count: textures.length, indexOf, extraOffset: plan.extraOffset };
+}
+
+/**
+ * The same buffer `writeTextures` builds, written to the device a piece at a time: the tables, then each texture's
+ * texels straight from the snapshot, then the extra words. The page never holds the whole buffer, which for a scene of
+ * many large textures is hundreds of megabytes it would only hold to hand over.
+ */
+export interface TextureUpload {
+  byteLength: number;
+  count: number;
+  indexOf: Map<string, number>;
+  extraOffset: number;
+  /** Where each texture's texels start, in words, by its index in the table. */
+  offsets: number[];
+  write(device: GPUDevice, buffer: GPUBuffer): void;
+}
+
+export function textureUpload(plan: TexturePlan, extraWords: Uint32Array): TextureUpload {
+  const byteLength = Math.max(4, plan.extraOffset + extraWords.length) * 4;
+
+  // A big endian page has to turn every byte texel around, which needs the whole buffer anyway.
+  if (!LITTLE_ENDIAN) {
+    const packed = writeTextures(plan, extraWords);
+
+    return {
+      byteLength,
+      count: packed.count,
+      indexOf: packed.indexOf,
+      extraOffset: packed.extraOffset,
+      offsets: plan.textures.map((_, index) => packed.data[textureEntry(index) + 2]),
+      write: (device, buffer) => device.queue.writeBuffer(buffer, 0, packed.data),
+    };
+  }
+
+  const header = new Uint32Array(plan.tableWords);
+  const offsets = writeTable(header, plan);
+
+  return {
+    byteLength,
+    count: plan.textures.length,
+    indexOf: plan.indexOf,
+    extraOffset: plan.extraOffset,
+    offsets,
+    write(device, buffer) {
+      device.queue.writeBuffer(buffer, 0, header);
+
+      plan.textures.forEach((texture, index) => {
+        const view = texelView(texture, plan.channelOf.get(texture.id)) as ArrayBufferView;
+
+        if (view.byteLength) device.queue.writeBuffer(buffer, offsets[index] * 4, view);
+      });
 
-  return { data, count: textures.length, indexOf, extraOffset: texelAt };
+      if (extraWords.length) device.queue.writeBuffer(buffer, plan.extraOffset * 4, extraWords);
+    },
+  };
 }
 
 export { MIRRORED_REPEAT, REPEAT };

package/src/wgsl/bvh.wgsl.ts

@@ -4,6 +4,10 @@
  * The positions are uploaded in the hierarchy's leaf order, so a leaf is a run of triangles read straight off the
  * buffer; the scene's own triangle number is looked up once, for the hit a trace returns. Every other reader goes the
  * other way, from a triangle number to where its corners sit.
+ *
+ * With INSTANCES compiled in, a leaf with a count of -1 is an instance: the ray is taken into its object space and
+ * the traversal goes on in its prototype's hierarchy, with a marker on the stack that brings it back to world space.
+ * The distance along the ray is the same in both spaces, since the direction is transformed and not normalized.
  */
 export const BVH_WGSL = /* wgsl */ `
 /** A corner of the triangle at this position of the hierarchy's leaf order. */
@@ -18,8 +22,37 @@ fn leafOf(triangle: u32) -> u32 {
   return indices[frame.leafOffset + triangle];
 }
 
+/** A corner of a triangle a hit named, in world space. */
 fn triangleVertex(triangle: u32, corner: u32) -> vec3<f32> {
-  return leafVertex(leafOf(triangle), corner);
+  let instance = instanceOf(triangle);
+  let p = leafVertex(leafOf(storedTriangle(triangle, instance)), corner);
+
+  if (instance != NO_INSTANCE) {
+    return instancePoint(instance, p);
+  }
+
+  return p;
+}
+
+/** The stack entry that leaves an instance: the traversal goes back to world space. */
+const RETURN_ENTRY: u32 = 0xffffffffu;
+
+/** A huge finite reciprocal instead of an infinite one: an axis aligned slab would otherwise produce 0 * inf. */
+fn rayInverse(direction: vec3<f32>) -> vec3<f32> {
+  let signs = select(vec3<f32>(-1.0), vec3<f32>(1.0), direction >= vec3<f32>(0.0));
+
+  return signs / max(abs(direction), vec3<f32>(1e-20));
+}
+
+/** The number a hit goes by, from where it sits in the leaf order and the instance it was found in. */
+fn namedTriangle(at: u32, instance: u32) -> u32 {
+  let stored = orderedTriangle(at);
+
+  if (INSTANCES && instance != NO_INSTANCE) {
+    return instanceWord(instance, 26u) + stored - instanceWord(instance, 25u);
+  }
+
+  return stored;
 }
 
 /** Moller-Trumbore. Returns the distance in x and the barycentric coordinates in yz, or a negative distance. */
@@ -127,7 +160,7 @@ fn waitingLeaf(entry: u32) -> vec2<i32> {
  * A leaf is tested at the top of the next step, the one place the loop tests triangles, which keeps the kernel small.
  * This visits what the binary tree's traversal visited, in the same order, so it finds the same hit.
  */
-fn traceScene(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> Hit {
+fn traceScene(worldOrigin: vec3<f32>, worldDirection: vec3<f32>, maxDistance: f32) -> Hit {
   var hit: Hit;
   hit.distance = maxDistance;
   hit.triangle = NO_HIT;
@@ -138,12 +171,15 @@ fn traceScene(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> Hit
     return hit;
   }
 
-  // A huge finite reciprocal instead of an infinite one: an axis aligned slab would otherwise produce 0 * inf.
-  let signs = select(vec3<f32>(-1.0), vec3<f32>(1.0), direction >= vec3<f32>(0.0));
-  let inverse = signs / max(abs(direction), vec3<f32>(1e-20));
+  var origin = worldOrigin;
+  var direction = worldDirection;
+  var inverse = rayInverse(direction);
+  // The instance the traversal is inside, and the one the closest hit so far was found in.
+  var instance = NO_INSTANCE;
+  var hitInstance = NO_INSTANCE;
 
-  var stack: array<u32, 32>;
-  var enters: array<f32, 32>;
+  var stack: array<u32, BVH_STACK>;
+  var enters: array<f32, BVH_STACK>;
   var depth = 0u;
   var current = 0u;
   // A leaf to test before anything else: its link, and its triangle count, zero when there is none.
@@ -151,10 +187,32 @@ fn traceScene(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> Hit
 
   loop {
     if (leaf.y > 0) {
+      let before = hit.distance;
+
       intersectLeaf(leaf.x, leaf.y, origin, direction, &hit);
+
+      if (INSTANCES && hit.distance < before) {
+        hitInstance = instance;
+      }
+
       leaf.y = 0;
     }
 
+    if (INSTANCES && leaf.y < 0) {
+      leaf.y = 0;
+
+      if (depth < BVH_STACK) {
+        instance = u32(-1 - leaf.x);
+        stack[depth] = RETURN_ENTRY;
+        enters[depth] = -1.0;
+        depth = depth + 1u;
+        origin = instanceToObject(instance, worldOrigin, 1.0);
+        direction = instanceToObject(instance, worldDirection, 0.0);
+        inverse = rayInverse(direction);
+        current = instanceWord(instance, 24u);
+      }
+    }
+
     if (current == NO_NODE) {
       if (depth == 0u) {
         break;
@@ -169,6 +227,14 @@ fn traceScene(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> Hit
 
       let entry = stack[depth];
 
+      if (INSTANCES && entry == RETURN_ENTRY) {
+        instance = NO_INSTANCE;
+        origin = worldOrigin;
+        direction = worldDirection;
+        inverse = rayInverse(direction);
+        continue;
+      }
+
       if ((entry & LEAF_ENTRY) != 0u) {
         leaf = waitingLeaf(entry);
         continue;
@@ -198,7 +264,7 @@ fn traceScene(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> Hit
     }
 
     // The builder caps its depth so the far children always fit; the guard keeps a malformed tree inside the stack.
-    if (farEnter < 1e30 && depth < 32u) {
+    if (farEnter < 1e30 && depth < BVH_STACK) {
       stack[depth] = select(u32(farLink), leafEntry(parent, leftFirst), farLink < 0);
       enters[depth] = farEnter;
       depth = depth + 1u;
@@ -206,7 +272,7 @@ fn traceScene(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> Hit
   }
 
   if (hit.triangle != NO_HIT) {
-    hit.triangle = orderedTriangle(hit.triangle);
+    hit.triangle = namedTriangle(hit.triangle, hitInstance);
   }
 
   return hit;
@@ -217,15 +283,17 @@ fn traceScene(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> Hit
  * closest: what a shadow ray asks when every surface it could meet blocks it. Returns that triangle, or NO_HIT. The
  * right child goes first and the left one waits, the order the binary tree's traversal took.
  */
-fn traceAny(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> u32 {
+fn traceAny(worldOrigin: vec3<f32>, worldDirection: vec3<f32>, maxDistance: f32) -> u32 {
   if (frame.triangleCount == 0u) {
     return NO_HIT;
   }
 
-  let signs = select(vec3<f32>(-1.0), vec3<f32>(1.0), direction >= vec3<f32>(0.0));
-  let inverse = signs / max(abs(direction), vec3<f32>(1e-20));
+  var origin = worldOrigin;
+  var direction = worldDirection;
+  var inverse = rayInverse(direction);
+  var instance = NO_INSTANCE;
 
-  var stack: array<u32, 32>;
+  var stack: array<u32, BVH_STACK>;
   var depth = 0u;
   var current = 0u;
   var leaf = vec2<i32>(0, 0);
@@ -235,12 +303,26 @@ fn traceAny(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> u32 {
       let found = anyInLeaf(leaf.x, leaf.y, origin, direction, maxDistance);
 
       if (found != NO_HIT) {
-        return orderedTriangle(found);
+        return namedTriangle(found, instance);
       }
 
       leaf.y = 0;
     }
 
+    if (INSTANCES && leaf.y < 0) {
+      leaf.y = 0;
+
+      if (depth < BVH_STACK) {
+        instance = u32(-1 - leaf.x);
+        stack[depth] = RETURN_ENTRY;
+        depth = depth + 1u;
+        origin = instanceToObject(instance, worldOrigin, 1.0);
+        direction = instanceToObject(instance, worldDirection, 0.0);
+        inverse = rayInverse(direction);
+        current = instanceWord(instance, 24u);
+      }
+    }
+
     if (current == NO_NODE) {
       if (depth == 0u) {
         break;
@@ -250,6 +332,14 @@ fn traceAny(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> u32 {
 
       let entry = stack[depth];
 
+      if (INSTANCES && entry == RETURN_ENTRY) {
+        instance = NO_INSTANCE;
+        origin = worldOrigin;
+        direction = worldDirection;
+        inverse = rayInverse(direction);
+        continue;
+      }
+
       if ((entry & LEAF_ENTRY) != 0u) {
         leaf = waitingLeaf(entry);
         continue;
@@ -277,7 +367,7 @@ fn traceAny(origin: vec3<f32>, direction: vec3<f32>, maxDistance: f32) -> u32 {
       }
     }
 
-    if (rightHit && leftHit && depth < 32u) {
+    if (rightHit && leftHit && depth < BVH_STACK) {
       stack[depth] = select(u32(node.leftLink), leafEntry(parent, false), node.leftLink < 0);
       depth = depth + 1u;
     }