Skip to content

3D engine that AI agents drive

Make grid sequences change frames 6 times faster and measure a real VDB sequence (#1045)

Nguyen Xuan An484428b96200
diff --git a/bench/reference/volume-grid-vdb-sequence.mjs b/bench/reference/volume-grid-vdb-sequence.mjs
new file mode 100644
index 00000000..ebc4c2f7
--- /dev/null
+++ b/bench/reference/volume-grid-vdb-sequence.mjs
@@ -0,0 +1,135 @@
+// An animated grid volume (#1045): a converted VDB sequence on a round diorama, drawn by the rasterizer.
+// node bench/reference/volume-grid-vdb-sequence.mjs <grid folder> <output folder> [--width 1920] [--height 1080] [--fps 30] [--repeats 5] [--clip] [--voxel 0.05]
+// It prints milliseconds per frame (median, p95, worst) over the whole sequence in two passes: the frame changes on every draw
+// (one texSubImage3D upload each) and a held frame (no upload). With --clip it also writes frame_0000.png, frame_0001.png, ... to the output folder.
+// Chrome comes from CHROME_PATH; on a Linux GPU box pass CHROME_ARGS="--use-angle=vulkan --enable-features=Vulkan --ignore-gpu-blocklist --no-sandbox".
+// The grids come from `uv run --no-project --with numpy --with blosc scripts/vdb-to-grid.py "<sim>/*.vdb" <folder>/blast --sequence`.
+import { createServer as createHttpServer } from 'node:http';
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { chromium } from 'playwright';
+import { createServer } from 'vite';
+
+const positional = process.argv.slice(2).filter((argument, index, list) => !argument.startsWith('--') && !(index > 0 && list[index - 1].startsWith('--') && list[index - 1] !== '--clip'));
+const [gridFolder, outputFolder] = positional;
+if (!gridFolder || !outputFolder) throw new Error('usage: node bench/reference/volume-grid-vdb-sequence.mjs <grid folder> <output folder> [--width 1920] [--height 1080] [--fps 30] [--repeats 5] [--clip] [--voxel 0.05]');
+const option = (name, fallback) => {
+ const at = process.argv.indexOf(`--${name}`);
+ return at === -1 ? fallback : Number(process.argv[at + 1]);
+};
+const writeClip = process.argv.includes('--clip');
+const CHROME = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';
+const CHROME_ARGS = (process.env.CHROME_ARGS ?? '--enable-webgl --ignore-gpu-blocklist --use-angle=d3d11 --enable-gpu').split(' ');
+const options = { width: option('width', 1920), height: option('height', 1080), fps: option('fps', 30), repeats: option('repeats', 5), voxelMetres: option('voxel', 0.05), writeClip };
+const gridNames = readdirSync(gridFolder).filter(name => name.endsWith('.67vg')).sort();
+if (gridNames.length === 0) throw new Error(`No .67vg files in ${gridFolder}. Convert a VDB sequence with scripts/vdb-to-grid.py --sequence first.`);
+
+// Runs in the page. The scene is the "Slow-motion explosion" shot of #1993: a round slab on a plinth, a high oblique camera, no sky.
+async function drawSequence({ baseUrl, gridNames, width, height, fps, repeats, voxelMetres, writeClip }) {
+ const { cylinder } = await import('/src/geometry.js');
+ const { CrucibleRenderer } = await import('/src/renderer.js');
+ const { decodeVolumeGrid, registerVolumeGrid } = await import('/src/volume-grid.js');
+ await import('/src/fog-shader.js');
+ let size;
+ for (const name of gridNames) {
+ const grid = decodeVolumeGrid(new Uint8Array(await (await fetch(`${baseUrl}/${name}`)).arrayBuffer()));
+ registerVolumeGrid(name, grid);
+ size = grid.size.map(extent => extent * voxelMetres);
+ }
+ const placed = (translation, scale, color, roughness = 0.9) => ({
+ geometry: cylinder(128, 0.01, 4),
+ matrix: new Float32Array([scale[0], 0, 0, 0, 0, scale[1], 0, 0, 0, 0, scale[2], 0, translation[0], translation[1], translation[2], 1]),
+ material: { tag: 'surface', color, metallic: 0, roughness, emission: 0 },
+ });
+ const parts = [placed([0, -0.1, 0], [8, 0.2, 8], [0.62, 0.5, 0.33]), placed([0, -1.3, 0], [8.45, 2.2, 8.45], [0.2, 0.2, 0.22], 0.5), placed([0, -2.35, 0], [9.5, 0.35, 9.5], [0.12, 0.12, 0.13], 0.6)];
+ const volume = {
+ shape: 'grid', frames: gridNames, fps, loop: false, center: [0, size[1] / 2 - 0.35, 0.4], size, density: 8,
+ emission: [1, 0.4, 0.08], emissionStrength: 12, absorption: [0.9, 0.85, 0.8], steps: 96, lightsScene: true,
+ };
+ const canvas = document.createElement('canvas');
+ canvas.width = width;
+ canvas.height = height;
+ document.body.append(canvas);
+ const renderer = new CrucibleRenderer(canvas, parts, { hdr: true, depth: true, samples: 1, pixelRatio: 1, ground: false, background: [0.012, 0.014, 0.018] });
+ // The camera of the Cycles piece this shot follows: 50 mm lens on a 36 mm sensor, 31 degrees up, 40 m away, drifting round the blast.
+ const frameAt = clipFrame => {
+ const progress = (75 + clipFrame - 1) / 242;
+ const azimuth = (-58 + 14 * progress) * Math.PI / 180;
+ const elevation = 31 * Math.PI / 180;
+ const reach = 40 - 3 * progress;
+ const target = [0, 3, 0];
+ // Blender is z up with y toward the back: (x, y, z) becomes (x, z, -y).
+ const eye = [target[0] + Math.cos(azimuth) * Math.cos(elevation) * reach, target[1] + Math.sin(elevation) * reach, target[2] - Math.sin(azimuth) * Math.cos(elevation) * reach];
+ return { eye, target, focalLength: 50, far: 200, time: clipFrame / fps + 0.0001, environment: { keyIntensity: 0.45, fillIntensity: 0.04, ambientIntensity: 0.1, lightDirection: [-9, 22, -6], localVolumes: [volume] } };
+ };
+ const pixel = new Uint8Array(4);
+ const draw = clipFrame => {
+ renderer.render(frameAt(clipFrame));
+ renderer.context.readPixels(0, 0, 1, 1, renderer.context.RGBA, renderer.context.UNSIGNED_BYTE, pixel);
+ };
+ const frameCount = gridNames.length;
+ for (let index = 0; index < 8; index++) draw(index);
+ const summarize = list => {
+ const sorted = [...list].sort((first, second) => first - second);
+ return { median: sorted[sorted.length >> 1], p95: sorted[Math.floor(sorted.length * 0.95)], worst: sorted[sorted.length - 1] };
+ };
+ const passes = { changingFrame: [], heldFrame: [] };
+ for (let repeat = 0; repeat < repeats; repeat++) {
+ const changing = [];
+ const held = [];
+ for (let index = 0; index < frameCount; index++) {
+ const started = performance.now();
+ draw(index);
+ changing.push(performance.now() - started);
+ }
+ for (let index = 0; index < frameCount; index++) {
+ const started = performance.now();
+ draw(frameCount >> 1);
+ held.push(performance.now() - started);
+ }
+ passes.changingFrame.push(summarize(changing));
+ passes.heldFrame.push(summarize(held));
+ }
+ const clipFrames = [];
+ if (writeClip) {
+ const snapshot = document.createElement('canvas');
+ snapshot.width = width;
+ snapshot.height = height;
+ const snapshotContext = snapshot.getContext('2d');
+ for (let index = 0; index < frameCount; index++) {
+ draw(index);
+ snapshotContext.drawImage(canvas, 0, 0);
+ clipFrames.push(snapshot.toDataURL('image/png').split(',')[1]);
+ }
+ }
+ return { passes, clipFrames, glError: renderer.context.getError(), size };
+}
+
+const files = createHttpServer((request, response) => {
+ const name = decodeURIComponent(request.url.slice(1));
+ if (!gridNames.includes(name)) {
+ response.writeHead(404).end();
+ return;
+ }
+ response.writeHead(200, { 'content-type': 'application/octet-stream', 'access-control-allow-origin': '*' }).end(readFileSync(join(gridFolder, name)));
+});
+await new Promise(resolve => files.listen(0, '127.0.0.1', resolve));
+const server = await createServer({ server: { host: '127.0.0.1', port: 0 }, logLevel: 'silent' });
+await server.listen();
+const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: CHROME_ARGS });
+try {
+ const page = await browser.newPage({ viewport: { width: options.width, height: options.height } });
+ await page.goto(`http://127.0.0.1:${server.httpServer.address().port}/`);
+ const baseUrl = `http://127.0.0.1:${files.address().port}`;
+ const result = await page.evaluate(drawSequence, { ...options, baseUrl, gridNames });
+ mkdirSync(outputFolder, { recursive: true });
+ result.clipFrames.forEach((image, index) => writeFileSync(join(outputFolder, `frame_${String(index).padStart(4, '0')}.png`), Buffer.from(image, 'base64')));
+ const round = value => Number(value.toFixed(2));
+ const rows = list => list.map(row => ({ median: round(row.median), p95: round(row.p95), worst: round(row.worst) }));
+ console.log(JSON.stringify({ grids: gridNames.length, width: options.width, height: options.height, glError: result.glError, sizeMetres: result.size, changingFrameMillisecondsPerFrame: rows(result.passes.changingFrame), heldFrameMillisecondsPerFrame: rows(result.passes.heldFrame) }, null, 2));
+ if (result.glError !== 0) process.exitCode = 1;
+} finally {
+ await browser.close();
+ await server.close();
+ files.close();
+}
diff --git a/changes/1045.md b/changes/1045.md
new file mode 100644
index 00000000..d0ef8ad9
--- /dev/null
+++ b/changes/1045.md
@@ -0,0 +1 @@
+- A grid volume sequence changes frames about 6 times faster: the half float decode table is built once and a grid with no temperature uploads no emission texels, which brings a 90 frame JangaFX explosion to a median of 21 to 29 ms a frame at 1080p on an RTX 3060 (#1045)
diff --git a/changes/1045.size.md b/changes/1045.size.md
new file mode 100644
index 00000000..00215c75
--- /dev/null
+++ b/changes/1045.size.md
@@ -0,0 +1 @@
+- scene:agent-scene+lazy: 100 bytes gzip for a once-built half float table and an early exit that make a grid sequence about 6 times faster per frame (180 ms to 21-29 ms median at 1080p).
diff --git a/docs/volumetric.md b/docs/volumetric.md
index 4a8a2f5a..bb8d5522 100644
--- a/docs/volumetric.md
+++ b/docs/volumetric.md
@@ -238,6 +238,8 @@ One grid volume per scene for now. The rasterizer samples two RGBA16F 3D texture
`uv run --no-project scripts/vdb-to-grid.py "sim/smoke_*.vdb" blast --sequence --max-resolution 128` converts a numbered VDB sequence in one run: the files are sorted by their numbers (`smoke_2` before `smoke_10`), every frame is put on the union of all the frames' boxes so the resolution is the same, and the files `blast_0000.67vg`, `blast_0001.67vg` and so on are written, each with every channel any frame has (zero where a frame has none, so the shader never reads the density as flame there). A frame with an empty density grid is written empty with a warning that names the file. The byte budget is checked after the first pass and before anything is written. The script prints the `frames` list to paste into the volume.
+**Playback cost of a real sequence.** `node bench/reference/volume-grid-vdb-sequence.mjs <grid folder> <output folder> [--width 1920] [--height 1080] [--clip]` plays a converted VDB sequence on a round diorama (a slab on a plinth, a high oblique camera, no sky) and prints milliseconds per frame over the whole sequence, with the frame changing on every draw (one upload each) and with a held frame. Measured on the CC0 "Ground Explosion" by JangaFX (EmberGen), 90 frames converted with `--max-resolution 96` to 82 x 93 x 96 voxels with density and flame, on an RTX 3060 shared with other jobs, 1920 x 1080, five runs: the median of a changing frame was 20.5 to 29.1 ms (30 fps is 33.3 ms), its 95th percentile 30 to 44 ms and its worst frame 40 to 58 ms, and a held frame took a median of 6.8 to 11.0 ms. Before #1045 stopped rebuilding the half float table for every frame, walking the fire light's emission with an array per cell and uploading a zero emission texture for a grid with no temperature, the same sequence took a median of 180 ms a frame at 960 x 540. The 95th percentile is above 33 ms, so a frame now and then misses 30 fps.
+
**Grid file.** `"67VG"`, a uint32 version (1), a uint32 header length, a JSON header `{ "resolution": [x, y, z], "channels": ["density", "flame"], "size": [x, y, z] }` padded to 4 bytes, then each channel as half floats, x fastest, then y, then z, y up. Each axis is 1 to 256 and the data at most 64 MiB; anything past that is refused with the limit and the `--max-resolution` to use.
**From a VDB.** `uv run --no-project scripts/vdb-to-grid.py frame.vdb blast.67vg --max-resolution 128` reads OpenVDB float grids by their usual names (`density`; `temperature` or `heat`; `flame`, `flames` or `fire`), turns a z-up file to y up, box-averages down to the resolution and writes the file. `--map flame=burn` reads a channel from another grid name and `--up y` leaves the axes alone. The reader is in the script (OpenVDB file version 222 or later, float grids, none, zip or Blosc compression; Blosc, openvdb's default, needs `uv run --no-project --with blosc scripts/vdb-to-grid.py ...`, and without it the error prints that command), so it needs numpy only: no OpenVDB wheel exists for Windows, and `pyopenvdb` on PyPI is a 2020 Python 3.7 build.
diff --git a/src/fog-shader.js b/src/fog-shader.js
index 0caefa2c..4f5a4d4a 100644
--- a/src/fog-shader.js
+++ b/src/fog-shader.js
@@ -242,12 +242,13 @@ function localGridTexture(renderer, grid) {
function localGridEmissionTexture(renderer, volume) {
const grid = volume?.gridData ?? null;
- const baked = grid ? bakedGridEmission(grid, volume.temperatureScale) : null;
- return uploadGridTexture(renderer, 'localGridEmissionCache', grid, volume?.temperatureScale ?? 0, (texels, voxel, texel) => {
+ // A grid without a temperature channel bakes to zeros: its texture is the zero fill, with no pass over the voxels.
+ const baked = grid?.channels.temperature ? bakedGridEmission(grid, volume.temperatureScale) : null;
+ return uploadGridTexture(renderer, 'localGridEmissionCache', grid, volume?.temperatureScale ?? 0, baked && ((texels, voxel, texel) => {
texels[texel] = floatToHalf(Math.min(baked.red[voxel], HALF_FLOAT_MAXIMUM));
texels[texel + 1] = floatToHalf(Math.min(baked.green[voxel], HALF_FLOAT_MAXIMUM));
texels[texel + 2] = floatToHalf(Math.min(baked.blue[voxel], HALF_FLOAT_MAXIMUM));
- });
+ }));
}
// The gas velocity of a grid with velocity channels as box fractions per second, x y z (volume-grid.js gridUnitVelocity), for the motion blur of the march (#1759).
@@ -268,6 +269,12 @@ function uploadGridTexture(renderer, cacheName, grid, scale, writeVoxel) {
const resolution = grid ? grid.resolution : [1, 1, 1];
// The next frame of a sequence has the resolution of the one before: overwrite its texture instead of making a new one.
const reuse = cached && cached.resolution.join('x') === resolution.join('x');
+ const filled = Boolean(grid && writeVoxel);
+ if (reuse && !filled && !cached.filled) {
+ // Zeros over zeros (the emission of a grid with no temperature): nothing to upload.
+ renderer[cacheName] = { ...cached, grid, scale };
+ return cached.texture;
+ }
const texture = reuse ? cached.texture : context.createTexture();
if (cached && !reuse) context.deleteTexture(cached.texture);
context.bindTexture(context.TEXTURE_3D, texture);
@@ -278,7 +285,7 @@ function uploadGridTexture(renderer, cacheName, grid, scale, writeVoxel) {
}
const padded = resolution.map(count => count + 2 * GRID_BORDER_VOXELS);
const texels = new Uint16Array(padded[0] * padded[1] * padded[2] * 4);
- if (grid) {
+ if (filled) {
for (let z = 0; z < resolution[2]; z++) {
for (let y = 0; y < resolution[1]; y++) {
for (let x = 0; x < resolution[0]; x++) {
@@ -295,7 +302,7 @@ function uploadGridTexture(renderer, cacheName, grid, scale, writeVoxel) {
} else {
context.texImage3D(context.TEXTURE_3D, 0, context.RGBA16F, padded[0], padded[1], padded[2], 0, context.RGBA, context.HALF_FLOAT, texels);
}
- renderer[cacheName] = { grid, scale, texture, resolution };
+ renderer[cacheName] = { grid, scale, texture, resolution, filled };
return texture;
}
diff --git a/src/local-volume-fire-light.js b/src/local-volume-fire-light.js
index 1da5565f..34fb992f 100644
--- a/src/local-volume-fire-light.js
+++ b/src/local-volume-fire-light.js
@@ -35,14 +35,16 @@ function gridEmissionSums(gridData, volume) {
const total = [0, 0, 0];
const centroidWeight = [0, 0, 0];
const blackbody = [0, 0, 0];
+ const emitted = [0, 0, 0];
+ const glows = volume.blackbodyIntensity > 0 && temperature;
for (let z = 0; z < depth; z++) {
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const cell = x + y * width + z * width * height;
const flameValue = flame ? flame[cell] : 0;
- const emitted = [0, 0, 0];
+ if (flameValue === 0 && !glows) continue; // an empty cell emits nothing; a sequence runs this over every frame, so it stays free of allocations
for (let channel = 0; channel < 3; channel++) emitted[channel] = volume.emission[channel] * volume.emissionStrength * flameValue;
- if (volume.blackbodyIntensity > 0 && temperature) {
+ if (glows) {
blackbodyRadiance(temperature[cell] * volume.temperatureScale, blackbody);
for (let channel = 0; channel < 3; channel++) emitted[channel] += blackbody[channel] * volume.blackbodyIntensity * volume.emissionStrength;
}
diff --git a/src/volume-grid.js b/src/volume-grid.js
index 50114730..b77cbf7e 100644
--- a/src/volume-grid.js
+++ b/src/volume-grid.js
@@ -214,17 +214,29 @@ export function findVolumeGrid(name, label) {
const decodedByGrid = new WeakMap();
+let halfFloatLookup = null;
+
+// Every half float bit pattern as a float, built once for the process: a sequence decodes a grid per frame, and building the table for each one cost about as much as the decode.
+function halfFloatTable() {
+ if (halfFloatLookup) return halfFloatLookup;
+ halfFloatLookup = new Float32Array(65536);
+ for (let bits = 0; bits < 65536; bits++) halfFloatLookup[bits] = halfToFloat(bits);
+ return halfFloatLookup;
+}
+
/** The grid's channels as Float32Arrays, decoded once; a missing temperature or flame channel is left out. */
export function volumeGridFloats(grid) {
let floats = decodedByGrid.get(grid);
if (floats) return floats;
floats = Object.create(null);
- const table = new Float32Array(65536);
- for (let bits = 0; bits < 65536; bits++) table[bits] = halfToFloat(bits);
+ const table = halfFloatTable();
// Only the known channel names become keys, so a name read from a grid file can never write another property.
for (const name of VOLUME_GRID_CHANNELS) {
const values = grid.channels[name];
- if (values) floats[name] = Float32Array.from(values, bits => table[bits]);
+ if (!values) continue;
+ const decoded = new Float32Array(values.length);
+ for (let index = 0; index < values.length; index++) decoded[index] = table[values[index]];
+ floats[name] = decoded;
}
decodedByGrid.set(grid, floats);
return floats;
diff --git a/tests/volume-grid.test.js b/tests/volume-grid.test.js
index 2309f564..33b0a7fe 100644
--- a/tests/volume-grid.test.js
+++ b/tests/volume-grid.test.js
@@ -25,6 +25,19 @@ test('half floats round trip the values a simulation stores', () => {
assert.equal(floatToHalf(1e9), 0x7c00, 'past the range is infinity');
});
+test('the decoded floats of a grid are the half float of every bit pattern, for each channel', () => {
+ const everyPattern = new Uint16Array(65536).map((_, bits) => bits);
+ const grid = { resolution: [256, 16, 16], size: [1, 1, 1], channels: { density: everyPattern, flame: everyPattern.slice().reverse() } };
+ const floats = volumeGridFloats(grid);
+ for (let bits = 0; bits < 65536; bits++) {
+ const expected = halfToFloat(bits);
+ const reversed = halfToFloat(65535 - bits);
+ assert.ok(Object.is(floats.density[bits], Math.fround(expected)) || Number.isNaN(expected) && Number.isNaN(floats.density[bits]), `density bits ${bits}`);
+ assert.ok(Object.is(floats.flame[bits], Math.fround(reversed)) || Number.isNaN(reversed) && Number.isNaN(floats.flame[bits]), `flame bits ${bits}`);
+ }
+ assert.equal(volumeGridFloats(grid), floats, 'decoded once per grid');
+});
+
test('a grid file encodes and decodes with its channels, resolution and size', () => {
const resolution = [4, 3, 2];
const bytes = encodeVolumeGrid({ resolution, size: [2, 1.5, 1], channels: uniformGrid(resolution, { density: 0.75, flame: 2 }) });