Skip to main content
Version: Next (dev)

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​

  1. Drop the .vdb or .nvdb file into the asset browser, or create a VDB Volume asset and pick the file in its File property.
  2. 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).
  3. Pick the Resolution Mode and Max Resolution (256) for the baked grid.
  4. Leave Detail Map on (see Baked detail maps).
  5. 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.
  6. Transform the asset.
PropertyDefaultDescription
FileSource .vdb or .nvdb file.
Density GridemptyGrid that supplies density. Empty takes the first grid.
Temperature GridemptyOptional grid that supplies temperature, used for emission.
Velocity GridemptyOptional vector grid that supplies velocity.
Resolution ModeAuto From Voxel SizeAuto 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 Resolution256Clamp on the longest axis of the baked grid, 8–512, rounded to a power of two.
Voxels Per Metre32Target density in Voxels Per Metre mode.
Density Scale1Multiplier applied to density while baking.
Border Voxels1Empty voxels kept around the active bounds. At least 1 prevents a hard skin at the edge.
FormatR8Voxel 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 MipstrueBakes the mip chain that self-shadowing and ambient occlusion read.
Detail MaptrueBakes a quarter-resolution map of where downsampling lost structure. Dense volumes only.
Sparse StoragefalseStores only the occupied 8×8×8 bricks. Saves a lot of memory above 256³. Sequences ignore it.
Sparse Threshold0.004Bricks whose peak density is below this are dropped.
Blackbody From TemperaturefalseDerives emission colour from the temperature grid with a blackbody ramp.
Blackbody Intensity1Scale of the blackbody emission.
Import SequencefalseBakes every numbered frame next to the source file into one animated volume.
Max Frames120Caps the number of baked frames. 0 = no limit.
Frames Per Second24Playback rate stored with the volume.

Place a volume​

Add a VDB Volume component to a game object and set Volume to the asset.

PropertyDefaultDescription
VolumeThe VDB Volume asset.
Density Scale1Multiplier on density.
AlbedowhiteScattering colour.
Emission Color, Emission Scaleblack, 0Self-illumination, for example for fire.
Anisotropy0Phase function, -0.99 to 0.99. Positive values scatter forward (bright when looking towards the light).
Playback Speed1Multiplier on the sequence's frame rate. 0 freezes playback.
LooptrueLoops an animated volume.
Start Frame0Frame shown while stopped, and where playback starts.
PrewarmtrueLoads 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 ModeAutoHow 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​

ModeWhat it does
FroxelInjects 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 MarchRay 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)DefaultDescription
Detail EnabledtrueProcedural edge detail. Only the ray march draws it.
Detail Strength0.7How much of the edge band the detail may erode, 0–1.
Detail Size0.15 mWorld-space size of one detail feature.
Detail Edge Band0.5Normalised density below which detail applies, 0.05–1.
Detail MotionFollow VelocityFollow 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/sVelocity in Drift mode, and the fallback for Follow Velocity.
Light DetailtrueSelf-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​

CVarDefaultDescription
Rendering.VDBVolumes.EnabledtrueRenders VDB volumes.
Rendering.VDBVolumes.AllowRayMarchtrueOff renders every volume through the froxel grid.
Rendering.VDBVolumes.AutoMarchScreenPixels64Projected size below which an Auto volume uses the froxel grid.
Rendering.VDBVolumes.TileDispatchtrueRay marches only the screen tiles that volumes cover.
Rendering.VDBVolumes.RayMarchSteps64Samples along each view ray. Set by quality presets.
Rendering.VDBVolumes.RayMarchShadowSteps4Samples towards each light for self-shadowing. Set by quality presets.
Rendering.VDBVolumes.EdgeStepScale1Step length multiplier where detail applies. Below 1 resolves finer detail at extra cost, for close-up shots.
Rendering.VDBVolumes.InteriorStepScale1.5Step length multiplier in the detail-free core.
Rendering.VDBVolumes.DetailtrueProcedural edge detail. Quality presets turn it off on Low.
Rendering.VDBVolumes.DetailMaptrueUses baked detail maps to place the detail.
Rendering.VDBVolumes.DetailFadePixels1Feature size in pixels at which detail has faded out.
Rendering.VDBVolumes.ScatterOctaves2Multiple-scattering octaves, 1–3. Quality presets use 1 on Low, 2 on Medium and 3 on High and Max.
Rendering.VDBVolumes.SharedLightingfalseShares lighting samples between neighbouring pixels deep inside volumes.
Rendering.VDBVolumes.VolumetricShadowstrueVolumes cast volumetric shadows on themselves and the scene.
Rendering.VDBVolumes.SelfShadowTaps5Samples towards a directional light in the froxel path. 0 disables self-shadowing. Set by quality presets.
Rendering.VDBVolumes.ShadowResolution128Size of each volumetric shadow map. Set by quality presets.
Rendering.VDBVolumes.AmbientOcclusion4How strongly surrounding density occludes sky light. 0 disables it.
Rendering.VDBVolumes.AmbientStrength1Multiplier on sky light in the ray march.
Rendering.VDBVolumes.Powder0.4Darkens thin lit fringes so edges do not wash out.
Rendering.VDBVolumes.DebugView01 = 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​

SymptomCause and fix
A distant volume turns into a faint hazeIt is in Froxel mode, or AllowRayMarch is off. Use Auto or Ray March.
Banding or visible slices in the ray marchToo few steps for the volume's depth. Raise RayMarchSteps or lower EdgeStepScale.
Edges look noisy where the simulation was smoothLower 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 volumeRendering.VDBVolumes.SharedLighting is on. Turn it off.
An animated volume stutters on first playLeave Prewarm on, and wait for IsPrewarmed() before triggering the effect.

See Also​