Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion FORMAT-v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ Total size: **336 bytes** (`21 × 16 B`), alignment: **16 bytes**.
| `308` | `4` | `4` | `u32` | `portal_count` | Light portals stored after the `light_count` emitters in the light table (section 6); `0` for none |
| `312` | `8` | `8` | `vec2<u32>` | `tile_origin` | Pixel origin `[x, y]` of the tile one dispatch covers. The packer writes `[0, 0]`; the host writes it for every dispatch (zero when the frame is not split), so whatever a pack carries here never shifts the picture. `dispatchBudgetMs` splits a frame into tiles; the kernel adds the origin to the global invocation id |
| `320` | `4` | `4` | `f32` | `aperture_ratio` | Anamorphic bokeh: the width of the aperture over its height (Cycles `aperture_ratio`). The kernel multiplies the lens sample's x by `1 / aperture_ratio`; the packer writes `1.0` by default and accepts `0.01` to `100`; a block with `0.0` here is read as `1.0` |
| `324` | `4` | `4` | `u32` | `reserved_aperture_0` | Reserved (`0`), pads the block to a multiple of 16 bytes |
| `324` | `4` | `4` | `u32` | `caustic_photons` | Light paths traced from the emitters per pixel sample (`1` to `64`) while the `kernel_flags` bit `8192=CAUSTIC_LIGHT_TRACING` is set, `0` otherwise. A word of an older block is `0`, so it renders as before. See "Caustic light tracing" in the README |
| `328` | `4` | `4` | `u32` | `reserved_aperture_1` | Reserved (`0`) |
| `332` | `4` | `4` | `u32` | `reserved_aperture_2` | Reserved (`0`) |

Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,8 @@ A rect area light with `portal: true` is a light portal, as in Cycles: it emits

Cook's `cycles` kernel samples with Cycles' Sobol-Burley blue-noise pattern (`sampler: 'sobol-burley'`, default; `'white'` keeps the earlier hash sampler, and `'pcg'` and `'sobol'` are other names for `'white'` and `'sobol-burley'`). It picks lights through the Cycles light tree over the analytic lights, a sun and the emissive triangles (`lightSampling: 'auto'`, default: tree from more than one emitter; `'tree'`; `'uniform'` for the flat pick, and `useLightTree: true|false` is another name for `'tree'|'uniform'`). Naming an option twice with different values is an error. `envCompensation: true` (a fraction from 0 to 1 also works; off by default) subtracts the mean radiance from the environment sampling table so light sampling covers only the bright part of the map, which lowers the error under a sunny HDRI. The pixel filter is `box` unless `filterType` says otherwise. Details and measurements: [docs/cycles-parity.md](https://github.com/codepawl/crucible/blob/main/docs/cycles-parity.md), layout: [FORMAT-v2.md](./FORMAT-v2.md).

`caustics: "light-tracing"` (a packing option, off by default; `causticPhotons`, 1 to 64, default 1, sets the light paths per pixel sample) renders what a small light does through glass onto a diffuse surface, such as the rainbow of a prism, which camera paths find too rarely to be anything but speckle. Paths start on the emissive triangles, follow only smooth glass and mirror bounces (dispersion included, with the hero wavelength of the path), and at the first rough or diffuse hit, after at least one such bounce through a solid (not thin-walled) surface, are joined to the pinhole camera with a visibility ray and splatted into the image. The camera paths drop the same light (a diffuse vertex, then a smooth bounce, then an emitter), so nothing counts twice; the two are not combined by MIS. Limits: emissive triangles only (analytic lights and the environment are not light traced), a pinhole (no depth of field in the caustic, no `orthographic`), no `noiseThreshold`, and a caustic seen through glass is not joined. `filterGlossy` does not blur a smooth glass or mirror lobe while it is on (the light paths follow those lobes exactly, and a blurred camera-path copy of the caustic would count twice). Every count is bounded and an option the kernel cannot use throws with what to pass. With the option off the kernel is compiled without any of this and renders the same pixels as before.

`shadowRayPick: "contribution"` (a packing option; the default `"all"` keeps one shadow ray per light sample) traces one shadow ray per vertex: the light tree sample and the environment sample are both evaluated without a shadow ray, one is picked in proportion to the luminance of its unshadowed contribution, and its value is divided by the probability of the pick. The mean is the same; the noise and the time per sample are being measured, so it stays off.

Four more options of the `cycles` kernel; `pathRegeneration` is on by default, the other three are off:
Expand Down
50 changes: 50 additions & 0 deletions pack-input-v2.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,14 @@ export const KERNEL_FLAG_PATH_REGENERATION = 1024;
/** Set when any texture of the pool stores mip levels; the kernel then carries a ray footprint (see FORMAT-v2.md). */
export const KERNEL_FLAG_TEXTURE_MIPS = 2048;
export const KERNEL_FLAG_SHADOW_RAY_PICK = 4096;
/** Set by `caustics: "light-tracing"`: see `KERNEL_FLAG_CAUSTIC_LIGHT_TRACING` in abi.wgsl. */
export const KERNEL_FLAG_CAUSTIC_LIGHT_TRACING = 8192;
/** `caustics` values: "off" (default) or "light-tracing" (paths from the emitters through glass, connected to the camera). */
export const VALID_CAUSTICS = Object.freeze(['off', 'light-tracing']);
export const MAX_CAUSTIC_PHOTONS = 64;
export const DEFAULT_CAUSTIC_PHOTONS = 1;
/** Byte offset of `caustic_photons` inside a `KernelParamsV2` buffer (the first word after `aperture_ratio`). */
export const KERNEL_PARAMS_V2_CAUSTIC_PHOTONS_BYTE_OFFSET = 324;

/** `flags` of a material extension record: the diffuse transmission colour multiplies the base colour. */
const MATERIAL_EXTENSION_FLAG_TINTS_BASE_COLOR = 1;
Expand Down Expand Up @@ -2194,6 +2202,41 @@ export function validateShadowRayPickOption(shadowRayPick, callerName) {
}
}

/**
* Throws unless `caustics` is undefined, "off" or "light-tracing", and `causticPhotons` is a whole number from 1 to 64 that comes
* with "light-tracing". Light tracing needs a perspective camera and fixed sampling (no `noiseThreshold`), which it names.
*/
export function validateCausticsOptions(options, callerName) {
const { caustics, causticPhotons } = options;
if (caustics !== undefined && !VALID_CAUSTICS.includes(caustics)) {
throw new RangeError(
`${callerName}: \`caustics\` must be "off" (default) or "light-tracing" (paths from the emitters through glass, connected to the camera), got ${JSON.stringify(caustics)}.`
);
}
if (causticPhotons !== undefined) {
if (!Number.isInteger(causticPhotons) || causticPhotons < 1 || causticPhotons > MAX_CAUSTIC_PHOTONS) {
throw new RangeError(
`${callerName}: \`causticPhotons\` must be a whole number from 1 to ${MAX_CAUSTIC_PHOTONS} (light paths per pixel sample), got ${JSON.stringify(causticPhotons)}.`
);
}
if (caustics !== 'light-tracing') {
throw new RangeError(
`${callerName}: \`causticPhotons\` only applies with \`caustics: "light-tracing"\`; pass that option or remove \`causticPhotons\`.`
);
}
}
if (caustics !== 'light-tracing') {
return;
}
if (options.orthographic === true) {
throw new RangeError(`${callerName}: \`caustics: "light-tracing"\` connects light paths to a pinhole camera and does not support \`orthographic: true\`; use a perspective camera or remove \`caustics\`.`);
}
const adaptiveThreshold = Number(options.noiseThreshold ?? options.adaptiveThreshold ?? 0);
if (adaptiveThreshold > 0) {
throw new RangeError(`${callerName}: \`caustics: "light-tracing"\` splats photons over the whole image, so a pixel cannot stop early; remove \`noiseThreshold\`/\`adaptiveThreshold\` or \`caustics\`.`);
}
}

export function validatePackOptions(options, callerName, requireDimensionsAndSamples = false) {
if (!options || typeof options !== 'object') {
throw new TypeError(`${callerName}: \`options\` must be an object.`);
Expand All @@ -2215,6 +2258,7 @@ export function validatePackOptions(options, callerName, requireDimensionsAndSam
resolveSamplingOptions(options, callerName);
resolveEnvCompensationFraction(options.envCompensation, callerName);
validateShadowRayPickOption(options.shadowRayPick, callerName);
validateCausticsOptions(options, callerName);
validateDenoiseOption(options.denoise, callerName);
validateTextureMipsOption(options.textureMips, 'textureMips', callerName);
validateFilterOptions(options, callerName);
Expand Down Expand Up @@ -2652,6 +2696,11 @@ function packKernelParamsV2({
if (options.shadowRayPick === 'contribution') {
kernelFlags |= KERNEL_FLAG_SHADOW_RAY_PICK;
}
validateCausticsOptions(options, 'packKernelParamsV2');
const causticPhotons = options.caustics === 'light-tracing' ? (options.causticPhotons ?? DEFAULT_CAUSTIC_PHOTONS) : 0;
if (causticPhotons > 0) {
kernelFlags |= KERNEL_FLAG_CAUSTIC_LIGHT_TRACING;
}

const maxBounces = Math.max(0, Math.round(Number(options.bounces ?? options.maxBounces ?? 8)));
const maxDiffuseBounces = Math.max(0, Math.round(Number(options.diffuseBounces ?? maxBounces)));
Expand Down Expand Up @@ -2747,6 +2796,7 @@ function packKernelParamsV2({
u32[77] = (counts.portalCount ?? 0) >>> 0;
u32[78] = 0;
u32[79] = 0;
u32[KERNEL_PARAMS_V2_CAUSTIC_PHOTONS_BYTE_OFFSET / 4] = causticPhotons >>> 0;

return new Uint8Array(buffer);
}
Expand Down
14 changes: 13 additions & 1 deletion src/cycles/abi.wgsl
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ const BINDING_TEXTURE_DESCRIPTORS: u32 = 8u;
const BINDING_TEXTURE_TEXELS: u32 = 9u;
const BINDING_ENVIRONMENT_TEXELS: u32 = 10u;
const BINDING_FILM_ACCUMULATION: u32 = 11u;
const BINDING_CAUSTIC_SPLAT: u32 = 15u;

// `KernelParamsV2.kernel_flags` bits.
const KERNEL_FLAG_USE_LIGHT_TREE: u32 = 1u;
Expand All @@ -56,6 +57,12 @@ const KERNEL_FLAG_TEXTURE_MIPS: u32 = 2048u;
// Set: each vertex traces one shadow ray for one of its direct light samples, picked in proportion to the luminance of the unshadowed
// contribution, instead of one ray per sample. Same mean, fewer rays. Clear (default): every direct sample gets its own shadow ray.
const KERNEL_FLAG_SHADOW_RAY_PICK: u32 = 4096u;
// Set (`caustics: "light-tracing"`): paths also start on the emissive triangles, follow only smooth glass and mirror bounces, and from
// the first diffuse hit after at least one such bounce are connected to the pinhole camera and splatted into `caustic_splat`
// (`KernelParamsV2.caustic_photons` paths per pixel sample). The camera paths then drop the same light: a path that leaves a diffuse
// vertex, crosses a smooth glass or mirror bounce and reaches an emitter counts nothing. Clear (default): none of this exists in the
// compiled kernel (the host sets `FRAME_HAS_CAUSTIC_LIGHT_TRACING` to false), so the image is the one without the option, bit for bit.
const KERNEL_FLAG_CAUSTIC_LIGHT_TRACING: u32 = 8192u;

// `KernelParamsV2.filter_type` values.
const FILTER_BOX: u32 = 0u;
Expand Down Expand Up @@ -148,6 +155,8 @@ const SCENE_HAS_FINITE_LIGHTS: bool = true;
const SCENE_HAS_ENV_IMPORTANCE: bool = true;
const SCENE_HAS_LIGHT_LINKING: bool = true;
const SCENE_HAS_LIGHT_TREE: bool = true;
// Frame setting, not scene: false unless the frame's `kernel_flags` carry KERNEL_FLAG_CAUSTIC_LIGHT_TRACING. `true` is the safe default.
const FRAME_HAS_CAUSTIC_LIGHT_TRACING: bool = true;
const LOBE_NONE: u32 = 0u;
const LOBE_DIFFUSE: u32 = 1u;
const LOBE_GLOSSY_GGX: u32 = 2u;
Expand Down Expand Up @@ -251,7 +260,8 @@ struct KernelParamsV2 {

// Anamorphic bokeh: the aperture width over its height (Cycles `aperture_ratio`); `0.0` is read as `1.0`.
aperture_ratio: f32,
reserved_aperture_0: u32,
// Light paths traced per pixel sample when KERNEL_FLAG_CAUSTIC_LIGHT_TRACING is set (1 to 64); `0` otherwise.
caustic_photons: u32,
reserved_aperture_1: u32,
reserved_aperture_2: u32,
}
Expand Down Expand Up @@ -599,6 +609,8 @@ struct ClosureSample {
@group(0) @binding(12) var<storage, read> cycles_lut: array<u32>;
@group(0) @binding(13) var<storage, read> light_tree_emitters: array<LightTreeEmitter>;
@group(0) @binding(14) var<storage, read> light_to_tree: array<u32>;
// Caustic light tracing: four u32 per pixel (red, green, blue, unused), fixed point with `LT_FIXED_POINT_SCALE`, summed with atomicAdd.
@group(0) @binding(15) var<storage, read_write> caustic_splat: array<atomic<u32>>;

// ---------------------------------------------------------------------------------------------------------------------
// Cross-lane closure interface contract (defined in Lane L4 `src/cycles/closure.wgsl`, called by Lane L3 integrator)
Expand Down
Loading