Repository navigation
Render dense grid volumes with Principled Volume terms (#44) - #55
Merged
Merged
Conversation
Grid volumes are 3D grids of density, temperature and flame placed by a box, read from scene.gridVolumes (the .67vg layout of Crucible's volume-grid.js). They live in the texture texel pool behind a descriptor table, found through the two reserved words of KernelParamsV2 and kernel flag 8192, so no binding changes and a pack without grids is unchanged bit for bit. The kernel walks camera and path rays with delta tracking against a global majorant and shadow rays with ratio tracking, with absorption colour, scattering with Henyey-Greenstein anisotropy, emission per unit length and physical blackbody from temperature. Tools compare one Crucible explosion frame with the Cycles reference.
This was referenced Nov 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #44. The Crucible pin bump that stops the native backend throwing for grid volumes is a separate change.
What it does
Cook renders dense grid volumes: 3D grids of density, temperature and flame (half or full floats) placed by a box, with the
.67vgchannel layout of Crucible'svolume-grid.js(decodeGridFilereads it). Passscene.gridVolumes.5.670373e-8 * 1e-6 / pi * T^4 * blackbodyIntensitytimes the Planck colour of luminance 1, the same table Crucible uses.KernelParamsV2and kernel flag 8192; the kernel code is compiled in only for such a pack. Format notes are in FORMAT-v2.md, "Grid volumes". The new code issrc/cycles/grid_volume.wgslandgrid-volume-input.mjs;integrator.wgslgets six small hooks.Evidence
One frame of the #1735 explosion (frame 9, 427x240, same spec for both): Cook on the left, Blender 5.3 Cycles on the right, linear data tone mapped the same way.
Measured on an RTX 3060 (Cook) and the CPU with 8 threads (Cycles), linear RGB, image mean 0.1454:
Most of the first number is noise. The two renders' own noise is about 0.0017 together (inferred from their per-pixel noise at 16 spp scaled to those sample counts), which leaves a bias of about 0.002, 1.4% (inferred). The error sits in the fire (RMSE 0.0069 there, 0.0004 on the open floor).
Noise (standard deviation of one render, from two seeds, same frame):
At equal samples Cook is noisier (0.0286 against 0.0156 at 16 spp, 1.8 times). At equal time it is 1.8 times less noisy than fixed-sample Cycles and equal to Cycles with its adaptive sampling. GPU against CPU, so the time comparison says little about the algorithms.
No grids, no change: the SHA-256 of the linear output of the room fixture (160x120, 16 spp) is
7dc98f89...2862and of a world fog scene (128x96, 32 spp, sun, albedo and anisotropy) is276f3dc0...eda6, identical between the addon built frommainand this branch.How I checked it
node --test: 194 pass, none skipped (a GPU adapter with ray queries was present). New:tests/grid-volume-input.test.mjs(input validation, descriptor layout,.67vgdecoding, the no-grid pack equals the old one) andtests/gpu/grid-volume.test.mjs, three closed forms: a camera ray through a box with chromatic absorption keepsexp(-sigma * length)of the background per channel; a shadow ray through a slab gives the same transmittance by ratio tracking (shadowed over open floor pixel); the emission of a box equals the numeric integral ofemission * density * exp(-optical depth). The box edge is half density at a face, so the closed forms uselength * (1 - 1 / (4 n)).node tools/run-cargo-tests.mjs: 139 and 23 pass, with two new tests on the specialization and the module in the kernel manifest. The existing texel pool invariant test now allows the grid readervg_word, which is not a texture sampler.node tools/check-exports.mjsandrelease-guardagainstorigin/main: clean.node tools/grid-volume-parity.mjs <spec.json> <grid.67vg> <prefix> --samples Nrenders Cook, Crucible'sscripts/cycles-volume-reference.pyrenders Cycles,tools/exr-to-npy.pyconverts the EXR in Blender, andtools/grid-volume-compare.mjs rmse|noisescores.Not in this slice
gby their scattering.