Heterogeneous Volumes

The Heterogeneous Volume actor is used to render volume-domain materials that sample Sparse Volume Textures. This actor supports rendering volumes in real-time and with the Path Tracer. Heterogeneous Volume actors can render static or animated sparse volume texture materials.

Left, static single-volume SVT; Right, an animated SVT.

Working with Heterogeneous Volume Actors

Use the following workflow to get using Heterogeneous Volumes in your project:

• Import a VDB to create a Sparse Volume Texture asset in Unreal Engine.
• Set up a Volume-domain material that samples an SVT asset.
• Add a Heterogeneous Volume Actor to the scene and assign an SVT material to it.

Importing VDB Files

To get started, you must have a VDB (or Voxel Data Base) file to import into the Content Browser.

To import a VDB file, follow these steps:

• Drag and drop the VDB directly into the Content Browser.
• Use the Import button in the Content Browser.

VDBs have their own import window for importing static and animated VDB files.

You have the option of importing a static or animated VDB file. Static VDBs only include the single file and its stored volume data whereas Animated VDBs are a set of individual files sequentially numbered. Animated VDBs only need to import any one of the sequentially numbered VDB files to import the animated VDB in its entirety.

VDBs can include different attributes stored with their data. These can be split between Attributes A and Attribute B. The general recommendation is to split the incoming data across two sampling attributes where the first attribute data is imported as 8-bit unorm and the second attribute data is 16-bit float.

For projects at Epic Games, we prefer to push density as an 8-bit unorm and pass all other data through the 16-bit float attribute list during import.

Imported transforms are applied automatically with a heterogeneous volume. If the transforms were authored with the pivot being at the origin, which is usually one of the corners of the volume, you can check the box for Pivot at Centroid to move the pivot to the center of the volume. However, be aware that forcing the pivot to the volume’s center may end up breaking transforms.

For more information specific to importing and using sparse volume textures, see Sparse Volume Textures.

Setting up a SVT Material

For detailed information about setting up a material with an SVT and using it within a material, see Sparse Volume Textures.

Heterogeneous Volumes require a volume-based material that samples an sparse volume texture. These materials use the Sparse Volume Texture Sample node to sample an SVT, which you can use in conjunction with Heterogeneous Volumes, Volumetric Fog, and Volumetric Clouds, or any volume-based material.

Unreal Engine includes an empty sample SVT material already set up that you can apply your SVT asset to. You can find it in the Content Browser under Engine > Engine Materials named SparseVolumeMaterial. Make a copy of this material and create an instance of it.

Once you open the material instance, override the SparseVolumeTexture parameter and apply your own imported SVT asset to the assignment slot.

Setting Up a Heterogeneous Volume

To set up a heterogeneous volume, follow these steps:

1. Using the Place Actors panel, search for and add a Heterogeneous Volume actor to the scene.
2. With the actor selected, use the Details panel to assign an SVT material to the actor.
3. [Optional] If you imported an animated VDB, you'll want to check the boxes for Playing and Looping under the Animation section.

Heterogeneous Volume Actor Properties

Heterogeneous Volume actors have the following properties:

Animation

The Animation properties provide custom rules for playback. By default, the Start Frame and End Frame properties are bound to the available range of the imported SVT but can be trimmed to play only part of the SVT's animation. Playback is expected to occur at a "cinematic" rate of 24 frames-per-second but can be adjusted as needed.

The SVT interactively plays in the scene when the Playing checkbox is set, and continuously repeats when the Looping checkbox is set. When the Playing checkbox is left unchecked, you can left-mouse click the Frame text field and drag left or right to scrub through playback of the SVT's available frames.

Lighting

The deferred rendering model uses ray marching when rendering high-quality volumetric assets with the Heterogeneous Volume actor. Each adjustable Factor property is relative to the Volume Resolution property. The resolution of the imported SVT has a direct correlation to runtime performance.

Blueprints

In Blueprints, you can use the Play and Set Playing nodes to trigger animation data start and stop.

Using Heterogeneous Volumes with Path Tracer

You can create heterogeneous volumes with the Niagara Fluids plugin or instancing a Heterogeneous Volume actor in your scenes. These volumes begin rendering when the path tracer is enabled.

Example of a Niagara Fluid heterogeneous volume rendered with the path tracer.

To render heterogeneous volumes with the path tracer, enable the following:

• Project Settings
  • Set the Default RHI to DirectX 12.
  • Enable Support Hardware Ray Tracing.
  • Enable Path Tracing
• Plugins
  • [Optional] Niagara Fluids

For a complete list of specifications, see Path Tracer.

Heterogeneous Volumes with Niagara Fluids

The Niagara Fluids plugin must be enabled to use this feature. For more information, see Niagara Fluids.

To render with Niagara Fluids, follow these steps:

1. Create a new Niagara Fluid in the Content Browser.
2. In the Niagara picker window, select New system from a template or behavior example and click Next.
3. Choose one of the examples from the 3D Gas list in the window.
4. Double-click the Niagara Fluid asset to open the Niagara Editor.
5. Select the Niagara Fluid system node in the graph.
6. In the Details panel, set the following:
   • Loop Behavior to Infinite.
   • Loop Duration should be shorter than 5 seconds.
7. Compile and save the Niagara Fluid asset.
8. Place the Niagara Fluid in your scene.
9. Open the console window and input r.PathTracing.HeterogeneousVolumes 1 to enable path tracer support for heterogeneous volume rendering.

Heterogeneous Volumes with Sparse Volume Textures

To render with Sparse Volume Textures, follow these steps:

1. Import a VDB file and set up a sparse volume texture material to display it.
2. In the Level editor, use the Place Actors panel to add a Heterogeneous Volumes actor to the scene.
3. Assign the sparse volume texture material to its material slot.
4. Open the console window and input r.PathTracing.HeterogeneousVolumes 1 to enable path tracer support for heterogeneous volume rendering.

Useful Console Variables

Heterogeneous Volumes Project Settings

Heterogeneous Volume actors have the following project settings. These are found under the Engine > Rendering section in the Heterogeneous Volumes category.

Limitations and Known Issues

Real-time:

• Rendering in Real-Time vs Path Tracer
  • More complete support for rendering volumes is now available in the Path Tracer, which can accurately simulate global illumination.
• Cast Shadows on the environment
  • This feature is experimental.
  • You can enable heterogeneous volume shadow casting in the project settings.

Path Tracer:

This feature is experimental.

• Blocky or blurry heterogeneous volumes
  • The default shading rate for heterogeneous volume rendering is 4, to support interactive path tracing. Lowering the shading rate to 1 removes perceptible artifacts, but requires increased memory to correctly render. The recommended cinematic default shading rate is 1, and the recommended default memory limit is 512. We recommend setting these in the Movie Render Queue settings when rendering.
• Missing voxels in renders
  • Lowering the shading rate of the world-space and frustum-aligned voxel grids may attempt to allocate more bottom-level voxels than allowed by the imposed memory limit. In these instances, voxels will not be allocated and portions of the volume will be missing. At this time, you must use more bottom-level memory or raise the shading rate.
• Overlapping heterogeneous volumes appear blocky
  • Bottom-level voxel data in the world-space voxel grid is aggregated if the region is determined to be homogeneous. Homogeneous detection is performed within the confines of a single volume and may be improperly aggregated in the presence of overlapping volumes within the same region. You can prevent aggregation by setting r.HeterogeneousVolumes.Tessellation.BottomLevelGrid.HomogeneousAggregation to 0 to disable it.
• Screen door effect with Niagara Fluid
  • Niagara systems only trigger path tracing invalidation events when the Niagara Editor is open. Having the editor open allows the animation to be viewed correctly in the path tracer. When the editor is closed, the path tracer continues to accumulate samples throughout the animation.
• Screen door effect with Heterogeneous Volume actor
  • The Heterogeneous Volume actor does not currently trigger path tracing invalidation events. Uncheck the Animate property on the actor to suspend the animation.

Additional Resources

• Niagara Fluids Plugin
  • The Niagara Fluids plugin includes examples that can be used with heterogeneous volume rendering. Enable the plugin in your project and create a new Niagara system from the provided templates. For more information, see Niagara Fluids
• The VDB files used in the examples in this page are from JangaFX's free VDB set created with EmberGen.
  • Download their free examples here.