Skip to content

3D engine that AI agents drive

68.2 KB
Raw Blame
import { portalPdf, samplePortalDirection } from './path-tracer-portal.js';
import { cameraFieldOfView, resolveThinLens } from './camera.js';
import { fresnelSchlick } from './material-layers.js';
import { pointLightFalloff } from './ray-query.js';
import { profileGain } from './light-profile.js';
import { buildTraceScene, buildTraceSceneForDevice, refuseLocalVolumes, SUN_ANGULAR_RADIUS, uniqueTriangleCount } from './path-tracer-scene.js';
import { denoiseRadiance, estimateRelativeNoise } from './path-tracer-denoise.js';
import { acesChannel, displayColor } from './view-transform.js';
import { VIEW_TRANSFORM_NAMES } from './view-transform-names.js';
import {
  buildFrame, createSurface, environmentPdf, environmentRadiance, evaluateSurface, luminance, mirrorWeight, prepareSurface,
  roughnessToAlpha, sampleEnvironment, sampleGlass, sampleSurface, setWhiteDiffuse, splitSubsurface,
} from './path-tracer-shading.js';
import { buildLightTree, chooseLightFromTree, LIGHT_TREE_FIRST_HIT_LIGHTS, resolveLightSelection } from './path-tracer-light-tree.js';
import { createRandomWalk, WALK_OUTCOME } from './path-tracer-subsurface.js';
import { henyeyGreensteinPhase, sampleHenyeyGreensteinCosine, volumeInterval, createLocalVolumeCrossing, createLocalVolumeSurfaceShadow, meanEnvironmentRadiance } from './path-tracer-volume.js';

// Offline still renderer: unidirectional path tracing on the CPU with next-event estimation for every light, the
// environment map drawn by importance, and a wavelet denoiser. It reads the same parts, materials, lights and camera
// as the rasterizer. Same input gives the same bytes: random numbers come from a hash of pixel, sample and seed, and
// the clock only decides whether a render is allowed to finish.

export const PATH_TRACER_LIMITS = Object.freeze({
  width: Object.freeze({ minimum: 16, maximum: 4096, fallback: 960 }),
  height: Object.freeze({ minimum: 16, maximum: 4096, fallback: 540 }),
  samples: Object.freeze({ minimum: 1, maximum: 1024, fallback: 64 }),
  bounces: Object.freeze({ minimum: 1, maximum: 16, fallback: 8 }),
  maxSeconds: Object.freeze({ minimum: 1, maximum: 1800, fallback: 300 }),
  fireflyClamp: Object.freeze({ minimum: 1, maximum: 1000, fallback: 20 }),
  noiseThreshold: Object.freeze({ minimum: 0, maximum: 1, fallback: 0 }),
  seed: Object.freeze({ minimum: 0, maximum: 2 ** 31 - 1, fallback: 0 }),
  threads: Object.freeze({ minimum: 1, maximum: 8, fallback: 4 }),
});
export const MAX_TRACE_PIXELS = 2_073_600;
export const MAX_TRACE_RAY_WORK = 4_000_000_000;
const ALPHA_STEP_LIMIT = 64;
const WORKER_BAND_ROWS = 8;
// Held in a constant so the bundler leaves the URL alone: the worker is its own package entry, built beside this file.
const WORKER_FILE = './path-tracer-worker.js';
const RUSSIAN_ROULETTE_START = 3;
// A pixel is checked for convergence from this many samples on, then after every batch of samples.
const ADAPTIVE_MINIMUM_SAMPLES = 16;
const ADAPTIVE_BATCH_SAMPLES = 8;
// Mean luminance added to the standard error's reference, so very dark pixels are not held to a relative error.
const CONVERGENCE_LUMINANCE_FLOOR = 0.05;
const IGNORED_MAP_FIELDS = ['occlusionMap'];
// Shading layers of the rasterizer that the tracer's surface model has no term for.
const IGNORED_LAYERS = [
  ['anisotropy', material => material.anisotropy > 0, true],
  ['iridescence', material => material.iridescence > 0, true],
  ['sheen', material => (material.sheenColor ?? []).some(channel => channel !== 0), true],
  ['moss', material => material.moss > 0],
  ['splat layers', (material, kernelMaterials) => Boolean(material.layers || Object.keys(material.layerMaps ?? {}).some(name => !(kernelMaterials ? KERNEL_LAYER_MAPS : ['clearcoatTexture']).includes(name)))],
  ['lightMap', material => Boolean(material.lightMap)],
];
// The layer maps the native "cycles" kernel reads with its whole materials (the roughness maps of the coat and the sheen have no slot).
const KERNEL_LAYER_MAPS = ['clearcoatTexture', 'clearcoatNormalTexture', 'anisotropyTexture', 'sheenColorTexture'];

// The native kernel reads a coat's weight and roughness, and a sheen's tint and roughness, from one map each
// (@codepawlhq/cook job-input carries the map only when it cannot change the roughness).
function hasSplitLayerMap(material) {
  const maps = material.layerMaps ?? {};
  const coatIsSplit = Boolean(maps.clearcoatTexture) && material.clearcoatRoughness > 0 && maps.clearcoatTexture.image !== maps.clearcoatRoughnessTexture?.image;
  const sheenIsSplit = Boolean(maps.sheenColorTexture) && material.sheenRoughness > 0 && maps.sheenColorTexture.image !== maps.sheenRoughnessTexture?.image;
  return coatIsSplit || sheenIsSplit;
}

function hasGraphOpacity(material) {
  return material.pattern?.type === 'graph' && Object.hasOwn(material.pattern.graph ?? {}, 'opacity');
}

function boundedInteger(options, name) {
  const limit = PATH_TRACER_LIMITS[name];
  const value = options[name] ?? limit.fallback;
  if (!Number.isInteger(value) || value < limit.minimum || value > limit.maximum) {
    throw new RangeError(`Path tracer ${name} must be an integer from ${limit.minimum} to ${limit.maximum}.`);
  }
  return value;
}

function boundedNumber(options, name) {
  const limit = PATH_TRACER_LIMITS[name];
  const value = options[name] ?? limit.fallback;
  if (typeof value !== 'number' || !Number.isFinite(value) || value < limit.minimum || value > limit.maximum) {
    throw new RangeError(`Path tracer ${name} must be a number from ${limit.minimum} to ${limit.maximum}.`);
  }
  return value;
}

// Kept equal to PATH_TRACER_DENOISERS in path-tracer-capabilities.js by tests/path-tracer-denoise-oidn.test.js; the
// capabilities file stays out of this bundle.
export const PATH_TRACER_DENOISERS = Object.freeze(['wavelet', 'oidn', 'none']);
export const SAMPLING_PATTERNS = Object.freeze(['random', 'blue-noise-first']);
export const LIGHT_SELECTIONS = Object.freeze(['auto', 'uniform', 'importance', 'tree']);

/**
 * `denoise` is true (the wavelet filter) or false (none), or a name: "wavelet", "oidn" or "none". "oidn" is the optional
 * native Open Image Denoise (packages/denoise-oidn): the tracer then leaves the colour as traced and returns the feature
 * images, and the caller that has the package filters them.
 */
function denoiserNamed(value) {
  if (value === true) return 'wavelet';
  if (value === false) return 'none';
  if (PATH_TRACER_DENOISERS.includes(value)) return value;
  throw new TypeError(`Path tracer denoise must be a boolean or one of ${PATH_TRACER_DENOISERS.join(', ')}.`);
}

// "webgpu" is the WGSL compute tracer (src/path-tracer-webgpu.js, loaded only for that backend).
const PATH_TRACER_BACKENDS = ['cpu', 'gpu', 'webgpu'];

export function normalizePathTracerOptions(options = {}) {
  if (options === null || typeof options !== 'object') throw new TypeError('Path tracer options must be an object.');
  const result = {
    width: boundedInteger(options, 'width'),
    height: boundedInteger(options, 'height'),
    samples: boundedInteger(options, 'samples'),
    bounces: boundedInteger(options, 'bounces'),
    seed: boundedInteger(options, 'seed'),
    threads: boundedInteger(options, 'threads'),
    maxSeconds: boundedNumber(options, 'maxSeconds'),
    fireflyClamp: boundedNumber(options, 'fireflyClamp'),
    noiseThreshold: boundedNumber(options, 'noiseThreshold'),
    denoiser: denoiserNamed(options.denoise ?? true),
    viewTransform: options.viewTransform ?? 'aces',
    look: options.look ?? null,
    exposure: options.exposure ?? 1,
    backend: options.backend ?? 'cpu',
    samplingPattern: options.samplingPattern ?? 'random',
    lightSelection: options.lightSelection ?? 'auto',
  };
  result.denoise = result.denoiser !== 'none';
  if (typeof result.exposure !== 'number' || !Number.isFinite(result.exposure) || result.exposure <= 0) throw new RangeError(`Path tracer exposure must be a finite number above 0 (got ${result.exposure}). Pass 1 to leave the picture as traced, 2 to double it.`);
  if (!VIEW_TRANSFORM_NAMES.includes(result.viewTransform)) throw new RangeError(`Path tracer viewTransform must be one of ${VIEW_TRANSFORM_NAMES.join(', ')}.`);
  if (!PATH_TRACER_BACKENDS.includes(result.backend)) throw new TypeError('Path tracer backend must be "cpu", "gpu" or "webgpu".');
  if (!SAMPLING_PATTERNS.includes(result.samplingPattern)) throw new RangeError(`Path tracer samplingPattern must be one of ${SAMPLING_PATTERNS.join(', ')}.`);
  if (!LIGHT_SELECTIONS.includes(result.lightSelection)) throw new RangeError(`Path tracer lightSelection must be one of ${LIGHT_SELECTIONS.join(', ')}.`);
  if (result.backend !== 'gpu' && result.samplingPattern !== 'random') {
    throw new RangeError('Path tracer samplingPattern "blue-noise-first" needs backend "gpu"; the CPU reference and the WebGPU tracer draw random samples.');
  }
  if (result.lightSelection === 'importance' && result.backend !== 'gpu') {
    throw new RangeError('Path tracer lightSelection "importance" needs backend "gpu"; the CPU reference and the WebGPU tracer pick lights uniformly; "tree" also runs on the WebGPU tracer.');
  }
  if (result.width * result.height > MAX_TRACE_PIXELS) throw new RangeError(`A path trace takes at most ${MAX_TRACE_PIXELS} pixels.`);
  if (result.width * result.height * result.samples * (result.bounces + 1) > MAX_TRACE_RAY_WORK) throw new RangeError('This path trace would need too much ray work: lower the size, samples or bounces.');
  return result;
}

function finiteVector(value, name) {
  if (!Array.isArray(value) || value.length !== 3 || value.some(entry => typeof entry !== 'number' || !Number.isFinite(entry))) {
    throw new TypeError(`Path tracer camera ${name} must be three finite numbers.`);
  }
  return value;
}

export function createCamera(camera, width, height) {
  const eye = finiteVector(camera.eye, 'eye');
  const target = finiteVector(camera.target, 'target');
  const up = finiteVector(camera.up ?? [0, 1, 0], 'up');
  if (camera.projection === 'orthographic' || camera.shift) throw new RangeError('The path tracer draws perspective cameras without lens shift. Render those without the renderer option.');
  const fov = camera.focalLength === undefined ? camera.fov : cameraFieldOfView(camera, width / height);
  if (typeof fov !== 'number' || !(fov > 1 && fov < 170)) throw new RangeError('Path tracer camera fov must be between 1 and 170 degrees.');
  const forward = [target[0] - eye[0], target[1] - eye[1], target[2] - eye[2]];
  const forwardLength = Math.hypot(...forward);
  if (forwardLength === 0) throw new RangeError('Path tracer camera eye and target must differ.');
  for (let axis = 0; axis < 3; axis++) forward[axis] /= forwardLength;
  const right = [forward[1] * up[2] - forward[2] * up[1], forward[2] * up[0] - forward[0] * up[2], forward[0] * up[1] - forward[1] * up[0]];
  const rightLength = Math.hypot(...right);
  if (rightLength === 0) throw new RangeError('Path tracer camera up must not be parallel to its view.');
  for (let axis = 0; axis < 3; axis++) right[axis] /= rightLength;
  const above = [right[1] * forward[2] - right[2] * forward[1], right[2] * forward[0] - right[0] * forward[2], right[0] * forward[1] - right[1] * forward[0]];
  const halfHeight = Math.tan(fov * Math.PI / 360);
  const clipStart = camera.clipStart ?? 0;
  if (typeof clipStart !== 'number' || !Number.isFinite(clipStart) || clipStart < 0 || clipStart > 1e5) throw new RangeError(`Path tracer camera clipStart must be a distance from 0 to 100000 scene units along the view axis, got ${JSON.stringify(camera.clipStart)}. Leave it out to start rays at the eye.`);
  if (typeof camera.far === 'number' && clipStart >= camera.far) throw new RangeError(`Path tracer camera clipStart ${clipStart} is at or past the far plane ${camera.far}, so nothing would be drawn. Pass a clipStart below far, or raise far.`);
  const view = { eye, forward, right, above, halfHeight, halfWidth: halfHeight * width / height, ...(clipStart > 0 ? { clipStart, near: clipStart } : {}) };
  // A camera with an fStop adds its thin lens (apertureRadius, focalDistance, apertureBlades, apertureRotation). Only the
  // native "cycles" kernel draws it; every other tracer ignores the extra fields, and a pinhole view is unchanged.
  const thinLens = resolveThinLens(camera, { aspect: width / height, eye, target });
  return thinLens ? { ...view, ...thinLens } : view;
}

// ---- Random numbers ----

function createRandom() {
  let state = 1;
  return {
    reset(pixel, sample, seed) {
      let mixed = Math.imul(pixel + 0x9e3779b9, 0x85ebca6b) ^ Math.imul(sample + 0x7f4a7c15, 0xc2b2ae35) ^ Math.imul(seed + 0x165667b1, 0x27d4eb2f);
      mixed = Math.imul(mixed ^ (mixed >>> 15), 0x2c1b3c6d);
      mixed = Math.imul(mixed ^ (mixed >>> 12), 0x297a2d39);
      mixed ^= mixed >>> 15;
      state = mixed === 0 ? 1 : mixed;
    },
    // PCG (RXS-M-XS): successive values are independent enough for light and lobe choices that share one path.
    next() {
      state = (Math.imul(state, 747796405) + 2891336453) >>> 0;
      const word = Math.imul((state >>> ((state >>> 28) + 4)) ^ state, 277803737);
      return (((word >>> 22) ^ word) >>> 0) / 4294967296;
    },
  };
}

// ---- Hits ----

function createHit() {
  return {
    distance: 0, material: null,
    point: new Float64Array(3), normal: new Float64Array(3), color: new Float64Array(3),
    texel: new Float64Array(4), mapTexel: new Float64Array(4), emission: new Float64Array(3),
    metallic: 0, roughness: 0, clearcoat: 0, transmission: 0,
  };
}

// Edges of the hit triangle and the matching UV differences, set by fillHit for the tangent frame of a normal map.
const TANGENT_EDGES = new Float64Array(6);
const TANGENT_UV_DIFFERENCES = new Float64Array(4);

/**
 * Tilts the interpolated normal by a tangent-space normal map, with the tangent frame of the hit triangle as in the
 * rasterizer: tangent from the UV gradient made perpendicular to the normal, bitangent following the UV handedness.
 */
function applyNormalMap(material, hit, u, v) {
  const edgeOneX = TANGENT_EDGES[0];
  const edgeOneY = TANGENT_EDGES[1];
  const edgeOneZ = TANGENT_EDGES[2];
  const edgeTwoX = TANGENT_EDGES[3];
  const edgeTwoY = TANGENT_EDGES[4];
  const edgeTwoZ = TANGENT_EDGES[5];
  const uOne = TANGENT_UV_DIFFERENCES[0];
  const vOne = TANGENT_UV_DIFFERENCES[1];
  const uTwo = TANGENT_UV_DIFFERENCES[2];
  const vTwo = TANGENT_UV_DIFFERENCES[3];
  const determinant = uOne * vTwo - uTwo * vOne;
  if (Math.abs(determinant) < 1e-12) return;
  const normalX = hit.normal[0];
  const normalY = hit.normal[1];
  const normalZ = hit.normal[2];
  let tangentX = (edgeOneX * vTwo - edgeTwoX * vOne) / determinant;
  let tangentY = (edgeOneY * vTwo - edgeTwoY * vOne) / determinant;
  let tangentZ = (edgeOneZ * vTwo - edgeTwoZ * vOne) / determinant;
  const bitangentX = (edgeTwoX * uOne - edgeOneX * uTwo) / determinant;
  const bitangentY = (edgeTwoY * uOne - edgeOneY * uTwo) / determinant;
  const bitangentZ = (edgeTwoZ * uOne - edgeOneZ * uTwo) / determinant;
  const alongNormal = tangentX * normalX + tangentY * normalY + tangentZ * normalZ;
  tangentX -= normalX * alongNormal;
  tangentY -= normalY * alongNormal;
  tangentZ -= normalZ * alongNormal;
  const tangentLength = Math.hypot(tangentX, tangentY, tangentZ);
  if (tangentLength === 0) return;
  tangentX /= tangentLength;
  tangentY /= tangentLength;
  tangentZ /= tangentLength;
  let crossX = normalY * tangentZ - normalZ * tangentY;
  let crossY = normalZ * tangentX - normalX * tangentZ;
  let crossZ = normalX * tangentY - normalY * tangentX;
  const crossLength = Math.hypot(crossX, crossY, crossZ) || 1;
  const handedness = (crossX * bitangentX + crossY * bitangentY + crossZ * bitangentZ) < 0 ? -1 : 1;
  crossX *= handedness / crossLength;
  crossY *= handedness / crossLength;
  crossZ *= handedness / crossLength;
  const { mapTexel } = hit;
  sampleTexture(material.normalTexture, u, v, mapTexel);
  const sideways = (mapTexel[0] * 2 - 1) * material.normalScale[0];
  const forwards = (mapTexel[1] * 2 - 1) * material.normalScale[1];
  const outwards = mapTexel[2] * 2 - 1;
  const mappedX = tangentX * sideways + crossX * forwards + normalX * outwards;
  const mappedY = tangentY * sideways + crossY * forwards + normalY * outwards;
  const mappedZ = tangentZ * sideways + crossZ * forwards + normalZ * outwards;
  const mappedLength = Math.hypot(mappedX, mappedY, mappedZ);
  if (!(mappedLength > 1e-6)) return;
  hit.normal[0] = mappedX / mappedLength;
  hit.normal[1] = mappedY / mappedLength;
  hit.normal[2] = mappedZ / mappedLength;
}

// The interpolated UVs of the hit, set by fillHit: TEXCOORD_0 then TEXCOORD_1 (zeros when the part has no second set).
const HIT_UV = new Float64Array(4);

/** Samples a map at the hit with the UV set the map names. */
function sampleMap(texture, out) {
  const offset = texture.uvSet === 1 ? 2 : 0;
  sampleTexture(texture, HIT_UV[offset], HIT_UV[offset + 1], out);
}

// A texel index folded into 0..size-1 by a wrap code: 0 repeat, 1 clamp to edge, 2 mirrored repeat.
export function wrapTexelIndex(index, size, mode) {
  if (mode === 1) return Math.max(0, Math.min(size - 1, index));
  if (mode === 2) {
    const folded = ((index % (2 * size)) + 2 * size) % (2 * size);
    return folded < size ? folded : 2 * size - 1 - folded;
  }
  return ((index % size) + size) % size;
}

function sampleTexture(texture, u, v, out) {
  const { width, height, data, colorLookup } = texture;
  const wrapU = texture.wrapU ?? (texture.repeat ? 0 : 1);
  const wrapV = texture.wrapV ?? (texture.repeat ? 0 : 1);
  const x = u * width - 0.5;
  const y = v * height - 0.5;
  const left = Math.floor(x);
  const top = Math.floor(y);
  const shareX = x - left;
  const shareY = y - top;
  out[0] = 0;
  out[1] = 0;
  out[2] = 0;
  out[3] = 0;
  for (let corner = 0; corner < 4; corner++) {
    let column = left + (corner & 1);
    let row = top + (corner >> 1);
    column = wrapTexelIndex(column, width, wrapU);
    row = wrapTexelIndex(row, height, wrapV);
    const weight = ((corner & 1) ? shareX : 1 - shareX) * ((corner >> 1) ? shareY : 1 - shareY);
    const base = (row * width + column) * 4;
    for (let channel = 0; channel < 3; channel++) out[channel] += weight * (colorLookup ? colorLookup[data[base + channel]] : data[base + channel] / 255);
    out[3] += weight * data[base + 3] / 255;
  }
}

const CORNER_VERTICES = new Uint32Array(3);
const CORNER_WEIGHTS = new Float64Array(3);

/** Interpolates the surface at a hit: position, facing-corrected normal is left to the caller, colour and alpha. */
function fillHit(scene, triangleId, originX, originY, originZ, directionX, directionY, directionZ, distance, hit) {
  const { positions, normals, uvs, uvs1, colors, indices } = scene;
  const first = indices[triangleId * 3];
  const second = indices[triangleId * 3 + 1];
  const third = indices[triangleId * 3 + 2];
  hit.distance = distance;
  hit.point[0] = originX + directionX * distance;
  hit.point[1] = originY + directionY * distance;
  hit.point[2] = originZ + directionZ * distance;
  const edgeOneX = positions[second * 3] - positions[first * 3];
  const edgeOneY = positions[second * 3 + 1] - positions[first * 3 + 1];
  const edgeOneZ = positions[second * 3 + 2] - positions[first * 3 + 2];
  const edgeTwoX = positions[third * 3] - positions[first * 3];
  const edgeTwoY = positions[third * 3 + 1] - positions[first * 3 + 1];
  const edgeTwoZ = positions[third * 3 + 2] - positions[first * 3 + 2];
  const offsetX = hit.point[0] - positions[first * 3];
  const offsetY = hit.point[1] - positions[first * 3 + 1];
  const offsetZ = hit.point[2] - positions[first * 3 + 2];
  const oneOne = edgeOneX * edgeOneX + edgeOneY * edgeOneY + edgeOneZ * edgeOneZ;
  const oneTwo = edgeOneX * edgeTwoX + edgeOneY * edgeTwoY + edgeOneZ * edgeTwoZ;
  const twoTwo = edgeTwoX * edgeTwoX + edgeTwoY * edgeTwoY + edgeTwoZ * edgeTwoZ;
  const offsetOne = offsetX * edgeOneX + offsetY * edgeOneY + offsetZ * edgeOneZ;
  const offsetTwo = offsetX * edgeTwoX + offsetY * edgeTwoY + offsetZ * edgeTwoZ;
  const denominator = oneOne * twoTwo - oneTwo * oneTwo || 1;
  const secondWeight = (twoTwo * offsetOne - oneTwo * offsetTwo) / denominator;
  const thirdWeight = (oneOne * offsetTwo - oneTwo * offsetOne) / denominator;
  const firstWeight = 1 - secondWeight - thirdWeight;
  let normalX = 0;
  let normalY = 0;
  let normalZ = 0;
  let red = 0;
  let green = 0;
  let blue = 0;
  let u = 0;
  let v = 0;
  let secondSetU = 0;
  let secondSetV = 0;
  CORNER_VERTICES[0] = first;
  CORNER_VERTICES[1] = second;
  CORNER_VERTICES[2] = third;
  CORNER_WEIGHTS[0] = firstWeight;
  CORNER_WEIGHTS[1] = secondWeight;
  CORNER_WEIGHTS[2] = thirdWeight;
  for (let corner = 0; corner < 3; corner++) {
    const vertex = CORNER_VERTICES[corner];
    const weight = CORNER_WEIGHTS[corner];
    normalX += weight * normals[vertex * 3];
    normalY += weight * normals[vertex * 3 + 1];
    normalZ += weight * normals[vertex * 3 + 2];
    red += weight * colors[vertex * 3];
    green += weight * colors[vertex * 3 + 1];
    blue += weight * colors[vertex * 3 + 2];
    u += weight * uvs[vertex * 2];
    v += weight * uvs[vertex * 2 + 1];
    if (uvs1) {
      secondSetU += weight * uvs1[vertex * 2];
      secondSetV += weight * uvs1[vertex * 2 + 1];
    }
  }
  HIT_UV[0] = u;
  HIT_UV[1] = v;
  HIT_UV[2] = secondSetU;
  HIT_UV[3] = secondSetV;
  const length = Math.hypot(normalX, normalY, normalZ) || 1;
  hit.normal[0] = normalX / length;
  hit.normal[1] = normalY / length;
  hit.normal[2] = normalZ / length;
  const material = scene.materials[scene.triangleMaterial[triangleId]];
  hit.material = material;
  let alpha = 1;
  hit.color[0] = material.color[0] * red;
  hit.color[1] = material.color[1] * green;
  hit.color[2] = material.color[2] * blue;
  if (material.texture) {
    sampleMap(material.texture, hit.texel);
    hit.color[0] *= hit.texel[0];
    hit.color[1] *= hit.texel[1];
    hit.color[2] *= hit.texel[2];
    alpha = hit.texel[3];
  }
  hit.emission[0] = material.emission[0];
  hit.emission[1] = material.emission[1];
  hit.emission[2] = material.emission[2];
  if (material.emissiveTexture) {
    sampleMap(material.emissiveTexture, hit.mapTexel);
    hit.emission[0] *= hit.mapTexel[0];
    hit.emission[1] *= hit.mapTexel[1];
    hit.emission[2] *= hit.mapTexel[2];
  }
  hit.metallic = material.metallic;
  hit.roughness = material.roughness;
  hit.clearcoat = material.clearcoat;
  hit.transmission = material.transmission;
  if (material.clearcoatTexture) {
    sampleMap(material.clearcoatTexture, hit.mapTexel);
    hit.clearcoat *= hit.mapTexel[0];
  }
  if (material.transmissionTexture) {
    sampleMap(material.transmissionTexture, hit.mapTexel);
    hit.transmission *= hit.mapTexel[0];
  }
  if (material.surfaceTexture) {
    sampleMap(material.surfaceTexture, hit.mapTexel);
    hit.roughness *= hit.mapTexel[1];
    hit.metallic *= hit.mapTexel[2];
  }
  if (material.normalTexture) {
    TANGENT_EDGES[0] = edgeOneX;
    TANGENT_EDGES[1] = edgeOneY;
    TANGENT_EDGES[2] = edgeOneZ;
    TANGENT_EDGES[3] = edgeTwoX;
    TANGENT_EDGES[4] = edgeTwoY;
    TANGENT_EDGES[5] = edgeTwoZ;
    const normalSet = material.normalTexture.uvSet === 1 && uvs1 ? uvs1 : uvs;
    TANGENT_UV_DIFFERENCES[0] = normalSet[second * 2] - normalSet[first * 2];
    TANGENT_UV_DIFFERENCES[1] = normalSet[second * 2 + 1] - normalSet[first * 2 + 1];
    TANGENT_UV_DIFFERENCES[2] = normalSet[third * 2] - normalSet[first * 2];
    TANGENT_UV_DIFFERENCES[3] = normalSet[third * 2 + 1] - normalSet[first * 2 + 1];
    const normalOffset = normalSet === uvs1 ? 2 : 0;
    applyNormalMap(material, hit, HIT_UV[normalOffset], HIT_UV[normalOffset + 1]);
  }
  return alpha;
}

/**
 * The nearest solid hit along a ray, stepping through the transparent texels of cutout materials. A camera ray also
 * steps through a shadow-only part, which stays in the scene for shadow and bounce rays (Blender's camera visibility off).
 */
function intersect(scene, originX, originY, originZ, directionX, directionY, directionZ, hit, isCameraRay = false) {
  let startX = originX;
  let startY = originY;
  let startZ = originZ;
  let travelled = 0;
  for (let attempt = 0; attempt < ALPHA_STEP_LIMIT; attempt++) {
    const found = scene.tracer.trace(startX, startY, startZ, directionX, directionY, directionZ, scene.farDistance, false);
    if (found.nearestTriangle < 0) return false;
    const seenByCamera = !(isCameraRay && scene.shadowOnlyParts?.[scene.triangleMaterial[found.nearestTriangle]] === 1);
    const alpha = seenByCamera ? fillHit(scene, found.nearestTriangle, startX, startY, startZ, directionX, directionY, directionZ, found.nearestDistance, hit) : 0;
    if (seenByCamera && (hit.material.alphaCutoff === 0 || alpha >= hit.material.alphaCutoff)) {
      hit.distance += travelled;
      return true;
    }
    const advance = found.nearestDistance + scene.surfaceOffset;
    travelled += advance;
    startX += directionX * advance;
    startY += directionY * advance;
    startZ += directionZ * advance;
  }
  return false;
}

function occluded(scene, originX, originY, originZ, directionX, directionY, directionZ, limit, hit) {
  let startX = originX;
  let startY = originY;
  let startZ = originZ;
  let remaining = limit;
  // An any-hit trace returns the first hit traversal meets, not the nearest. A solid one shadows the point wherever it lies;
  // a transparent one says nothing about what sits before it, so the walk then retraces for nearest hits and steps through.
  let anyHit = true;
  for (let attempt = 0; attempt < ALPHA_STEP_LIMIT; attempt++) {
    const found = scene.tracer.trace(startX, startY, startZ, directionX, directionY, directionZ, remaining, anyHit);
    if (found.nearestTriangle < 0) return false;
    // Only a cutout material needs its texture read to know whether the ray passes through: skip the interpolation for the rest.
    if (scene.materials[scene.triangleMaterial[found.nearestTriangle]].alphaCutoff === 0) return true;
    const alpha = fillHit(scene, found.nearestTriangle, startX, startY, startZ, directionX, directionY, directionZ, found.nearestDistance, hit);
    if (alpha >= hit.material.alphaCutoff) return true;
    if (anyHit) {
      anyHit = false;
      continue;
    }
    const advance = found.nearestDistance + scene.surfaceOffset;
    remaining -= advance;
    if (remaining <= 0) return false;
    startX += directionX * advance;
    startY += directionY * advance;
    startZ += directionZ * advance;
  }
  return true;
}

// ---- One path ----

function smoothstep(value) {
  return value * value * (3 - 2 * value);
}

function createPathTracer(scene, options) {
  const surface = createSurface();
  const hit = createHit();
  const shadowHit = createHit();
  const throughput = new Float64Array(3);
  const radiance = new Float64Array(3);
  const direction = new Float64Array(3);
  const lightDirection = new Float64Array(3);
  const lightRadiance = new Float64Array(3);
  const sky = new Float64Array(3);
  const sunFrame = new Float64Array(9);
  const mirror = new Float64Array(3);
  const normal = new Float64Array(3);
  const features = { albedo: new Float64Array(3), normal: new Float64Array(3), depth: 0 };
  const random = createRandom();
  // The denoiser's features come from the first surface a camera ray meets, not from fog in front of it.
  let featuresRecorded = false;
  const { lights, environment } = scene;
  // With portals the sky is drawn through them (#1144); a scene with none samples the whole map as before.
  const portals = environment ? lights.portals ?? [] : [];
  if (lights.sun) buildFrame(lights.sun.direction, sunFrame);
  const sunCosineMax = Math.cos(lights.sun?.angularRadius ?? SUN_ANGULAR_RADIUS);

  function addRadiance(depth, red, green, blue) {
    let clampedRed = red;
    let clampedGreen = green;
    let clampedBlue = blue;
    if (depth > 0) {
      const peak = Math.max(red, green, blue);
      if (peak > options.fireflyClamp) {
        const scale = options.fireflyClamp / peak;
        clampedRed *= scale;
        clampedGreen *= scale;
        clampedBlue *= scale;
      }
    }
    radiance[0] += clampedRed;
    radiance[1] += clampedGreen;
    radiance[2] += clampedBlue;
  }

  // True while a light is sampled from a scattering event in the fog instead of from a surface.
  let inMedium = false;
  const phaseCandidate = { pdf: 0 };
  const volumeSpan = new Float64Array(2);
  const mediumFrame = new Float64Array(9);
  const scatteredDirection = new Float64Array(3);

  /** The share of light that survives the fog along a shadow ray of the given length. */
  function fogTransmittance(originX, originY, originZ, distance) {
    const { volume } = scene;
    if (!volume) return 1;
    if (!volumeInterval(volume, originX, originY, originZ, lightDirection[0], lightDirection[1], lightDirection[2], distance, volumeSpan)) return 1;
    return Math.exp(-volume.density * (volumeSpan[1] - volumeSpan[0]));
  }

  /** Light from the sampled direction at a scattering event: phase function, shadow ray, fog on the way to the light. */
  function addMediumDirect(depth, distance, weight) {
    const { volume } = scene;
    const cosine = lightDirection[0] * direction[0] + lightDirection[1] * direction[1] + lightDirection[2] * direction[2];
    const phase = henyeyGreensteinPhase(volume.anisotropy, cosine);
    const [originX, originY, originZ] = hit.point;
    if (occluded(scene, originX, originY, originZ, lightDirection[0], lightDirection[1], lightDirection[2], distance, shadowHit)) return;
    phaseCandidate.pdf = phase;
    const scale = phase * fogTransmittance(originX, originY, originZ, distance) * weight(phaseCandidate);
    addRadiance(
      depth + 1,
      throughput[0] * lightRadiance[0] * scale,
      throughput[1] * lightRadiance[1] * scale,
      throughput[2] * lightRadiance[2] * scale,
    );
  }

  /** Adds the light from one sampled direction: surface value, cosine, shadow ray. `weight` carries MIS and sampling. */
  function addDirect(depth, normal, distance, weight) {
    if (inMedium) {
      addMediumDirect(depth, distance, weight);
      return;
    }
    const cosine = normal[0] * lightDirection[0] + normal[1] * lightDirection[1] + normal[2] * lightDirection[2];
    if (cosine <= 0) return;
    evaluateSurface(surface, lightDirection[0], lightDirection[1], lightDirection[2]);
    const value = surface.value;
    if (value[0] + value[1] + value[2] <= 0) return;
    const originX = hit.point[0] + normal[0] * scene.surfaceOffset;
    const originY = hit.point[1] + normal[1] * scene.surfaceOffset;
    const originZ = hit.point[2] + normal[2] * scene.surfaceOffset;
    if (occluded(scene, originX, originY, originZ, lightDirection[0], lightDirection[1], lightDirection[2], distance, shadowHit)) return;
    const scale = cosine * weight(surface) * fogTransmittance(originX, originY, originZ, distance);
    if (lightIsSun && writeSunShadow) writeSunShadow(originX, originY, originZ, lightDirection[0], lightDirection[1], lightDirection[2], sunShadow);
    else sunShadow.fill(1);
    addRadiance(
      depth,
      throughput[0] * value[0] * lightRadiance[0] * scale * sunShadow[0],
      throughput[1] * value[1] * lightRadiance[1] * scale * sunShadow[1],
      throughput[2] * value[2] * lightRadiance[2] * scale * sunShadow[2],
    );
  }

  // Past the first hit one light is drawn at random instead of all of them, so a scene with many lights costs one shadow
  // ray per bounce. `selectionProbability` is the chance that this light was the one drawn; dividing by it keeps the sum unbiased.
  let selectionProbability = 1;
  const fullWeight = () => 1 / selectionProbability;

  // A light skips a part whose mask has its bit clear, at every bounce, so it is no bounce source there either.
  const reaches = light => inMedium || (hit.material.lightMask >> light.bit & 1) === 1;

  function sampleSun(depth, normal) {
    if (!reaches(lights.sun)) return;
    const cosineTheta = 1 - random.next() * (1 - sunCosineMax);
    const sineTheta = Math.sqrt(Math.max(0, 1 - cosineTheta * cosineTheta));
    const phi = 2 * Math.PI * random.next();
    const across = sineTheta * Math.cos(phi);
    const along = sineTheta * Math.sin(phi);
    for (let axis = 0; axis < 3; axis++) lightDirection[axis] = sunFrame[axis] * across + sunFrame[3 + axis] * along + sunFrame[6 + axis] * cosineTheta;
    for (let channel = 0; channel < 3; channel++) lightRadiance[channel] = lights.sun.color[channel];
    lightIsSun = true;
    addDirect(depth, normal, scene.farDistance, fullWeight);
    lightIsSun = false;
  }

  function aimAt(targetX, targetY, targetZ) {
    const deltaX = targetX - hit.point[0];
    const deltaY = targetY - hit.point[1];
    const deltaZ = targetZ - hit.point[2];
    const distanceSquared = deltaX * deltaX + deltaY * deltaY + deltaZ * deltaZ;
    const distance = Math.sqrt(distanceSquared);
    lightDirection[0] = deltaX / distance;
    lightDirection[1] = deltaY / distance;
    lightDirection[2] = deltaZ / distance;
    return { distance, distanceSquared };
  }

  function randomOnSphere(radius, out) {
    const height = 2 * random.next() - 1;
    const angle = 2 * Math.PI * random.next();
    const ring = Math.sqrt(1 - height * height);
    out[0] = radius * ring * Math.cos(angle);
    out[1] = radius * height;
    out[2] = radius * ring * Math.sin(angle);
  }

  const jitter = new Float64Array(3);

  function samplePointLight(depth, normal, light) {
    if (!reaches(light)) return;
    randomOnSphere(light.radius, jitter);
    const { distance, distanceSquared } = aimAt(light.position[0] + jitter[0], light.position[1] + jitter[1], light.position[2] + jitter[2]);
    if (distance < 1e-6) return;
    const strength = light.intensity * pointLightFalloff(distanceSquared, light);
    for (let channel = 0; channel < 3; channel++) lightRadiance[channel] = light.color[channel] * strength;
    addDirect(depth, normal, distance - scene.surfaceOffset, fullWeight);
  }

  function sampleSpotLight(depth, normal, light) {
    if (!reaches(light)) return;
    randomOnSphere(light.radius, jitter);
    const { distance, distanceSquared } = aimAt(light.position[0] + jitter[0], light.position[1] + jitter[1], light.position[2] + jitter[2]);
    if (distance < 1e-6) return;
    const axisCosine = -(light.direction[0] * lightDirection[0] + light.direction[1] * lightDirection[1] + light.direction[2] * lightDirection[2]);
    const inside = axisCosine - light.cosineHalfAngle;
    if (inside <= 0) return;
    const mask = light.blend > 0 && inside < light.blend ? smoothstep(inside / light.blend) : 1;
    const strength = light.intensity * pointLightFalloff(distanceSquared, light) * mask * (light.profile ? profileGain(light.profile, axisCosine) : 1);
    for (let channel = 0; channel < 3; channel++) lightRadiance[channel] = light.color[channel] * strength;
    addDirect(depth, normal, distance - scene.surfaceOffset, fullWeight);
  }

  function sampleAreaLight(depth, normal, light) {
    if (!reaches(light)) return;
    const across = (random.next() - 0.5) * light.width;
    const along = (random.next() - 0.5) * light.height;
    const pointX = light.position[0] + light.across[0] * across + light.along[0] * along;
    const pointY = light.position[1] + light.across[1] * across + light.along[1] * along;
    const pointZ = light.position[2] + light.across[2] * across + light.along[2] * along;
    const { distance, distanceSquared } = aimAt(pointX, pointY, pointZ);
    if (distance < 1e-6) return;
    const emitCosine = -(light.normal[0] * lightDirection[0] + light.normal[1] * lightDirection[1] + light.normal[2] * lightDirection[2]);
    if (emitCosine <= 0) return;
    const strength = light.intensity * emitCosine / distanceSquared * (light.profile ? profileGain(light.profile, emitCosine) : 1);
    for (let channel = 0; channel < 3; channel++) lightRadiance[channel] = light.color[channel] * strength;
    addDirect(depth, normal, distance - scene.surfaceOffset, fullWeight);
  }

  let environmentSampledPdf = 0;
  const environmentWeight = candidate => {
    const lightPdf = environmentSampledPdf * selectionProbability;
    const total = lightPdf * lightPdf + candidate.pdf * candidate.pdf;
    return lightPdf * lightPdf / total / lightPdf;
  };

  function sampleEnvironmentLight(depth, normal) {
    environmentSampledPdf = portals.length > 0
      ? samplePortalDirection(portals, hit.point[0], hit.point[1], hit.point[2], random.next(), random.next(), random.next(), lightDirection)
      : sampleEnvironment(environment, random.next(), random.next(), random.next(), random.next(), lightDirection);
    if (!(environmentSampledPdf > 0)) return;
    environmentRadiance(environment, lightDirection[0], lightDirection[1], lightDirection[2], lightRadiance);
    addDirect(depth, normal, scene.farDistance, environmentWeight);
  }

  const emitterCount = (lights.sun ? 1 : 0) + lights.points.length + lights.spots.length + lights.areas.length + (environment ? 1 : 0);

  function addEveryLight(depth, normal) {
    selectionProbability = 1;
    if (lights.sun) sampleSun(depth, normal);
    for (const light of lights.points) samplePointLight(depth, normal, light);
    for (const light of lights.spots) sampleSpotLight(depth, normal, light);
    for (const light of lights.areas) sampleAreaLight(depth, normal, light);
    if (environment) sampleEnvironmentLight(depth, normal);
  }

  const lightCount = lights.points.length + lights.spots.length + lights.areas.length;
  const useLightTree = resolveLightSelection(options.lightSelection, lights) === 'tree' && lightCount > 1;
  const lightTree = useLightTree ? buildLightTree(lights) : null;
  const drawRandom = () => random.next();
  function sampleLightByIndex(depth, normal, index) {
    if (index < lights.points.length) return samplePointLight(depth, normal, lights.points[index]);
    index -= lights.points.length;
    if (index < lights.spots.length) return sampleSpotLight(depth, normal, lights.spots[index]);
    return sampleAreaLight(depth, normal, lights.areas[index - lights.spots.length]);
  }

  const linkedLightsByMask = new Map();
  const allLights = () => [...lights.points, ...lights.spots, ...lights.areas];
  /** The sampling-order indices of the local lights the hit part is lit by; every light inside a medium. */
  function linkedLights() {
    const mask = inMedium ? -1 : hit.material.lightMask;
    let linked = linkedLightsByMask.get(mask);
    if (!linked) {
      linked = [];
      allLights().forEach((light, index) => {
        if ((mask >> light.bit & 1) === 1) linked.push(index);
      });
      linkedLightsByMask.set(mask, linked);
    }
    return linked;
  }

  /** One emitter by the light tree: the sun and the sky keep a uniform share, the local lights share theirs down the tree. */
  function addOneLightByTree(depth, normal) {
    const lightsShare = lightCount / emitterCount;
    let remaining = Math.floor(random.next() * emitterCount);
    if (lights.sun) {
      if (remaining === 0) {
        selectionProbability = 1 / emitterCount;
        return sampleSun(depth, normal);
      }
      remaining--;
    }
    if (remaining >= lightCount) {
      selectionProbability = 1 / emitterCount;
      return sampleEnvironmentLight(depth, normal);
    }
    const linked = linkedLights();
    if (linked.length < lightCount) {
      // The tree weighs a node by every light under it, linked or not, so a receiver with light linking draws uniformly among the lights it can see.
      selectionProbability = 1 / emitterCount;
      if (linked.length === 0) return;
      selectionProbability = lightsShare / linked.length;
      sampleLightByIndex(depth, normal, linked[Math.floor(random.next() * linked.length)]);
      selectionProbability = 1 / emitterCount;
      return;
    }
    const picked = chooseLightFromTree(lightTree, hit.point[0], hit.point[1], hit.point[2], normal[0], normal[1], normal[2], drawRandom);
    selectionProbability = 1 / emitterCount;
    if (picked.lightIndex < 0) return;
    selectionProbability = lightsShare * picked.probability;
    sampleLightByIndex(depth, normal, picked.lightIndex);
    // The sky is drawn with its uniform share whatever light was chosen: that share weighs the next escape ray.
    selectionProbability = 1 / emitterCount;
  }

  function addOneLight(depth, normal) {
    selectionProbability = 1 / emitterCount;
    let remaining = Math.floor(random.next() * emitterCount);
    if (lights.sun) {
      if (remaining === 0) return sampleSun(depth, normal);
      remaining--;
    }
    if (remaining < lights.points.length) return samplePointLight(depth, normal, lights.points[remaining]);
    remaining -= lights.points.length;
    if (remaining < lights.spots.length) return sampleSpotLight(depth, normal, lights.spots[remaining]);
    remaining -= lights.spots.length;
    if (remaining < lights.areas.length) return sampleAreaLight(depth, normal, lights.areas[remaining]);
    return sampleEnvironmentLight(depth, normal);
  }

  function addLights(depth, normal) {
    const firstHitByTree = useLightTree && lightCount > LIGHT_TREE_FIRST_HIT_LIGHTS;
    if ((depth === 0 && !firstHitByTree) || emitterCount <= 1) addEveryLight(depth, normal);
    else if (useLightTree) addOneLightByTree(depth, normal);
    else addOneLight(depth, normal);
  }

  function addEscape(depth, previousPdf, afterMirror, originX, originY, originZ) {
    if (!environment) return;
    environmentRadiance(environment, direction[0], direction[1], direction[2], sky);
    let weight = 1;
    if (!afterMirror) {
      const environmentSide = (portals.length > 0 ? portalPdf(portals, originX, originY, originZ, direction[0], direction[1], direction[2]) : environmentPdf(environment, direction[0], direction[1], direction[2])) * selectionProbability;
      weight = previousPdf * previousPdf / (previousPdf * previousPdf + environmentSide * environmentSide);
    }
    addRadiance(depth, throughput[0] * sky[0] * weight, throughput[1] * sky[1] * weight, throughput[2] * sky[2] * weight);
  }

  function recordFeatures(normal, isGlass) {
    features.albedo[0] = isGlass ? 1 : hit.color[0];
    features.albedo[1] = isGlass ? 1 : hit.color[1];
    features.albedo[2] = isGlass ? 1 : hit.color[2];
    features.normal[0] = normal[0];
    features.normal[1] = normal[1];
    features.normal[2] = normal[2];
    features.depth = hit.distance;
  }

  function survivesRoulette(depth) {
    if (depth < RUSSIAN_ROULETTE_START) return true;
    const survival = Math.min(0.95, Math.max(0.05, Math.max(throughput[0], throughput[1], throughput[2])));
    if (random.next() >= survival) return false;
    for (let channel = 0; channel < 3; channel++) throughput[channel] /= survival;
    return true;
  }

  /**
   * Draws the distance to the next scattering event along the segment. When it falls inside the fog before the segment ends,
   * puts the event in `hit.point` and returns true; otherwise the ray crosses the fog (or misses it) unchanged, because the
   * chance of not scattering is exactly the transmittance that the sampling would otherwise multiply in.
   */
  function scatterInFog(originX, originY, originZ, segmentLength) {
    const { volume } = scene;
    if (!volumeInterval(volume, originX, originY, originZ, direction[0], direction[1], direction[2], segmentLength, volumeSpan)) return false;
    const eventDistance = volumeSpan[0] - Math.log(1 - random.next()) / volume.density;
    if (eventDistance >= volumeSpan[1]) return false;
    hit.point[0] = originX + direction[0] * eventDistance;
    hit.point[1] = originY + direction[1] * eventDistance;
    hit.point[2] = originZ + direction[2] * eventDistance;
    return true;
  }

  /** Lights the scattering event, then turns `direction` by a Henyey-Greenstein draw. Returns the draw's density. */
  function scatterInMedium(depth) {
    const { volume } = scene;
    for (let channel = 0; channel < 3; channel++) throughput[channel] *= volume.albedo[channel];
    inMedium = true;
    addLights(depth, normal);
    inMedium = false;
    const cosine = sampleHenyeyGreensteinCosine(volume.anisotropy, random.next());
    const sine = Math.sqrt(Math.max(0, 1 - cosine * cosine));
    const azimuth = 2 * Math.PI * random.next();
    buildFrame(direction, mediumFrame);
    for (let axis = 0; axis < 3; axis++) {
      scatteredDirection[axis] = mediumFrame[axis] * sine * Math.cos(azimuth) + mediumFrame[3 + axis] * sine * Math.sin(azimuth) + mediumFrame[6 + axis] * cosine;
    }
    for (let axis = 0; axis < 3; axis++) direction[axis] = scatteredDirection[axis];
    return henyeyGreensteinPhase(volume.anisotropy, cosine);
  }

  // A scattering local volume is lit by the sky's mean radiance and by the sun through a shadow ray, as the rasterizer lights it.
  const localVolumeLighting = scene.localVolumes?.some(volume => volume.scatter > 0)
    ? {
      sun: lights.sun,
      ambient: meanEnvironmentRadiance(environment),
      sunVisibility: (pointX, pointY, pointZ) => (occluded(scene, pointX, pointY, pointZ, lights.sun.direction[0], lights.sun.direction[1], lights.sun.direction[2], scene.farDistance, shadowHit) ? 0 : 1),
    }
    : null;
  const crossLocalVolumes = scene.localVolumes ? createLocalVolumeCrossing(scene.localVolumes, localVolumeLighting) : null;
  // The local volumes that cast shadows dim the sun's direct light at a surface (#1047); sunShadow holds the per-channel factor of the last sun sample.
  const writeSunShadow = scene.localVolumes ? createLocalVolumeSurfaceShadow(scene.localVolumes) : null;
  const sunShadow = new Float64Array(3);
  let lightIsSun = false;
  const localEmitted = new Float64Array(3);

  const walkSubsurface = createRandomWalk(scene, random, intersect);
  const walkWeight = new Float64Array(3);

  /**
   * Sends the diffuse light of the hit through its subsurface random walk. On success the path stands where the walk left (or,
   * for a card with nothing behind it, on the near or far face), `normal` faces out of that point, `surface` is a white diffuse
   * lobe there with its lights added, and the throughput carries the walk. False when the walk ended inside the part.
   */
  function enterSubsurface(depth, subsurface) {
    const color = subsurface.color ?? hit.color;
    walkWeight.fill(1);
    const outcome = walkSubsurface(subsurface, color, hit.point[0], hit.point[1], hit.point[2], normal, hit.material, shadowHit, walkWeight);
    if (outcome === WALK_OUTCOME.lost) return false;
    const entryScale = surface.diffuseShare * subsurface.weight / surface.subsurfaceChance;
    if (outcome === WALK_OUTCOME.exit) {
      const facing = shadowHit.normal[0] * walkSubsurface.direction[0] + shadowHit.normal[1] * walkSubsurface.direction[1] + shadowHit.normal[2] * walkSubsurface.direction[2] < 0 ? -1 : 1;
      for (let axis = 0; axis < 3; axis++) {
        hit.point[axis] = shadowHit.point[axis];
        normal[axis] = shadowHit.normal[axis] * facing;
      }
      for (let channel = 0; channel < 3; channel++) throughput[channel] *= walkWeight[channel] * entryScale;
    } else {
      // A card: half of the colour is reflected on the side the ray came from and half is transmitted diffusely through it.
      if (random.next() < 0.5) for (let axis = 0; axis < 3; axis++) normal[axis] = -normal[axis];
      for (let channel = 0; channel < 3; channel++) throughput[channel] *= color[channel] * entryScale;
    }
    setWhiteDiffuse(surface, normal);
    addLights(depth, normal);
    return true;
  }

  /** Follows one camera ray. Leaves the radiance in `radiance` and the first-hit features in `features`. */
  function trace(originX, originY, originZ, directionX, directionY, directionZ, pixel, sample) {
    random.reset(pixel, sample, options.seed);
    radiance[0] = 0;
    radiance[1] = 0;
    radiance[2] = 0;
    throughput[0] = 1;
    throughput[1] = 1;
    throughput[2] = 1;
    features.albedo.fill(1);
    featuresRecorded = false;
    // A ray that finds nothing has the sky as its feature: one fixed normal and depth, so the filter treats sky as one surface.
    features.normal[0] = 0;
    features.normal[1] = 0;
    features.normal[2] = 1;
    features.depth = 0;
    direction[0] = directionX;
    direction[1] = directionY;
    direction[2] = directionZ;
    let positionX = originX;
    let positionY = originY;
    let positionZ = originZ;
    let previousPdf = 0;
    let afterMirror = true;
    for (let depth = 0; depth <= options.bounces; depth++) {
      const found = intersect(scene, positionX, positionY, positionZ, direction[0], direction[1], direction[2], hit, depth === 0);
      const scattersInFog = scene.volume && scatterInFog(positionX, positionY, positionZ, found ? hit.distance : scene.farDistance);
      if (crossLocalVolumes) {
        const segmentLength = scattersInFog ? Math.hypot(hit.point[0] - positionX, hit.point[1] - positionY, hit.point[2] - positionZ) : (found ? hit.distance : scene.farDistance);
        crossLocalVolumes(positionX, positionY, positionZ, direction[0], direction[1], direction[2], segmentLength, random.next(), throughput, localEmitted);
        addRadiance(depth, localEmitted[0], localEmitted[1], localEmitted[2]);
      }
      if (scattersInFog) {
        previousPdf = scatterInMedium(depth);
        afterMirror = false;
        positionX = hit.point[0];
        positionY = hit.point[1];
        positionZ = hit.point[2];
        if (!survivesRoulette(depth)) break;
        continue;
      }
      if (!found) {
        addEscape(depth, previousPdf, afterMirror, positionX, positionY, positionZ);
        break;
      }
      const material = hit.material;
      const entering = hit.normal[0] * direction[0] + hit.normal[1] * direction[1] + hit.normal[2] * direction[2] < 0;
      const facing = entering ? 1 : -1;
      normal[0] = hit.normal[0] * facing;
      normal[1] = hit.normal[1] * facing;
      normal[2] = hit.normal[2] * facing;
      const isGlass = hit.transmission > 0 && random.next() < hit.transmission;
      if (!featuresRecorded) {
        recordFeatures(normal, isGlass);
        featuresRecorded = true;
      }
      const emissionScale = hit.material.emissionFresnel > 0
        ? fresnelSchlick(-(direction[0] * normal[0] + direction[1] * normal[1] + direction[2] * normal[2]), hit.material.emissionFresnel)
        : 1;
      addRadiance(depth, throughput[0] * hit.emission[0] * emissionScale, throughput[1] * hit.emission[1] * emissionScale, throughput[2] * hit.emission[2] * emissionScale);
      const viewX = -direction[0];
      const viewY = -direction[1];
      const viewZ = -direction[2];
      if (isGlass) {
        const alpha = roughnessToAlpha(hit.roughness);
        if (!sampleGlass(normal, viewX, viewY, viewZ, entering, material.ior, alpha, random.next(), random.next(), random.next(), direction)) break;
        const refracted = direction[0] * normal[0] + direction[1] * normal[1] + direction[2] * normal[2] < 0;
        if (refracted) {
          throughput[0] *= hit.color[0];
          throughput[1] *= hit.color[1];
          throughput[2] *= hit.color[2];
        }
        afterMirror = true;
      } else {
        prepareSurface(surface, material, hit.metallic, hit.roughness, hit.color, normal, viewX, viewY, viewZ, hit.clearcoat);
        const subsurface = material.subsurface;
        if (subsurface) splitSubsurface(surface, subsurface.weight);
        addLights(depth, normal);
        let lobeUnit = random.next();
        if (subsurface) {
          if (lobeUnit < surface.subsurfaceChance) {
            if (!enterSubsurface(depth, subsurface)) break;
            lobeUnit = 0;
          } else {
            lobeUnit -= surface.subsurfaceChance;
          }
        }
        const isMirror = sampleSurface(surface, lobeUnit, random.next(), random.next(), direction);
        const cosine = direction[0] * normal[0] + direction[1] * normal[1] + direction[2] * normal[2];
        if (cosine <= 0) break;
        if (isMirror) {
          mirrorWeight(surface, mirror);
          for (let channel = 0; channel < 3; channel++) throughput[channel] *= mirror[channel];
          afterMirror = true;
        } else {
          evaluateSurface(surface, direction[0], direction[1], direction[2]);
          if (!(surface.pdf > 0)) break;
          for (let channel = 0; channel < 3; channel++) throughput[channel] *= surface.value[channel] * cosine / surface.pdf;
          previousPdf = surface.pdf;
          afterMirror = false;
        }
      }
      positionX = hit.point[0] + direction[0] * scene.surfaceOffset;
      positionY = hit.point[1] + direction[1] * scene.surfaceOffset;
      positionZ = hit.point[2] + direction[2] * scene.surfaceOffset;
      if (!survivesRoulette(depth)) break;
    }
  }

  return { trace, radiance, features };
}

// ---- Image ----

/** The display transform of the rasterizer's post pass (exposure, view transform, gamma 2.2, optional look) applied to linear pixels. */
export function toneMapToRgba8(linear, width, height, { viewTransform = 'aces', look = null, exposure = 1 } = {}) {
  const rgba = new Uint8ClampedArray(width * height * 4);
  const plainCurve = viewTransform === 'aces' && !look;
  for (let pixel = 0; pixel < width * height; pixel++) {
    const color = plainCurve
      ? [0, 1, 2].map(channel => acesChannel(linear[pixel * 3 + channel] * exposure) ** (1 / 2.2))
      : displayColor([linear[pixel * 3] * exposure, linear[pixel * 3 + 1] * exposure, linear[pixel * 3 + 2] * exposure], { viewTransform, look });
    for (let channel = 0; channel < 3; channel++) rgba[pixel * 4 + channel] = Math.round(color[channel] * 255);
    rgba[pixel * 4 + 3] = 255;
  }
  return rgba;
}

/** Names what this scene asks for that the path tracer does not draw, so a result never claims more than it traced. */
export function describeIgnoredFeatures(parts, environment, backend = 'cpu', { kernelMaterials = false, clipStart = 0 } = {}) {
  const notes = new Set();
  if (clipStart > 0 && backend === 'gpu') notes.add('camera.clipStart is ignored: only the CPU, WebGPU and native cycles tracers start camera rays at it, so geometry between the eye and the clip start is drawn.');
  const fog = environment?.volumeFog;
  if (fog?.density > 0 && (fog.noiseAmount ?? 0.5) > 0) notes.add('volumeFog is traced as a uniform medium: noiseAmount, noiseScale and drift are ignored.');
  if (fog?.density > 0 && fog.ambient) notes.add('volumeFog.ambient is not added: the fog is lit by the traced lights and sky.');
  const hasSoftFalloff = [...(environment?.pointLights ?? []), ...(environment?.spotLights ?? [])].some(light => light.softFalloff === true);
  if (hasSoftFalloff && !kernelMaterials) notes.add('softFalloff is ignored: only the native cycles kernel draws a light as an oriented disk, the other tracers draw a sphere.');
  const lightsWithOwnLimit = [...(environment?.pointLights ?? []), ...(environment?.spotLights ?? []), ...(environment?.areaLights ?? [])];
  const hasBounceLimit = environment?.sunMaxBounces !== undefined || lightsWithOwnLimit.some(light => light.maxBounces !== undefined);
  if (hasBounceLimit && !kernelMaterials) notes.add('A light maxBounces (sunMaxBounces for the sun) is ignored: only the native cycles kernel stops a light after its own bounces, the other tracers run every light to the scene bounces.');
  const hasPortal = (environment?.areaLights ?? []).some(light => light.portal === true);
  if (hasPortal && !kernelMaterials && backend === 'gpu') notes.add('Light portals (areaLights with portal: true) are ignored: only the native cycles kernel, the CPU tracer and the WebGPU tracer sample the environment through them, the other tracers draw no light from a portal.');
  const hasGridVolume = (environment?.localVolumes ?? []).some(volume => volume?.shape === 'grid');
  if (hasGridVolume && kernelMaterials && environment.volumeShutter > 0) notes.add('environment.volumeShutter is ignored for a grid volume: Cook draws the grid as it is at the frame time, with no motion blur from its velocity channel. Use backend "cpu" or "webgpu" for a blurred blast.');
  if (!environment?.map) notes.add('There is no environment map, so the sky is black and only the lights shine.');
  if (environment?.fillIntensity > 0) notes.add('fillIntensity is ignored: the two fixed fill lights are rasterizer only. Add a point or area light, or raise environmentIntensity, to light the shadow side of a trace.');
  if (environment?.world === true) notes.add('world: true is ignored: the outdoor haze shading is rasterizer only, and a trace draws the environment map behind the picture and lights with it whatever world says.');
  if (environment?.cameraIntensity !== undefined && !kernelMaterials) notes.add('cameraIntensity is ignored: only the native cycles kernel draws the sky a camera ray sees at its own strength, the other tracers use the map intensity.');
  for (const part of parts) {
    const material = part.material ?? {};
    for (const field of IGNORED_MAP_FIELDS) if (material[field]) notes.add(`${field} is ignored.`);
    if (material.tag && material.tag !== 'surface') notes.add(`${material.tag} materials are traced as plain surfaces.`);
    if (material.alphaMode === 'blend' && hasGraphOpacity(material)) notes.add('A graph opacity output is traced as a cutout at 0.5.');
    else if (material.alphaMode === 'blend' && !kernelMaterials) notes.add('Blended transparency is traced as opaque.');
    if (!kernelMaterials && (material.layerMaps?.clearcoatTexture || material.transmissionMap)) notes.add('Graph clearcoat and transmission masks are read by the CPU tracer; the GPU tracers use the factors.');
    if (kernelMaterials && hasSplitLayerMap(material)) notes.add('A clearcoat or sheen colour map is ignored when the layer has a roughness above 0 kept in another map.');
    if (material.emissionFresnel > 0 && backend !== 'cpu') notes.add('emission fresnel is ignored by the GPU path tracers; the cpu backend applies it.');
    if (material.emissionMask) notes.add('emissionMask is ignored by the path tracers; the rasterizer applies it.');
    for (const [name, isUsed, kernelShades] of IGNORED_LAYERS) if (!(kernelMaterials && kernelShades) && isUsed(material, kernelMaterials)) notes.add(`${name} is ignored.`);
  }
  return [...notes];
}

/**
 * Renders rows `rowStart` up to `rowEnd` and returns their buffers (colour, albedo, normal, depth, variance), row
 * major from the band's first row. A pixel's random numbers depend only on its place in the whole image, so bands
 * can be drawn in any order, on any thread, and give the same pixels.
 */
/**
 * True when the mean luminance of a pixel is known well enough: its standard error, relative to the mean plus a small
 * floor so that near-black pixels do not ask for endless samples, is under `threshold`. It reads only the pixel's own
 * samples, so the decision is the same on any thread and in any band split.
 */
function hasConverged(sumLuminance, sumLuminanceSquares, sampleCount, threshold) {
  const mean = sumLuminance / sampleCount;
  const sampleVariance = Math.max(0, sumLuminanceSquares / sampleCount - mean * mean) * sampleCount / (sampleCount - 1);
  const standardError = Math.sqrt(sampleVariance / sampleCount);
  return standardError < threshold * (mean + CONVERGENCE_LUMINANCE_FLOOR);
}

function isConvergenceCheckDue(sampleCount, options) {
  if (!(options.noiseThreshold > 0)) return false;
  if (sampleCount < ADAPTIVE_MINIMUM_SAMPLES) return false;
  return (sampleCount - ADAPTIVE_MINIMUM_SAMPLES) % ADAPTIVE_BATCH_SAMPLES === 0;
}

export function renderBand(scene, camera, options, rowStart, rowEnd, shouldStop = () => {}) {
  const tracer = createPathTracer(scene, options);
  const { width, height, samples } = options;
  const pixelCount = (rowEnd - rowStart) * width;
  const color = new Float32Array(pixelCount * 3);
  const albedo = new Float32Array(pixelCount * 3);
  const normal = new Float32Array(pixelCount * 3);
  const depth = new Float32Array(pixelCount);
  const variance = new Float32Array(pixelCount);
  const samplesTaken = new Uint16Array(pixelCount);
  for (let row = rowStart; row < rowEnd; row++) {
    shouldStop();
    for (let column = 0; column < width; column++) {
      const pixel = row * width + column;
      const slot = (row - rowStart) * width + column;
      let sumLuminance = 0;
      let sumLuminanceSquares = 0;
      let taken = 0;
      while (taken < samples) {
        const sample = taken;
        const jitterX = hashJitter(pixel, sample, options.seed, 1);
        const jitterY = hashJitter(pixel, sample, options.seed, 2);
        const screenX = ((column + jitterX) / width * 2 - 1) * camera.halfWidth;
        const screenY = (1 - (row + jitterY) / height * 2) * camera.halfHeight;
        const directionX = camera.forward[0] + camera.right[0] * screenX + camera.above[0] * screenY;
        const directionY = camera.forward[1] + camera.right[1] * screenX + camera.above[1] * screenY;
        const directionZ = camera.forward[2] + camera.right[2] * screenX + camera.above[2] * screenY;
        const length = Math.hypot(directionX, directionY, directionZ);
        // clipStart is a distance along the view axis, as Cycles' clip start: a ray from the eye starts where it has gone that far along the axis.
        const rayDirectionX = directionX / length;
        const rayDirectionY = directionY / length;
        const rayDirectionZ = directionZ / length;
        const clipDistance = camera.clipStart ? camera.clipStart / (rayDirectionX * camera.forward[0] + rayDirectionY * camera.forward[1] + rayDirectionZ * camera.forward[2]) : 0;
        tracer.trace(camera.eye[0] + rayDirectionX * clipDistance, camera.eye[1] + rayDirectionY * clipDistance, camera.eye[2] + rayDirectionZ * clipDistance, rayDirectionX, rayDirectionY, rayDirectionZ, pixel, sample);
        const { radiance, features } = tracer;
        const sampleLuminance = luminance(radiance[0], radiance[1], radiance[2]);
        sumLuminance += sampleLuminance;
        sumLuminanceSquares += sampleLuminance * sampleLuminance;
        for (let channel = 0; channel < 3; channel++) {
          color[slot * 3 + channel] += radiance[channel];
          albedo[slot * 3 + channel] += features.albedo[channel];
          normal[slot * 3 + channel] += features.normal[channel];
        }
        depth[slot] += features.depth;
        taken++;
        if (isConvergenceCheckDue(taken, options) && hasConverged(sumLuminance, sumLuminanceSquares, taken, options.noiseThreshold)) break;
      }
      for (let channel = 0; channel < 3; channel++) {
        color[slot * 3 + channel] /= taken;
        albedo[slot * 3 + channel] /= taken;
        normal[slot * 3 + channel] /= taken;
      }
      depth[slot] /= taken;
      const meanLuminance = sumLuminance / taken;
      variance[slot] = Math.max(0, sumLuminanceSquares / taken - meanLuminance * meanLuminance) / Math.max(taken - 1, 1);
      samplesTaken[slot] = taken;
    }
  }
  return { color, albedo, normal, depth, variance, samplesTaken };
}

function hashJitter(pixel, sample, seed, dimension) {
  let mixed = Math.imul(pixel ^ 0x51ed270b, 0x9e3779b1) ^ Math.imul(sample + dimension * 0x632be5ab, 0x85ebca6b) ^ Math.imul(seed + 0x1b873593, 0xc2b2ae35);
  mixed = Math.imul(mixed ^ (mixed >>> 16), 0x7feb352d);
  mixed = Math.imul(mixed ^ (mixed >>> 15), 0x846ca68b);
  mixed ^= mixed >>> 16;
  return (mixed >>> 0) / 4294967296;
}

function totalSamples(samplesTaken) {
  let total = 0;
  for (let pixel = 0; pixel < samplesTaken.length; pixel++) total += samplesTaken[pixel];
  return total;
}

function normalizeNormals(normal, pixelCount) {
  for (let pixel = 0; pixel < pixelCount; pixel++) {
    const length = Math.hypot(normal[pixel * 3], normal[pixel * 3 + 1], normal[pixel * 3 + 2]);
    if (length === 0) continue;
    for (let axis = 0; axis < 3; axis++) normal[pixel * 3 + axis] /= length;
  }
}

function copyBand(buffers, band, rowStart, width) {
  const pixelOffset = rowStart * width;
  for (const name of ['color', 'albedo', 'normal']) buffers[name].set(band[name], pixelOffset * 3);
  for (const name of ['depth', 'variance', 'samplesTaken']) buffers[name].set(band[name], pixelOffset);
}

/** Draws bands on a pool of module workers, handing the next band to whichever worker finishes first. */
function renderBandsInWorkers(scene, camera, options, buffers, shouldStop) {
  const bandCount = Math.ceil(options.height / WORKER_BAND_ROWS);
  const workerCount = Math.min(options.threads, bandCount);
  const workers = [];
  const { tracer: _tracer, ...transferableScene } = scene;
  return new Promise((resolve, reject) => {
    let nextBand = 0;
    let finishedBands = 0;
    let settled = false;
    const finish = (error) => {
      if (settled) return;
      settled = true;
      clearInterval(clock);
      for (const worker of workers) worker.terminate();
      if (error) reject(error);
      else resolve();
    };
    const clock = setInterval(() => {
      try {
        shouldStop();
      } catch (error) {
        finish(error);
      }
    }, 250);
    const assign = (worker) => {
      if (nextBand >= bandCount) return;
      const rowStart = nextBand * WORKER_BAND_ROWS;
      nextBand++;
      worker.postMessage({ type: 'band', rowStart, rowEnd: Math.min(rowStart + WORKER_BAND_ROWS, options.height) });
    };
    for (let index = 0; index < workerCount; index++) {
      const worker = new Worker(new URL(WORKER_FILE, import.meta.url), { type: 'module' });
      workers.push(worker);
      worker.onerror = (event) => finish(new Error(`Path tracer worker failed: ${event.message}`));
      worker.onmessage = (event) => {
        if (event.data.type === 'ready') {
          assign(worker);
          return;
        }
        copyBand(buffers, event.data.band, event.data.rowStart, options.width);
        finishedBands++;
        if (finishedBands === bandCount) finish();
        else assign(worker);
      };
      worker.postMessage({ type: 'scene', scene: transferableScene, camera, options });
    }
  });
}

/**
 * Renders one still. `scene` is `{ parts, environment, camera }` as the rasterizer takes them. Resolves with the linear
 * pixels, the tone-mapped RGBA bytes, and a report. Rejects, and returns nothing, when `maxSeconds` runs out.
 * `threads` above 1 uses module workers where the platform has them; the pixels are the same either way.
 */
export async function renderPathTracedImage({ parts, environment = {}, camera }, rawOptions = {}) {
  const options = normalizePathTracerOptions(rawOptions);
  const started = performance.now();
  const shouldStop = () => {
    if ((performance.now() - started) / 1000 > options.maxSeconds) throw new Error(`The path trace passed its ${options.maxSeconds} second limit and was stopped.`);
  };
  const { width, height } = options;
  const view = createCamera(camera, width, height);
  const gpuModule = options.backend === 'gpu' || options.backend === 'webgpu'
    ? await (options.backend === 'webgpu' ? import('./path-tracer-webgpu.js') : import('./path-tracer-gpu.js'))
    : null;
  const scene = gpuModule ? await buildTraceSceneForDevice(parts, environment, gpuModule) : buildTraceScene(parts, environment);
  if (options.backend !== 'cpu' && options.backend !== 'webgpu') refuseLocalVolumes(scene, `backend "${options.backend}"`);
  const pixelCount = width * height;
  const buffers = {
    color: new Float32Array(pixelCount * 3), albedo: new Float32Array(pixelCount * 3), normal: new Float32Array(pixelCount * 3),
    depth: new Float32Array(pixelCount), variance: new Float32Array(pixelCount), samplesTaken: new Uint16Array(pixelCount),
  };
  const threads = typeof Worker === 'function' ? options.threads : 1;
  let gpuName = null;
  let gpuCompileSeconds = 0;
  let gpuKernelCompiles = 0;
  if (gpuModule) {
    const { traceOnGpu, gpuKernelCompileCount } = gpuModule;
    const traced = await traceOnGpu(scene, view, options, shouldStop);
    gpuName = traced.gpu;
    gpuCompileSeconds = traced.compileSeconds;
    gpuKernelCompiles = gpuKernelCompileCount();
    copyBand(buffers, traced, 0, width);
  } else if (threads > 1) {
    await renderBandsInWorkers(scene, view, { ...options, threads }, buffers, shouldStop);
  } else {
    copyBand(buffers, renderBand(scene, view, options, 0, height, shouldStop), 0, width);
  }
  shouldStop();
  const tracedSeconds = (performance.now() - started) / 1000;
  normalizeNormals(buffers.normal, pixelCount);
  const { samplesTaken, ...denoiseInputs } = buffers;
  const linear = options.denoiser === 'wavelet' ? denoiseRadiance({ width, height, ...denoiseInputs }) : buffers.color;
  const averageSamples = totalSamples(samplesTaken) / pixelCount;
  const estimatedNoise = estimateRelativeNoise({ color: buffers.color, variance: buffers.variance, averageSamples });
  return {
    width, height, linear, rgba: toneMapToRgba8(linear, width, height, options), features: denoiseInputs,
    report: {
      width, height, samples: options.samples, bounces: options.bounces, seed: options.seed, denoised: options.denoiser === 'wavelet',
      denoiser: options.denoiser, threads,
      backend: options.backend, ...(gpuName ? { gpu: gpuName, gpuCompileSeconds, gpuKernelCompiles } : {}),
      averageSamples, noiseThreshold: options.noiseThreshold, ...(estimatedNoise === null ? {} : { estimatedNoise }),
      triangles: uniqueTriangleCount(scene), tracedSeconds, seconds: (performance.now() - started) / 1000,
      ignored: describeIgnoredFeatures(parts, environment, options.backend, { clipStart: view.clipStart }),
    },
  };
}

// Cook is the public name of the path tracer.
export const Cook = renderPathTracedImage;