3D engine that AI agents drive
Add opt-in texture mip levels to the cycles kernel: chains in the packer, ray cone level choice in the kernel (#896)
Nguyen Xuan An3d3e576bd27e
diff --git a/bench/cycles-parity/make-texture-mips-figure.py b/bench/cycles-parity/make-texture-mips-figure.pynew file mode 100644index 00000000..3295abea--- /dev/null+++ b/bench/cycles-parity/make-texture-mips-figure.py@@ -0,0 +1,61 @@+"""Three panels of the minified checker floor of texture-mips-bench.mjs: mip levels off, on, and the converged reference.++ uv run --no-project --with numpy --with pillow python bench/cycles-parity/make-texture-mips-figure.py <benchDirectory> <output.jpg> [--samples 16]+"""+import json+import sys+from pathlib import Path++import numpy as np+from PIL import Image, ImageDraw++PANEL_SCALE = 1+LABEL_PADDING = 6+++def linear_to_srgb_bytes(linear_rgb: np.ndarray) -> np.ndarray:+ clipped = np.clip(linear_rgb, 0.0, 1.0)+ encoded = np.where(clipped <= 0.0031308, clipped * 12.92, 1.055 * np.power(clipped, 1 / 2.4) - 0.055)+ return np.round(encoded * 255).astype(np.uint8)+++def load_picture(path: Path, width: int, height: int) -> np.ndarray:+ return np.fromfile(path, dtype="<f4").reshape(height, width, 3)+++def panel(picture: np.ndarray, label: str) -> Image.Image:+ image = Image.fromarray(linear_to_srgb_bytes(picture)).resize(+ (picture.shape[1] * PANEL_SCALE, picture.shape[0] * PANEL_SCALE), Image.NEAREST+ )+ draw = ImageDraw.Draw(image)+ text_box = draw.textbbox((LABEL_PADDING, LABEL_PADDING), label)+ draw.rectangle((text_box[0] - 3, text_box[1] - 2, text_box[2] + 3, text_box[3] + 2), fill=(0, 0, 0))+ draw.text((LABEL_PADDING, LABEL_PADDING), label, fill=(255, 255, 255))+ return image+++def main() -> None:+ bench_directory = Path(sys.argv[1])+ output_path = Path(sys.argv[2])+ samples = int(sys.argv[sys.argv.index("--samples") + 1]) if "--samples" in sys.argv else 16+ metrics = json.loads((bench_directory / "metrics.json").read_text())+ width, height = metrics["width"], metrics["height"]+ run = next(entry for entry in metrics["receding"]["runs"] if entry["samples"] == samples)+ panels = [+ panel(load_picture(bench_directory / f"receding-off-{samples}spp.f32", width, height), f"mips off, {samples} spp, relMSE {run['relMseOffPerSeed'][0]:.4f}"),+ panel(load_picture(bench_directory / f"receding-on-{samples}spp.f32", width, height), f"mips on, {samples} spp, relMSE {run['relMseOnPerSeed'][0]:.4f}"),+ panel(load_picture(bench_directory / "receding-reference.f32", width, height), f"reference, {metrics['receding']['referenceSamples']} spp, mips off"),+ ]+ gap = 4+ sheet = Image.new("RGB", (sum(p.width for p in panels) + gap * (len(panels) - 1), panels[0].height), (255, 255, 255))+ cursor = 0+ for each in panels:+ sheet.paste(each, (cursor, 0))+ cursor += each.width + gap+ output_path.parent.mkdir(parents=True, exist_ok=True)+ sheet.save(output_path, "JPEG", quality=86, optimize=True)+ print(output_path, sheet.size, output_path.stat().st_size, "bytes")+++if __name__ == "__main__":+ main()diff --git a/bench/cycles-parity/texture-mips-bench.mjs b/bench/cycles-parity/texture-mips-bench.mjsnew file mode 100644index 00000000..35938aca--- /dev/null+++ b/bench/cycles-parity/texture-mips-bench.mjs@@ -0,0 +1,154 @@+// Does a mip chain lower the error of a minified texture at low sample counts, and leave a magnified one alone? (#896)+// node bench/cycles-parity/texture-mips-bench.mjs <outputDirectory> [--width 320] [--height 180] [--seeds 3] [--reference-samples 2048]+//+// The scene is a fine checker on a floor that runs to the horizon, lit by a uniform sky. It is traced with level 0 only and with+// mip levels, at 16 and 64 samples per pixel, and each picture is scored against a level 0 picture of the same scene at the+// reference sample count. relMSE is the mean squared difference over the rows below the horizon over the mean squared reference value there. A+// second camera looks down at the floor from 30 cm, where one texel covers many pixels: mip levels must change nothing there.+// Writes one .f32 file (float32 rgb, rows from the top) per picture and metrics.json.+import { mkdir, writeFile } from 'node:fs/promises';+import { join, resolve } from 'node:path';+import { pathToFileURL } from 'node:url';+import { buildNativeInputV2, traceNative } from '../../packages/render-native/index.mjs';+import { createCamera } from '../../src/path-tracer.js';++export const CHECKER_SIDE = 64;+export const CHECKER_CELL = 4;+const FLOOR_UV_PER_METRE = 0.5;+const SKY_RADIANCE = [0.8, 0.8, 0.8];+const SAMPLE_COUNTS = [16, 64];++export const CAMERAS = Object.freeze({+ receding: { eye: [0, 1.5, 6], target: [0, 1.3, -20], fov: 50 },+ magnified: { eye: [0, 0.3, 0.12], target: [0, 0, 0], fov: 30 },+});++export function checkerImage() {+ const data = new Uint8Array(CHECKER_SIDE * CHECKER_SIDE * 4);+ for (let row = 0; row < CHECKER_SIDE; row++) {+ for (let column = 0; column < CHECKER_SIDE; column++) {+ const isLight = ((Math.floor(column / CHECKER_CELL) + Math.floor(row / CHECKER_CELL)) & 1) === 0;+ data.set(isLight ? [220, 220, 220, 255] : [30, 30, 30, 255], (row * CHECKER_SIDE + column) * 4);+ }+ }+ return { width: CHECKER_SIDE, height: CHECKER_SIDE, data };+}++function floorGeometry() {+ const corners = [[-50, 20], [50, 20], [50, -2000], [-50, -2000]];+ return {+ positions: new Float32Array(corners.flatMap(([x, z]) => [x, 0, z])),+ normals: new Float32Array(corners.flatMap(() => [0, 1, 0])),+ uvs: new Float32Array(corners.flatMap(([x, z]) => [x * FLOOR_UV_PER_METRE, z * FLOOR_UV_PER_METRE])),+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+ };+}++/** Traces the checker floor and returns linear rgb floats (width * height * 3, rows from the top). */+export function renderFloor({ cameraName, textureMips, samples, seed, width, height }) {+ const camera = createCamera(CAMERAS[cameraName], width, height);+ const options = { width, height, samples, seed, bounces: 2, textureMips, backgroundColor: SKY_RADIANCE };+ const input = buildNativeInputV2(+ {+ materials: [{ color: [1, 1, 1], roughness: 1, metallic: 0, map: { image: checkerImage(), colorSpace: 'srgb' } }],+ instances: [{ geometry: floorGeometry(), materialIndex: 0 }],+ lights: {},+ },+ camera,+ options,+ );+ const traced = traceNative(input, { ...options, kernel: 'cycles' });+ const rgb = new Float32Array(width * height * 3);+ for (let pixel = 0; pixel < width * height; pixel++) {+ rgb.set(traced.rgba.subarray(pixel * 4, pixel * 4 + 3), pixel * 3);+ }+ return rgb;+}++/** Mean squared difference over the rows from `firstRow` down, over the mean squared reference value there. */+export function relativeMeanSquaredError(image, reference, width, height, firstRow) {+ let squaredDifference = 0;+ let squaredReference = 0;+ for (let index = firstRow * width * 3; index < width * height * 3; index++) {+ squaredDifference += (image[index] - reference[index]) ** 2;+ squaredReference += reference[index] ** 2;+ }+ return squaredDifference / squaredReference;+}++export function maxAbsoluteDifference(first, second) {+ let largest = 0;+ for (let index = 0; index < first.length; index++) {+ largest = Math.max(largest, Math.abs(first[index] - second[index]));+ }+ return largest;+}++function parseCommandLine(argumentList) {+ const read = (flagName, fallbackValue) => {+ const flagIndex = argumentList.indexOf(flagName);+ return flagIndex === -1 ? fallbackValue : Number(argumentList[flagIndex + 1]);+ };+ if (argumentList.length === 0 || argumentList[0].startsWith('--')) {+ throw new RangeError('Usage: node bench/cycles-parity/texture-mips-bench.mjs <outputDirectory> [--width 320] [--height 180] [--seeds 3] [--reference-samples 2048]');+ }+ return {+ outputDirectory: resolve(argumentList[0]),+ width: read('--width', 320),+ height: read('--height', 180),+ seedCount: read('--seeds', 3),+ referenceSamples: read('--reference-samples', 2048),+ };+}++async function writePicture(outputDirectory, name, rgb) {+ await writeFile(join(outputDirectory, `${name}.f32`), Buffer.from(rgb.buffer, rgb.byteOffset, rgb.byteLength));+}++async function runCameraSweep(settings, cameraName, metrics) {+ const { outputDirectory, width, height, seedCount, referenceSamples } = settings;+ // The horizon of the receding camera sits a pixel or two above the middle of the picture; the magnified camera sees only floor.+ const firstRow = cameraName === 'receding' ? Math.floor(height / 2) + 2 : 0;+ const reference = renderFloor({ cameraName, textureMips: false, samples: referenceSamples, seed: 4242, width, height });+ await writePicture(outputDirectory, `${cameraName}-reference`, reference);+ metrics[cameraName] = { referenceSamples, firstRow, runs: [] };+ for (const samples of SAMPLE_COUNTS) {+ const errors = { off: [], on: [] };+ let largestDifference = 0;+ for (let seed = 1; seed <= seedCount; seed++) {+ const off = renderFloor({ cameraName, textureMips: false, samples, seed, width, height });+ const on = renderFloor({ cameraName, textureMips: true, samples, seed, width, height });+ errors.off.push(relativeMeanSquaredError(off, reference, width, height, firstRow));+ errors.on.push(relativeMeanSquaredError(on, reference, width, height, firstRow));+ largestDifference = Math.max(largestDifference, maxAbsoluteDifference(off, on));+ if (seed === 1) {+ await writePicture(outputDirectory, `${cameraName}-off-${samples}spp`, off);+ await writePicture(outputDirectory, `${cameraName}-on-${samples}spp`, on);+ }+ }+ const mean = (values) => values.reduce((sum, value) => sum + value, 0) / values.length;+ metrics[cameraName].runs.push({+ samples,+ seeds: seedCount,+ relMseOff: mean(errors.off),+ relMseOn: mean(errors.on),+ relMseOffPerSeed: errors.off,+ relMseOnPerSeed: errors.on,+ largestPixelDifferenceOnVsOff: largestDifference,+ });+ }+}++async function runCli() {+ const settings = parseCommandLine(process.argv.slice(2));+ await mkdir(settings.outputDirectory, { recursive: true });+ const metrics = { width: settings.width, height: settings.height };+ await runCameraSweep(settings, 'receding', metrics);+ await runCameraSweep(settings, 'magnified', metrics);+ await writeFile(join(settings.outputDirectory, 'metrics.json'), JSON.stringify(metrics, null, 2));+ console.log(JSON.stringify(metrics, null, 2));+}++if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {+ await runCli();+}diff --git a/bench/cycles-parity/texture-mips-identity.sh b/bench/cycles-parity/texture-mips-identity.shnew file mode 100644index 00000000..ca47b0ff--- /dev/null+++ b/bench/cycles-parity/texture-mips-identity.sh@@ -0,0 +1,47 @@+#!/usr/bin/env bash+# Are the pictures of the existing scenes unchanged by the mip level support? (#896)+# bash bench/cycles-parity/texture-mips-identity.sh <baselineCheckout> <outputDirectory>+#+# Traces five scenes on both kernels with this checkout and with a checkout of the commit this branch was cut from, each with its+# own built addon, and compares the SHA-256 of the float pictures. Mip levels are off in all of them (the default). Prints one+# line per picture, then "identical" or "DIFFERENT" and exits 1 for a difference. Run it on a machine with a GPU.+set -uo pipefail++baseline_checkout=$(cd "$1" && pwd)+output_directory=$(mkdir -p "$2" && cd "$2" && pwd)+candidate_checkout=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)+scenes_directory="$output_directory/scenes"+mkdir -p "$scenes_directory"++(cd "$candidate_checkout" && node bench/cycles-parity/texture-scenes.mjs "$output_directory" > /dev/null) || exit 2+for reference_scene in lit-interior glass brick-graph; do+ (cd "$candidate_checkout" && node bench/cycles-parity/export-scene.mjs "$output_directory" --scene "$reference_scene" > /dev/null) || exit 2+done++picture_hashes() {+ local checkout="$1"+ local label="$2"+ local scene+ local kernel+ for scene in lit-interior glass brick-graph tex-repeat tex-wraps; do+ for kernel in legacy cycles; do+ local prefix="$output_directory/$label-$scene-$kernel"+ if (cd "$checkout" && node bench/cycles-parity/trace-native.mjs "$scenes_directory/$scene.json" "$prefix" \+ --kernel "$kernel" --samples 16 --width 160 --height 90 --seed 1 > "$prefix.log" 2>&1); then+ echo "$scene $kernel $(sha256sum "$prefix.npy" | cut -d' ' -f1)"+ else+ echo "$scene $kernel FAILED"+ fi+ done+ done+}++picture_hashes "$baseline_checkout" baseline > "$output_directory/baseline.sha256"+picture_hashes "$candidate_checkout" candidate > "$output_directory/candidate.sha256"+paste -d'|' "$output_directory/baseline.sha256" "$output_directory/candidate.sha256" | tee "$output_directory/identity-table.txt"+if cmp -s "$output_directory/baseline.sha256" "$output_directory/candidate.sha256" && ! grep -q FAILED "$output_directory/candidate.sha256"; then+ echo identical+else+ echo DIFFERENT+ exit 1+fidiff --git a/bench/cycles-parity/texture-mips-run-all.sh b/bench/cycles-parity/texture-mips-run-all.shnew file mode 100644index 00000000..2b9980a2--- /dev/null+++ b/bench/cycles-parity/texture-mips-run-all.sh@@ -0,0 +1,53 @@+#!/usr/bin/env bash+# Everything the texture mip levels of #896 are checked with, in one run on a machine with a GPU, Rust and Node:+# bash bench/cycles-parity/texture-mips-run-all.sh <outputDirectory>+# 1. builds the addon of this checkout, and of the commit it was cut from (a second checkout beside it, its own cargo target);+# 2. cargo test of the addon, then the node tests of the textures (the ones that need a GPU run, not skip);+# 3. the byte identity of five existing scenes on both kernels against the base build;+# 4. the error of a minified and a magnified checker with and without levels (texture-mips-bench.mjs).+# Each step keeps going after a failure and the last lines say which steps failed.+set -uo pipefail++output_directory=$(mkdir -p "$1" && cd "$1" && pwd)+candidate_checkout=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)+baseline_checkout="${candidate_checkout}-base"+failed_steps=()++run_step() {+ local step_name="$1"+ shift+ echo "=== $step_name"+ if ! "$@" > "$output_directory/$step_name.log" 2>&1; then+ failed_steps+=("$step_name")+ echo "FAILED $step_name (tail of $output_directory/$step_name.log follows)"+ tail -n 40 "$output_directory/$step_name.log"+ fi+}++prepare_baseline_checkout() {+ rm -rf "$baseline_checkout"+ git -C "$candidate_checkout" worktree prune+ git -C "$candidate_checkout" worktree add --detach "$baseline_checkout" HEAD \+ && ln -s "$candidate_checkout/node_modules" "$baseline_checkout/node_modules"+}++build_addon() {+ (cd "$1/packages/render-native" && CARGO_TARGET_DIR="$2" node build.mjs)+}++run_step build-candidate build_addon "$candidate_checkout" "${CARGO_TARGET_DIR:-/root/cargo-target/candidate}"+run_step prepare-baseline prepare_baseline_checkout+run_step build-baseline build_addon "$baseline_checkout" /root/cargo-target/baseline+run_step cargo-test bash -c "set -o pipefail; cd '$candidate_checkout/packages/render-native' && cargo test 2>&1 | tail -n 80"+run_step node-tests bash -c "cd '$candidate_checkout' && node --test tests/native-texture-mips.test.js tests/native-texture-sampler.test.js tests/native-pack-v2.test.js tests/native-job-materials.test.js"+run_step identity bash "$candidate_checkout/bench/cycles-parity/texture-mips-identity.sh" "$baseline_checkout" "$output_directory/identity"+run_step mips-bench node "$candidate_checkout/bench/cycles-parity/texture-mips-bench.mjs" "$output_directory/bench"++echo "=== summary"+grep -hE "^# (tests|pass|fail|skipped)|^ℹ (tests|pass|fail|skipped)|test result" "$output_directory"/cargo-test.log "$output_directory"/node-tests.log || true+tail -n 1 "$output_directory/identity.log" || true+if [ "${#failed_steps[@]}" -gt 0 ]; then+ echo "failed steps: ${failed_steps[*]}"+ exit 1+fi+echo "all steps passed"diff --git a/changes/896-texture-mips.md b/changes/896-texture-mips.mdnew file mode 100644index 00000000..d4a470b5--- /dev/null+++ b/changes/896-texture-mips.md@@ -0,0 +1 @@+- The native `cycles` kernel can read texture mip levels: `textureMips: true` stores a box filtered chain after level 0 and picks the level from a ray cone (off by default, so pictures match Blender Cycles and every existing scene stays byte-identical) (#896)diff --git a/packages/render-native/FORMAT-v2.md b/packages/render-native/FORMAT-v2.mdindex fb0db33d..3b4a9e8e 100644--- a/packages/render-native/FORMAT-v2.md+++ b/packages/render-native/FORMAT-v2.md@@ -40,7 +40,7 @@ Total size: **320 bytes** (`20 × 16 B`), alignment: **16 bytes**.| `20` | `4` | `4` | `u32` | `samples_per_dispatch` | Samples traced per pixel in one dispatch (`>= 1`) || `24` | `4` | `4` | `u32` | `total_samples` | Target total samples per pixel || `28` | `4` | `4` | `u32` | `seed` | Deterministic scramble seed |-| `32` | `4` | `4` | `u32` | `kernel_flags` | Bitmask: `1=USE_LIGHT_TREE`, `2=HAS_VOLUME`, `4=HAS_SUBSURFACE`, `8=ORTHOGRAPHIC_CAMERA`, `16=ADAPTIVE_SAMPLING`, `32=TRANSPARENT_BACKGROUND`, `64=WHITE_NOISE_SAMPLER` (bit clear: Cycles' Sobol-Burley blue-noise pattern, the default; bit set: the PCG hash sampler), `128=LIGHT_TREE_PROBE`, `256=TEST_NEE_ONLY`, `512=TEST_BSDF_ONLY` (the last three are for tests). Bit `1` is set by the packer from `lightSampling` (`auto` default: tree from more than one emitter; `tree`; `uniform`) and compiles the traversal in or out (`SCENE_HAS_LIGHT_TREE`) |+| `32` | `4` | `4` | `u32` | `kernel_flags` | Bitmask: `1=USE_LIGHT_TREE`, `2=HAS_VOLUME`, `4=HAS_SUBSURFACE`, `8=ORTHOGRAPHIC_CAMERA`, `16=ADAPTIVE_SAMPLING`, `32=TRANSPARENT_BACKGROUND`, `64=WHITE_NOISE_SAMPLER` (bit clear: Cycles' Sobol-Burley blue-noise pattern, the default; bit set: the PCG hash sampler), `128=LIGHT_TREE_PROBE`, `256=TEST_NEE_ONLY`, `512=TEST_BSDF_ONLY` (the last three are for tests), `1024=PATH_REGENERATION`, `2048=TEXTURE_MIPS` (set by the packer when any texture stores mip levels: the kernel then carries a ray cone along each path and reads those levels, see section 8; clear, every texture is read at level 0). Bit `1` is set by the packer from `lightSampling` (`auto` default: tree from more than one emitter; `tree`; `uniform`) and compiles the traversal in or out (`SCENE_HAS_LIGHT_TREE`) || `36` | `4` | `4` | `f32` | `adaptive_threshold` | Adaptive stop threshold (`0.0` = disabled) || `40` | `4` | `4` | `f32` | `clamp_direct` | Effective direct radiance ceiling at bounce `0` (`0.0` or `>= 1e30` = unclamped; Cycles `sample_clamp_direct * 3.0`) || `44` | `4` | `4` | `f32` | `clamp_indirect` | Effective indirect radiance ceiling at bounce `> 0` (`0.0` or `>= 1e30` = unclamped; Cycles `sample_clamp_indirect * 3.0`) |@@ -353,12 +353,17 @@ Total stride: **32 bytes** (`2 × 16 B`), alignment: **16 bytes**.| `0` | `4` | `16` | `u32` | `data_offset` | Base `u32` word offset in `texture_texels` (`@binding(9)`, `@align(16)`) || `4` | `4` | `4` | `u32` | `width` | Mip `0` width in texels || `8` | `4` | `4` | `u32` | `height` | Mip `0` height in texels |-| `12` | `4` | `4` | `u32` | `format_and_sampler` | Bits `0..7`: `0=RGBA8_UNORM`, `1=RGBA8_SRGB`, `2=RGBA32_FLOAT`, `3=RG16_FLOAT`; bits `8..15`: mip count; bits `16..17`: wrap U; bits `18..19`: wrap V; bit `20`: nearest; bit `21`: use `UV1` |+| `12` | `4` | `4` | `u32` | `format_and_sampler` | Bits `0..7`: `0=RGBA8_UNORM`, `1=RGBA8_SRGB`, `2=RGBA32_FLOAT`, `3=RG16_FLOAT`; bits `8..15`: mip count (levels stored, level `0` included; `1` means level `0` only); bits `16..17`: wrap U; bits `18..19`: wrap V; bit `20`: nearest; bit `21`: use `UV1` || `16` | `8` | `8` | `vec2<f32>` | `uv_scale` | UV scale `(su, sv)` || `24` | `8` | `8` | `vec2<f32>` | `uv_offset` | UV offset `(ou, ov)` |One sampler reads every descriptor: `texture_sample` in `src/cycles/closure.wgsl`. Shading, bump, normal maps and the alpha tests of the integrator (the opacity of a cutout or blended surface, for camera, bounce and shadow rays) all go through it, so a surface is seen and shaded with the same wrap, filter and format. Wrap `0` repeats, `1` clamps and `2` mirrors in float UV space before the texel lookup; `nearest` picks the texel the wrapped UV falls in, otherwise the four neighbours are blended. `texture_texels` is one storage binding, so the pool of all textures (each texture padded to 16 bytes) must fit the device's storage binding size, at most 1 GiB. `buildNativeInputV2` refuses a pool past 1 GiB and the host refuses one past the device's binding size, each with an error that names the size and the limit. The struct sizes above do not change.+**Mip levels (opt in).** Level `0` is the texture as given. When the mip count is above `1`, the levels follow level `0` in the same run of words, with no padding between them: level `k` has `max(1, width >> k)` by `max(1, height >> k)` texels, each level stored as level `0` is (`1` word per texel for `RGBA8_*` and `RG16_FLOAT`, `4` for `RGBA32_FLOAT`), and the whole run is padded to 16 bytes once. The kernel finds level `k` by walking from `data_offset` (`texture_level_descriptor`). The packer builds the chain with a 2 x 2 box filter (`texture-mips.mjs`): a 2 x 2 block averaged per channel, the bytes of an 8-bit map rounded, the floats of a float map as they are, alpha averaged like any channel (not weighted), an odd last row or column read twice. An sRGB map is averaged in linear light (decoded, averaged, encoded back to bytes); every other format is averaged on its stored values.++A texture stores levels only when `textureMips: true` is passed to the packer (or `mips: true` on that texture; `mips: false` overrides the option). The default is level `0` only, which is what Blender Cycles reads. A nearest-filtered texture or one of a single texel never stores levels. The dedupe key holds the mip count, so one image packed with and without levels is two descriptors. With `kernel_flags` bit `2048` set, the integrator keeps a ray cone per path (width at the ray origin, spread), and a hit passes the sampler the width of the ray footprint in UV units; the sampler turns it into `log2` of the footprint in texels (the larger of the two axes after `uv_scale`), reads level `0` while that is not above `0`, otherwise blends the two levels around it (trilinear, each level bilinear on the stored values, the blend decoded after, the order of level `0`) and stops at the last level. The alpha tests of the integrator and the bump taps always read level `0`.++---## 9. Film Accumulation Buffer (`@binding(11)`)diff --git a/packages/render-native/README.md b/packages/render-native/README.mdindex 5d165806..423ac18f 100644--- a/packages/render-native/README.md+++ b/packages/render-native/README.md@@ -36,9 +36,10 @@ const { radiance, escaped } = traceNativeTexels(input, { count: texelCount, poinCook'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](../../docs/cycles-parity.md), layout: [FORMAT-v2.md](./FORMAT-v2.md).-Three more options of the `cycles` kernel; `pathRegeneration` is on by default, the other two are off:+Four more options of the `cycles` kernel; `pathRegeneration` is on by default, the other three are off:- `pathRegeneration` (on by default; pass `false` for the earlier order) starts a pixel's next sample as soon as a path ends instead of waiting for the longest path of the dispatch. The image is bit-identical for the same dispatch sizes and sampling time was 0.63 to 0.73 times the old order on three scenes (`lit-interior`, `glass`, `many-lights-500`; `metal` 0.91 to 0.97). The legacy kernel ignores it. `bench/cycles-parity/trace-native.mjs` takes `--no-path-regeneration`.+- `textureMips: true` (a packing option of `buildNativeInputV2`, `upgradeNativeInputV1ToV2` and the job packers; off by default) stores a mip chain after level 0 of every linearly filtered texture, float and RGBA8 alike, and the kernel reads the level a ray footprint asks for, blended between two levels, instead of always level 0. Blender Cycles reads level 0, so leave it off to match Cycles: with it off every picture is byte-identical to a build without the option. A single texture can say `mips: true` or `mips: false`. The footprint is a ray cone: the camera pixel angle, widened by 1 radian at a diffuse bounce and by twice the roughness at a glossy one, times the distance, times the UV density of the triangle. Levels cost a third more texels in the pool, which the 1 GiB check counts. The format is in `FORMAT-v2.md` section 8, the numbers in `docs/cycles-parity.md` ("Texture mip levels").- `envCompensation: true` (or a fraction from 0 to 1) is the MIS compensation of the environment sampling table, described above. It is unbiased; it cut the error under the sunny HDRI scene by 1.4 to 2.2 times and leaves scenes without an environment unchanged.- `denoise: 'atrous'` also filters the image on the GPU with an edge-avoiding a-trous wavelet filter (about 1.5 ms of dispatches, 8 to 14 ms in all at 960 x 540) and returns it as `denoisedRgba` next to `rgba`, plus `denoiseSeconds`, `denoiseGpuSeconds` and `denoiseCompileSeconds`. `rgba` is untouched. The filter is biased (it smooths): never compare `denoisedRgba` with a converged image as if it were unbiased. `denoiseAtrous({ width, height, rgba, albedo, normal, depth, variance })` filters any traced image the same way.diff --git a/packages/render-native/job-input.mjs b/packages/render-native/job-input.mjsindex 055f6fb2..f332bf7c 100644--- a/packages/render-native/job-input.mjs+++ b/packages/render-native/job-input.mjs@@ -164,6 +164,7 @@ export function buildJobNativeInput(scene, camera, options, pack, resolveTexturesubsurfaceVec4Offset: tables.subsurfaceVec4Offset,materialCount: scene.traceMaterials.length,carriedFields: carriedMaterialFieldsOfScene(scene, resolveTexture),+ textureMips: options.textureMips,});const instances = scene.instances.map(instance => {const lightMask = reducedMaterials.materialLightMasks[instance.materialIndex] ?? ALL_LIGHT_GROUPS;@@ -181,6 +182,9 @@ export function buildJobNativeInput(scene, camera, options, pack, resolveTextureexport function buildFlattenedJobNativeInput(scene, camera, options, pack, resolveTexture) {const carriedFields = carriedMaterialFieldsOfScene(scene, resolveTexture);// The sample count goes into the kernel parameters, as it does when the kernel upgrades the tables itself.- const upgradeOptions = options.samples === undefined ? {} : { samples: options.samples };+ const upgradeOptions = {+ ...(options.samples === undefined ? {} : { samples: options.samples }),+ ...(options.textureMips === undefined ? {} : { textureMips: options.textureMips }),+ };return upgradeNativeInputV1ToV2(buildNativeInput(scene, camera, options, pack), upgradeOptions, carriedFields);}diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjsindex 25335710..f0d4cf67 100644--- a/packages/render-native/pack-input-v2.mjs+++ b/packages/render-native/pack-input-v2.mjs@@ -3,6 +3,15 @@import { buildLightTree } from './light-tree-v2.mjs';import { THIN_LENS_FLOAT_INDEXES } from './pack-input.mjs';+import {+ TEXTURE_KIND_RG16_FLOAT,+ TEXTURE_KIND_RGBA32_FLOAT,+ TEXTURE_KIND_RGBA8,+ TEXTURE_KIND_RGBA8_SRGB,+ buildMipChain,+ mipChainWordCount,+ mipLevelCount,+} from './texture-mips.mjs';export const FORMAT_V2_MAGIC = 0x36375054;export const FORMAT_V2_VERSION = 2;@@ -46,6 +55,8 @@ const KERNEL_FLAG_ADAPTIVE_SAMPLING = 16;const KERNEL_FLAG_TRANSPARENT_BACKGROUND = 32;export const KERNEL_FLAG_WHITE_NOISE_SAMPLER = 64;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;const INSTANCE_VISIBILITY_CAMERA = 1;const INSTANCE_DEFAULT_VISIBILITY = 1 | 2 | 4 | 8 | 16 | 32;@@ -252,7 +263,40 @@ function transformDirection3x4(rows, vector) {];}-function createTextureCollector() {+/** Throws unless `value` is undefined, true or false. `name` and `callerName` say which option it was. */+export function validateTextureMipsOption(value, name, callerName) {+ if (value !== undefined && typeof value !== 'boolean') {+ throw new TypeError(+ `${callerName}: \`${name}\` must be true (store mip levels), false or left out (level 0 only, as Blender Cycles reads), got ${JSON.stringify(value)}.`+ );+ }+}++function mipKindOfFormat(format) {+ if (format === TEXTURE_FORMAT_RGBA32_FLOAT) {+ return TEXTURE_KIND_RGBA32_FLOAT;+ }+ if (format === TEXTURE_FORMAT_RG16_FLOAT) {+ return TEXTURE_KIND_RG16_FLOAT;+ }+ return format === TEXTURE_FORMAT_RGBA8_SRGB ? TEXTURE_KIND_RGBA8_SRGB : TEXTURE_KIND_RGBA8;+}++// Level 0 without padding, then the levels after it, padded once at the end to a multiple of four words.+function joinMipLevels(levelZeroWords, mipChain) {+ const joined = new Uint32Array(Math.max(4, Math.ceil((levelZeroWords.length + mipChain.length) / 4) * 4));+ joined.set(levelZeroWords, 0);+ joined.set(mipChain, levelZeroWords.length);+ return joined;+}++/**+ * Collects the textures of a scene into one pool. `textureMips: true` stores a full mip chain after level 0 of every texture+ * that is filtered linearly and has more than one texel; a texture can say `mips: true` or `mips: false` to differ from that.+ * The default is level 0 only, which is what Blender Cycles reads.+ */+function createTextureCollector({ textureMips } = {}) {+ validateTextureMipsOption(textureMips, 'textureMips', 'createTextureCollector');const indexByKey = new Map();const dataIdMap = new WeakMap();let nextDataId = 1;@@ -260,12 +304,24 @@ function createTextureCollector() {const wordChunks = [];let totalWords = 0;let finished = null;+ let anyTextureHasMips = false;- function packedWordCount(format, pixelCount) {- if (format === TEXTURE_FORMAT_RGBA32_FLOAT) {- return pixelCount * 4;+ function packedWordCount(format, pixelCount, mipWords = 0) {+ const levelZeroWords = format === TEXTURE_FORMAT_RGBA32_FLOAT ? pixelCount * 4 : pixelCount;+ if (mipWords === 0 && format === TEXTURE_FORMAT_RGBA32_FLOAT) {+ return levelZeroWords;+ }+ return Math.max(4, Math.ceil((levelZeroWords + mipWords) / 4) * 4);+ }++ // The number of levels a texture is stored with, level 0 included: 1 unless mips are asked for and can be used.+ function resolveMipCount(textureOption, nearest, width, height) {+ validateTextureMipsOption(textureOption, 'mips', 'texture');+ const wanted = textureOption ?? textureMips ?? false;+ if (!wanted || nearest) {+ return 1;}- return Math.max(4, Math.ceil(pixelCount / 4) * 4);+ return mipLevelCount(width, height);}// Checked before a texture is converted, so an oversize image fails fast instead of after allocating its words.@@ -316,8 +372,8 @@ function createTextureCollector() {const repeatU = rawDescriptor.wrapU ?? (rawDescriptor.repeat === false ? 1 : 0);const repeatV = rawDescriptor.wrapV ?? (rawDescriptor.repeat === false ? 1 : 0);- const mipCount = Math.max(1, Math.min(255, Number(rawDescriptor.mipCount ?? 1)));const nearest = rawDescriptor.nearest ? 1 : 0;+ const mipCount = resolveMipCount(rawDescriptor.mips, nearest === 1, width, height);const useUv1 = rawDescriptor.uvSet === 1 ? 1 : 0;const uvScale = rawDescriptor.uvScale ?? [1, 1];const uvOffset = rawDescriptor.uvOffset ?? [0, 0];@@ -336,7 +392,8 @@ function createTextureCollector() {}const pixelCount = width * height;- assertRoomInPool(packedWordCount(format, pixelCount), width, height);+ const mipWords = mipCount > 1 ? mipChainWordCount(mipKindOfFormat(format), width, height) : 0;+ assertRoomInPool(packedWordCount(format, pixelCount, mipWords), width, height);const dataOffset = totalWords;let packedWords;let sumR = 0;@@ -391,6 +448,16 @@ function createTextureCollector() {}}+ if (mipCount > 1) {+ const levelZeroWordCount = format === TEXTURE_FORMAT_RGBA32_FLOAT ? pixelCount * 4 : pixelCount;+ const levelZeroWords = packedWords.subarray(0, levelZeroWordCount);+ const levelZeroTexels = format === TEXTURE_FORMAT_RGBA32_FLOAT+ ? new Float32Array(packedWords.buffer, packedWords.byteOffset, levelZeroWordCount)+ : levelZeroWords;+ packedWords = joinMipLevels(levelZeroWords, buildMipChain(mipKindOfFormat(format), levelZeroTexels, width, height));+ anyTextureHasMips = true;+ }+const descriptorBytes = new ArrayBuffer(STRUCT_STRIDES_V2.textureDescriptor);const descriptorU32 = new Uint32Array(descriptorBytes);const descriptorF32 = new Float32Array(descriptorBytes);@@ -418,10 +485,18 @@ function createTextureCollector() {function addPackedRgba8Words(words, width, height, isSrgb, repeat) {const pixelCount = width * height;- const alignedWords = packedWordCount(TEXTURE_FORMAT_RGBA8_UNORM, pixelCount);+ const mipCount = resolveMipCount(undefined, false, width, height);+ const atlasKind = isSrgb ? TEXTURE_KIND_RGBA8_SRGB : TEXTURE_KIND_RGBA8;+ const mipWords = mipCount > 1 ? mipChainWordCount(atlasKind, width, height) : 0;+ const alignedWords = packedWordCount(TEXTURE_FORMAT_RGBA8_UNORM, pixelCount, mipWords);assertRoomInPool(alignedWords, width, height);- const padded = new Uint32Array(alignedWords);+ let padded = new Uint32Array(alignedWords);padded.set(words.subarray(0, pixelCount));+ if (mipCount > 1) {+ const levelZeroWords = padded.slice(0, pixelCount);+ padded = joinMipLevels(levelZeroWords, buildMipChain(atlasKind, levelZeroWords, width, height));+ anyTextureHasMips = true;+ }let sumR = 0;let sumG = 0;let sumB = 0;@@ -436,7 +511,7 @@ function createTextureCollector() {}const format = isSrgb ? TEXTURE_FORMAT_RGBA8_SRGB : TEXTURE_FORMAT_RGBA8_UNORM;const wrap = repeat ? 0 : 1;- const formatAndSampler = (format | (1 << 8) | (wrap << 16) | (wrap << 18)) >>> 0;+ const formatAndSampler = (format | (mipCount << 8) | (wrap << 16) | (wrap << 18)) >>> 0;const descriptorBytes = new ArrayBuffer(STRUCT_STRIDES_V2.textureDescriptor);const descriptorU32 = new Uint32Array(descriptorBytes);const descriptorF32 = new Float32Array(descriptorBytes);@@ -482,6 +557,7 @@ function createTextureCollector() {textureDescriptors: descriptorBuffer,textureCount,textureTexels: texelBuffer,+ usesTextureMips: anyTextureHasMips,};}@@ -1705,6 +1781,7 @@ export function validatePackOptions(options, callerName, requireDimensionsAndSamresolveSamplingOptions(options, callerName);resolveEnvCompensationFraction(options.envCompensation, callerName);validateDenoiseOption(options.denoise, callerName);+ validateTextureMipsOption(options.textureMips, 'textureMips', callerName);validateFilterOptions(options, callerName);if (width !== undefined && height !== undefined) {validateImagePixelCount(width, height, callerName);@@ -1876,6 +1953,9 @@ function packKernelParamsV2({if (sampler === 'white') {kernelFlags |= KERNEL_FLAG_WHITE_NOISE_SAMPLER;}+ if (counts.usesTextureMips === true) {+ kernelFlags |= KERNEL_FLAG_TEXTURE_MIPS;+ }const maxBounces = Math.max(0, Math.round(Number(options.bounces ?? options.maxBounces ?? 8)));const maxDiffuseBounces = Math.max(0, Math.round(Number(options.diffuseBounces ?? maxBounces)));@@ -2466,7 +2546,7 @@ export function buildNativeInputV2(scene, camera, options = {}) {throw new TypeError('buildNativeInputV2 option `reducedMaterials` must be the result of reduceV1MaterialTable (materialRecords and textureCollector).');}}- const textureCollector = reducedMaterials?.textureCollector ?? createTextureCollector();+ const textureCollector = reducedMaterials?.textureCollector ?? createTextureCollector({ textureMips: options.textureMips });const packedGeometry = explicitInstances? packInstancedGeometry(explicitInstances, options.materials ?? scene.materials ?? [{}], textureCollector, reducedMaterials): packFlattenedTraceScene(scene, options.parts ?? scene.parts, textureCollector);@@ -2486,6 +2566,7 @@ export function buildNativeInputV2(scene, camera, options = {}) {lightCount: packedLights.lightCount,lightTreeNodeCount: packedLightTree.lightTreeNodeCount,textureCount: packedTextures.textureCount,+ usesTextureMips: packedTextures.usesTextureMips,};const kernelParams = packKernelParamsV2({@@ -2572,8 +2653,8 @@ function withCarriedFields(descriptor, carried, textureCollector) {* (blend opacity, sheen, specular, anisotropy, iridescence, attenuation, the layer textures and the rest of the record).* `materials` holds the table with the subsurface table after it, `atlas` the atlas words and `atlasWidth` their row width.*/-export function reduceV1MaterialTable({ materials: matSource, atlas: atlasWords, atlasWidth, subsurfaceVec4Offset, materialCount, carriedFields }) {- const textureCollector = createTextureCollector();+export function reduceV1MaterialTable({ materials: matSource, atlas: atlasWords, atlasWidth, subsurfaceVec4Offset, materialCount, carriedFields, textureMips }) {+ const textureCollector = createTextureCollector({ textureMips });const atlasCache = new Map();function registerAtlasRect(rectX, rectY, width, height, flagsValue) {@@ -2711,6 +2792,7 @@ export function upgradeNativeInputV1ToV2(v1Input, options = {}, carriedFields =subsurfaceVec4Offset,materialCount,carriedFields,+ textureMips: options.textureMips,});const materialsBuffer = new Uint8Array(Math.max(1, materialRecords.length) * STRUCT_STRIDES_V2.material);@@ -2961,6 +3043,7 @@ export function upgradeNativeInputV1ToV2(v1Input, options = {}, carriedFields =lightCount: packedLights.lightCount,lightTreeNodeCount: packedLightTree.lightTreeNodeCount,textureCount: packedTextures.textureCount,+ usesTextureMips: packedTextures.usesTextureMips,};const kernelParams = packKernelParamsV2({diff --git a/packages/render-native/package.json b/packages/render-native/package.jsonindex 929e7ee7..23a673f7 100644--- a/packages/render-native/package.json+++ b/packages/render-native/package.json@@ -12,6 +12,7 @@"pack-input.mjs","pack-input-v2.mjs","light-tree-v2.mjs",+ "texture-mips.mjs","FORMAT-v2.md","build.mjs","build.rs",diff --git a/packages/render-native/src/cycles/abi.wgsl b/packages/render-native/src/cycles/abi.wgslindex d2db86db..a1a98462 100644--- a/packages/render-native/src/cycles/abi.wgsl+++ b/packages/render-native/src/cycles/abi.wgsl@@ -49,6 +49,10 @@ const KERNEL_FLAG_TEST_BSDF_ONLY: u32 = 512u;// Set: a path that ends is replaced at once by the pixel's next sample (one bounce per loop iteration). Clear (default): each path// runs to its end before the next one starts. The image is the same either way; only the time per sample differs.const KERNEL_FLAG_PATH_REGENERATION: u32 = 1024u;+// Set: the integrator carries a ray cone along each path and a hit hands the texture sampler its footprint, so a texture that+// stores mip levels is read at the level the footprint asks for. Clear (default): every texture is read at level 0, as Blender+// Cycles does.+const KERNEL_FLAG_TEXTURE_MIPS: u32 = 2048u;// `KernelParamsV2.filter_type` values.const FILTER_BOX: u32 = 0u;@@ -489,6 +493,9 @@ struct ShadingPoint {vertex_color: vec3<f32>,light_group_mask_hi: u32,++ // Width of the ray footprint on the surface in `uv0` units; 0 reads every texture at level 0.+ uv_footprint: f32,}// Single BSDF lobe parameterized by L4 closure setup.diff --git a/packages/render-native/src/cycles/closure.wgsl b/packages/render-native/src/cycles/closure.wgslindex d2038918..8e29cb82 100644--- a/packages/render-native/src/cycles/closure.wgsl+++ b/packages/render-native/src/cycles/closure.wgsl@@ -107,10 +107,84 @@ fn texture_decode_filtered(color: vec4<f32>, format: u32) -> vec4<f32> {return color;}+// The descriptor of one mip level. Level 0 is the texture as the descriptor holds it; each level after it is stored right after+// the one before it, half as wide and as high (never less than one texel), with the same number of words per texel.+fn texture_level_descriptor(desc: TextureDescriptor, level: u32, format: u32) -> TextureDescriptor {+ let words_per_texel = select(1u, 4u, format == 2u);+ var level_desc = desc;+ for (var skipped = 0u; skipped < level; skipped = skipped + 1u) {+ level_desc.data_offset = level_desc.data_offset + level_desc.width * level_desc.height * words_per_texel;+ level_desc.width = max(level_desc.width >> 1u, 1u);+ level_desc.height = max(level_desc.height >> 1u, 1u);+ }+ return level_desc;+}++// Bilinear filter of one mip level on the stored values. The caller decodes the result (see texture_decode_filtered).+fn texture_filter_level(+ desc: TextureDescriptor,+ level: u32,+ format: u32,+ wrap_u: u32,+ wrap_v: u32,+ u_wrapped: f32,+ v_wrapped: f32,+) -> vec4<f32> {+ let level_desc = texture_level_descriptor(desc, level, format);+ let level_width = i32(level_desc.width);+ let level_height = i32(level_desc.height);+ let level_fx = u_wrapped * f32(level_width) - 0.5;+ let level_fy = v_wrapped * f32(level_height) - 0.5;+ let level_bx0 = i32(floor(level_fx));+ let level_by0 = i32(floor(level_fy));+ let level_tx = level_fx - f32(level_bx0);+ let level_ty = level_fy - f32(level_by0);+ let level_ix0 = texture_wrap_texel_index(level_bx0, level_width, wrap_u);+ let level_ix1 = texture_wrap_texel_index(level_bx0 + 1, level_width, wrap_u);+ let level_iy0 = texture_wrap_texel_index(level_by0, level_height, wrap_v);+ let level_iy1 = texture_wrap_texel_index(level_by0 + 1, level_height, wrap_v);+ let level_c00 = texture_fetch_texel(level_desc, level_ix0, level_iy0, format);+ let level_c10 = texture_fetch_texel(level_desc, level_ix1, level_iy0, format);+ let level_c01 = texture_fetch_texel(level_desc, level_ix0, level_iy1, format);+ let level_c11 = texture_fetch_texel(level_desc, level_ix1, level_iy1, format);+ return mix(mix(level_c00, level_c10, level_tx), mix(level_c01, level_c11, level_tx), level_ty);+}++// Trilinear read for a footprint larger than a texel: the two levels around `level_of_detail` are each filtered on their stored+// values, blended, and only then decoded, so an sRGB map keeps the order of the level 0 path.+fn texture_filter_trilinear(+ desc: TextureDescriptor,+ mip_count: u32,+ level_of_detail: f32,+ format: u32,+ wrap_u: u32,+ wrap_v: u32,+ u_wrapped: f32,+ v_wrapped: f32,+) -> vec4<f32> {+ let clamped_detail = min(level_of_detail, f32(mip_count - 1u));+ let lower_level = u32(floor(clamped_detail));+ let upper_level = min(lower_level + 1u, mip_count - 1u);+ let blend = clamped_detail - f32(lower_level);+ let lower = texture_filter_level(desc, lower_level, format, wrap_u, wrap_v, u_wrapped, v_wrapped);+ if (upper_level == lower_level) {+ return texture_decode_filtered(lower, format);+ }+ let upper = texture_filter_level(desc, upper_level, format, wrap_u, wrap_v, u_wrapped, v_wrapped);+ return texture_decode_filtered(mix(lower, upper, blend), format);+}+// The one texture sampler of the kernel: shading (closure_sample_texture), bump, and the alpha tests of the integrator all// read texels here, so the visibility of a cutout and its shading agree on wrap, filter and format. `tex_index` outside the-// table or an empty descriptor reads as white.+// table or an empty descriptor reads as white. The alpha tests and the bump taps read level 0.fn texture_sample(tex_index: i32, raw_uv0: vec2<f32>, raw_uv1: vec2<f32>) -> vec4<f32> {+ return texture_sample_footprint(tex_index, raw_uv0, raw_uv1, 0.0);+}++// `uv_footprint` is the width of the ray footprint on the surface in the units of the raw uv. 0, or a texture without mip+// levels or one filtered nearest, reads level 0 exactly as before. A footprint larger than a texel reads the mip level whose+// texel is as wide as the footprint, blended with the next one.+fn texture_sample_footprint(tex_index: i32, raw_uv0: vec2<f32>, raw_uv1: vec2<f32>, uv_footprint: f32) -> vec4<f32> {if (tex_index < 0) {return vec4<f32>(1.0);}@@ -136,6 +210,16 @@ fn texture_sample(tex_index: i32, raw_uv0: vec2<f32>, raw_uv1: vec2<f32>) -> veclet w_i = i32(desc.width);let h_i = i32(desc.height);+ let mip_count = (flags >> 8u) & 0xFFu;+ if (uv_footprint > 0.0 && mip_count > 1u && !is_nearest) {+ let texels_across_u = uv_footprint * abs(desc.uv_scale.x) * f32(w_i);+ let texels_across_v = uv_footprint * abs(desc.uv_scale.y) * f32(h_i);+ let level_of_detail = log2(max(max(texels_across_u, texels_across_v), 1.0e-6));+ if (level_of_detail > 0.0) {+ return texture_filter_trilinear(desc, mip_count, level_of_detail, format, wrap_u, wrap_v, u_wrapped, v_wrapped);+ }+ }+if (is_nearest) {let ix = clamp(i32(floor(u_wrapped * f32(w_i))), 0, w_i - 1);let iy = clamp(i32(floor(v_wrapped * f32(h_i))), 0, h_i - 1);@@ -161,7 +245,7 @@ fn texture_sample(tex_index: i32, raw_uv0: vec2<f32>, raw_uv1: vec2<f32>) -> vec}fn closure_sample_texture(tex_index: i32, point: ptr<function, ShadingPoint>) -> vec4<f32> {- return texture_sample(tex_index, (*point).uv0, (*point).uv1);+ return texture_sample_footprint(tex_index, (*point).uv0, (*point).uv1, (*point).uv_footprint);}fn closure_apply_normal_map(diff --git a/packages/render-native/src/cycles/integrator.wgsl b/packages/render-native/src/cycles/integrator.wgslindex 99052090..c40452c3 100644--- a/packages/render-native/src/cycles/integrator.wgsl+++ b/packages/render-native/src/cycles/integrator.wgsl@@ -341,7 +341,60 @@ fn int_transform_normal(instance: InstanceRecord, normal_obj: vec3<f32>, fallbacreturn fallback;}-fn int_build_shading_point(surface_hit: IntSurfaceHit, wo: vec3<f32>) -> ShadingPoint {+// Ray cone of a camera ray: x is the width of the cone at the ray origin (a pixel for an orthographic camera, 0 for a pinhole),+// y its spread, the angle one pixel covers (twice the length of `camera_up`, the half height of the image plane at unit+// distance, over the image height). The aperture and the pixel filter are left out.+fn int_camera_ray_cone() -> vec2<f32> {+ let pixel_size = 2.0 * length(kernel_params.camera_up) / f32(max(kernel_params.image_height, 1u));+ if ((kernel_params.kernel_flags & KERNEL_FLAG_ORTHOGRAPHIC_CAMERA) != 0u) {+ return vec2<f32>(pixel_size, 0.0);+ }+ return vec2<f32>(0.0, pixel_size);+}++// How much a bounce widens the cone. A diffuse or sheen lobe scatters over a hemisphere, so it widens by one radian; a glossy,+// coat or glass lobe by twice its roughness alpha (at most one radian); a mirror or a straight-through lobe not at all.+// The curvature of the surface is not counted.+fn int_bounce_cone_spread(closure: ptr<function, Closure>, sampled_lobe_type: u32) -> f32 {+ if (sampled_lobe_type == LOBE_DIFFUSE || sampled_lobe_type == LOBE_SHEEN) {+ return 1.0;+ }+ var widest_alpha = 0.0;+ for (var lobe_index = 0u; lobe_index < (*closure).lobe_count; lobe_index += 1u) {+ let lobe = (*closure).lobes[lobe_index];+ if (lobe.lobe_type == sampled_lobe_type) {+ widest_alpha = max(widest_alpha, max(lobe.alpha_x, lobe.alpha_y));+ }+ }+ return min(2.0 * widest_alpha, 1.0);+}++// The width of the ray footprint on the surface in `uv0` units: the cone width at the hit, times the uv units per world unit+// of the triangle (sqrt of its uv area over its surface area). On the surface the footprint is an ellipse whose long axis is+// the cone width over cos, the cosine being that of the angle between the ray and the geometric normal. One mip level+// is chosen for both axes, from the geometric mean of the two: width over sqrt(cos), cos at least 0.1. The long axis would+// blur across the short one, the short axis would leave the long one aliased. `uv1` is read with the density of `uv0`.+// The samples of a pixel already average over its footprint, so the width is scaled by max(1/8, 1/sqrt(samples per pixel))+// as pbrt scales its ray differentials; a level as wide as the whole footprint would blur twice.+fn int_uv_footprint(+ ray_cone: vec2<f32>,+ hit_distance: f32,+ wo: vec3<f32>,+ geometric_normal: vec3<f32>,+ twice_surface_area: f32,+ twice_uv_area: f32,+) -> f32 {+ if (twice_surface_area <= 1.0e-20) {+ return 0.0;+ }+ let cone_width = ray_cone.x + ray_cone.y * hit_distance;+ let facing = max(abs(dot(wo, geometric_normal)), 0.1);+ let uv_per_world_unit = sqrt(twice_uv_area / twice_surface_area);+ let samples_per_pixel_scale = clamp(inverseSqrt(f32(max(kernel_params.total_samples, 1u))), 0.125, 1.0);+ return cone_width / sqrt(facing) * uv_per_world_unit * samples_per_pixel_scale;+}++fn int_build_shading_point(surface_hit: IntSurfaceHit, wo: vec3<f32>, ray_cone: vec2<f32>) -> ShadingPoint {let instance = instances[surface_hit.instance_index];let triangle = triangles[surface_hit.triangle_index];let bary_u = surface_hit.barycentrics.x;@@ -449,6 +502,13 @@ fn int_build_shading_point(surface_hit: IntSurfaceHit, wo: vec3<f32>) -> Shadingpoint.light_group_mask_lo = instance.light_group_mask_lo;point.vertex_color = vertex_color;point.light_group_mask_hi = instance.light_group_mask_hi;+ point.uv_footprint = 0.0;+ if ((kernel_params.kernel_flags & KERNEL_FLAG_TEXTURE_MIPS) != 0u) {+ let uv_edge1 = uv0_1 - uv0_0;+ let uv_edge2 = uv0_2 - uv0_0;+ let twice_uv_area = abs(uv_edge1.x * uv_edge2.y - uv_edge2.x * uv_edge1.y);+ point.uv_footprint = int_uv_footprint(ray_cone, surface_hit.t, wo, geometric_normal, ng_len, twice_uv_area);+ }return point;}@@ -679,6 +739,7 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {var ray_visibility = INSTANCE_VISIBILITY_CAMERA;var self_instance = INVALID_INDEX;var self_triangle = INVALID_INDEX;+ var ray_cone = vec2<f32>(0.0);var throughput = vec3<f32>(1.0);var medium_sigma = vec3<f32>(0.0);@@ -730,6 +791,7 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {ray_visibility = INSTANCE_VISIBILITY_CAMERA;self_instance = INVALID_INDEX;self_triangle = INVALID_INDEX;+ ray_cone = int_camera_ray_cone();throughput = vec3<f32>(1.0);medium_sigma = vec3<f32>(0.0);@@ -857,6 +919,7 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {throughput /= survival;}}+ ray_cone = vec2<f32>(ray_cone.x + ray_cone.y * volume_scatter_t, ray_cone.y + 1.0);ray_origin = scatter_pos;ray_dir = next_dir;ray_t_min = 0.0;@@ -901,7 +964,7 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {}let wo = -ray_dir;- var point = int_build_shading_point(surface_hit, wo);+ var point = int_build_shading_point(surface_hit, wo, ray_cone);var closure = closure_build(&point, wo);let material = materials[point.material_index];let is_pure_transparent = closure.lobe_count == 1u && closure.lobes[0].lobe_type == LOBE_TRANSPARENT;@@ -1080,6 +1143,10 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {}}+ ray_cone = vec2<f32>(+ ray_cone.x + ray_cone.y * surface_hit.t,+ ray_cone.y + int_bounce_cone_spread(&closure, bsdf_sample.sampled_lobe_type),+ );ray_origin = int_ray_offset_origin(&point, bsdf_sample.wi);ray_dir = bsdf_sample.wi;ray_t_min = 0.0;diff --git a/packages/render-native/src/cycles/mod.rs b/packages/render-native/src/cycles/mod.rsindex 0942b714..59193847 100644--- a/packages/render-native/src/cycles/mod.rs+++ b/packages/render-native/src/cycles/mod.rs@@ -1144,6 +1144,40 @@ mod tests {assert!(kernel.contains("texture_decode_filtered(texture_fetch_texel(desc, ix, iy, format), format)"));}+ /// Mip levels are opt in. The shared sampler without a footprint, which the alpha tests and the bump taps use, must read+ /// level 0 only, and a hit hands a footprint to the sampler only when the kernel flag is set.+ #[test]+ fn mip_levels_are_read_only_for_a_footprint_and_only_with_the_kernel_flag() {+ let kernel = assemble_cycles_kernel().expect("the kernel assembles");+ assert!(kernel.contains("const KERNEL_FLAG_TEXTURE_MIPS: u32 = 2048u;"));+ assert!(kernel.contains("return texture_sample_footprint(tex_index, raw_uv0, raw_uv1, 0.0);"));+ assert!(kernel.contains("texture_sample_footprint(tex_index, (*point).uv0, (*point).uv1, (*point).uv_footprint)"));+ assert!(kernel.contains("if (uv_footprint > 0.0 && mip_count > 1u && !is_nearest)"));+ let build_start = kernel.find("fn int_build_shading_point(").expect("the shading point builder exists");+ let build_body = &kernel[build_start..];+ let flag_test = build_body.find("(kernel_params.kernel_flags & KERNEL_FLAG_TEXTURE_MIPS) != 0u").expect("the footprint is gated by the flag");+ let footprint_call = build_body.find("point.uv_footprint = int_uv_footprint(").expect("the footprint is computed");+ assert!(flag_test < footprint_call);+ assert!(build_body.contains("point.uv_footprint = 0.0;"));+ }++ /// The mip levels sit after level 0 in one run of words (`texture_fetch_texel` stays the only reader of the pool).+ #[test]+ fn a_mip_level_is_found_by_walking_the_halving_chain_from_level_0() {+ let kernel = assemble_cycles_kernel().expect("the kernel assembles");+ let walk_start = kernel.find("fn texture_level_descriptor(").expect("the level descriptor walk exists");+ let walk_end = walk_start + kernel[walk_start..].find("\n}").expect("the walk ends");+ let walk = &kernel[walk_start..walk_end];+ assert!(walk.contains("select(1u, 4u, format == 2u)"));+ assert!(walk.contains("level_desc.width * level_desc.height * words_per_texel"));+ assert!(walk.contains("max(level_desc.width >> 1u, 1u)"));+ assert!(walk.contains("max(level_desc.height >> 1u, 1u)"));+ assert!(kernel.contains("return texture_decode_filtered(mix(lower, upper, blend), format);"));+ let level_start = kernel.find("fn texture_filter_level(").expect("the level filter exists");+ let level_end = level_start + kernel[level_start..].find("\n}").expect("the level filter ends");+ assert!(!kernel[level_start..level_end].contains("texture_decode_filtered"), "a mip level is blended on stored values and decoded after, as level 0 is");+ }+#[test]fn the_bootstrap_entry_samples_alpha_through_the_shared_sampler() {let bootstrap = include_str!("bootstrap_main.wgsl");diff --git a/packages/render-native/texture-mips.mjs b/packages/render-native/texture-mips.mjsnew file mode 100644index 00000000..f8c5b6d5--- /dev/null+++ b/packages/render-native/texture-mips.mjs@@ -0,0 +1,228 @@+// Mip chains for the texture pool of FORMAT-v2 (issue 896). Pure functions on typed arrays, no GPU.+//+// Level 0 is the texture as the caller gave it. Each level after it is half as wide and as high, rounded down and never less+// than one texel, and is the plain average of the 2 x 2 texels of the level before it. A linear 8-bit map and a float map are+// averaged on their stored values. An sRGB map is averaged in linear light and encoded back to bytes: the kernel still filters+// its bytes and decodes the blend, as at level 0, but a level that held the mean of the stored bytes would read darker than+// the mean of the light (a black and white checker: 0.21 against 0.5 once decoded), and a minified surface would turn+// darker than the same surface supersampled. The alpha channel is averaged on its stored values and not weighted by itself, so a texel with alpha 0 pulls its+// colour into the next level; a map whose alpha is a cutout should not ask for levels. Where a side has an odd length, the+// last row or column has no pair: it is averaged with itself in the next level's last texel, and the one beyond the halved+// size is not read. Normal maps are averaged as stored and are not normalised again; the kernel normalises the result.++export const TEXTURE_KIND_RGBA8 = 'rgba8';+export const TEXTURE_KIND_RGBA8_SRGB = 'rgba8-srgb';+export const TEXTURE_KIND_RGBA32_FLOAT = 'rgba32f';+export const TEXTURE_KIND_RG16_FLOAT = 'rg16f';++const MAX_TEXTURE_SIDE = 1 << 20;++const halfScratchView = new DataView(new ArrayBuffer(4));++/** The float value of an IEEE half-precision bit pattern. */+export function halfToFloat(halfBits) {+ const sign = (halfBits & 0x8000) === 0 ? 1 : -1;+ const exponent = (halfBits >> 10) & 0x1f;+ const fraction = halfBits & 0x3ff;+ if (exponent === 0) {+ return sign * (fraction / 1024) * 2 ** -14;+ }+ if (exponent === 31) {+ return fraction === 0 ? sign * Infinity : Number.NaN;+ }+ return sign * (1 + fraction / 1024) * 2 ** (exponent - 15);+}++/** The IEEE half-precision bit pattern nearest to `value` (ties to even; too large becomes infinity). */+export function floatToHalf(value) {+ halfScratchView.setFloat32(0, value);+ const bits = halfScratchView.getUint32(0);+ const signBit = (bits >>> 16) & 0x8000;+ const exponent = (bits >>> 23) & 0xff;+ const mantissa = bits & 0x7fffff;+ if (exponent === 0xff) {+ return signBit | 0x7c00 | (mantissa === 0 ? 0 : 0x200);+ }+ const halfExponent = exponent - 127 + 15;+ if (halfExponent >= 31) {+ return signBit | 0x7c00;+ }+ if (halfExponent <= 0) {+ if (halfExponent < -10) {+ return signBit;+ }+ const withLeadingBit = mantissa | 0x800000;+ const shift = 14 - halfExponent;+ let subnormal = withLeadingBit >>> shift;+ const roundBit = (withLeadingBit >>> (shift - 1)) & 1;+ const stickyBits = withLeadingBit & ((1 << (shift - 1)) - 1);+ if (roundBit === 1 && (stickyBits !== 0 || (subnormal & 1) === 1)) {+ subnormal += 1;+ }+ return signBit | subnormal;+ }+ let half = (halfExponent << 10) | (mantissa >>> 13);+ if ((mantissa & 0x1000) !== 0 && ((mantissa & 0x0fff) !== 0 || (half & 1) === 1)) {+ half += 1;+ }+ return signBit | half;+}++function requireTextureSide(width, height) {+ const isValid = Number.isInteger(width) && Number.isInteger(height) && width >= 1 && height >= 1 && width <= MAX_TEXTURE_SIDE && height <= MAX_TEXTURE_SIDE;+ if (!isValid) {+ throw new RangeError(`A texture side must be an integer from 1 to ${MAX_TEXTURE_SIDE}, got ${width}x${height}. Pass the width and height of the image.`);+ }+}++/** The number of levels of a full chain, level 0 included: 1 + floor(log2(longest side)). */+export function mipLevelCount(width, height) {+ requireTextureSide(width, height);+ return 32 - Math.clz32(Math.max(width, height));+}++/** The size of level `level`: each side halved `level` times, rounded down, never below 1. */+export function mipLevelSize(width, height, level) {+ return { width: Math.max(1, width >> level), height: Math.max(1, height >> level) };+}++function wordsPerTexel(kind) {+ return kind === TEXTURE_KIND_RGBA32_FLOAT ? 4 : 1;+}++/** The 32-bit words the levels after level 0 take, with no padding between levels. */+export function mipChainWordCount(kind, width, height) {+ const levelCount = mipLevelCount(width, height);+ let totalWords = 0;+ for (let level = 1; level < levelCount; level++) {+ const size = mipLevelSize(width, height, level);+ totalWords += size.width * size.height * wordsPerTexel(kind);+ }+ return totalWords;+}++// Calls `visit(destinationIndex, topLeft, topRight, bottomLeft, bottomRight)` with the texel indexes of the 2 x 2 block of the+// source level that the destination texel covers. A side of one texel, or the last column of an odd side, reads itself twice.+function visitBlocks(sourceWidth, sourceHeight, destinationWidth, destinationHeight, visit) {+ for (let row = 0; row < destinationHeight; row++) {+ const topRow = Math.min(row * 2, sourceHeight - 1);+ const bottomRow = Math.min(row * 2 + 1, sourceHeight - 1);+ for (let column = 0; column < destinationWidth; column++) {+ const leftColumn = Math.min(column * 2, sourceWidth - 1);+ const rightColumn = Math.min(column * 2 + 1, sourceWidth - 1);+ visit(+ row * destinationWidth + column,+ topRow * sourceWidth + leftColumn,+ topRow * sourceWidth + rightColumn,+ bottomRow * sourceWidth + leftColumn,+ bottomRow * sourceWidth + rightColumn,+ );+ }+ }+}++function averageBytes(first, second, third, fourth) {+ return (first + second + third + fourth + 2) >> 2;+}++function srgbByteToLinearTable() {+ const table = new Float64Array(256);+ for (let byteValue = 0; byteValue < 256; byteValue++) {+ const encoded = byteValue / 255;+ table[byteValue] = encoded <= 0.04045 ? encoded / 12.92 : ((encoded + 0.055) / 1.055) ** 2.4;+ }+ return table;+}++const SRGB_BYTE_TO_LINEAR = srgbByteToLinearTable();++function linearToSrgbByte(linear) {+ const clamped = Math.min(1, Math.max(0, linear));+ const encoded = clamped <= 0.0031308 ? clamped * 12.92 : 1.055 * clamped ** (1 / 2.4) - 0.055;+ return Math.round(encoded * 255);+}++function averageSrgbBytesInLinearLight(first, second, third, fourth) {+ return linearToSrgbByte((SRGB_BYTE_TO_LINEAR[first] + SRGB_BYTE_TO_LINEAR[second] + SRGB_BYTE_TO_LINEAR[third] + SRGB_BYTE_TO_LINEAR[fourth]) * 0.25);+}++function averageRgba8Level(source, destination, sourceWidth, sourceHeight, destinationWidth, destinationHeight, isSrgb = false) {+ visitBlocks(sourceWidth, sourceHeight, destinationWidth, destinationHeight, (target, topLeft, topRight, bottomLeft, bottomRight) => {+ let packed = 0;+ for (let channel = 0; channel < 4; channel++) {+ const shift = channel * 8;+ const averageOfChannel = isSrgb && channel < 3 ? averageSrgbBytesInLinearLight : averageBytes;+ const average = averageOfChannel(+ (source[topLeft] >>> shift) & 0xff,+ (source[topRight] >>> shift) & 0xff,+ (source[bottomLeft] >>> shift) & 0xff,+ (source[bottomRight] >>> shift) & 0xff,+ );+ packed |= average << shift;+ }+ destination[target] = packed >>> 0;+ });+}++function averageFloatLevel(source, destination, sourceWidth, sourceHeight, destinationWidth, destinationHeight) {+ visitBlocks(sourceWidth, sourceHeight, destinationWidth, destinationHeight, (target, topLeft, topRight, bottomLeft, bottomRight) => {+ for (let channel = 0; channel < 4; channel++) {+ destination[target * 4 + channel] = (+ source[topLeft * 4 + channel] + source[topRight * 4 + channel] + source[bottomLeft * 4 + channel] + source[bottomRight * 4 + channel]+ ) * 0.25;+ }+ });+}++function averageHalfPairLevel(source, destination, sourceWidth, sourceHeight, destinationWidth, destinationHeight) {+ visitBlocks(sourceWidth, sourceHeight, destinationWidth, destinationHeight, (target, topLeft, topRight, bottomLeft, bottomRight) => {+ let packed = 0;+ for (let channel = 0; channel < 2; channel++) {+ const shift = channel * 16;+ const total = halfToFloat((source[topLeft] >>> shift) & 0xffff)+ + halfToFloat((source[topRight] >>> shift) & 0xffff)+ + halfToFloat((source[bottomLeft] >>> shift) & 0xffff)+ + halfToFloat((source[bottomRight] >>> shift) & 0xffff);+ packed |= floatToHalf(total * 0.25) << shift;+ }+ destination[target] = packed >>> 0;+ });+}++/**+ * The levels after level 0 of one texture, one after the other, as 32-bit words. `texels` holds level 0 without padding:+ * one word per texel for `rgba8` and `rgba8-srgb` (bytes r, g, b, a from the low byte) and `rg16f` (two halves, r in the low half), four+ * floats per texel for `rgba32f`. Returns an empty array for a texture of one texel.+ */+export function buildMipChain(kind, texels, width, height) {+ requireTextureSide(width, height);+ const levelCount = mipLevelCount(width, height);+ const chain = new Uint32Array(mipChainWordCount(kind, width, height));+ if (levelCount === 1) {+ return chain;+ }+ const isFloat = kind === TEXTURE_KIND_RGBA32_FLOAT;+ const average = {+ [TEXTURE_KIND_RGBA8]: averageRgba8Level,+ [TEXTURE_KIND_RGBA8_SRGB]: (...levelArguments) => averageRgba8Level(...levelArguments, true),+ [TEXTURE_KIND_RGBA32_FLOAT]: averageFloatLevel,+ [TEXTURE_KIND_RG16_FLOAT]: averageHalfPairLevel,+ }[kind];+ if (!average) {+ throw new RangeError(`buildMipChain: kind must be "${TEXTURE_KIND_RGBA8}", "${TEXTURE_KIND_RGBA8_SRGB}", "${TEXTURE_KIND_RGBA32_FLOAT}" or "${TEXTURE_KIND_RG16_FLOAT}", got ${JSON.stringify(kind)}.`);+ }+ let source = isFloat ? new Float32Array(texels.buffer, texels.byteOffset, width * height * 4) : texels;+ let sourceSize = { width, height };+ let cursor = 0;+ for (let level = 1; level < levelCount; level++) {+ const destinationSize = mipLevelSize(width, height, level);+ const levelWords = destinationSize.width * destinationSize.height * wordsPerTexel(kind);+ const destinationWords = chain.subarray(cursor, cursor + levelWords);+ const destination = isFloat ? new Float32Array(destinationWords.buffer, destinationWords.byteOffset, levelWords) : destinationWords;+ average(source, destination, sourceSize.width, sourceSize.height, destinationSize.width, destinationSize.height);+ source = destination;+ sourceSize = destinationSize;+ cursor += levelWords;+ }+ return chain;+}diff --git a/tests/native-texture-mips.test.js b/tests/native-texture-mips.test.jsnew file mode 100644index 00000000..e4a2103f--- /dev/null+++ b/tests/native-texture-mips.test.js@@ -0,0 +1,310 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { STRUCT_STRIDES_V2, buildNativeInputV2, findNativeAddon, traceNative } from '../packages/render-native/index.mjs';+import {+ KERNEL_FLAG_TEXTURE_MIPS,+ KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET,+ TEXTURE_POOL_MAX_BYTES,+} from '../packages/render-native/pack-input-v2.mjs';+import {+ TEXTURE_KIND_RG16_FLOAT,+ TEXTURE_KIND_RGBA32_FLOAT,+ TEXTURE_KIND_RGBA8,+ TEXTURE_KIND_RGBA8_SRGB,+ buildMipChain,+ floatToHalf,+ halfToFloat,+ mipChainWordCount,+ mipLevelCount,+ mipLevelSize,+} from '../packages/render-native/texture-mips.mjs';+import { createCamera } from '../src/path-tracer.js';++const QUAD_UVS = new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]);+const FORMAT_RGBA8_UNORM = 0;+const FORMAT_RGBA8_SRGB = 1;+const FORMAT_RGBA32_FLOAT = 2;+const FORMAT_RG16_FLOAT = 3;++function quadGeometry(z = 0) {+ return {+ positions: new Float32Array([-1, -1, z, 1, -1, z, 1, 1, z, -1, 1, z]),+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),+ uvs: QUAD_UVS,+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+ };+}++function packedWord(red, green, blue, alpha) {+ return (red | (green << 8) | (blue << 16) | (alpha << 24)) >>> 0;+}++function byteImage(width, height, fillTexel) {+ const data = new Uint8Array(width * height * 4);+ for (let pixel = 0; pixel < width * height; pixel++) {+ const texel = fillTexel(pixel % width, Math.floor(pixel / width));+ data.set(texel, pixel * 4);+ }+ return { width, height, data };+}++function packMaterials(materials, options = {}) {+ const camera = createCamera({ eye: [0, 0, 3], target: [0, 0, 0], fov: 40 }, 8, 8);+ return buildNativeInputV2(+ {+ materials,+ instances: materials.map((_, index) => ({ geometry: quadGeometry(index), materialIndex: index })),+ lights: {},+ },+ camera,+ { width: 8, height: 8, samples: 1, ...options },+ );+}++function packMaps(maps, options = {}) {+ return packMaterials(maps.map((map) => ({ color: [1, 1, 1], map })), options);+}++function descriptorWord(input, textureIndex, wordIndex) {+ const stride = STRUCT_STRIDES_V2.textureDescriptor;+ const view = new Uint32Array(input.textureDescriptors.buffer, input.textureDescriptors.byteOffset + textureIndex * stride, stride / 4);+ return view[wordIndex];+}++function mipCountOf(input, textureIndex) {+ return (descriptorWord(input, textureIndex, 3) >>> 8) & 0xff;+}++function kernelFlagsOf(input) {+ return new DataView(input.kernelParams.buffer, input.kernelParams.byteOffset, input.kernelParams.byteLength)+ .getUint32(KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET, true);+}++test('the level count and sizes halve each side down to one texel, rounding down', () => {+ assert.equal(mipLevelCount(1, 1), 1);+ assert.equal(mipLevelCount(2, 2), 2);+ assert.equal(mipLevelCount(16, 4), 5);+ assert.equal(mipLevelCount(5, 3), 3);+ assert.deepEqual(mipLevelSize(16, 4, 1), { width: 8, height: 2 });+ assert.deepEqual(mipLevelSize(16, 4, 3), { width: 2, height: 1 });+ assert.deepEqual(mipLevelSize(16, 4, 4), { width: 1, height: 1 });+ assert.deepEqual(mipLevelSize(5, 3, 1), { width: 2, height: 1 });+ assert.equal(mipChainWordCount(TEXTURE_KIND_RGBA8, 4, 4), 4 + 1);+ assert.equal(mipChainWordCount(TEXTURE_KIND_RGBA32_FLOAT, 4, 4), (4 + 1) * 4);+ assert.throws(() => mipLevelCount(0, 4), /texture side must be an integer from 1/);+});++test('half floats round trip the values a mip average produces', () => {+ for (const value of [0, 1, -1, 0.5, 0.333251953125, 65504, 6.103515625e-5, 5.960464477539063e-8]) {+ assert.equal(halfToFloat(floatToHalf(value)), value);+ }+ assert.equal(floatToHalf(1e9), 0x7c00);+ assert.equal(floatToHalf(-1e9), 0xfc00);+ assert.equal(floatToHalf(1e-9), 0);+ assert.equal(floatToHalf(1.00048828125), floatToHalf(1), 'a tie rounds to the even neighbour');+});++test('an 8-bit chain averages the stored bytes of each 2 x 2 block, alpha included, with rounding', () => {+ const level0 = new Uint32Array([+ packedWord(0, 0, 0, 255), packedWord(255, 255, 255, 255),+ packedWord(255, 255, 255, 255), packedWord(0, 0, 0, 255),+ ]);+ const chain = buildMipChain(TEXTURE_KIND_RGBA8, level0, 2, 2);+ assert.equal(chain.length, 1);+ assert.equal(chain[0], packedWord(128, 128, 128, 255));+ const transparent = new Uint32Array([packedWord(200, 0, 0, 0), packedWord(0, 0, 0, 255), packedWord(0, 0, 0, 255), packedWord(0, 0, 0, 255)]);+ assert.equal(buildMipChain(TEXTURE_KIND_RGBA8, transparent, 2, 2)[0], packedWord(50, 0, 0, 191), 'alpha is averaged, not used as a weight');+});++test('a chain of an uneven or thin texture keeps every level the size the kernel walks to', () => {+ const level0 = Uint32Array.from({ length: 5 * 3 }, (_, index) => packedWord(index * 10, 0, 0, 255));+ const chain = buildMipChain(TEXTURE_KIND_RGBA8, level0, 5, 3);+ assert.equal(chain.length, 2 * 1 + 1 * 1);+ assert.equal(chain[0] & 0xff, Math.round((0 + 10 + 50 + 60) / 4), 'first texel of level 1 averages the top left block');+ assert.equal(chain[1] & 0xff, Math.round((20 + 30 + 70 + 80) / 4), 'the fifth column has no pair and is not read');+ assert.equal(chain[2] & 0xff, Math.round(((chain[0] & 0xff) + (chain[1] & 0xff)) / 2), 'level 2 is the 1 x 1 average of the two texels of level 1');+ assert.equal(buildMipChain(TEXTURE_KIND_RGBA8, new Uint32Array(1), 1, 1).length, 0);+});++test('a float chain averages the floats without clamping, so a bright texel keeps its energy', () => {+ const level0 = new Float32Array([8, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1]);+ const chain = buildMipChain(TEXTURE_KIND_RGBA32_FLOAT, level0, 2, 2);+ assert.equal(chain.length, 4);+ assert.deepEqual(Array.from(new Float32Array(chain.buffer, chain.byteOffset, 4)), [2, 0, 0, 1]);+});++test('a two-channel half chain averages each channel as a float', () => {+ const pair = (red, green) => (floatToHalf(red) | (floatToHalf(green) << 16)) >>> 0;+ const level0 = new Uint32Array([pair(1, 0), pair(0, 0), pair(0, 0.5), pair(0, 0)]);+ const chain = buildMipChain(TEXTURE_KIND_RG16_FLOAT, level0, 2, 2);+ assert.equal(halfToFloat(chain[0] & 0xffff), 0.25);+ assert.equal(halfToFloat(chain[0] >>> 16), 0.125);+});++test('without textureMips a texture is level 0 only, the flag is clear and the pool is as it was', () => {+ const image = byteImage(8, 8, (x, y) => [x * 30, y * 30, 7, 255]);+ const byDefault = packMaps([{ image }]);+ const explicitOff = packMaps([{ image }], { textureMips: false });+ assert.equal(mipCountOf(byDefault, 0), 1);+ assert.equal(byDefault.textureTexels.length, 64);+ assert.equal(kernelFlagsOf(byDefault) & KERNEL_FLAG_TEXTURE_MIPS, 0);+ assert.deepEqual(explicitOff.textureTexels, byDefault.textureTexels);+ assert.deepEqual(explicitOff.textureDescriptors, byDefault.textureDescriptors);+ assert.deepEqual(explicitOff.kernelParams, byDefault.kernelParams);+});++test('textureMips stores the chain after level 0, counts the levels in the descriptor and sets the kernel flag', () => {+ const image = byteImage(8, 8, (x, y) => [x * 30, y * 30, 7, 255]);+ const off = packMaps([{ image, colorSpace: 'linear' }]);+ const on = packMaps([{ image, colorSpace: 'linear' }], { textureMips: true });+ assert.equal(KERNEL_FLAG_TEXTURE_MIPS, 2048);+ assert.equal(mipCountOf(on, 0), 4);+ assert.equal(kernelFlagsOf(on) & KERNEL_FLAG_TEXTURE_MIPS, KERNEL_FLAG_TEXTURE_MIPS);+ assert.equal(kernelFlagsOf(on) & ~KERNEL_FLAG_TEXTURE_MIPS, kernelFlagsOf(off));+ assert.equal(on.textureTexels.length, 64 + 16 + 4 + 1 + 3, 'padded once to four words at the end');+ assert.deepEqual(on.textureTexels.subarray(0, 64), off.textureTexels.subarray(0, 64), 'level 0 is untouched');+ assert.equal(on.textureTexels[64] & 0xff, Math.round((0 + 30 + 0 + 30) / 4), 'level 1 starts right after level 0');+ assert.ok(Math.abs((on.textureTexels[64 + 16 + 4] & 0xff) - 105) <= 1, 'level 3 is one texel holding the mean of the red ramp');+});++test('an sRGB chain averages in linear light and stores bytes again, alpha on its stored value', () => {+ const blackAndWhite = new Uint32Array([packedWord(0, 0, 0, 255), packedWord(255, 255, 255, 255), packedWord(255, 255, 255, 255), packedWord(0, 0, 0, 200)]);+ const chain = buildMipChain(TEXTURE_KIND_RGBA8_SRGB, blackAndWhite, 2, 2);+ assert.equal(chain[0], packedWord(188, 188, 188, 241), 'half the light is the byte 188, not the byte 128');+ assert.equal(buildMipChain(TEXTURE_KIND_RGBA8, blackAndWhite, 2, 2)[0], packedWord(128, 128, 128, 241), 'a linear map keeps the plain average');+ const grey = new Uint32Array(4).fill(packedWord(77, 77, 77, 255));+ assert.equal(buildMipChain(TEXTURE_KIND_RGBA8_SRGB, grey, 2, 2)[0], packedWord(77, 77, 77, 255), 'a flat colour survives the round trip');+});++test('an sRGB map keeps its format at every level and its levels hold the mean of the light', () => {+ const checker = byteImage(2, 2, (x, y) => ((x + y) % 2 === 0 ? [0, 0, 0, 255] : [255, 255, 255, 255]));+ const input = packMaps([{ image: checker, colorSpace: 'srgb' }], { textureMips: true });+ assert.equal(descriptorWord(input, 0, 3) & 0xff, FORMAT_RGBA8_SRGB);+ assert.equal(input.textureTexels[4], packedWord(188, 188, 188, 255), 'the level holds half the light of black and white, which is the stored byte 188');+});++test('mips are per texture too: mips true on one map, false on another, and nearest maps never take levels', () => {+ const image = byteImage(8, 8, () => [10, 20, 30, 255]);+ const mixed = packMaps([{ image, mips: true }, { image: byteImage(8, 8, () => [1, 2, 3, 255]), mips: false }]);+ assert.equal(mipCountOf(mixed, 0), 4);+ assert.equal(mipCountOf(mixed, 1), 1);+ assert.equal(kernelFlagsOf(mixed) & KERNEL_FLAG_TEXTURE_MIPS, KERNEL_FLAG_TEXTURE_MIPS);+ const overridden = packMaps([{ image, mips: false }], { textureMips: true });+ assert.equal(mipCountOf(overridden, 0), 1);+ assert.equal(kernelFlagsOf(overridden) & KERNEL_FLAG_TEXTURE_MIPS, 0, 'no texture stores levels, so the kernel carries no footprint');+ const nearest = packMaps([{ image, nearest: true }], { textureMips: true });+ assert.equal(mipCountOf(nearest, 0), 1);+ const single = packMaps([{ image: byteImage(1, 1, () => [9, 9, 9, 255]) }], { textureMips: true });+ assert.equal(mipCountOf(single, 0), 1);+});++test('one image with and without levels stays two descriptors, and the uv transform stays in the key', () => {+ const image = byteImage(8, 8, () => [5, 5, 5, 255]);+ const split = packMaps([{ image, mips: true }, { image, mips: false }]);+ assert.equal(split.textureCount, 2);+ const same = packMaps([{ image }, { image }], { textureMips: true });+ assert.equal(same.textureCount, 1);+ const scaled = packMaps([{ image, uvScale: [2, 2] }, { image }], { textureMips: true });+ assert.equal(scaled.textureCount, 2);+ const offset = packMaps([{ image, uvOffset: [0.5, 0] }, { image }], { textureMips: true });+ assert.equal(offset.textureCount, 2);+ const wrapped = packMaps([{ image, wrapU: 1 }, { image }], { textureMips: true });+ assert.equal(wrapped.textureCount, 2);+});++test('float and half textures are packed in their own formats, with levels on request', () => {+ const floatData = new Float32Array(4 * 4 * 4).fill(0.5);+ floatData.set([12, 6, 3, 1], 0);+ const halfData = new Uint16Array(4 * 4 * 2).fill(floatToHalf(0.25));+ const input = packMaterials(+ [+ { color: [0, 0, 0], emissiveTexture: { image: { width: 4, height: 4, data: floatData } } },+ { color: [1, 1, 1], normalMap: { image: { width: 4, height: 4, data: halfData } } },+ ],+ { textureMips: true },+ );+ assert.equal(input.textureCount, 2);+ assert.equal(descriptorWord(input, 0, 3) & 0xff, FORMAT_RGBA32_FLOAT);+ assert.equal(descriptorWord(input, 1, 3) & 0xff, FORMAT_RG16_FLOAT);+ assert.equal(mipCountOf(input, 0), 3);+ const floatTexels = new Float32Array(input.textureTexels.buffer, input.textureTexels.byteOffset, 64 + 16 + 4);+ assert.deepEqual(Array.from(floatTexels.subarray(0, 4)), [12, 6, 3, 1], 'an HDR texel is stored unclamped');+ assert.equal(floatTexels[64], (12 + 0.5 + 0.5 + 0.5) / 4, 'level 1 averages the unclamped floats');+ const halfStart = descriptorWord(input, 1, 0);+ assert.equal(halfToFloat(input.textureTexels[halfStart + 16] & 0xffff), 0.25);+});++test('textureMips and mips fail at the boundary with what to pass', () => {+ const image = byteImage(4, 4, () => [1, 1, 1, 255]);+ assert.throws(() => packMaps([{ image }], { textureMips: 'yes' }), (error) => {+ assert.ok(error instanceof TypeError);+ assert.match(error.message, /`textureMips` must be true \(store mip levels\), false or left out/);+ assert.match(error.message, /got "yes"/);+ return true;+ });+ assert.throws(() => packMaps([{ image, mips: 1 }]), /`mips` must be true/);+});++test('the pool budget counts the mip levels', () => {+ // 16384 x 16384 bytes-per-texel 4 is exactly the 1 GiB pool: level 0 alone would fit, the chain on top of it does not.+ const side = 16384;+ assert.equal(side * side * 4, TEXTURE_POOL_MAX_BYTES);+ assert.equal(mipChainWordCount(TEXTURE_KIND_RGBA8, side, side), (side * side - 1) / 3, 'the chain adds a third of level 0');+ const oversize = { width: side, height: side, data: new Uint8Array(4) };+ assert.throws(+ () => packMaps([{ image: oversize, mips: true }]),+ (error) => {+ assert.ok(error instanceof RangeError);+ assert.match(error.message, /texture pool is full: the 16384x16384 texture needs 1366 MiB/);+ return true;+ },+ );+});++// ---- GPU-gated: the kernel reads the levels ----++const gpuSkip = { skip: !findNativeAddon() };++test('a magnified texture reads level 0 with mip levels on, to the last bit', gpuSkip, async () => {+ const { renderFloor, maxAbsoluteDifference } = await import('../bench/cycles-parity/texture-mips-bench.mjs');+ const settings = { cameraName: 'magnified', samples: 4, seed: 3, width: 48, height: 27 };+ const withoutMips = renderFloor({ ...settings, textureMips: false });+ const withMips = renderFloor({ ...settings, textureMips: true });+ assert.equal(maxAbsoluteDifference(withoutMips, withMips), 0);+});++test('a minified checker reads other levels with mip levels on, and stays finite', gpuSkip, async () => {+ const { renderFloor, maxAbsoluteDifference } = await import('../bench/cycles-parity/texture-mips-bench.mjs');+ const settings = { cameraName: 'receding', width: 96, height: 54, samples: 16, seed: 5 };+ const withoutMips = renderFloor({ ...settings, textureMips: false });+ const withMips = renderFloor({ ...settings, textureMips: true });+ assert.ok(withMips.every(Number.isFinite));+ assert.ok(maxAbsoluteDifference(withoutMips, withMips) > 0.01, 'the far floor is read at a coarser level');+});++test('an HDR float emissive map keeps values above one through the kernel, with and without levels', gpuSkip, () => {+ const size = 9;+ const camera = createCamera({ eye: [0, 0, 2.2], target: [0, 0, 0], fov: 30 }, size, size);+ const texelValue = 4;+ const hdrData = new Float32Array(4 * 4 * 4);+ for (let texel = 0; texel < 16; texel++) {+ hdrData.set([texelValue, texelValue * 0.5, texelValue * 0.25, 1], texel * 4);+ }+ for (const textureMips of [false, true]) {+ const options = { width: size, height: size, samples: 4, textureMips };+ const input = buildNativeInputV2(+ {+ materials: [{ color: [0, 0, 0], emissionStrength: 1, emissionColor: [1, 1, 1], emissiveTexture: { image: { width: 4, height: 4, data: hdrData } } }],+ instances: [{ geometry: quadGeometry(0), materialIndex: 0 }],+ lights: {},+ },+ camera,+ options,+ );+ assert.equal(descriptorWord(input, 0, 3) & 0xff, FORMAT_RGBA32_FLOAT);+ const result = traceNative(input, { ...options, kernel: 'cycles' });+ const centrePixel = Math.floor(size / 2) * size + Math.floor(size / 2);+ assert.ok(Math.abs(result.rgba[centrePixel * 4] - texelValue) < 0.05, `centre red ${result.rgba[centrePixel * 4]} (levels ${textureMips})`);+ assert.ok(Math.abs(result.rgba[centrePixel * 4 + 1] - texelValue * 0.5) < 0.05);+ }+});