@plasius/gpu-lighting 0.2.5 → 0.2.7

package/src/index.js

@@ -40,6 +40,15 @@ const techniqueSpecs = {
       denoise: "denoise.job.wgsl",
     },
   },
+  wavefront: {
+    description:
+      "Renderer-aligned wavefront lighting jobs for terminal radiance and continuation scattering.",
+    prelude: "prelude.wgsl",
+    jobs: {
+      accumulateTerminalRadiance: "accumulate-terminal-radiance.job.wgsl",
+      scatterContinuations: "scatter-continuations.job.wgsl",
+    },
+  },
   volumetrics: {
     description:
       "Froxel volumetric lighting for fog, shafts, and participating media shadows.",
@@ -1128,6 +1137,775 @@ export function createWavefrontEnvironmentLightingOptions(options = {}) {
   });
 }
 
+export const lightingWavefrontSchemaVersion = 1;
+export const lightingWavefrontQueuePairStrategy = "ping-pong-active-next";
+export const lightingWavefrontHitTypes = Object.freeze([
+  "surface",
+  "emissive",
+  "environment",
+  "transparent",
+  "miss",
+]);
+export const lightingWavefrontRayKinds = Object.freeze([
+  "path",
+  "visibility-probe",
+]);
+export const lightingWavefrontVisibilityProbeModes = Object.freeze([
+  "disabled",
+  "mis-balanced",
+  "exclusive-emissive",
+]);
+export const lightingWavefrontTerminalHitTypes = Object.freeze([
+  "emissive",
+  "environment",
+  "miss",
+]);
+export const lightingWavefrontContinuationHitTypes = Object.freeze([
+  "surface",
+  "transparent",
+]);
+export const lightingWavefrontPassOrder = Object.freeze([
+  "accumulateTerminalRadiance",
+  "scatterContinuations",
+]);
+export const lightingRequiredRendererWavefrontPassOrder = Object.freeze([
+  "generatePrimaryRays",
+  "intersectActiveQueue",
+  "resolveSurfaceRecords",
+  "accumulateTerminalRadiance",
+  "scatterContinuations",
+  "compactAndSwapQueues",
+]);
+
+function createLightingWavefrontField(name, type, description) {
+  return Object.freeze({
+    name,
+    type,
+    description,
+  });
+}
+
+function createLightingWavefrontRecordContract(recordName, fields) {
+  return Object.freeze({
+    schemaVersion: lightingWavefrontSchemaVersion,
+    recordName,
+    fields: Object.freeze(fields),
+  });
+}
+
+export const lightingWavefrontBufferContracts = Object.freeze({
+  ray: createLightingWavefrontRecordContract(
+    "RayRecord",
+    [
+      createLightingWavefrontField("rayId", "u32", "Stable ray identifier."),
+      createLightingWavefrontField("parentRayId", "u32", "Parent ray identifier."),
+      createLightingWavefrontField("sourcePixelId", "u32", "Source pixel/sample owner."),
+      createLightingWavefrontField("sampleId", "u32", "Per-pixel sample slot."),
+      createLightingWavefrontField("bounce", "u32", "Current bounce depth."),
+      createLightingWavefrontField("mediumRefId", "u32", "Current medium reference."),
+      createLightingWavefrontField(
+        "mediumStackDepth",
+        "u32",
+        "Depth of the bounded nested medium stack."
+      ),
+      createLightingWavefrontField(
+        "flags",
+        "u32",
+        "Renderer-owned ray flags. Low bits may encode ray kind metadata."
+      ),
+      createLightingWavefrontField(
+        "mediumStack0",
+        "vec4<u32>",
+        "Lower half of the bounded nested medium stack."
+      ),
+      createLightingWavefrontField(
+        "mediumStack1",
+        "vec4<u32>",
+        "Upper half of the bounded nested medium stack."
+      ),
+      createLightingWavefrontField(
+        "spectralState",
+        "vec4<f32>",
+        "Spectral transport payload for wavelength-driven reference validation."
+      ),
+      createLightingWavefrontField("origin", "vec3<f32>", "Ray origin."),
+      createLightingWavefrontField("direction", "vec3<f32>", "Normalized ray direction."),
+      createLightingWavefrontField("throughput", "vec3<f32>", "Accumulated path throughput."),
+    ]
+  ),
+  hit: createLightingWavefrontRecordContract(
+    "HitRecord",
+    [
+      createLightingWavefrontField("rayId", "u32", "Stable ray identifier."),
+      createLightingWavefrontField("sourcePixelId", "u32", "Source pixel/sample owner."),
+      createLightingWavefrontField("hitType", "u32", "Surface, emissive, environment, transparent, or miss."),
+      createLightingWavefrontField("distance", "f32", "Nearest-hit distance."),
+      createLightingWavefrontField("entityId", "u32", "Owning entity identifier."),
+      createLightingWavefrontField("instanceId", "u32", "Owning instance identifier."),
+      createLightingWavefrontField("primitiveId", "u32", "Primitive identifier."),
+      createLightingWavefrontField("materialId", "u32", "Resolved material identifier."),
+      createLightingWavefrontField("barycentrics", "vec3<f32>", "Triangle barycentrics."),
+      createLightingWavefrontField("uv", "vec2<f32>", "Resolved UV coordinates."),
+      createLightingWavefrontField("geometricNormal", "vec3<f32>", "Geometric surface normal."),
+      createLightingWavefrontField("shadingNormal", "vec3<f32>", "Interpolated shading normal."),
+      createLightingWavefrontField("frontFace", "u32", "Front-face classification."),
+    ]
+  ),
+  surface: createLightingWavefrontRecordContract(
+    "SurfaceRecord",
+    [
+      createLightingWavefrontField("rayId", "u32", "Stable ray identifier."),
+      createLightingWavefrontField("entityId", "u32", "Owning entity identifier."),
+      createLightingWavefrontField("materialRefId", "u32", "Renderer material reference id."),
+      createLightingWavefrontField("mediumRefId", "u32", "Renderer medium reference id."),
+      createLightingWavefrontField("geometricNormal", "vec3<f32>", "Geometric surface normal."),
+      createLightingWavefrontField("shadingNormal", "vec3<f32>", "Interpolated shading normal."),
+      createLightingWavefrontField("uv", "vec2<f32>", "Resolved UV coordinates."),
+      createLightingWavefrontField("tangentFrame", "mat3x3<f32>", "Resolved tangent frame."),
+    ]
+  ),
+  materialReference: createLightingWavefrontRecordContract(
+    "MaterialReferenceRecord",
+    [
+      createLightingWavefrontField("materialRefId", "u32", "Lighting-visible material reference id."),
+      createLightingWavefrontField("materialId", "u32", "Source material identifier."),
+      createLightingWavefrontField("shadingModel", "u32", "Renderer shading-model discriminator."),
+      createLightingWavefrontField("textureSetId", "u32", "Resolved texture-set identifier."),
+      createLightingWavefrontField("flags", "u32", "Renderer material flags."),
+    ]
+  ),
+  mediumReference: createLightingWavefrontRecordContract(
+    "MediumReferenceRecord",
+    [
+      createLightingWavefrontField("mediumRefId", "u32", "Lighting-visible medium reference id."),
+      createLightingWavefrontField("mediumId", "u32", "Source medium identifier."),
+      createLightingWavefrontField("phaseModel", "u32", "Phase-function discriminator."),
+      createLightingWavefrontField("absorption", "vec3<f32>", "Medium absorption coefficients."),
+      createLightingWavefrontField("scattering", "vec3<f32>", "Medium scattering coefficients."),
+    ]
+  ),
+  accumulation: createLightingWavefrontRecordContract(
+    "AccumulationRecord",
+    [
+      createLightingWavefrontField("sourcePixelId", "u32", "Source pixel/sample owner."),
+      createLightingWavefrontField("sampleCount", "u32", "Accumulated sample count."),
+      createLightingWavefrontField("radiance", "vec3<f32>", "Accumulated radiance."),
+      createLightingWavefrontField("throughput", "vec3<f32>", "Last surviving throughput."),
+      createLightingWavefrontField("resetEpoch", "u32", "Renderer accumulation reset epoch."),
+    ]
+  ),
+});
+
+export const lightingWavefrontTerminationPolicy = Object.freeze({
+  terminalHitTypes: lightingWavefrontTerminalHitTypes,
+  continuationHitTypes: lightingWavefrontContinuationHitTypes,
+  emissive: Object.freeze({
+    action: "accumulate-and-stop",
+    contributesRadiance: true,
+  }),
+  environment: Object.freeze({
+    action: "accumulate-and-stop",
+    contributesRadiance: true,
+  }),
+  miss: Object.freeze({
+    action: "accumulate-environment-or-dark-stop",
+    contributesRadiance: true,
+  }),
+});
+
+const defaultWavefrontDarkRadiance = Object.freeze([0.0001, 0.0001, 0.0001]);
+const wavefrontEventKinds = Object.freeze([
+  "diffuse",
+  "reflection",
+  "refraction",
+  "transparency",
+  "terminate",
+]);
+const wavefrontRayKindFlagMask = 0x3;
+const wavefrontRayKindFlagValues = Object.freeze({
+  path: 0,
+  "visibility-probe": 1,
+});
+
+function normalizeWavefrontRayKind(value) {
+  return lightingWavefrontRayKinds.includes(value) ? value : "path";
+}
+
+function normalizeWavefrontVisibilityProbeMode(value) {
+  return lightingWavefrontVisibilityProbeModes.includes(value)
+    ? value
+    : "disabled";
+}
+
+function normalizeWavefrontHitType(value) {
+  return lightingWavefrontHitTypes.includes(value) ? value : "surface";
+}
+
+function normalizeWavefrontEventKind(value) {
+  return wavefrontEventKinds.includes(value) ? value : null;
+}
+
+function normalizeVec3(value, fallback = [0, 0, 0]) {
+  if (!Array.isArray(value) || value.length < 3) {
+    return [...fallback];
+  }
+  return [
+    Number.isFinite(value[0]) ? value[0] : fallback[0],
+    Number.isFinite(value[1]) ? value[1] : fallback[1],
+    Number.isFinite(value[2]) ? value[2] : fallback[2],
+  ];
+}
+
+function clampUnit(value, fallback = 0) {
+  return Math.max(0, Math.min(1, readFinite(value, fallback)));
+}
+
+function saturateVec3(value) {
+  return value.map((component) => Math.max(0, component));
+}
+
+function scaleVec3(value, scalar) {
+  return value.map((component) => component * scalar);
+}
+
+function addVec3(left, right) {
+  return left.map((component, index) => component + right[index]);
+}
+
+function multiplyVec3(left, right) {
+  return left.map((component, index) => component * right[index]);
+}
+
+function dotVec3(left, right) {
+  return left[0] * right[0] + left[1] * right[1] + left[2] * right[2];
+}
+
+function lengthVec3(value) {
+  return Math.hypot(value[0], value[1], value[2]);
+}
+
+function normalizeDirection(value, fallback = [0, 1, 0]) {
+  const vector = normalizeVec3(value, fallback);
+  const length = lengthVec3(vector);
+  if (!Number.isFinite(length) || length <= 0.000001) {
+    return [...fallback];
+  }
+  return vector.map((component) => component / length);
+}
+
+function mixVec3(left, right, factor) {
+  return left.map((component, index) =>
+    component * (1 - factor) + right[index] * factor
+  );
+}
+
+function reflectDirection(direction, normal) {
+  const scale = 2 * dotVec3(direction, normal);
+  return normalizeDirection(
+    [
+      direction[0] - scale * normal[0],
+      direction[1] - scale * normal[1],
+      direction[2] - scale * normal[2],
+    ],
+    normal
+  );
+}
+
+function refractDirection(direction, normal, etaRatio) {
+  const cosTheta = Math.min(-dotVec3(direction, normal), 1);
+  const rOutPerp = scaleVec3(addVec3(direction, scaleVec3(normal, cosTheta)), etaRatio);
+  const rOutPerpLengthSquared = dotVec3(rOutPerp, rOutPerp);
+  const parallelFactor = 1 - rOutPerpLengthSquared;
+  if (parallelFactor <= 0) {
+    return null;
+  }
+  const rOutParallel = scaleVec3(normal, -Math.sqrt(parallelFactor));
+  return normalizeDirection(addVec3(rOutPerp, rOutParallel), direction);
+}
+
+function normalizeMediumRefId(value) {
+  const mediumRefId = Math.max(0, Math.trunc(readFinite(value, 0)));
+  return Number.isFinite(mediumRefId) ? mediumRefId : 0;
+}
+
+function normalizeMediumStack(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value
+    .map((entry) => normalizeMediumRefId(entry))
+    .filter((entry, index, stack) => entry > 0 && stack.indexOf(entry) === index)
+    .slice(0, 4);
+}
+
+function createWavefrontMediumStatePayload(currentMediumRefId, stack) {
+  const normalizedStack = normalizeMediumStack(stack);
+  const stackSlots = [0, 0, 0, 0];
+  normalizedStack.forEach((entry, index) => {
+    stackSlots[index] = entry;
+  });
+  return Object.freeze({
+    currentMediumRefId,
+    stackDepth: normalizedStack.length,
+    stack: Object.freeze(normalizedStack),
+    stackSlots: Object.freeze(stackSlots),
+  });
+}
+
+export function evaluateWavefrontMediumState(options = {}) {
+  const currentMediumRefId = normalizeMediumRefId(
+    options.currentMediumRefId ?? options.mediumRefId
+  );
+  const surfaceMediumRefId = normalizeMediumRefId(options.surfaceMediumRefId);
+  const stack = normalizeMediumStack(options.mediumStack);
+  const frontFace = options.frontFace !== false;
+  const eventKind =
+    normalizeWavefrontEventKind(options.eventKind) ?? "transparency";
+
+  if (
+    surfaceMediumRefId === 0 ||
+    (eventKind !== "refraction" && eventKind !== "transparency")
+  ) {
+    return Object.freeze({
+      ...createWavefrontMediumStatePayload(currentMediumRefId, stack),
+      enteredMediumRefId: 0,
+      exitedMediumRefId: 0,
+    });
+  }
+
+  let nextStack = [...stack];
+  let nextMediumRefId = currentMediumRefId;
+  let enteredMediumRefId = 0;
+  let exitedMediumRefId = 0;
+  const stackTop = nextStack.at(-1) ?? 0;
+
+  if (frontFace) {
+    if (stackTop !== surfaceMediumRefId) {
+      nextStack.push(surfaceMediumRefId);
+      nextStack = nextStack.slice(-4);
+    }
+    nextMediumRefId = surfaceMediumRefId;
+    enteredMediumRefId = surfaceMediumRefId;
+  } else if (stackTop === surfaceMediumRefId) {
+    nextStack.pop();
+    nextMediumRefId = nextStack.at(-1) ?? 0;
+    exitedMediumRefId = surfaceMediumRefId;
+  }
+
+  return Object.freeze({
+    ...createWavefrontMediumStatePayload(nextMediumRefId, nextStack),
+    enteredMediumRefId,
+    exitedMediumRefId,
+  });
+}
+
+function encodeWavefrontRayFlags(flags, rayKind) {
+  const normalizedFlags = Math.max(0, Math.trunc(readFinite(flags, 0)));
+  const rayKindValue = wavefrontRayKindFlagValues[rayKind];
+  return (normalizedFlags & ~wavefrontRayKindFlagMask) | rayKindValue;
+}
+
+export function createWavefrontRayPayload(options = {}) {
+  const rayKind = normalizeWavefrontRayKind(options.rayKind);
+  const mediumState = evaluateWavefrontMediumState({
+    currentMediumRefId: options.mediumRefId,
+    mediumStack: options.mediumStack,
+  });
+  const spectralState = Object.freeze(
+    normalizeVec3(options.spectralState, [550, 1, 0]).concat(
+      readFinite(options.spectralWeight, 0)
+    )
+  );
+  const mediumStack0 = Object.freeze([
+    mediumState.stackSlots[0],
+    mediumState.stackSlots[1],
+    mediumState.stackSlots[2],
+    mediumState.stackSlots[3],
+  ]);
+  const mediumStack1 = Object.freeze([0, 0, 0, 0]);
+  return Object.freeze({
+    rayId: Math.max(0, Math.trunc(readFinite(options.rayId, 0))),
+    parentRayId: Math.max(0, Math.trunc(readFinite(options.parentRayId, 0))),
+    sourcePixelId: Math.max(0, Math.trunc(readFinite(options.sourcePixelId, 0))),
+    sampleId: Math.max(0, Math.trunc(readFinite(options.sampleId, 0))),
+    bounce: Math.max(0, Math.trunc(readFinite(options.bounce, 0))),
+    origin: Object.freeze(normalizeVec3(options.origin, [0, 0, 0])),
+    direction: Object.freeze(normalizeDirection(options.direction, [0, 0, -1])),
+    throughput: Object.freeze(
+      saturateVec3(normalizeVec3(options.throughput, [1, 1, 1]))
+    ),
+    mediumRefId: mediumState.currentMediumRefId,
+    mediumStackDepth: mediumState.stackDepth,
+    mediumStack: mediumState.stack,
+    mediumStackSlots: mediumState.stackSlots,
+    mediumStack0,
+    mediumStack1,
+    spectralState,
+    rayKind,
+    flags: encodeWavefrontRayFlags(options.flags, rayKind),
+  });
+}
+
+export function createWavefrontVisibilityProbeRay(options = {}) {
+  return createWavefrontRayPayload({
+    ...options,
+    rayKind: "visibility-probe",
+  });
+}
+
+export function createWavefrontLightingPlan(options = {}) {
+  const maxDepth = Math.max(1, Math.trunc(readFinite(options.maxDepth, 4)));
+  const queueCapacity = Math.max(
+    1,
+    Math.trunc(readFinite(options.queueCapacity, 4096))
+  );
+  const explicitLightSampling = Boolean(options.explicitLightSampling);
+  const visibilityProbeMode = normalizeWavefrontVisibilityProbeMode(
+    options.visibilityProbeMode ??
+      (explicitLightSampling ? "mis-balanced" : "disabled")
+  );
+  const accumulationResetEpoch = Math.max(
+    0,
+    Math.trunc(readFinite(options.accumulationResetEpoch, 0))
+  );
+
+  return Object.freeze({
+    schemaVersion: lightingWavefrontSchemaVersion,
+    maxDepth,
+    queueCapacity,
+    explicitLightSampling,
+    visibilityProbeMode,
+    rayKinds: lightingWavefrontRayKinds,
+    accumulationResetEpoch,
+    queueLayout: Object.freeze({
+      strategy: lightingWavefrontQueuePairStrategy,
+      compactAfterScatter: true,
+      queues: Object.freeze([
+        Object.freeze({ name: "active", role: "current-bounce" }),
+        Object.freeze({ name: "next", role: "next-bounce" }),
+      ]),
+    }),
+    bufferContracts: lightingWavefrontBufferContracts,
+    terminationPolicy: lightingWavefrontTerminationPolicy,
+    requiredRendererPassOrder: lightingRequiredRendererWavefrontPassOrder,
+    lightingPasses: Object.freeze([
+      Object.freeze({
+        key: "accumulateTerminalRadiance",
+        stage: "accumulateTerminalRadiance",
+        reads: Object.freeze([
+          "ray",
+          "hit",
+          "surface",
+          "materialReference",
+          "mediumReference",
+        ]),
+        writes: Object.freeze(["accumulation"]),
+        terminalHitTypes: lightingWavefrontTerminalHitTypes,
+      }),
+      Object.freeze({
+        key: "scatterContinuations",
+        stage: "scatterContinuations",
+        reads: Object.freeze([
+          "ray",
+          "hit",
+          "surface",
+          "materialReference",
+          "mediumReference",
+        ]),
+        writes: Object.freeze(["ray"]),
+        continuationHitTypes: lightingWavefrontContinuationHitTypes,
+        explicitLightSampling,
+        visibilityProbeMode,
+      }),
+    ]),
+  });
+}
+
+export function evaluateWavefrontTerminalRadiance(options = {}) {
+  const hitType = normalizeWavefrontHitType(options.hitType);
+  const throughput = saturateVec3(normalizeVec3(options.throughput, [1, 1, 1]));
+  const emission = saturateVec3(normalizeVec3(options.emission, [0, 0, 0]));
+  const environmentRadiance = saturateVec3(
+    normalizeVec3(options.environmentRadiance, [0, 0, 0])
+  );
+  const missRadiance = saturateVec3(
+    normalizeVec3(options.missRadiance, defaultWavefrontDarkRadiance)
+  );
+  const environmentLuminance = colorLuminance(environmentRadiance);
+  let source = "none";
+  let rawRadiance = [0, 0, 0];
+
+  if (hitType === "emissive") {
+    source = "emissive";
+    rawRadiance = emission;
+  } else if (hitType === "environment") {
+    source = "environment";
+    rawRadiance = environmentRadiance;
+  } else if (hitType === "miss") {
+    source = environmentLuminance > 0.000001 ? "environment" : "dark";
+    rawRadiance = environmentLuminance > 0.000001 ? environmentRadiance : missRadiance;
+  }
+
+  const radiance = multiplyVec3(throughput, rawRadiance);
+  const terminated = lightingWavefrontTerminalHitTypes.includes(hitType);
+
+  return Object.freeze({
+    hitType,
+    source,
+    terminated,
+    radiance: Object.freeze(radiance),
+    nearDarkSample:
+      source === "dark" && colorLuminance(radiance) <= colorLuminance(defaultWavefrontDarkRadiance),
+  });
+}
+
+export function evaluateWavefrontContinuationEvent(options = {}) {
+  const hitType = normalizeWavefrontHitType(options.hitType);
+  const bounceIndex = Math.max(0, Math.trunc(readFinite(options.bounceIndex, 0)));
+  const maxDepth = Math.max(1, Math.trunc(readFinite(options.maxDepth, 4)));
+  const throughput = saturateVec3(normalizeVec3(options.throughput, [1, 1, 1]));
+  const albedo = saturateVec3(normalizeVec3(options.albedo, [0.8, 0.8, 0.8]));
+  const transmission = saturateVec3(
+    normalizeVec3(options.transmission, [0, 0, 0])
+  );
+  const shadingNormal = normalizeDirection(options.shadingNormal, [0, 1, 0]);
+  const viewDirection = normalizeDirection(options.viewDirection, [0, 0, 1]);
+  const incomingDirection = normalizeDirection(
+    scaleVec3(viewDirection, -1),
+    [0, 0, -1]
+  );
+  const frontFace = options.frontFace !== false;
+  const orientedNormal = frontFace
+    ? shadingNormal
+    : scaleVec3(shadingNormal, -1);
+  const metalness = clampUnit(options.metalness, 0);
+  const roughness = clampUnit(options.roughness, 0.5);
+  const opacity = clampUnit(options.opacity, 1);
+  const refractiveIndex = Math.max(1, readFinite(options.refractiveIndex ?? options.ior, 1.45));
+  const transmissionStrength = Math.max(...transmission);
+  const requestedEventKind =
+    normalizeWavefrontEventKind(options.eventKind) ??
+    (hitType === "transparent" || opacity < 0.999
+      ? "transparency"
+      : transmissionStrength > 0.001
+        ? "refraction"
+        : metalness >= 0.5 || roughness <= 0.2
+          ? "reflection"
+          : "diffuse");
+  let eventKind = requestedEventKind;
+  let totalInternalReflection = false;
+
+  let nextDirection = incomingDirection;
+  let attenuation;
+
+  if (!lightingWavefrontContinuationHitTypes.includes(hitType) || bounceIndex >= maxDepth - 1) {
+    eventKind = "terminate";
+    attenuation = [0, 0, 0];
+  } else if (eventKind === "reflection") {
+    nextDirection = reflectDirection(incomingDirection, orientedNormal);
+    attenuation = mixVec3([0.04, 0.04, 0.04], albedo, metalness);
+  } else if (eventKind === "refraction") {
+    const etaRatio = frontFace ? 1 / refractiveIndex : refractiveIndex;
+    const refractedDirection = refractDirection(
+      incomingDirection,
+      orientedNormal,
+      etaRatio
+    );
+    if (refractedDirection) {
+      nextDirection = refractedDirection;
+      attenuation = transmissionStrength > 0.001 ? transmission : [1, 1, 1];
+    } else {
+      totalInternalReflection = true;
+      eventKind = "reflection";
+      nextDirection = reflectDirection(incomingDirection, orientedNormal);
+      attenuation = mixVec3([0.04, 0.04, 0.04], albedo, metalness);
+    }
+  } else if (eventKind === "transparency") {
+    nextDirection = incomingDirection;
+    const transparencyWeight = Math.max(1 - opacity, transmissionStrength, 0.05);
+    attenuation = transmissionStrength > 0.001
+      ? transmission
+      : [transparencyWeight, transparencyWeight, transparencyWeight];
+  } else {
+    nextDirection = normalizeDirection(
+      addVec3(orientedNormal, albedo.map((component) => component - 0.5)),
+      orientedNormal
+    );
+    attenuation = scaleVec3(albedo, Math.max(0.05, 1 - metalness));
+  }
+
+  const nextThroughput = multiplyVec3(throughput, saturateVec3(attenuation));
+  const continueTracing =
+    eventKind !== "terminate" && colorLuminance(nextThroughput) > 0.0001;
+  const mediumState = evaluateWavefrontMediumState({
+    currentMediumRefId: options.currentMediumRefId ?? options.mediumRefId,
+    surfaceMediumRefId: options.surfaceMediumRefId,
+    mediumStack: options.mediumStack,
+    frontFace,
+    eventKind,
+  });
+
+  return Object.freeze({
+    hitType,
+    requestedEventKind,
+    eventKind,
+    continueTracing,
+    totalInternalReflection,
+    nextDirection: Object.freeze(nextDirection),
+    attenuation: Object.freeze(saturateVec3(attenuation)),
+    nextThroughput: Object.freeze(nextThroughput),
+    mediumState,
+    explicitLightSamplingEnabled: Boolean(options.explicitLightSampling),
+  });
+}
+
+export function evaluateWavefrontVisibilityProbe(options = {}) {
+  const probeMode = normalizeWavefrontVisibilityProbeMode(
+    options.probeMode ??
+      (options.explicitLightSampling ? "mis-balanced" : "disabled")
+  );
+  const probeRay = createWavefrontVisibilityProbeRay({
+    ...options.probeRay,
+    throughput: options.throughput ?? options.probeRay?.throughput,
+    direction: options.direction ?? options.probeRay?.direction,
+    mediumRefId: options.currentMediumRefId ?? options.probeRay?.mediumRefId,
+    mediumStack: options.mediumStack ?? options.probeRay?.mediumStack,
+  });
+  const transparentSegments = Array.isArray(options.transparentSegments)
+    ? options.transparentSegments
+    : [];
+  const transmittance = transparentSegments.reduce(
+    (current, segment) =>
+      multiplyVec3(current, saturateVec3(normalizeVec3(segment, [1, 1, 1]))),
+    [1, 1, 1]
+  );
+  const emissiveRadiance = saturateVec3(
+    normalizeVec3(options.emissiveRadiance, [0, 0, 0])
+  );
+  const environmentRadiance = saturateVec3(
+    normalizeVec3(options.environmentRadiance, [0, 0, 0])
+  );
+  const activeEmissiveRadiance = saturateVec3(
+    normalizeVec3(options.activeEmissiveRadiance, [0, 0, 0])
+  );
+  const prefersEnvironment = Boolean(options.prefersEnvironment);
+  const sourceRadiance =
+    prefersEnvironment || colorLuminance(emissiveRadiance) <= 0.000001
+      ? environmentRadiance
+      : emissiveRadiance;
+  const rawContribution = multiplyVec3(
+    probeRay.throughput,
+    multiplyVec3(sourceRadiance, transmittance)
+  );
+  const activeEmissiveVisible =
+    colorLuminance(activeEmissiveRadiance) > 0.000001;
+  const misWeight =
+    probeMode === "mis-balanced" && activeEmissiveVisible ? 0.5 : 1;
+  const contribution =
+    probeMode === "exclusive-emissive" && activeEmissiveVisible
+      ? [0, 0, 0]
+      : scaleVec3(rawContribution, misWeight);
+
+  return Object.freeze({
+    probeMode,
+    probeRay,
+    transmittance: Object.freeze(transmittance),
+    misWeight,
+    doubleCountPrevented:
+      activeEmissiveVisible && probeMode !== "disabled",
+    contribution: Object.freeze(contribution),
+  });
+}
+
+export function evaluateWavefrontMaterialReference(options = {}) {
+  const material = Object.freeze({
+    albedo: Object.freeze(
+      saturateVec3(normalizeVec3(options.albedo, [0.8, 0.8, 0.8]))
+    ),
+    emission: Object.freeze(
+      saturateVec3(normalizeVec3(options.emission, [0, 0, 0]))
+    ),
+    roughness: clampUnit(options.roughness, 0.5),
+    metalness: clampUnit(options.metalness, 0),
+    opacity: clampUnit(options.opacity, 1),
+    transmission: Object.freeze(
+      saturateVec3(normalizeVec3(options.transmission, [0, 0, 0]))
+    ),
+    refractiveIndex: Math.max(
+      1,
+      readFinite(options.refractiveIndex ?? options.ior, 1.45)
+    ),
+  });
+  const continuation = evaluateWavefrontContinuationEvent({
+    ...options,
+    albedo: material.albedo,
+    roughness: material.roughness,
+    metalness: material.metalness,
+    opacity: material.opacity,
+    transmission: material.transmission,
+    refractiveIndex: material.refractiveIndex,
+  });
+  const terminal = evaluateWavefrontTerminalRadiance({
+    ...options,
+    emission: material.emission,
+  });
+
+  return Object.freeze({
+    material,
+    terminal,
+    continuation,
+    throughputUpdate: continuation.nextThroughput,
+  });
+}
+
+export function createWavefrontReferenceFixture(options = {}) {
+  const tolerance = Math.max(0.0001, readFinite(options.tolerance, 0.0005));
+  const ray = createWavefrontRayPayload({
+    rayId: options.rayId,
+    parentRayId: options.parentRayId,
+    sourcePixelId: options.sourcePixelId,
+    sampleId: options.sampleId,
+    bounce: options.bounceIndex ?? options.bounce,
+    origin: options.origin,
+    direction: options.direction ?? scaleVec3(options.viewDirection ?? [0, 0, 1], -1),
+    throughput: options.throughput,
+    mediumRefId: options.currentMediumRefId ?? options.mediumRefId,
+    mediumStack: options.mediumStack,
+  });
+  const reference = evaluateWavefrontMaterialReference(options);
+  const visibilityProbe =
+    options.visibilityProbe === undefined
+      ? null
+      : evaluateWavefrontVisibilityProbe({
+          ...options.visibilityProbe,
+          throughput: options.visibilityProbe.throughput ?? ray.throughput,
+        });
+  const accumulationRadiance = addVec3(
+    reference.terminal.radiance,
+    visibilityProbe?.contribution ?? [0, 0, 0]
+  );
+
+  return Object.freeze({
+    tolerance,
+    ray,
+    material: reference.material,
+    continuation: reference.continuation,
+    terminal: reference.terminal,
+    visibilityProbe,
+    accumulation: Object.freeze({
+      sourcePixelId: ray.sourcePixelId,
+      sampleCount: reference.terminal.terminated ? 1 : 0,
+      radiance: Object.freeze(accumulationRadiance),
+      throughput: reference.continuation.nextThroughput,
+      resetEpoch: Math.max(
+        0,
+        Math.trunc(readFinite(options.accumulationResetEpoch, 0))
+      ),
+    }),
+  });
+}
+
 const lightingImportanceLevels = Object.freeze([
   "low",
   "medium",
@@ -1725,6 +2503,91 @@ const lightingWorkerSpecPresets = {
       },
     },
   },
+  wavefront: {
+    suggestedAllocationIds: [
+      "lighting.wavefront.active-queue",
+      "lighting.wavefront.next-queue",
+      "lighting.wavefront.accumulation",
+    ],
+    jobs: {
+      accumulateTerminalRadiance: {
+        domain: "lighting",
+        importance: "critical",
+        levels: buildWorkerBudgetLevels(
+          "lighting.wavefront.accumulateTerminalRadiance",
+          lightingWorkerQueueClass,
+          {
+            low: {
+              estimatedCostMs: 0.7,
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 32,
+              cadenceDivisor: 2,
+              workgroupScale: 0.5,
+              maxQueueDepth: 96,
+            },
+            medium: {
+              estimatedCostMs: 1.2,
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 64,
+              cadenceDivisor: 1,
+              workgroupScale: 0.75,
+              maxQueueDepth: 192,
+            },
+            high: {
+              estimatedCostMs: 1.8,
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 128,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 256,
+            },
+          }
+        ),
+        suggestedAllocationIds: [
+          "lighting.wavefront.accumulation",
+          "lighting.wavefront.active-queue",
+        ],
+      },
+      scatterContinuations: {
+        domain: "lighting",
+        importance: "critical",
+        levels: buildWorkerBudgetLevels(
+          "lighting.wavefront.scatterContinuations",
+          lightingWorkerQueueClass,
+          {
+            low: {
+              estimatedCostMs: 0.8,
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 32,
+              cadenceDivisor: 2,
+              workgroupScale: 0.5,
+              maxQueueDepth: 96,
+            },
+            medium: {
+              estimatedCostMs: 1.4,
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 64,
+              cadenceDivisor: 1,
+              workgroupScale: 0.75,
+              maxQueueDepth: 192,
+            },
+            high: {
+              estimatedCostMs: 2.1,
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 128,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 256,
+            },
+          }
+        ),
+        suggestedAllocationIds: [
+          "lighting.wavefront.active-queue",
+          "lighting.wavefront.next-queue",
+        ],
+      },
+    },
+  },
   volumetrics: {
     suggestedAllocationIds: [
       "lighting.volumetrics.froxel-grid",
@@ -1935,6 +2798,13 @@ const lightingWorkerDagSpecs = {
     accumulate: { priority: 3, dependencies: ["pathTrace"] },
     denoise: { priority: 2, dependencies: ["accumulate"] },
   },
+  wavefront: {
+    accumulateTerminalRadiance: { priority: 3, dependencies: [] },
+    scatterContinuations: {
+      priority: 2,
+      dependencies: ["accumulateTerminalRadiance"],
+    },
+  },
   volumetrics: {
     volumetricShadow: { priority: 3, dependencies: [] },
     froxelIntegrate: { priority: 2, dependencies: ["volumetricShadow"] },
@@ -1969,6 +2839,16 @@ function resolveLightingQualityDimensions(techniqueName, jobKey) {
       "pathtracer.pathTrace": { rayTracing: 1, lightingSamples: 1 },
       "pathtracer.accumulate": { temporalReuse: 1, updateCadence: 0.4 },
       "pathtracer.denoise": { temporalReuse: 1, shading: 0.4 },
+      "wavefront.accumulateTerminalRadiance": {
+        rayTracing: 1,
+        lightingSamples: 1,
+        temporalReuse: 0.4,
+      },
+      "wavefront.scatterContinuations": {
+        rayTracing: 1,
+        shading: 0.7,
+        updateCadence: 0.5,
+      },
       "volumetrics.froxelIntegrate": {
         lightingSamples: 0.6,
         shading: 0.4,
@@ -2014,6 +2894,15 @@ function resolveLightingImportanceSignals(techniqueName, jobKey) {
       },
       "pathtracer.accumulate": { visible: true },
       "pathtracer.denoise": { visible: true },
+      "wavefront.accumulateTerminalRadiance": {
+        visible: true,
+        shadowSignificance: "high",
+        reflectionSignificance: "high",
+      },
+      "wavefront.scatterContinuations": {
+        visible: true,
+        reflectionSignificance: "high",
+      },
       "volumetrics.froxelIntegrate": { visible: true },
       "volumetrics.volumetricShadow": { visible: true, shadowSignificance: "high" },
       "hdri.irradianceConvolution": { visible: false },