Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Read cutout alpha through the shared texture sampler and fail early on an oversize texture pool (#896)

Nguyen Xuan Ance6c20a60613
diff --git a/bench/cycles-parity/texture-pool-bench.mjs b/bench/cycles-parity/texture-pool-bench.mjs
new file mode 100644
index 00000000..539695e7
--- /dev/null
+++ b/bench/cycles-parity/texture-pool-bench.mjs
@@ -0,0 +1,92 @@
+// Cost of a scene with many textures on the native Cycles host: pack time, setup, compile and upload seconds, and the
+// peak resident memory of this process (one scene per process, so the peak is the scene's).
+// node bench/cycles-parity/texture-pool-bench.mjs [--textures 256] [--size 512]
+// Prints one JSON line. A scene whose textures do not fit one pool prints the error text instead of a trace.
+import { buildNativeInputV2, findNativeAddon, traceNative } from '../../packages/render-native/index.mjs';
+import { createCamera } from '../../src/path-tracer.js';
+
+const IMAGE_WIDTH = 64;
+const IMAGE_HEIGHT = 36;
+
+function readNumberFlag(flagName, fallbackValue) {
+ const flagIndex = process.argv.indexOf(flagName);
+ if (flagIndex === -1) {
+ return fallbackValue;
+ }
+ const parsed = Number(process.argv[flagIndex + 1]);
+ if (!Number.isInteger(parsed) || parsed < 1) {
+ throw new RangeError(`Flag ${flagName} must be a positive integer, got ${process.argv[flagIndex + 1]}.`);
+ }
+ return parsed;
+}
+
+function quadGeometry() {
+ return {
+ positions: new Float32Array([-1, -1, 0, 1, -1, 0, 1, 1, 0, -1, 1, 0]),
+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),
+ uvs: new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]),
+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+ };
+}
+
+function noiseImage(size, seed) {
+ const data = new Uint8Array(size * size * 4);
+ let state = (seed * 2654435761) >>> 0;
+ for (let index = 0; index < data.length; index++) {
+ state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+ data[index] = state >>> 24;
+ }
+ return { width: size, height: size, data };
+}
+
+function buildScene(textureCount, size) {
+ const columns = Math.ceil(Math.sqrt(textureCount));
+ const geometry = quadGeometry();
+ const materials = [];
+ const instances = [];
+ for (let index = 0; index < textureCount; index++) {
+ materials.push({ color: [1, 1, 1], roughness: 0.7, map: { image: noiseImage(size, index + 1), colorSpace: 'srgb' } });
+ const column = index % columns;
+ const row = Math.floor(index / columns);
+ const matrix = [0.45, 0, 0, 0, 0, 0.45, 0, 0, 0, 0, 1, 0, (column - columns / 2) * 1.0, (row - columns / 2) * 1.0, 0, 1];
+ instances.push({ geometry, matrix, materialIndex: index });
+ }
+ return { materials, instances, lights: { points: [{ position: [0, 0, 10], color: [1, 1, 1], intensity: 400, radius: 0.1 }] } };
+}
+
+function run() {
+ const textureCount = readNumberFlag('--textures', 256);
+ const size = readNumberFlag('--size', 512);
+ const report = { textures: textureCount, size, poolMebibytes: (textureCount * size * size * 4) / (1 << 20) };
+ if (!findNativeAddon()) {
+ console.log(JSON.stringify({ ...report, skipped: 'no native addon' }));
+ return;
+ }
+ const camera = createCamera({ eye: [0, 0, 24], target: [0, 0, 0], fov: 50 }, IMAGE_WIDTH, IMAGE_HEIGHT);
+ const packStarted = performance.now();
+ const input = buildScene(textureCount, size);
+ let nativeInput;
+ try {
+ nativeInput = buildNativeInputV2(input, camera, { width: IMAGE_WIDTH, height: IMAGE_HEIGHT, samples: 1 });
+ } catch (error) {
+ console.log(JSON.stringify({ ...report, stage: 'pack', error: error.message }));
+ return;
+ }
+ report.packSeconds = (performance.now() - packStarted) / 1000;
+ const traceStarted = performance.now();
+ try {
+ const result = traceNative(nativeInput, { width: IMAGE_WIDTH, height: IMAGE_HEIGHT, samples: 1, kernel: 'cycles' });
+ report.traceWallSeconds = (performance.now() - traceStarted) / 1000;
+ report.setupSeconds = result.setupSeconds;
+ report.compileSeconds = result.compileSeconds;
+ report.uploadSeconds = result.uploadSeconds;
+ report.adapter = result.adapter;
+ } catch (error) {
+ report.stage = 'trace';
+ report.error = error.message;
+ }
+ report.peakRssMebibytes = process.resourceUsage().maxRSS / 1024;
+ console.log(JSON.stringify(report));
+}
+
+run();
diff --git a/bench/cycles-parity/texture-scenes.mjs b/bench/cycles-parity/texture-scenes.mjs
new file mode 100644
index 00000000..6c461d13
--- /dev/null
+++ b/bench/cycles-parity/texture-scenes.mjs
@@ -0,0 +1,139 @@
+// Textured scenes for the sampler checks of #896, exported in the same JSON as `export-scene.mjs`, so `trace-native.mjs`,
+// `render-cycles.py` and `run-m1-parity.py` take them like any parity scene.
+// node bench/cycles-parity/texture-scenes.mjs <outputDirectory>
+//
+// tex-repeat a repeating sRGB colour map and an alpha-masked map, wrap mode and filter at Cycles' defaults, so Cycles can
+// render it as the reference.
+// tex-wraps clamp, mirror and nearest maps, a blended alpha map and a normal map. The Cycles bridge reads the colour map
+// only, so this one is for byte comparisons between two builds of Cook, not for scoring.
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { serializeSceneDescription } from './scene-bridge.mjs';
+
+const TEXTURE_SIZE = 16;
+const LIGHT_LEVEL = 0.05;
+
+function quadGeometry(uvRepeat) {
+ return {
+ positions: new Float32Array([-1, -1, 0, 1, -1, 0, 1, 1, 0, -1, 1, 0]),
+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),
+ uvs: new Float32Array([0, 0, uvRepeat, 0, uvRepeat, uvRepeat, 0, uvRepeat]),
+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+ };
+}
+
+function placedMatrix(translation, scale) {
+ return new Float32Array([scale[0], 0, 0, 0, 0, scale[1], 0, 0, 0, 0, scale[2], 0, translation[0], translation[1], translation[2], 1]);
+}
+
+function part(name, geometry, translation, scale, material) {
+ return { name, geometry, matrix: placedMatrix(translation, scale), material: { tag: 'surface', metallic: 0, roughness: 0.6, emission: 0, ...material } };
+}
+
+// A gradient with a checker, so that wrap, filter and colour space each leave a visible mark.
+function gradientChecker(withAlphaGradient) {
+ const data = new Uint8Array(TEXTURE_SIZE * TEXTURE_SIZE * 4);
+ for (let y = 0; y < TEXTURE_SIZE; y++) {
+ for (let x = 0; x < TEXTURE_SIZE; x++) {
+ const offset = (y * TEXTURE_SIZE + x) * 4;
+ const checker = ((x >> 2) + (y >> 2)) & 1;
+ data[offset] = checker ? 230 : 40 + x * 8;
+ data[offset + 1] = checker ? 200 : 40 + y * 8;
+ data[offset + 2] = checker ? 60 : 200 - x * 6;
+ data[offset + 3] = withAlphaGradient ? Math.round(255 * (x + 0.5) / TEXTURE_SIZE) : 255;
+ }
+ }
+ return { width: TEXTURE_SIZE, height: TEXTURE_SIZE, data };
+}
+
+function bumpyNormalMap() {
+ const data = new Uint8Array(TEXTURE_SIZE * TEXTURE_SIZE * 4);
+ for (let y = 0; y < TEXTURE_SIZE; y++) {
+ for (let x = 0; x < TEXTURE_SIZE; x++) {
+ const offset = (y * TEXTURE_SIZE + x) * 4;
+ const tilt = Math.sin(x * 0.8) * Math.cos(y * 0.8) * 0.5;
+ data[offset] = Math.round((tilt * 0.5 + 0.5) * 255);
+ data[offset + 1] = Math.round((-tilt * 0.5 + 0.5) * 255);
+ data[offset + 2] = 255;
+ data[offset + 3] = 255;
+ }
+ }
+ return { width: TEXTURE_SIZE, height: TEXTURE_SIZE, data };
+}
+
+function environment() {
+ const pointLights = [
+ { position: [0, 2.5, 4], color: [1, 0.95, 0.85], intensity: 30, radius: 0.1, castShadow: true },
+ { position: [-3, 0.5, 3], color: [0.6, 0.7, 1], intensity: 10, radius: 0.1, castShadow: true },
+ ];
+ return {
+ world: true, fillIntensity: 0, ambientIntensity: 1, fogDensity: 0, lightDirection: [-3, 6, 4], keyColor: [0, 0, 0],
+ pointLights, spotLights: [], areaLights: [],
+ };
+}
+
+function sceneWithParts(parts) {
+ return {
+ parts,
+ blenderWorld: { type: 'constant', value: LIGHT_LEVEL },
+ environment: environment(),
+ camera: { eye: [0, 0, 8], target: [0, 0, 0], up: [0, 1, 0], fov: 40, near: 0.1, far: 50 },
+ };
+}
+
+function backdrop() {
+ return part('backdrop', quadGeometry(1), [0, 0, -1.5], [7, 4, 1], { color: [0.55, 0.12, 0.1], roughness: 0.9 });
+}
+
+function textureRepeatScene() {
+ const colourMap = { image: gradientChecker(false), colorSpace: 'srgb' };
+ const maskMap = { image: gradientChecker(true), colorSpace: 'srgb' };
+ return sceneWithParts([
+ backdrop(),
+ part('colour', quadGeometry(3), [-2.2, 0, 0], [1.9, 1.9, 1], { color: [1, 1, 1], map: colourMap }),
+ part('mask', quadGeometry(3), [2.2, 0, 0], [1.9, 1.9, 1], { color: [0.9, 0.95, 0.9], alphaMode: 'mask', alphaCutoff: 0.5, map: maskMap }),
+ ]);
+}
+
+function textureWrapsScene() {
+ const wrapped = (extra) => ({ image: gradientChecker(false), colorSpace: 'srgb', uvScale: [2.5, 2.5], uvOffset: [0.15, -0.1], ...extra });
+ const alpha = (extra) => ({ image: gradientChecker(true), colorSpace: 'srgb', uvScale: [2.5, 2.5], ...extra });
+ const columnSpacing = 1.55;
+ const place = (index, row) => [(index - 2) * columnSpacing, row, 0];
+ const size = [0.68, 0.68, 1];
+ const top = 1.5;
+ const bottom = -0.2;
+ return sceneWithParts([
+ backdrop(),
+ part('clamp', quadGeometry(1), place(0, top), size, { color: [1, 1, 1], map: wrapped({ wrapU: 1, wrapV: 1 }) }),
+ part('mirror', quadGeometry(1), place(1, top), size, { color: [1, 1, 1], map: wrapped({ wrapU: 2, wrapV: 2 }) }),
+ part('repeat-nearest', quadGeometry(1), place(2, top), size, { color: [1, 1, 1], map: wrapped({ nearest: true }) }),
+ part('mirror-nearest', quadGeometry(1), place(3, top), size, { color: [1, 1, 1], map: wrapped({ wrapU: 2, wrapV: 2, nearest: true }) }),
+ part('linear-colour', quadGeometry(1), place(4, top), size, { color: [1, 1, 1], map: wrapped({ colorSpace: 'linear' }) }),
+ part('mask-mirror', quadGeometry(1), place(0, bottom), size, { color: [0.9, 1, 0.9], alphaMode: 'mask', alphaCutoff: 0.5, map: alpha({ wrapU: 2, wrapV: 2 }) }),
+ part('mask-clamp', quadGeometry(1), place(1, bottom), size, { color: [0.9, 1, 0.9], alphaMode: 'mask', alphaCutoff: 0.5, map: alpha({ wrapU: 1, wrapV: 1 }) }),
+ part('mask-nearest', quadGeometry(1), place(2, bottom), size, { color: [0.9, 1, 0.9], alphaMode: 'mask', alphaCutoff: 0.5, map: alpha({ nearest: true }) }),
+ part('blend-repeat', quadGeometry(1), place(3, bottom), size, { color: [0.9, 0.9, 1], alphaMode: 'blend', opacity: 0.9, map: alpha({}) }),
+ part('normal-map', quadGeometry(1), place(4, bottom), size, { color: [0.7, 0.7, 0.75], roughness: 0.3, normalMap: { image: bumpyNormalMap(), colorSpace: 'linear', uvScale: [2, 2] } }),
+ ]);
+}
+
+export const TEXTURE_SCENES = { 'tex-repeat': textureRepeatScene, 'tex-wraps': textureWrapsScene };
+
+async function writeScenes(outputDirectory) {
+ const scenesDirectory = join(outputDirectory, 'scenes');
+ await mkdir(scenesDirectory, { recursive: true });
+ for (const [sceneId, build] of Object.entries(TEXTURE_SCENES)) {
+ const description = await serializeSceneDescription(sceneId, build());
+ await writeFile(join(scenesDirectory, `${sceneId}.json`), JSON.stringify(description));
+ console.log(JSON.stringify({ sceneId, parts: description.parts.length, images: description.images.length }));
+ }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'))) {
+ if (!process.argv[2]) {
+ throw new RangeError('Usage: node bench/cycles-parity/texture-scenes.mjs <outputDirectory>');
+ }
+ await writeScenes(resolve(process.argv[2]));
+}
diff --git a/changes/896-shared-sampler.md b/changes/896-shared-sampler.md
new file mode 100644
index 00000000..c5743915
--- /dev/null
+++ b/changes/896-shared-sampler.md
@@ -0,0 +1 @@
+- The Cycles kernel reads the alpha of cutouts through the same texture sampler as shading, and a texture set past the 1 GiB pool fails at packing with its size and the limit (#896)
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.md
index fc630736..01d57c5f 100644
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@ -975,3 +975,25 @@ Both pairs are identical in Cook and in Cycles: left Cook, right Cycles, 4096 sp
With the fix, on one Modal container (NVIDIA A10) `[measured]`: the seven scenes at 4096 spp (box filter) pass 7 of 7 (mean ratios 1.0000 `spot-area`, 1.0008 `light-linking`, 0.9993 `metal`, 0.9979 `glass`, 0.9996 `outdoor-hdri`, 1.0034 `lit-interior`, 1.0009 `many-lights-500`); `area-shapes` (0.9997) and `transparent-shadow` (1.0006) still pass 64 of 64 tiles with the numbers of the table above; `cargo test` 32 passed, 0 failed; the native node tests 84 passed, 0 failed, 1 skipped (it skipped before); `check-lobes.mjs` and `verify-lobes.py` (lobe probes and furnace scenes) exit 0. Against the kernel before the fix, the new test fails all three cases (the limit 0 mean was 3.3 percent off in red, the backdrop at limit 2 0.99 percent).
`tests/native-transparent-bounces.test.js` pins the behaviour on a GPU (it skips without the addon): the image mean and the sky behind one layer at limits 0 and 1, and the image mean and the backdrop behind one layer at limit 2, against the Cycles means above with a tolerance of 0.5 percent.
+
+## One texture sampler for shading and alpha tests (#896, slice T1)
+
+The `cycles` kernel had three texture readers: `closure_sample_texture_uv` (shading), `int_sample_texture_channel` (the alpha of cutouts and blended surfaces for every ray) and an inline nearest read in `bootstrap_main.wgsl`. They now call one function, `texture_sample` in `closure.wgsl`, so a cutout is seen and shaded through the same wrap, filter and format. The `legacy` kernel is untouched. The texture pool also fails early now: a pool past the 1 GiB storage binding raises an error that names the size and the limit at `buildNativeInputV2` (and at the host, against the device's binding size), where the base build aborted the process in the device. The host no longer copies the pool once more before upload (`storage_buffer` borrows bytes that already fit), and the packer drops its per-texture arrays once they are joined.
+
+Measured on an NVIDIA A10G (Modal), one run each unless noted `[measured]`:
+
+| Check | Base | T1 |
+| --- | --- | --- |
+| `cycles` kernel, `lit-interior` (no texture), 64 spp, same seed | image bytes | identical |
+| `legacy` kernel, `lit-interior` and the textured `tex-repeat` | image bytes | identical |
+| `cycles` kernel, `tex-repeat` and `tex-wraps` (alpha-masked and blended textures) | image bytes | **different**: 47 percent of pixels, mean ratio 1.012 and 1.009 |
+| Pool of 256 MiB (256 textures of 512x512), peak process memory | 2240 and 2161 MiB | 1753 and 1646 MiB |
+| Same, upload seconds | 0.28 and 0.14 | 0.20 and 0.06 |
+| Pool of 1100 MiB | process aborted in the device | `RangeError` at packing with size and limit |
+| Cycles kernel WGSL | 6607 lines, 242,913 bytes | 6538 lines, 240,235 bytes |
+
+The number of textures is not limited by either build (2000 descriptors of 16x16 packed and rendered the same); the limit is the 1 GiB pool. Bindings, bind groups and struct sizes are unchanged.
+
+The two images that differ are scenes with alpha-masked or blended textures. A numeric emulation of both old samplers over a 3000 x 3000 UV grid of a repeating 16x16 alpha texture agrees to 1.4e-7 (108 of 9,000,000 cutoff decisions differ at exact ties), so the samplers' arithmetic does not explain a difference of this size, and the cause is not found. Against Cycles on `tex-repeat` (2048 spp, 960x540, Cycles seed 1): before, mean ratio (1.06, 0.97, 1.01) for red, green, blue, relMSE 0.0215, 31 of 64 tiles within 5 percent; after, relMSE 0.0272, 31 of 64 tiles. Both are far from Cycles on the cutout (Cycles shows half of each strip opaque, Cook a fraction of it, before and after), so the scene does not pass the gates either way. Seed-to-seed noise floor of the reference is 1.7e-6. `brick-graph` (the only textured reference scene) and `glass` were not compared against the base: the base copy had no HDRI file, so only the T1 side ran.
+
+Commands: `node bench/cycles-parity/texture-scenes.mjs <dir>` writes `tex-repeat` (Cycles can render it) and `tex-wraps` (clamp, mirror, nearest, blend and normal map; Cook only), `node bench/cycles-parity/texture-pool-bench.mjs --textures 256 --size 512` prints pack, setup, compile and upload seconds and peak memory.
diff --git a/packages/render-native/FORMAT-v2.md b/packages/render-native/FORMAT-v2.md
index 70e244fc..fb86ce90 100644
--- a/packages/render-native/FORMAT-v2.md
+++ b/packages/render-native/FORMAT-v2.md
@@ -349,6 +349,8 @@ Total stride: **32 bytes** (`2 × 16 B`), alignment: **16 bytes**.
| `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.
+
---
## 9. Film Accumulation Buffer (`@binding(11)`)
diff --git a/packages/render-native/README.md b/packages/render-native/README.md
index 4a6363fc..16ea47a9 100644
--- a/packages/render-native/README.md
+++ b/packages/render-native/README.md
@@ -19,7 +19,7 @@ const { rgba, adapter, tracedSeconds } = traceNative(input, options);
`rgba` is linear float RGBA, rows from the top, averaged over the samples. `albedo` and `normal` (three floats per pixel, normalise the normal), `depth` and `variance` (one float) are the first-hit features the wavelet and OIDN denoisers read. `pack-input.mjs` holds `buildNativeInput` without Node imports, so the job page packs the scene itself. `bench/native-tracer` compares it with the browser kernel.
-Fog (`scene.volume`), subsurface scattering and `options.noiseThreshold` (the CPU tracer's stop rule: converged pixels draw no more samples, `averageSamples` in the result is the mean drawn) are in the kernel. `traceNative` also takes `maxSeconds` (stopping with an error once the trace has run that long) and `kernel` (`"legacy"` by default, or `"cycles"`, with `JS67_NATIVE_KERNEL` as environment fallback; see [FORMAT-v2.md](./FORMAT-v2.md)). Alpha cutouts are traced by stepping through transparent texels in the kernel (the acceleration structure is opaque).
+Fog (`scene.volume`), subsurface scattering and `options.noiseThreshold` (the CPU tracer's stop rule: converged pixels draw no more samples, `averageSamples` in the result is the mean drawn) are in the kernel. `traceNative` also takes `maxSeconds` (stopping with an error once the trace has run that long) and `kernel` (`"legacy"` by default, or `"cycles"`, with `JS67_NATIVE_KERNEL` as environment fallback; see [FORMAT-v2.md](./FORMAT-v2.md)). Alpha cutouts are traced by stepping through transparent texels in the kernel (the acceleration structure is opaque). The `cycles` kernel reads a cutout's alpha through the same texture sampler as the shading, so the visible edge and the shaded colour agree for every wrap mode and filter. All textures share one pool of at most 1 GiB (the storage binding of the device); a larger set fails at `buildNativeInputV2` with the size and the limit in the message, and the fix is smaller maps.
The light bake uses the texel entry of the same kernel:
diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjs
index 7a73d5a8..a6b9fde2 100644
--- a/packages/render-native/pack-input-v2.mjs
+++ b/packages/render-native/pack-input-v2.mjs
@@ -84,6 +84,11 @@ const TEXTURE_FORMAT_RGBA8_SRGB = 1;
const TEXTURE_FORMAT_RGBA32_FLOAT = 2;
const TEXTURE_FORMAT_RG16_FLOAT = 3;
+// All textures share one storage binding of 32-bit words. The native host opens its device with a binding of at most 1 GiB
+// (`open_device` in src/host/device.rs), so a pool past this size cannot be bound.
+export const TEXTURE_POOL_MAX_BYTES = 1 << 30;
+const BYTES_PER_MEBIBYTE = 1 << 20;
+
const DEFAULT_HDRI_RADIANCE_LIMIT = 16;
const SUN_DEFAULT_HALF_ANGLE = Math.PI / 360;
const IDENTITY_MATRIX_4X4 = Object.freeze([
@@ -253,6 +258,27 @@ function createTextureCollector() {
const descriptors = [];
const wordChunks = [];
let totalWords = 0;
+ let finished = null;
+
+ function packedWordCount(format, pixelCount) {
+ if (format === TEXTURE_FORMAT_RGBA32_FLOAT) {
+ return pixelCount * 4;
+ }
+ return Math.max(4, Math.ceil(pixelCount / 4) * 4);
+ }
+
+ // Checked before a texture is converted, so an oversize image fails fast instead of after allocating its words.
+ function assertRoomInPool(wordCount, width, height) {
+ if ((totalWords + wordCount) * 4 <= TEXTURE_POOL_MAX_BYTES) {
+ return;
+ }
+ const neededMebibytes = Math.ceil(wordCount * 4 / BYTES_PER_MEBIBYTE);
+ const usedMebibytes = Math.ceil(totalWords * 4 / BYTES_PER_MEBIBYTE);
+ throw new RangeError(
+ `The texture pool is full: the ${width}x${height} texture needs ${neededMebibytes} MiB and the ${descriptors.length} before it take ${usedMebibytes} MiB, ` +
+ `but one pool holds at most ${TEXTURE_POOL_MAX_BYTES / BYTES_PER_MEBIBYTE} MiB. Pass smaller textures: downscale the largest maps or drop the ones the look does not need.`,
+ );
+ }
function objectIdentity(dataBuffer) {
if (!dataIdMap.has(dataBuffer)) {
@@ -309,6 +335,7 @@ function createTextureCollector() {
}
const pixelCount = width * height;
+ assertRoomInPool(packedWordCount(format, pixelCount), width, height);
const dataOffset = totalWords;
let packedWords;
let sumR = 0;
@@ -390,7 +417,8 @@ function createTextureCollector() {
function addPackedRgba8Words(words, width, height, isSrgb, repeat) {
const pixelCount = width * height;
- const alignedWords = Math.max(4, Math.ceil(pixelCount / 4) * 4);
+ const alignedWords = packedWordCount(TEXTURE_FORMAT_RGBA8_UNORM, pixelCount);
+ assertRoomInPool(alignedWords, width, height);
const padded = new Uint32Array(alignedWords);
padded.set(words.subarray(0, pixelCount));
let sumR = 0;
@@ -431,6 +459,12 @@ function createTextureCollector() {
}
function finish() {
+ finished ??= buildFinishedTextures();
+ return finished;
+ }
+
+ // The per-texture word arrays are dropped once they are joined, so the host holds one copy of the pool, not two.
+ function buildFinishedTextures() {
const textureCount = descriptors.length;
const descriptorBuffer = new Uint8Array(Math.max(1, textureCount) * STRUCT_STRIDES_V2.textureDescriptor);
for (let index = 0; index < textureCount; index++) {
@@ -442,6 +476,7 @@ function createTextureCollector() {
texelBuffer.set(chunk, cursor);
cursor += chunk.length;
}
+ wordChunks.length = 0;
return {
textureDescriptors: descriptorBuffer,
textureCount,
diff --git a/packages/render-native/src/cycles/bootstrap_main.wgsl b/packages/render-native/src/cycles/bootstrap_main.wgsl
index 1dcdf933..07f0785e 100644
--- a/packages/render-native/src/cycles/bootstrap_main.wgsl
+++ b/packages/render-native/src/cycles/bootstrap_main.wgsl
@@ -31,15 +31,12 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
let cand_mat_idx = select(cand_inst.material_override, cand_tri.material_index, cand_inst.material_override == INVALID_INDEX);
let cand_mat = materials[cand_mat_idx];
var alpha = cand_mat.alpha;
- if (cand_mat.base_color_tex >= 0 && u32(cand_mat.base_color_tex) < kernel_params.texture_count) {
- let desc = texture_descriptors[u32(cand_mat.base_color_tex)];
+ if (cand_mat.base_color_tex >= 0) {
let bary_w = 1.0 - candidate.barycentrics.x - candidate.barycentrics.y;
- let hit_u = fract(bary_w * cand_tri.uv0_u + candidate.barycentrics.x * cand_tri.uv1_u + candidate.barycentrics.y * cand_tri.uv2_u);
- let hit_v = fract(bary_w * cand_tri.uv0_v + candidate.barycentrics.x * cand_tri.uv1_v + candidate.barycentrics.y * cand_tri.uv2_v);
- let tex_x = min(u32(max(hit_u, 0.0) * f32(desc.width)), max(desc.width, 1u) - 1u);
- let tex_y = min(u32(max(hit_v, 0.0) * f32(desc.height)), max(desc.height, 1u) - 1u);
- let packed_texel = unpack4x8unorm(texture_texels[desc.data_offset + tex_y * desc.width + tex_x]);
- alpha = alpha * packed_texel.a;
+ let hit_uv = bary_w * vec2<f32>(cand_tri.uv0_u, cand_tri.uv0_v)
+ + candidate.barycentrics.x * vec2<f32>(cand_tri.uv1_u, cand_tri.uv1_v)
+ + candidate.barycentrics.y * vec2<f32>(cand_tri.uv2_u, cand_tri.uv2_v);
+ alpha = alpha * texture_sample(cand_mat.base_color_tex, hit_uv, hit_uv).a;
}
if (cand_mat.alpha_mode != ALPHA_MODE_MASK || alpha >= cand_mat.alpha_cutoff) {
rayQueryConfirmIntersection(&rq);
diff --git a/packages/render-native/src/cycles/closure.wgsl b/packages/render-native/src/cycles/closure.wgsl
index 9a6811cf..96c13206 100644
--- a/packages/render-native/src/cycles/closure.wgsl
+++ b/packages/render-native/src/cycles/closure.wgsl
@@ -60,7 +60,7 @@ fn closure_srgb_to_linear(rgb: vec3<f32>) -> vec3<f32> {
);
}
-fn closure_wrap_coord(coord: f32, wrap_mode: u32) -> f32 {
+fn texture_wrap_coord(coord: f32, wrap_mode: u32) -> f32 {
if (wrap_mode == 1u) {
return clamp(coord, 0.0, 1.0);
}
@@ -71,7 +71,7 @@ fn closure_wrap_coord(coord: f32, wrap_mode: u32) -> f32 {
return coord - floor(coord);
}
-fn closure_wrap_texel_index(idx: i32, dim: i32, wrap_mode: u32) -> i32 {
+fn texture_wrap_texel_index(idx: i32, dim: i32, wrap_mode: u32) -> i32 {
if (wrap_mode == 0u) {
let rem = idx % dim;
return select(rem, rem + dim, rem < 0);
@@ -79,7 +79,7 @@ fn closure_wrap_texel_index(idx: i32, dim: i32, wrap_mode: u32) -> i32 {
return clamp(idx, 0, dim - 1);
}
-fn closure_fetch_texel(desc: TextureDescriptor, ix: i32, iy: i32, format: u32) -> vec4<f32> {
+fn texture_fetch_texel(desc: TextureDescriptor, ix: i32, iy: i32, format: u32) -> vec4<f32> {
let texel_idx = u32(iy) * desc.width + u32(ix);
if (format == 2u) {
let base = desc.data_offset + texel_idx * 4u;
@@ -101,7 +101,10 @@ fn closure_fetch_texel(desc: TextureDescriptor, ix: i32, iy: i32, format: u32) -
return rgba;
}
-fn closure_sample_texture_uv(tex_index: i32, raw_uv0: vec2<f32>, raw_uv1: vec2<f32>) -> vec4<f32> {
+// 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.
+fn texture_sample(tex_index: i32, raw_uv0: vec2<f32>, raw_uv1: vec2<f32>) -> vec4<f32> {
if (tex_index < 0) {
return vec4<f32>(1.0);
}
@@ -122,15 +125,15 @@ fn closure_sample_texture_uv(tex_index: i32, raw_uv0: vec2<f32>, raw_uv1: vec2<f
let base_uv = select(raw_uv0, raw_uv1, use_uv1);
let uv = base_uv * desc.uv_scale + desc.uv_offset;
- let u_wrapped = closure_wrap_coord(uv.x, wrap_u);
- let v_wrapped = closure_wrap_coord(uv.y, wrap_v);
+ let u_wrapped = texture_wrap_coord(uv.x, wrap_u);
+ let v_wrapped = texture_wrap_coord(uv.y, wrap_v);
let w_i = i32(desc.width);
let h_i = i32(desc.height);
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);
- return closure_fetch_texel(desc, ix, iy, format);
+ return texture_fetch_texel(desc, ix, iy, format);
}
let fx = u_wrapped * f32(w_i) - 0.5;
@@ -139,20 +142,20 @@ fn closure_sample_texture_uv(tex_index: i32, raw_uv0: vec2<f32>, raw_uv1: vec2<f
let by0 = i32(floor(fy));
let tx = fx - f32(bx0);
let ty = fy - f32(by0);
- let ix0 = closure_wrap_texel_index(bx0, w_i, wrap_u);
- let ix1 = closure_wrap_texel_index(bx0 + 1, w_i, wrap_u);
- let iy0 = closure_wrap_texel_index(by0, h_i, wrap_v);
- let iy1 = closure_wrap_texel_index(by0 + 1, h_i, wrap_v);
-
- let c00 = closure_fetch_texel(desc, ix0, iy0, format);
- let c10 = closure_fetch_texel(desc, ix1, iy0, format);
- let c01 = closure_fetch_texel(desc, ix0, iy1, format);
- let c11 = closure_fetch_texel(desc, ix1, iy1, format);
+ let ix0 = texture_wrap_texel_index(bx0, w_i, wrap_u);
+ let ix1 = texture_wrap_texel_index(bx0 + 1, w_i, wrap_u);
+ let iy0 = texture_wrap_texel_index(by0, h_i, wrap_v);
+ let iy1 = texture_wrap_texel_index(by0 + 1, h_i, wrap_v);
+
+ let c00 = texture_fetch_texel(desc, ix0, iy0, format);
+ let c10 = texture_fetch_texel(desc, ix1, iy0, format);
+ let c01 = texture_fetch_texel(desc, ix0, iy1, format);
+ let c11 = texture_fetch_texel(desc, ix1, iy1, format);
return mix(mix(c00, c10, tx), mix(c01, c11, tx), ty);
}
fn closure_sample_texture(tex_index: i32, point: ptr<function, ShadingPoint>) -> vec4<f32> {
- return closure_sample_texture_uv(tex_index, (*point).uv0, (*point).uv1);
+ return texture_sample(tex_index, (*point).uv0, (*point).uv1);
}
fn closure_apply_normal_map(
@@ -196,9 +199,9 @@ fn closure_apply_bump_map(
}
let du = vec2<f32>(1.0 / f32(desc.width), 0.0);
let dv = vec2<f32>(0.0, 1.0 / f32(desc.height));
- let h_c = bsdf_mf_average(closure_sample_texture_uv(tex_index, (*point).uv0, (*point).uv1).rgb);
- let h_u = bsdf_mf_average(closure_sample_texture_uv(tex_index, (*point).uv0 + du, (*point).uv1 + du).rgb);
- let h_v = bsdf_mf_average(closure_sample_texture_uv(tex_index, (*point).uv0 + dv, (*point).uv1 + dv).rgb);
+ let h_c = bsdf_mf_average(texture_sample(tex_index, (*point).uv0, (*point).uv1).rgb);
+ let h_u = bsdf_mf_average(texture_sample(tex_index, (*point).uv0 + du, (*point).uv1 + du).rgb);
+ let h_v = bsdf_mf_average(texture_sample(tex_index, (*point).uv0 + dv, (*point).uv1 + dv).rgb);
let dh_du = (h_u - h_c) * f32(desc.width) * bump_distance;
let dh_dv = (h_v - h_c) * f32(desc.height) * bump_distance;
let perturbed = base_normal - dh_du * tangent - dh_dv * bitangent;
diff --git a/packages/render-native/src/cycles/integrator.wgsl b/packages/render-native/src/cycles/integrator.wgsl
index d8c9831d..99052090 100644
--- a/packages/render-native/src/cycles/integrator.wgsl
+++ b/packages/render-native/src/cycles/integrator.wgsl
@@ -82,78 +82,6 @@ fn int_resolve_material_index(instance: InstanceRecord, triangle: TriangleRecord
return select(instance.material_override, triangle.material_index, instance.material_override == INVALID_INDEX);
}
-fn int_wrap_coord(coord: i32, extent: i32, wrap_mode: u32) -> u32 {
- if (wrap_mode == 1u) {
- return u32(clamp(coord, 0, extent - 1));
- }
- if (wrap_mode == 2u) {
- let period = 2 * extent;
- let wrapped = ((coord % period) + period) % period;
- let mirrored = select(wrapped, period - 1 - wrapped, wrapped >= extent);
- return u32(clamp(mirrored, 0, extent - 1));
- }
- return u32(((coord % extent) + extent) % extent);
-}
-
-fn int_fetch_texel_channel(descriptor: TextureDescriptor, x: u32, y: u32, channel: u32) -> f32 {
- let format = descriptor.format_and_sampler & 0xFFu;
- let texel_index = y * descriptor.width + x;
- if (format == 0u || format == 1u) {
- let rgba = unpack4x8unorm(texture_texels[descriptor.data_offset + texel_index]);
- return select(rgba.w, rgba.x, channel == 0u);
- }
- if (format == 2u) {
- let chan_offset = select(3u, 0u, channel == 0u);
- return bitcast<f32>(texture_texels[descriptor.data_offset + texel_index * 4u + chan_offset]);
- }
- if (format == 3u && channel == 0u) {
- return unpack2x16float(texture_texels[descriptor.data_offset + texel_index]).x;
- }
- return 1.0;
-}
-
-fn int_sample_texture_channel(texture_index: i32, uv0: vec2<f32>, uv1: vec2<f32>, channel: u32) -> f32 {
- if (texture_index < 0 || u32(texture_index) >= kernel_params.texture_count) {
- return 1.0;
- }
- let descriptor = texture_descriptors[u32(texture_index)];
- if (descriptor.width == 0u || descriptor.height == 0u) {
- return 1.0;
- }
- let use_uv1 = (descriptor.format_and_sampler & (1u << 21u)) != 0u;
- let base_uv = select(uv0, uv1, use_uv1);
- let transformed_uv = base_uv * descriptor.uv_scale + descriptor.uv_offset;
- let wrap_u = (descriptor.format_and_sampler >> 16u) & 3u;
- let wrap_v = (descriptor.format_and_sampler >> 18u) & 3u;
- let nearest = (descriptor.format_and_sampler & (1u << 20u)) != 0u;
- let width_i = i32(descriptor.width);
- let height_i = i32(descriptor.height);
-
- if (nearest) {
- let col = int_wrap_coord(i32(floor(transformed_uv.x * f32(descriptor.width))), width_i, wrap_u);
- let row = int_wrap_coord(i32(floor(transformed_uv.y * f32(descriptor.height))), height_i, wrap_v);
- return int_fetch_texel_channel(descriptor, col, row, channel);
- }
-
- let px = transformed_uv.x * f32(descriptor.width) - 0.5;
- let py = transformed_uv.y * f32(descriptor.height) - 0.5;
- let x0 = floor(px);
- let y0 = floor(py);
- let fx = px - x0;
- let fy = py - y0;
- var value_sum = 0.0;
- for (var corner = 0u; corner < 4u; corner += 1u) {
- let dx = i32(corner & 1u);
- let dy = i32(corner >> 1u);
- let col = int_wrap_coord(i32(x0) + dx, width_i, wrap_u);
- let row = int_wrap_coord(i32(y0) + dy, height_i, wrap_v);
- let wx = select(1.0 - fx, fx, dx == 1);
- let wy = select(1.0 - fy, fy, dy == 1);
- value_sum += int_fetch_texel_channel(descriptor, col, row, channel) * (wx * wy);
- }
- return value_sum;
-}
-
fn int_evaluate_surface_opacity(triangle: TriangleRecord, material: MaterialRecord, barycentrics: vec2<f32>) -> f32 {
if (material.alpha_mode == ALPHA_MODE_OPAQUE) {
return 1.0;
@@ -174,10 +102,10 @@ fn int_evaluate_surface_opacity(triangle: TriangleRecord, material: MaterialReco
(triangle.flags & TRIANGLE_FLAG_HAS_UV1) != 0u,
);
if (material.base_color_tex >= 0) {
- opacity *= int_sample_texture_channel(material.base_color_tex, uv0, uv1, 3u);
+ opacity *= texture_sample(material.base_color_tex, uv0, uv1).a;
}
if (material.alpha_tex >= 0) {
- opacity *= int_sample_texture_channel(material.alpha_tex, uv0, uv1, 0u);
+ opacity *= texture_sample(material.alpha_tex, uv0, uv1).r;
}
return clamp(opacity, 0.0, 1.0);
}
diff --git a/packages/render-native/src/cycles/mod.rs b/packages/render-native/src/cycles/mod.rs
index 3ad73030..b6017929 100644
--- a/packages/render-native/src/cycles/mod.rs
+++ b/packages/render-native/src/cycles/mod.rs
@@ -831,7 +831,7 @@ pub(crate) fn assemble_cycles_kernel() -> Result<String> {
#[cfg(test)]
mod tests {
- use super::{has_compute_entry_point, parse_kernel_manifest};
+ use super::{assemble_cycles_kernel, has_compute_entry_point, parse_kernel_manifest};
#[test]
fn parses_manifest_with_utf8_bom_and_comments() {
@@ -852,4 +852,27 @@ mod tests {
assert!(!has_compute_entry_point(source, "main"));
assert!(!has_compute_entry_point(source, "helper"));
}
+
+ /// The texel pool is read in one function. A second reader would sample with its own wrap and filter, and a cutout
+ /// would then be seen through different texels than it is shaded with.
+ #[test]
+ fn the_kernel_reads_the_texel_pool_in_one_shared_sampler_only() {
+ let kernel = assemble_cycles_kernel().expect("the kernel assembles");
+ let fetch_start = kernel.find("fn texture_fetch_texel(").expect("the shared texel fetch exists");
+ let fetch_end = fetch_start + kernel[fetch_start..].find("\n}").expect("the fetch function ends");
+ let reads_inside_fetch = kernel[fetch_start..fetch_end].matches("texture_texels[").count();
+ assert_eq!(kernel.matches("texture_texels[").count(), reads_inside_fetch);
+ assert!(reads_inside_fetch > 0);
+ assert!(!kernel.contains("fn int_sample_texture_channel"));
+ assert!(!kernel.contains("fn int_wrap_coord"));
+ assert!(kernel.contains("texture_sample(material.base_color_tex, uv0, uv1).a"));
+ assert!(kernel.contains("texture_sample(material.alpha_tex, uv0, uv1).r"));
+ }
+
+ #[test]
+ fn the_bootstrap_entry_samples_alpha_through_the_shared_sampler() {
+ let bootstrap = include_str!("bootstrap_main.wgsl");
+ assert!(!bootstrap.contains("texture_texels["));
+ assert!(bootstrap.contains("texture_sample("));
+ }
}
diff --git a/packages/render-native/src/host/device.rs b/packages/render-native/src/host/device.rs
index 6b881ccc..f38b4fc3 100644
--- a/packages/render-native/src/host/device.rs
+++ b/packages/render-native/src/host/device.rs
@@ -1,3 +1,5 @@
+use std::borrow::Cow;
+
use napi::{Error, Result};
use wgpu::util::DeviceExt;
@@ -5,13 +7,22 @@ pub(crate) fn failure(message: impl Into<String>) -> Error {
Error::from_reason(message.into())
}
-pub(crate) fn storage_buffer(device: &wgpu::Device, label: &str, bytes: &[u8]) -> wgpu::Buffer {
+/// The bytes of a storage buffer: a multiple of four long and at least 16. Bytes that already fit are borrowed, so a texel
+/// pool of hundreds of megabytes is not copied once more on the host before it reaches the GPU.
+pub(crate) fn padded_storage_bytes(bytes: &[u8]) -> Cow<'_, [u8]> {
+ let padded_length = bytes.len().next_multiple_of(4).max(16);
+ if padded_length == bytes.len() {
+ return Cow::Borrowed(bytes);
+ }
let mut padded = bytes.to_vec();
- let padded_length = padded.len().next_multiple_of(4).max(16);
padded.resize(padded_length, 0);
+ Cow::Owned(padded)
+}
+
+pub(crate) fn storage_buffer(device: &wgpu::Device, label: &str, bytes: &[u8]) -> wgpu::Buffer {
device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
label: Some(label),
- contents: &padded,
+ contents: &padded_storage_bytes(bytes),
usage: wgpu::BufferUsages::STORAGE,
})
}
@@ -68,3 +79,26 @@ pub(crate) fn open_device() -> Result<(wgpu::Device, wgpu::Queue, wgpu::AdapterI
.map_err(|error| failure(format!("Could not open the device: {error}")))?;
Ok((device, queue, adapter.get_info()))
}
+
+#[cfg(test)]
+mod tests {
+ use super::padded_storage_bytes;
+ use std::borrow::Cow;
+
+ #[test]
+ fn padded_storage_bytes_borrows_bytes_that_already_fit() {
+ let bytes = [7u8; 32];
+ let padded = padded_storage_bytes(&bytes);
+ assert!(matches!(padded, Cow::Borrowed(_)));
+ assert_eq!(padded.as_ptr(), bytes.as_ptr());
+ }
+
+ #[test]
+ fn padded_storage_bytes_pads_short_and_unaligned_input_with_zeros() {
+ assert_eq!(padded_storage_bytes(&[]).len(), 16);
+ let unaligned = padded_storage_bytes(&[1u8; 18]);
+ assert_eq!(unaligned.len(), 20);
+ assert_eq!(&unaligned[18..], &[0u8, 0u8]);
+ assert_eq!(&unaligned[..18], &[1u8; 18]);
+ }
+}
diff --git a/packages/render-native/src/host/session.rs b/packages/render-native/src/host/session.rs
index 51d6b754..9b990012 100644
--- a/packages/render-native/src/host/session.rs
+++ b/packages/render-native/src/host/session.rs
@@ -17,7 +17,7 @@ use crate::host::accel::{
use crate::host::dispatch::{DispatchPlanner, DISPATCH_BUDGET_SECONDS};
use crate::host::device::{failure, layout_entry, open_device, storage_buffer, storage_entry};
use crate::host::film::{image_accumulation_bytes, read_accumulation};
-use crate::host::textures::{upload_cycles_scene_buffers, upload_scene_buffers};
+use crate::host::textures::{check_texture_pool_budget, upload_cycles_scene_buffers, upload_scene_buffers};
use crate::{NativeTraceInput, NativeTraceInputV2, ProbeCyclesLobeOptions};
// ---- In-process device and pipeline cache ----
@@ -689,6 +689,8 @@ pub(crate) fn prepare_cycles_scene(
// Use cached device; open once per process.
let (device, queue, adapter_name, backend_name, features) = get_cached_device()?;
+ let pool_limit_bytes = u64::from(device.limits().max_storage_buffer_binding_size);
+ check_texture_pool_budget(input.texture_texels.len() as u64 * 4, pool_limit_bytes)?;
let (device_lost, device_error) = cached_device_loss_state()?;
let setup_seconds = setup_started.elapsed().as_secs_f64();
diff --git a/packages/render-native/src/host/textures.rs b/packages/render-native/src/host/textures.rs
index 8881f7c1..6398f33b 100644
--- a/packages/render-native/src/host/textures.rs
+++ b/packages/render-native/src/host/textures.rs
@@ -1,6 +1,6 @@
use wgpu::util::DeviceExt;
-use crate::host::device::storage_buffer;
+use crate::host::device::{failure, storage_buffer};
use crate::{NativeTraceInput, NativeTraceInputV2};
const MATERIAL_TEXELS: usize = 10;
@@ -25,6 +25,20 @@ pub(crate) fn material_is_cutout(materials: &[f32], material: usize) -> bool {
is_shadow_only || (materials[base + 3 * 4 + 2] > 0.0 && materials[base + 6 * 4 + 2] > 0.0)
}
+/// The texel pool is one storage binding, so it cannot outgrow `limit_bytes` (the device's storage binding size, at most 1 GiB).
+/// Failing here names the size and the way out; the device would only report a validation error with no hint about textures.
+pub(crate) fn check_texture_pool_budget(pool_bytes: u64, limit_bytes: u64) -> napi::Result<()> {
+ if pool_bytes <= limit_bytes {
+ return Ok(());
+ }
+ const MEBIBYTE: u64 = 1 << 20;
+ Err(failure(format!(
+ "The textures take {} MiB but one texture pool holds at most {} MiB on this device. Pass smaller textures: downscale the largest maps or drop the ones the look does not need.",
+ pool_bytes.div_ceil(MEBIBYTE),
+ limit_bytes / MEBIBYTE,
+ )))
+}
+
pub(crate) fn upload_scene_buffers(
device: &wgpu::Device,
input: &NativeTraceInput,
@@ -134,3 +148,22 @@ pub(crate) fn upload_cycles_scene_buffers(
parameters,
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::check_texture_pool_budget;
+
+ #[test]
+ fn texture_pool_budget_accepts_a_pool_at_the_limit() {
+ assert!(check_texture_pool_budget(1 << 30, 1 << 30).is_ok());
+ assert!(check_texture_pool_budget(0, 1 << 20).is_ok());
+ }
+
+ #[test]
+ fn texture_pool_budget_error_names_the_size_the_limit_and_the_fix() {
+ let message = check_texture_pool_budget((1 << 30) + 1, 1 << 30).unwrap_err().reason;
+ assert!(message.contains("1025 MiB"), "{message}");
+ assert!(message.contains("1024 MiB"), "{message}");
+ assert!(message.contains("Pass smaller textures"), "{message}");
+ }
+}
diff --git a/tests/native-texture-sampler.test.js b/tests/native-texture-sampler.test.js
new file mode 100644
index 00000000..1a4b7cb1
--- /dev/null
+++ b/tests/native-texture-sampler.test.js
@@ -0,0 +1,134 @@
+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 { TEXTURE_POOL_MAX_BYTES } from '../packages/render-native/pack-input-v2.mjs';
+import { createCamera } from '../src/path-tracer.js';
+
+const QUAD_UVS = new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]);
+
+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 solidImage(width, height, byteValue) {
+ return { width, height, data: new Uint8Array(width * height * 4).fill(byteValue) };
+}
+
+function packWithMaps(maps, extraMaterial = {}) {
+ const camera = createCamera({ eye: [0, 0, 3], target: [0, 0, 0], fov: 40 }, 8, 8);
+ return buildNativeInputV2(
+ {
+ materials: maps.map((map) => ({ color: [1, 1, 1], ...extraMaterial, map })),
+ instances: maps.map((_, index) => ({ geometry: quadGeometry(index), materialIndex: index })),
+ lights: {},
+ },
+ camera,
+ { width: 8, height: 8, samples: 1 },
+ );
+}
+
+function readDescriptorWord(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];
+}
+
+test('a texture past the pool budget fails at packing with the size, the limit and what to pass', () => {
+ const oversize = { width: 16384, height: 32768, data: new Uint8Array(4) };
+ assert.throws(
+ () => packWithMaps([{ image: oversize, colorSpace: 'srgb' }]),
+ (error) => {
+ assert.ok(error instanceof RangeError);
+ assert.match(error.message, /texture pool is full/);
+ assert.match(error.message, /16384x32768 texture needs 2048 MiB/);
+ assert.match(error.message, /at most 1024 MiB/);
+ assert.match(error.message, /Pass smaller textures/);
+ return true;
+ },
+ );
+ assert.equal(TEXTURE_POOL_MAX_BYTES, 1 << 30);
+});
+
+test('the pool holds each texture once, in order, and descriptors point at their own words', () => {
+ const first = solidImage(4, 4, 10);
+ const second = solidImage(8, 2, 200);
+ const input = packWithMaps([{ image: first }, { image: second }]);
+ assert.equal(input.textureCount, 2);
+ assert.equal(readDescriptorWord(input, 0, 0), 0);
+ assert.equal(readDescriptorWord(input, 1, 0), 16);
+ assert.equal(input.textureTexels[0], 0x0a0a0a0a);
+ assert.equal(input.textureTexels[16], 0xc8c8c8c8);
+ assert.equal(input.textureTexels.length, 16 + 16);
+});
+
+test('two uv transforms of one image stay two descriptors (the dedupe key carries uvScale and uvOffset)', () => {
+ const image = solidImage(4, 4, 90);
+ const same = packWithMaps([{ image }, { image }]);
+ assert.equal(same.textureCount, 1);
+ const scaled = packWithMaps([{ image }, { image, uvScale: [2, 2] }]);
+ assert.equal(scaled.textureCount, 2);
+ const shifted = packWithMaps([{ image }, { image, uvOffset: [0.25, 0] }]);
+ assert.equal(shifted.textureCount, 2);
+});
+
+function opaqueLeftAndRightOfAMirroredMask() {
+ // Two texels wide: the left one opaque, the right one clear. Mirrored over u in [0, 2] the quad shows
+ // opaque, clear, clear, opaque, so the cutout must be symmetric about the middle of the quad.
+ const data = new Uint8Array([255, 255, 255, 255, 255, 255, 255, 0]);
+ return { width: 2, height: 1, data };
+}
+
+function renderMirroredCutout(filter) {
+ const width = 32;
+ const height = 8;
+ const camera = createCamera({ eye: [0, 0, 2.2], target: [0, 0, 0], fov: 30 }, width, height);
+ const mirroredMap = {
+ image: opaqueLeftAndRightOfAMirroredMask(),
+ colorSpace: 'linear',
+ wrapU: 2,
+ wrapV: 1,
+ uvScale: [2, 1],
+ ...filter,
+ };
+ const input = buildNativeInputV2(
+ {
+ materials: [
+ { color: [0.1, 0.9, 0.1], alphaMode: 'mask', alphaCutoff: 0.5, map: mirroredMap },
+ { color: [0.9, 0.1, 0.1] },
+ ],
+ instances: [
+ { geometry: quadGeometry(0), matrix: [1.6, 0, 0, 0, 0, 1.6, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], materialIndex: 0 },
+ { geometry: quadGeometry(0), matrix: [4, 0, 0, 0, 0, 4, 0, 0, 0, 0, 1, 0, 0, 0, -1, 1], materialIndex: 1 },
+ ],
+ lights: { points: [{ position: [0, 0, 3], color: [1, 1, 1], intensity: 4, radius: 0.1 }] },
+ },
+ camera,
+ { width, height, samples: 4 },
+ );
+ const result = traceNative(input, { width, height, samples: 4, kernel: 'cycles' });
+ const row = Math.floor(height / 2);
+ return Array.from({ length: width }, (_, column) => result.albedo[(row * width + column) * 3 + 1] > 0.5);
+}
+
+for (const [label, filter] of [['nearest', { nearest: true }], ['bilinear', {}]]) {
+ test(`a mirrored alpha cutout is symmetric about its fold (${label}), as its shading is`, { skip: !findNativeAddon() }, () => {
+ const showsForeground = renderMirroredCutout(filter);
+ const covered = showsForeground.filter(Boolean).length;
+ assert.ok(covered > 0 && covered < showsForeground.length, 'the quad is partly opaque and partly clear');
+ const mismatches = showsForeground.filter((value, column) => value !== showsForeground[showsForeground.length - 1 - column]);
+ assert.ok(mismatches.length <= 2, `columns that differ from their mirror: ${mismatches.length}`);
+ });
+}
+
+test('a pool of many small textures packs, uploads and renders', { skip: !findNativeAddon() }, () => {
+ const maps = Array.from({ length: 64 }, (_, index) => ({ image: solidImage(8, 8, 3 * index + 1), colorSpace: 'srgb' }));
+ const input = packWithMaps(maps);
+ assert.equal(input.textureCount, 64);
+ const result = traceNative(input, { width: 8, height: 8, samples: 1, kernel: 'cycles' });
+ assert.ok(result.rgba.every(Number.isFinite));
+});