@tinypoly/gpu-renderer 0.0.4 → 0.1.0

package/src/settings.ts

@@ -0,0 +1,234 @@
+import { DEFAULT_RENDER_SETTINGS, mergeSettings, type RenderSettings } from "./upstream.js";
+
+/**
+ * The settings this renderer reads beyond the CPU renderer's own: what makes a path traced image look photographed.
+ * They ride in the same object as the shared settings, so a host hands one object to either renderer; the CPU renderer
+ * leaves the groups it does not know alone.
+ */
+export interface GpuRenderSettings extends Omit<RenderSettings, "globalIllumination"> {
+  globalIllumination: RenderSettings["globalIllumination"] & {
+    /**
+     * Ends a path that carries little light by chance instead of by its bounce count, weighting the survivors up so
+     * the mean stays exact. It is what makes a high bounce count affordable.
+     */
+    russianRoulette: boolean;
+    /** Bounces every path takes before the roulette may end it: the first ones carry most of the light. */
+    rouletteStart: number;
+    /**
+     * Picks the light to aim at by what it can deliver to the point being shaded (its power, distance and the way it
+     * faces), through a tree over the scene's lights, instead of by its power alone. A small lamp near a surface then
+     * gets the samples a large panel far away would have taken.
+     */
+    lightTree: boolean;
+  };
+  /**
+   * The light a real lens and sensor scatter around anything bright: a soft halo that fades with distance. Energy
+   * conserving, with no threshold, so it only shows where something is much brighter than its surroundings.
+   */
+  bloom: {
+    enabled: boolean;
+    /** Share of the light the halo takes, `0` to `1`. A real lens scatters a few percent. */
+    intensity: number;
+    /** How far the halo reaches, `0` to `1`: from a tight glow to one across the frame. */
+    radius: number;
+  };
+  /**
+   * The rays that stream from a bright light through a lens: diffraction at the edges of the aperture's blades. An
+   * even number of blades makes as many rays, an odd number twice as many. Energy conserving like the bloom, so only
+   * light far brighter than its surroundings shows them.
+   */
+  glare: {
+    enabled: boolean;
+    /** Share of the light the rays take, `0` to `1`. */
+    intensity: number;
+    /** Blades of the aperture, `3` to `16`. */
+    blades: number;
+    /** How far the rays reach, as a share of the frame's half diagonal. */
+    length: number;
+    /** Degrees the aperture is turned by. */
+    rotation: number;
+  };
+  /** What an actual lens does to the image besides focusing it. */
+  lens: {
+    /**
+     * Lateral chromatic aberration, `0` to `1`: red and blue land slightly apart towards the corners, as through any
+     * real glass. `1` shifts them by half a percent of the frame's half diagonal at the corners.
+     */
+    chromaticAberration: number;
+    /** Radial distortion: positive bulges straight lines outwards (barrel), negative pinches them (pincushion). */
+    distortion: number;
+  };
+  /** A camera's exposure triangle and white balance. */
+  camera: {
+    /**
+     * Exposes from `iso`, `shutterSpeed` and `depthOfField.aperture` as a camera would, with `exposure` as a
+     * compensation on top. The scene's lights then have to be in physical units (lux, candela, nits).
+     */
+    physicalExposure: boolean;
+    iso: number;
+    /** Seconds. */
+    shutterSpeed: number;
+    /**
+     * The colour temperature the camera takes as white, in kelvin. `6500` is neutral; a lower value cools the image,
+     * as a camera set for tungsten light does in daylight.
+     */
+    whiteBalance: number;
+  };
+  /** Light that enters a material and leaves it somewhere else: skin, wax, marble, leaves, milk. */
+  subsurface: {
+    /** Materials with `userData.cpuRenderer.subsurface` scatter light inside themselves. Off renders them opaque. */
+    enabled: boolean;
+  };
+  /**
+   * Aerial perspective: the air between the camera and what it sees, which fades distant things towards the colour of
+   * the sky, bluer for clean air and greyer for haze. It needs a scene in metres to look right.
+   */
+  atmosphere: {
+    enabled: boolean;
+    /**
+     * Meteorological visibility, in scene units: the distance at which a dark object fades to 2 percent contrast.
+     * Twenty kilometres is a clear day, two a hazy one.
+     */
+    visibility: number;
+    /** `0` is clean air, scattering blue far more than red (Rayleigh); `1` is haze, scattering every colour alike. */
+    haze: number;
+    /** The colour the air glows with, `#rrggbb`; empty takes the average of the environment's light. */
+    color: string;
+  };
+  /** Edges rounded at shading time, where a material asks for it with `userData.cpuRenderer.bevel`. */
+  bevel: {
+    enabled: boolean;
+  };
+  /** Meshes filled with a medium: smoke, fog banks, murky water, a beam of light through dust. */
+  volumes: {
+    /** Meshes whose material has `userData.cpuRenderer.volume` scatter light inside. Off leaves them out. */
+    enabled: boolean;
+  };
+}
+
+/** Any subset of the settings, group by group: `{ bloom: { intensity: 0.1 } }` keeps the other fields. */
+export type GpuRenderSettingsInput = {
+  [K in keyof GpuRenderSettings]?: GpuRenderSettings[K] extends object
+    ? Partial<GpuRenderSettings[K]>
+    : GpuRenderSettings[K];
+};
+
+/**
+ * The CPU renderer's defaults, with what a photograph has turned on: paths long enough for light to fill a room, a
+ * film's tone curve, a lens's halo, rays and colour fringes, the air's haze, and materials and volumes that scatter
+ * light inside where the scene asks for it.
+ */
+export const DEFAULT_GPU_RENDER_SETTINGS: Readonly<GpuRenderSettings> = Object.freeze(mergeGpuSettings(
+  {
+    ...DEFAULT_RENDER_SETTINGS,
+    // AgX rolls highlights off as film does, where ACES pushes saturated colours to the gamut's edge.
+    toneMapping: "agx",
+    globalIllumination: { ...DEFAULT_RENDER_SETTINGS.globalIllumination, russianRoulette: true, rouletteStart: 3,
+      lightTree: true },
+    bloom: { enabled: true, intensity: 0.04, radius: 0.65 },
+    glare: { enabled: true, intensity: 0.06, blades: 6, length: 0.25, rotation: 15 },
+    lens: { chromaticAberration: 0.2, distortion: 0 },
+    camera: { physicalExposure: false, iso: 100, shutterSpeed: 1 / 125, whiteBalance: 6500 },
+    subsurface: { enabled: true },
+    atmosphere: { enabled: true, visibility: 20000, haze: 0.6, color: "" },
+    volumes: { enabled: true },
+    bevel: { enabled: true },
+  },
+  // Cycles' indirect light clamp: a rare bright path through a mirror or off a tiny lamp is cut down to ten, which
+  // trades a percent of indirect light for most of the fireflies it would leave.
+  { globalIllumination: { bounces: 12, clamp: 10 } }));
+
+/** Settings with `input` applied over `base`, group by group, as the CPU renderer's `mergeSettings` does. */
+export function mergeGpuSettings(base: GpuRenderSettings, input: GpuRenderSettingsInput = {}): GpuRenderSettings {
+  return mergeSettings(base as unknown as RenderSettings, input as never) as unknown as GpuRenderSettings;
+}
+
+/**
+ * What a camera's exposure triangle multiplies the scene's luminance by: one over the luminance that saturates the
+ * sensor, from the exposure value at ISO 100 (Lagarde and de Rousiers, "Moving Frostbite to PBR", 2014).
+ */
+export function physicalExposure(aperture: number, shutterSpeed: number, iso: number): number {
+  const n = Math.max(aperture, 0.5), t = Math.max(shutterSpeed, 1e-6), s = Math.max(iso, 1);
+  const ev100 = Math.log2(n * n / t * 100 / s);
+
+  return 1 / (1.2 * 2 ** ev100);
+}
+
+/** The exposure the image is multiplied by: the setting itself, or a camera's on top of it as compensation. */
+export function effectiveExposure(settings: GpuRenderSettings): number {
+  const { camera, depthOfField, exposure } = settings;
+
+  return camera.physicalExposure
+    ? exposure * physicalExposure(depthOfField.aperture, camera.shutterSpeed, camera.iso)
+    : exposure;
+}
+
+/** Chromaticity of a black body at this temperature (Kim et al.'s fit of the Planckian locus, 1667 K to 25000 K). */
+function planckian(kelvin: number): [number, number] {
+  const t = Math.min(25000, Math.max(1667, kelvin));
+
+  const x = t <= 4000
+    ? -0.2661239e9 / t ** 3 - 0.2343589e6 / t ** 2 + 0.8776956e3 / t + 0.17991
+    : -3.0258469e9 / t ** 3 + 2.1070379e6 / t ** 2 + 0.2226347e3 / t + 0.24039;
+
+  const y = t <= 2222
+    ? -1.1063814 * x ** 3 - 1.3481102 * x ** 2 + 2.18555832 * x - 0.20219683
+    : t <= 4000
+      ? -0.9549476 * x ** 3 - 1.37418593 * x ** 2 + 2.09137015 * x - 0.16748867
+      : 3.081758 * x ** 3 - 5.8733867 * x ** 2 + 3.75112997 * x - 0.37001483;
+
+  return [x, y];
+}
+
+type Matrix = number[];
+
+const multiply = (a: Matrix, b: Matrix): Matrix => Array.from({ length: 9 }, (_, k) => {
+  const row = Math.floor(k / 3), column = k % 3;
+
+  return a[row * 3] * b[column] + a[row * 3 + 1] * b[3 + column] + a[row * 3 + 2] * b[6 + column];
+});
+
+const apply = (m: Matrix, v: number[]) =>
+  [0, 1, 2].map(row => m[row * 3] * v[0] + m[row * 3 + 1] * v[1] + m[row * 3 + 2] * v[2]);
+
+const SRGB_TO_XYZ = [
+  0.4124564, 0.3575761, 0.1804375,
+  0.2126729, 0.7151522, 0.072175,
+  0.0193339, 0.119192, 0.9503041];
+
+const XYZ_TO_SRGB = [
+  3.2404542, -1.5371385, -0.4985314,
+  -0.969266, 1.8760108, 0.041556,
+  0.0556434, -0.2040259, 1.0572252];
+
+const BRADFORD = [
+  0.8951, 0.2664, -0.1614,
+  -0.7502, 1.7135, 0.0367,
+  0.0389, -0.0685, 1.0296];
+
+const BRADFORD_INVERSE = [
+  0.9869929, -0.1470543, 0.1599627,
+  0.4323053, 0.5183603, 0.0492912,
+  -0.0085287, 0.0400428, 0.9684867];
+
+/** The cone response to white light of this temperature. */
+function coneWhite(kelvin: number): number[] {
+  const [x, y] = planckian(kelvin);
+
+  return apply(BRADFORD, [x / y, 1, (1 - x - y) / y]);
+}
+
+/** The temperature the image is neutral at: white balance at this value changes nothing. */
+export const NEUTRAL_WHITE_BALANCE = 6500;
+
+/**
+ * The linear sRGB matrix, row by row, that a camera balanced for this temperature applies: a von Kries scaling of the
+ * cone responses (Bradford), which renders light of that temperature as the white of 6500 K. Exactly the identity at
+ * 6500 K, since both whites come from the same curve.
+ */
+export function whiteBalanceMatrix(kelvin: number): Matrix {
+  const source = coneWhite(kelvin), target = coneWhite(NEUTRAL_WHITE_BALANCE);
+  const scale = [target[0] / source[0], 0, 0, 0, target[1] / source[1], 0, 0, 0, target[2] / source[2]];
+
+  return multiply(XYZ_TO_SRGB, multiply(BRADFORD_INVERSE, multiply(scale, multiply(BRADFORD, SRGB_TO_XYZ))));
+}

package/src/subsurface.ts

@@ -0,0 +1,153 @@
+import type { SerializedMaterial } from "./upstream.js";
+
+/**
+ * How a material scatters light inside itself, from `userData.cpuRenderer.subsurface`. `true` takes every default.
+ *
+ * The material's own colour (with its map) is what the medium reflects in all once light has wandered through it, as
+ * in Blender's Principled BSDF, so a textured skin keeps its texture; `radius` says how far each colour gets before it
+ * scatters, which is what makes red bleed through an ear and blue stay at the surface.
+ */
+export type SubsurfaceInput = boolean | {
+  /** Share of the diffuse layer that scatters inside rather than at the surface, `0` to `1`. Defaults to `1`. */
+  weight?: number;
+  /**
+   * Mean free path of red, green and blue, as multiples of `scale`; one number for all three. Defaults to
+   * `[1, 0.2, 0.1]`, Blender's, which suits skin.
+   */
+  radius?: number | readonly number[];
+  /** World units `radius` is measured in. Defaults to `0.05`: five centimetres in a scene modelled in metres. */
+  scale?: number;
+  /** Henyey-Greenstein anisotropy of each scattering, `-1` (back) to `1` (forward). Defaults to `0`. */
+  anisotropy?: number;
+};
+
+/** A medium resolved to what the kernel reads. */
+export interface SubsurfaceMedium {
+  weight: number;
+  /** Mean free path per channel, in world units. */
+  radius: [number, number, number];
+  anisotropy: number;
+}
+
+/** A snapshot material, with the medium `serializeLive` attaches; a snapshot built elsewhere can carry one too. */
+export type SubsurfaceMaterial = SerializedMaterial & { subsurface?: SubsurfaceInput };
+
+const DEFAULT_RADIUS: [number, number, number] = [1, 0.2, 0.1];
+const DEFAULT_SCALE = 0.05;
+
+const finite = (value: unknown, fallback: number) =>
+  typeof value === "number" && Number.isFinite(value) ? value : fallback;
+
+/** The medium an input describes, with its defaults, or `null` when it describes none. */
+export function subsurfaceMedium(input: unknown): SubsurfaceMedium | null {
+  if (input === true) input = {};
+  if (!input || typeof input !== "object") return null;
+
+  const value = input as Exclude<SubsurfaceInput, boolean>;
+  const weight = Math.min(1, Math.max(0, finite(value.weight, 1)));
+
+  if (weight <= 0) return null;
+
+  const scale = Math.max(0, finite(value.scale, DEFAULT_SCALE));
+
+  const radius = typeof value.radius === "number"
+    ? [value.radius, value.radius, value.radius]
+    : Array.isArray(value.radius) && value.radius.length >= 3
+      ? value.radius.slice(0, 3)
+      : DEFAULT_RADIUS;
+
+  // A path that never travels would divide by zero; a hair of distance keeps it a very dense medium instead.
+  const paths = radius.map((channel, k) => Math.max(1e-5, finite(channel, DEFAULT_RADIUS[k]) * scale));
+
+  return {
+    weight,
+    radius: [paths[0], paths[1], paths[2]],
+    anisotropy: Math.min(0.95, Math.max(-0.95, finite(value.anisotropy, 0))),
+  };
+}
+
+/** The medium a snapshot material carries, if any. */
+export function subsurfaceOf(material: SerializedMaterial | undefined): SubsurfaceMedium | null {
+  return subsurfaceMedium((material as SubsurfaceMaterial | undefined)?.subsurface);
+}
+
+/**
+ * A mesh filled with a medium, from `userData.cpuRenderer.volume`: its surface is only the boundary, invisible, and
+ * light scatters and fades in the space it encloses. The mesh has to be closed, with its normals pointing out.
+ */
+export type VolumeInput = {
+  /** How much of the light the medium takes per scene unit: one over the mean distance a ray gets. Defaults to `1`. */
+  density?: number;
+  /** What it keeps at each scattering, `#rrggbb` or linear rgb: white for fog and clouds, dark for soot. */
+  color?: string | readonly number[];
+  /** Henyey-Greenstein anisotropy, `-1` (back) to `1` (forward). Defaults to `0`; haze and dust are forward, ~0.7. */
+  anisotropy?: number;
+};
+
+export interface VolumeMedium {
+  density: number;
+  /** Single scattering albedo, linear rgb. */
+  albedo: [number, number, number];
+  anisotropy: number;
+}
+
+/** A snapshot material that may carry a volume, as `serializeLive` attaches it. */
+export type VolumeMaterial = SerializedMaterial & { volume?: VolumeInput };
+
+const srgbToLinear = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+
+function albedoOf(color: unknown): [number, number, number] {
+  if (Array.isArray(color) && color.length >= 3) {
+    return [0, 1, 2].map(k => Math.min(1, Math.max(0, finite(color[k], 1)))) as [number, number, number];
+  }
+
+  const match = typeof color === "string" ? /^#?([0-9a-f]{6})$/i.exec(color) : null;
+
+  if (!match) return [1, 1, 1];
+
+  const value = parseInt(match[1], 16);
+
+  return [(value >> 16) & 255, (value >> 8) & 255, value & 255].map(c => srgbToLinear(c / 255)) as
+    [number, number, number];
+}
+
+/** The medium an input describes, with its defaults, or `null` when it describes none. */
+export function volumeMedium(input: unknown): VolumeMedium | null {
+  if (input === true) input = {};
+  if (!input || typeof input !== "object") return null;
+
+  const value = input as VolumeInput;
+  const density = Math.max(0, finite(value.density, 1));
+
+  if (density <= 0) return null;
+
+  return {
+    density,
+    albedo: albedoOf(value.color),
+    anisotropy: Math.min(0.95, Math.max(-0.95, finite(value.anisotropy, 0))),
+  };
+}
+
+/**
+ * Rounded edges at shading time, from `userData.cpuRenderer.bevel`: the radius, in scene units, over which the
+ * shading normal turns from one face to the next, as Cycles' bevel node rounds them. A number, or `{ radius }`.
+ */
+export type BevelInput = number | { radius?: number };
+
+/** A snapshot material that may carry a bevel, as `serializeLive` attaches it. */
+export type BevelMaterial = SerializedMaterial & { bevel?: BevelInput };
+
+/** The bevel radius an input asks for, or zero. */
+export function bevelRadius(input: unknown): number {
+  const radius = typeof input === "number" ? input : (input as { radius?: unknown } | null)?.radius;
+
+  return typeof radius === "number" && Number.isFinite(radius) && radius > 0 ? radius : 0;
+}
+
+export function bevelOf(material: SerializedMaterial | undefined): number {
+  return bevelRadius((material as BevelMaterial | undefined)?.bevel);
+}
+
+export function volumeOf(material: SerializedMaterial | undefined): VolumeMedium | null {
+  return volumeMedium((material as VolumeMaterial | undefined)?.volume);
+}

package/src/texturePack.ts

@@ -10,10 +10,10 @@ import type { SerializedScene, SerializedTexture } from "./upstream.js";
  */
 export interface PackedTextures {
   /**
-   * One buffer for all of it: `TEXTURE_WORDS` words per texture first, as `TextureInfo` in `wgsl/common.wgsl.ts`, then
-   * the texels each entry points at. A byte texture takes one word per texel, RGBA in the low to high bytes; a float
-   * texture takes four, each the bits of one linear channel. Keeping the two in one binding is what holds the shader
-   * inside the eight storage buffers a WebGPU device has to offer.
+   * One buffer for all of it: the lookup tables first (see `TEXTURE_TABLE`), then `TEXTURE_WORDS` words per texture, as
+   * `TextureInfo` in `wgsl/common.wgsl.ts`, then the texels each entry points at. A byte texture takes one word per
+   * texel, RGBA in the low to high bytes; a float texture takes four, each the bits of one linear channel. Keeping them
+   * in one binding is what holds the shader inside the eight storage buffers a WebGPU device has to offer.
    */
   data: Uint32Array;
   count: number;
@@ -32,6 +32,62 @@ export interface TextureExtras {
 /** Sixteen words per entry: see `TextureInfo` in `wgsl/common.wgsl.ts`. */
 export const TEXTURE_WORDS = 16;
 
+/**
+ * Lookup tables that lead the buffer, at offsets the shader knows as constants: the second Sobol dimension one byte of
+ * the index at a time (four tables of 256), then the linear value of each of the 256 sRGB codes. Both replace work the
+ * kernel did on every read with the very numbers it computed, so nothing they feed changes.
+ */
+export const SOBOL_TABLE = 0;
+export const SRGB_TABLE = SOBOL_TABLE + 4 * 256;
+/** Where the texture table starts, after the lookup tables. */
+export const TEXTURE_TABLE = SRGB_TABLE + 256;
+
+/** The four byte tables of the Sobol sequence's second dimension, whose generator matrix is Pascal's triangle mod 2. */
+function sobolTables(): Uint32Array {
+  const directions: number[] = [];
+  let direction = 0x80000000;
+
+  for (let bit = 0; bit < 32; bit++) {
+    directions.push(direction >>> 0);
+    direction = (direction ^ (direction >>> 1)) >>> 0;
+  }
+
+  const tables = new Uint32Array(4 * 256);
+
+  for (let byte = 0; byte < 4; byte++) {
+    for (let value = 0; value < 256; value++) {
+      let xor = 0;
+
+      for (let bit = 0; bit < 8; bit++) if (value & (1 << bit)) xor ^= directions[byte * 8 + bit];
+
+      tables[byte * 256 + value] = xor >>> 0;
+    }
+  }
+
+  return tables;
+}
+
+/** The linear value of every sRGB code, worked out in double precision and rounded once. */
+function srgbTable(): Float32Array {
+  return Float32Array.from({ length: 256 }, (_, code) => {
+    const value = Math.fround(code / 255);
+
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  });
+}
+
+const LOOKUP = (() => {
+  const words = new Uint32Array(TEXTURE_TABLE);
+
+  words.set(sobolTables(), SOBOL_TABLE);
+  words.set(new Uint32Array(srgbTable().buffer), SRGB_TABLE);
+
+  return words;
+})();
+
+/** Where a texture's entry starts in the buffer. */
+export const textureEntry = (index: number) => TEXTURE_TABLE + index * TEXTURE_WORDS;
+
 /** What a material's map index means when the material has no such map. */
 export const NO_TEXTURE = 0xffffffff;
 
@@ -49,6 +105,9 @@ const MIRRORED_REPEAT = 1002;
 /** How many UV sets the geometry carries, and so the highest channel a texture may ask for. */
 export const UV_CHANNELS = 2;
 
+/** Whether a word's first byte is its lowest, as it is on the device: then RGBA bytes are already RGBA words. */
+const LITTLE_ENDIAN = new Uint8Array(new Uint32Array([1]).buffer)[0] === 1;
+
 const texelCount = (texture: SerializedTexture) => Math.max(0, texture.width) * Math.max(0, texture.height);
 
 const isFloat = (texture: SerializedTexture) => texture.data instanceof Float32Array;
@@ -66,6 +125,7 @@ const isEncoded = (texture: SerializedTexture) => !isFloat(texture) && texture.c
 export interface TexturePlan {
   textures: SerializedTexture[];
   indexOf: Map<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;
@@ -80,7 +140,7 @@ export function planTextures(scene: SerializedScene, extraTextures: readonly Ser
     .filter(texture => !seen.has(texture.id) && !!seen.add(texture.id));
 
   const indexOf = new Map(textures.map((texture, index) => [texture.id, index]));
-  const tableWords = Math.max(1, textures.length) * TEXTURE_WORDS;
+  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);
 
   return { textures, indexOf, tableWords, extraOffset: tableWords + texelWords };
@@ -100,8 +160,10 @@ export function writeTextures(plan: TexturePlan, extraWords: Uint32Array): Packe
   const floats = new Float32Array(data.buffer);
   let texelAt = tableWords;
 
+  data.set(LOOKUP, 0);
+
   textures.forEach((texture, index) => {
-    const at = index * TEXTURE_WORDS;
+    const at = textureEntry(index);
     const texels = texelCount(texture);
     const float = isFloat(texture);
 
@@ -131,13 +193,18 @@ export function writeTextures(plan: TexturePlan, extraWords: Uint32Array): Packe
     } else {
       const source = texture.data as Uint8Array;
 
-      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);
+      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;

package/src/volumeContainment.ts

@@ -0,0 +1,81 @@
+import type { PackedGeometry } from "./geometry.js";
+import { MATERIAL_VOLUME } from "./materialLayout.js";
+
+/** What the kernel reads as no material at all. */
+export const NO_MATERIAL = 0xffffffff;
+
+/** The triangles that bound a volume, each with its material's index. */
+export interface VolumeTriangles {
+  /** Nine floats a triangle. */
+  positions: Float32Array;
+  materials: Uint32Array;
+}
+
+/** The boundaries of every volume in a packed scene, or `null` when it has none. */
+export function volumeTriangles(geometry: PackedGeometry): VolumeTriangles | null {
+  const volume = geometry.materialProperties.map(properties => (properties.flags & MATERIAL_VOLUME) !== 0);
+
+  if (!volume.some(Boolean)) return null;
+
+  const picked: number[] = [];
+
+  for (let triangle = 0; triangle < geometry.triangleCount; triangle++)
+    if (volume[geometry.materials[triangle]]) picked.push(triangle);
+
+  const positions = new Float32Array(picked.length * 9);
+  const materials = new Uint32Array(picked.length);
+
+  picked.forEach((triangle, k) => {
+    positions.set(geometry.positions.subarray(triangle * 9, triangle * 9 + 9), k * 9);
+    materials[k] = geometry.materials[triangle];
+  });
+
+  return { positions, materials };
+}
+
+/** An irrational direction, so a ray from the camera does not run along an edge of an axis aligned box. */
+const PROBE = [0.4123, 0.7071, 0.5745].map((value, _, all) => value / Math.hypot(...all));
+
+/**
+ * The volume a point stands inside, by the parity of the boundary crossings of a ray from it: an odd count of one
+ * volume's triangles means inside it. The camera usually stands in none, so the kernel only asks this of the camera.
+ */
+export function containingVolume(volumes: VolumeTriangles | null, point: readonly number[]): number {
+  if (!volumes) return NO_MATERIAL;
+
+  const crossings = new Map<number, number>();
+  const p = volumes.positions;
+  const [dx, dy, dz] = PROBE;
+
+  for (let k = 0; k < volumes.materials.length; k++) {
+    const at = k * 9;
+    const e1x = p[at + 3] - p[at], e1y = p[at + 4] - p[at + 1], e1z = p[at + 5] - p[at + 2];
+    const e2x = p[at + 6] - p[at], e2y = p[at + 7] - p[at + 1], e2z = p[at + 8] - p[at + 2];
+    // Moller and Trumbore.
+    const hx = dy * e2z - dz * e2y, hy = dz * e2x - dx * e2z, hz = dx * e2y - dy * e2x;
+    const det = e1x * hx + e1y * hy + e1z * hz;
+
+    if (Math.abs(det) < 1e-12) continue;
+
+    const inverse = 1 / det;
+    const sx = point[0] - p[at], sy = point[1] - p[at + 1], sz = point[2] - p[at + 2];
+    const u = (sx * hx + sy * hy + sz * hz) * inverse;
+
+    if (u < 0 || u > 1) continue;
+
+    const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;
+    const v = (dx * qx + dy * qy + dz * qz) * inverse;
+
+    if (v < 0 || u + v > 1) continue;
+
+    if ((e2x * qx + e2y * qy + e2z * qz) * inverse > 0) {
+      const material = volumes.materials[k];
+
+      crossings.set(material, (crossings.get(material) ?? 0) + 1);
+    }
+  }
+
+  for (const [material, count] of crossings) if (count % 2 === 1) return material;
+
+  return NO_MATERIAL;
+}