VDB Volumes
A VDB volume renders a baked density grid, such as smoke, fire, an explosion or a cloud, exported from Houdini, Blender or EmberGen as an OpenVDB (.vdb) or NanoVDB (.nvdb) file. You import the file as a VDB Volume asset and place it with a VDB Volume component (category Effects). The asset supplies the density grid and its bounds; the component supplies the shading, playback and transform.
VDB volumes render even when volumetric fog is off. Rendering.VDBVolumes.Enabled turns all of them off.
Import a volume
- Drop the
.vdbor.nvdbfile into the asset browser, or create a VDB Volume asset and pick the file in its File property. - Leave Density Grid empty to use the first grid in the file, or enter the grid's name. Optionally set a Temperature Grid (for emission) and a Velocity Grid (for detail that follows the motion).
- Pick the Resolution Mode and Max Resolution (256) for the baked grid.
- Leave Detail Map on (see Baked detail maps).
- For a simulation with numbered frames, turn on Import Sequence. Max Frames (120) caps how many frames are baked, and Frames Per Second (24) is the stored playback rate.
- Transform the asset.
| Property | Default | Description |
|---|---|---|
| File | Source .vdb or .nvdb file. | |
| Density Grid | empty | Grid that supplies density. Empty takes the first grid. |
| Temperature Grid | empty | Optional grid that supplies temperature, used for emission. |
| Velocity Grid | empty | Optional vector grid that supplies velocity. |
| Resolution Mode | Auto From Voxel Size | Auto From Voxel Size keeps the source voxel size (clamped by Max Resolution), Voxels Per Metre resamples to a fixed density, Fixed makes the longest axis exactly Max Resolution. |
| Max Resolution | 256 | Clamp on the longest axis of the baked grid, 8–512, rounded to a power of two. |
| Voxels Per Metre | 32 | Target density in Voxels Per Metre mode. |
| Density Scale | 1 | Multiplier applied to density while baking. |
| Border Voxels | 1 | Empty voxels kept around the active bounds. At least 1 prevents a hard skin at the edge. |
| Format | R8 | Voxel format: R8 or R16F (density only), RG8 (density and temperature), RGBA8 (density and emission or velocity), RGBA16F (density and signed velocity), BC4 (density only, block compressed at half the size of R8). |
| Generate Mips | true | Bakes the mip chain that self-shadowing and ambient occlusion read. |
| Detail Map | true | Bakes a quarter-resolution map of where downsampling lost structure. Dense volumes only. |
| Sparse Storage | false | Stores only the occupied 8×8×8 bricks. Saves a lot of memory above 256³. Sequences ignore it. |
| Sparse Threshold | 0.004 | Bricks whose peak density is below this are dropped. |
| Blackbody From Temperature | false | Derives emission colour from the temperature grid with a blackbody ramp. |
| Blackbody Intensity | 1 | Scale of the blackbody emission. |
| Import Sequence | false | Bakes every numbered frame next to the source file into one animated volume. |
| Max Frames | 120 | Caps the number of baked frames. 0 = no limit. |
| Frames Per Second | 24 | Playback rate stored with the volume. |
Place a volume
Add a VDB Volume component to a game object and set Volume to the asset.
| Property | Default | Description |
|---|---|---|
| Volume | The VDB Volume asset. | |
| Density Scale | 1 | Multiplier on density. |
| Albedo | white | Scattering colour. |
| Emission Color, Emission Scale | black, 0 | Self-illumination, for example for fire. |
| Anisotropy | 0 | Phase function, -0.99 to 0.99. Positive values scatter forward (bright when looking towards the light). |
| Playback Speed | 1 | Multiplier on the sequence's frame rate. 0 freezes playback. |
| Loop | true | Loops an animated volume. |
| Start Frame | 0 | Frame shown while stopped, and where playback starts. |
| Prewarm | true | Loads the sequence into GPU memory before it is needed, so a one-shot effect does not stream while it plays. Turn it off for long, always-visible sequences. |
| Render Mode | Auto | How the volume is drawn. See Render modes. |
Scripts can call Restart() to replay an animated volume from its start frame, and IsPrewarmed() to hold a trigger back until every frame that fits is loaded.
Render modes
| Mode | What it does |
|---|---|
| Froxel | Injects the volume into the volumetric fog's froxel grid. Cheap, and it inherits the fog's lighting and shadowing, but it is limited to the froxel resolution. A volume of a few metres at 20 m collapses into one or two froxel slices and turns into a faint haze. |
| Ray March | Ray marches the volume at full resolution with procedural detail, whatever its size on screen. |
| Auto (default) | Ray marches while the volume covers at least Rendering.VDBVolumes.AutoMarchScreenPixels (64) pixels on screen (bounding sphere diameter), and uses the froxel grid once it is smaller. |
The ray march only runs on the screen tiles that marched volumes cover (Rendering.VDBVolumes.TileDispatch), so a small volume costs little. Rendering.VDBVolumes.AllowRayMarch off is a quality cap that forces every volume into the froxel grid.
Edge detail
A bake at 128³ or 256³ smooths out the thin, wispy edges of a simulation. When the volume is ray marched, procedural edge detail breaks up the low-density edge band again with noise. The baked core above the edge band keeps its shape. The detail fades out once its features would be smaller than a pixel (Rendering.VDBVolumes.DetailFadePixels), so it never shimmers.
| Property (Detail group) | Default | Description |
|---|---|---|
| Detail Enabled | true | Procedural edge detail. Only the ray march draws it. |
| Detail Strength | 0.7 | How much of the edge band the detail may erode, 0–1. |
| Detail Size | 0.15 m | World-space size of one detail feature. |
| Detail Edge Band | 0.5 | Normalised density below which detail applies, 0.05–1. |
| Detail Motion | Follow Velocity | Follow Velocity advects the detail with the baked velocity grid (and uses Drift when the bake has none), Drift moves it at a constant velocity, Static fixes it to the volume. |
| Detail Drift | (0, 0, 0.4) m/s | Velocity in Drift mode, and the fallback for Follow Velocity. |
| Light Detail | true | Self-shadowing of the detail, at one extra noise tap towards each shadowed light. |
Baked detail maps
With Detail Map on in the asset, the importer bakes a quarter-resolution map of where downsampling lost structure. The renderer then puts detail only where the source actually had it, instead of spreading it over the whole edge band. Rendering.VDBVolumes.DetailMap off ignores the map. Sparse volumes have no detail map, because their brick table takes the slot the map would use.
Lighting
Each light that overlaps a VDB volume renders a volumetric shadow map of it, which shadows the volume itself, the scene behind it and the fog (Rendering.VDBVolumes.VolumetricShadows). Ambient light inside the volume is darkened by the density around it, so a volume in shadow keeps a solid core.
Multiple scattering. Light that scatters several times inside a dense volume brightens its core. Rendering.VDBVolumes.ScatterOctaves (2) sets how many scattering octaves are approximated, 1–3. 1 is single scattering. Both render paths use the same value, so a volume looks the same in froxel and ray march mode.
Shared lighting. Rendering.VDBVolumes.SharedLighting is off by default: every pixel of the ray march lights its own samples. On, pixels deep inside a volume share lighting samples with their neighbours (4 pixels below a transmittance of LightingHalfRateBelow, 0.6, and 16 below LightingQuarterRateBelow, 0.25). In testing it was slower than per-pixel lighting and smeared local light falloff into blocks, so leave it off unless you have measured a gain in your scene.
CVars
| CVar | Default | Description |
|---|---|---|
Rendering.VDBVolumes.Enabled | true | Renders VDB volumes. |
Rendering.VDBVolumes.AllowRayMarch | true | Off renders every volume through the froxel grid. |
Rendering.VDBVolumes.AutoMarchScreenPixels | 64 | Projected size below which an Auto volume uses the froxel grid. |
Rendering.VDBVolumes.TileDispatch | true | Ray marches only the screen tiles that volumes cover. |
Rendering.VDBVolumes.RayMarchSteps | 64 | Samples along each view ray. Set by quality presets. |
Rendering.VDBVolumes.RayMarchShadowSteps | 4 | Samples towards each light for self-shadowing. Set by quality presets. |
Rendering.VDBVolumes.EdgeStepScale | 1 | Step length multiplier where detail applies. Below 1 resolves finer detail at extra cost, for close-up shots. |
Rendering.VDBVolumes.InteriorStepScale | 1.5 | Step length multiplier in the detail-free core. |
Rendering.VDBVolumes.Detail | true | Procedural edge detail. Quality presets turn it off on Low. |
Rendering.VDBVolumes.DetailMap | true | Uses baked detail maps to place the detail. |
Rendering.VDBVolumes.DetailFadePixels | 1 | Feature size in pixels at which detail has faded out. |
Rendering.VDBVolumes.ScatterOctaves | 2 | Multiple-scattering octaves, 1–3. Quality presets use 1 on Low, 2 on Medium and 3 on High and Max. |
Rendering.VDBVolumes.SharedLighting | false | Shares lighting samples between neighbouring pixels deep inside volumes. |
Rendering.VDBVolumes.VolumetricShadows | true | Volumes cast volumetric shadows on themselves and the scene. |
Rendering.VDBVolumes.SelfShadowTaps | 5 | Samples towards a directional light in the froxel path. 0 disables self-shadowing. Set by quality presets. |
Rendering.VDBVolumes.ShadowResolution | 128 | Size of each volumetric shadow map. Set by quality presets. |
Rendering.VDBVolumes.AmbientOcclusion | 4 | How strongly surrounding density occludes sky light. 0 disables it. |
Rendering.VDBVolumes.AmbientStrength | 1 | Multiplier on sky light in the ray march. |
Rendering.VDBVolumes.Powder | 0.4 | Darkens thin lit fringes so edges do not wash out. |
Rendering.VDBVolumes.DebugView | 0 | 1 = detail cost (noise fetches per pixel), 2 = detail mask, 3 = march tiles. |
The quality presets set the step counts, self-shadow taps, shadow resolution, edge detail and scattering octaves per tier.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| A distant volume turns into a faint haze | It is in Froxel mode, or AllowRayMarch is off. Use Auto or Ray March. |
| Banding or visible slices in the ray march | Too few steps for the volume's depth. Raise RayMarchSteps or lower EdgeStepScale. |
| Edges look noisy where the simulation was smooth | Lower Detail Strength or Detail Edge Band, or rebake with Detail Map on so detail goes only where the source had it. |
| Blocky glow around point lights inside the volume | Rendering.VDBVolumes.SharedLighting is on. Turn it off. |
| An animated volume stutters on first play | Leave Prewarm on, and wait for IsPrewarmed() before triggering the effect. |