3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
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.mjsnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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.jsindex 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.jsindex 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 allocationsfor (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.jsindex 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.jsindex 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 }) });