# Phyisically based unified volumetrics system

## Overview

> Tracking issue: https://github.com/bevyengine/bevy/issues/18151

This is a design document for a unified volumetrics system that combines the functionality of `FogVolume`, `Atmosphere`, and other volumetric effects into a cohesive, physically-based system. The system focuses on providing robust defaults for common volumetric effects while maintaining a clean, extensible architecture for more specialized implementations.

## Current State
Bevy implements volumetric effects through three systems:
1. `Atmosphere` - Physical scattering using Rayleigh/Mie phase functions, precomputed LUTs for transmittance (2D), multiscattering (2D), and inscattering (3D), with full planetary curvature support
2. `FogVolume` - Localized volumes using bounded meshes, arbitrary 3D density fields, and Henyey-Greenstein phase function for anisotropic scattering
3. `DistanceFog` - Screen-space post-process effect (out of scope for this system)

The current `Atmosphere` implementation uses Rayleigh and Mie phase functions for physical scattering. The system pre-computes three distinct lookup textures (LUTs):
- a 2D transmittance LUT for accelerating the inner integral term
- a 2D multiscattering LUT storing isotropic phase function results under local uniformity assumptions
- an optional 3D frustum-fitted LUT for inscattering values

It accounts for planetary curvature, height-based density variation, and integrates with the PBR pipeline for accurate light transport and sunlight attenuation. The 3D inscattering LUT approach limits shadow resolution to the view-plane texture resolution.

`FogVolume` components define localized volumetric media through bounded meshes with world-space transforms. Unlike the height-based density profile of the atmosphere system, fog volumes support arbitrary 3D density distributions through uniform parameters or 3D textures. The implementation handles volumetric shadows from both directional and point light sources, using the Henyey-Greenstein phase function to model anisotropic light scattering through the medium.

The `DistanceFog` component is a basic screen-space effect for distance-based fog. It has an `Atmospheric` mode that mimics the behavior of the atmosphere, but only uses simple exponential math for light extinction and inscattering with a single bounce. The `Atmosphere` and `FogVolume` components are different - they work directly with the PBR lighting pipeline and use proper physics. Since `DistanceFog` is just a post-process effect that doesn't use real physics, it won't be part of the unified volumetrics system.

## Core Features

The following section describes the proposed architecture for the unified volumetrics system. It provides essential building blocks for volumetric rendering:

1. Core volumetric rendering pipeline integration
2. PBR-based light transport interfaces
3. Density field manipulation primitives
4. Common presets for basic effects

The system ships with robust defaults for:
- Global atmospheric scattering
- Local volumetric media
- Basic density field operations

Users can extend the system through compute shaders and the density field API for specialized effects. The clean separation between core rendering and simulation logic ensures consistent visual quality while maintaining flexibility. For example, smoke effects can be implemented using the basic density primitives, while more complex phenomena can leverage the compute shader interface for custom evolution rules.

## Proposed Changes

Component names and terminology are the following, specifically focusing on terms like:
- "Volumetric": spatial computation rather than opaque objects
- "Medium": the material properties of the volumetric effect

This is also a proposal to avoid the term "Fog" because that term refers to a particular scattering medium, rather than a generic component that can be used to describe any volumetric effect.

Module path in Bevy PBR crate:

bevy_pbr/src/volume/mod.rs

This proposal combines the `AtmospherePlugin` and `VolumetricFogPlugin` under a single `VolumetricPlugin`, as well as keep some existing components in order to control the volumetric effects. We also combine the `Atmosphere` and `FogVolume` under common interfaces, structs in `bevy_pbr/src/volume/mod.rs`:

- struct VolumetricFogPlugin
- struct VolumetricFog
- struct Atmosphere
- struct AtmosphereSettings

struct VolumetricLight

+ struct VolumetricPlugin
+ struct VolumetricMedium
+ struct VolumetricSettings

- `VolumetricMedium`: Core component for all volumetric effects
- `VolumetricSettings`: Shared rendering configuration

Key design principles:
- Physical accuracy: proper light transport and multiple scattering
- Extensibility: compute shader support for custom implementations
- Performance: unified render pass for multiple media
- Presets: `VolumetricMedium::EarthAtmosphere`, `VolumetricMedium::Clouds`

# Technical Design

## Media Interaction and Light Transport
The system handles multiple media through unified ray integration:

struct MediaProperties {
    density: f32,
    scattering: vec3<f32>,
    absorption: vec3<f32>,
}

fn sample_media(ray_pos: vec3<f32>) -> MediaProperties {
    var result = MediaProperties(
        0.0,           // density
        vec3(0.0),     // scattering
        vec3(0.0)      // absorption
    );
    
    for (var i = 0u; i < num_active_media; i++) {
        let medium = media_buffer[i];
        if (intersects_medium(ray_pos, medium.bounds)) {
            result = combine_media(result, sample_medium(ray_pos, medium));
        }
    }
    return result;
}

This eliminates transition artifacts while maintaining physical accuracy through proper extinction and in-scattering combination.

## Performance Optimization Strategy
Performance optimization uses a hybrid approach:
- Near-field (0-50m): Direct ray-marching, 64-128 steps
- Mid-field (50-500m): Frustum-fitted LUT (128³), 32-step ray-march
- Far-field (500m+): Pre-computed atmospheric LUT (32² × 8)

Acceleration structures:
- Deep opacity maps: 256² resolution per light
- Hierarchical min/max maps: 4 mip levels for 3D textures
- Temporal re-projection: 8-frame history
- Adaptive step size: 2x-8x reduction in sample count

Culling optimizations:
- Frustum culling using volume bounds and density thresholds
- Hardware occlusion queries for large opaque volumes
- Early-Z culling for volumes behind opaque geometry
- Distance-based culling for small volumes beyond mid-field range

## Compute Integration and Physical Accuracy

Density field evolution occurs through compute shaders in a dedicated pass, maintaining separation between simulation and rendering concerns. The system requires min/max MIP chains for density textures to support LOD selection and space skipping optimizations. Synchronization barriers ensure stable density sampling across varying update frequencies, while the volumetric medium component handles light transport computation. This architecture allows specialized implementations to balance physical accuracy with artistic control.

## Level of Detail and Scene Scale

The froxel-based sampling system adapts to different scene scales through a combination of frustum-fitted LUTs and dynamic LOD transitions. Memory constraints inform LUT configuration choices, with resolution and format selection based on visual importance and distance from viewer. The system preserves detail in near-field volumes while efficiently handling large-scale atmospheric effects through appropriate LOD selection. Using cascading LUTs at different scales could benefit this approach.

## Simulation Parameters

The core API focuses on the essential parameters for light transport: density distributions, scattering coefficients, and phase functions. We leave secondary physical properties like temperature gradients to user implementations via compute shaders, since they primarily affect phenomena evolution rather than the rendering process. This keeps the API focused on fundamental volumetric rendering but provides clear paths for extending the system with specialized simulations.

## PBR Integration

#define_import_path bevy_pbr::volume

// Core light transport computations
fn compute_transmittance;
fn compute_inscattering;
fn compute_multiple_scattering;
fn compute_phase_function;

// Pre-computed sampling functions
fn sample_transmittance;
fn sample_inscattering;
fn sample_multiple_scattering;

// Medium properties sampling
fn sample_local_medium;
fn sample_density_gradient;
fn sample_density_texture;

// Screen-space raymarch with built-in jitter/TAA support
fn ray_march_volume;

**Technical Requirements**

**Core Light Transport**
- Scattering and absorption coefficients (extinction = scattering + absorption)
- Phase functions: Rayleigh, Mie (Cornette-Shanks), Dual lobe Mie
- Multiple scattering computation and LUT pre-computation
- Self-shadowing via raymarch sampling

**Rendering Pipeline**
- Volumetric shadow map pass
- Volumetric lighting pass
- Integration with deferred/forward rendering
- HDR and tone mapping support
- Shadow map integration for directional/point lights

**Performance Optimizations**
- 3D density texture storage and sampling
- Pre-computed transmittance and in-scattering LUTs
- Froxel-based volume sampling
- Temporal re-projection (TAA)
- Adaptive ray-marching with jittered sampling
- Level of detail (LOD) for distant volumes

# Appendix

## Mathematical Theory

| Symbol | Description |
| :--- | :--- |
| $\mathbf{x}$ | Position |
| $t$ | Ray parameter |
| $\omega$ | Ray direction |
| $\mathbf{x}_{t}$ | Parameterized position along a ray: $\mathbf{x}_{t}=\mathbf{x}+t \omega$ |
| $\sigma_{a}(\mathbf{x})$ | Absorption coefficient |
| $\sigma_{s}(\mathbf{x})$ | Scattering coefficient |
| $\sigma_{t}(\mathbf{x})$ | Extinction coefficient: $=\sigma_{a}(\mathbf{x})+\sigma_{s}(\mathbf{x})$ |
| $\alpha(\mathbf{x})$ | Single scattering albedo: $=\sigma_{s}(\mathbf{x}) / \sigma_{t}(\mathbf{x})$ |
| $f_{p}\left(\mathbf{x}, \omega, \omega^{\prime}\right)$ | Phase function |
| $d$ | Ray length/domain of volume integration: $0<t<d$ |
| $\xi, \zeta$ | Random numbers |
| $L(\mathbf{x}, \omega)$ | Radiance at $\mathbf{x}$ in direction $\omega$ |
| $L_{d}\left(\mathbf{x}_{d}, \omega\right)$ | Incident boundary radiance at end of ray |
| $L_{e}(\mathbf{x}, \omega)$ | Emitted radiance |
| $L_{s}(\mathbf{x}, \omega)$ | In-scattered radiance at $\mathbf{x}$ from direction $\omega$ |

Transmittance

$$
T(t)=\exp \left(-\int_{s=0}^{t} \sigma_{t}\left(\mathbf{x}_{s}\right) d s\right)
$$

Volume Rendering Equation (VRE)

$$
L(\mathbf{x}, \omega) = \int_{t=0}^{d} T(t) \left[
\begin{matrix}
\sigma_{a}\left(\mathbf{x}_{t}\right) L_{e}\left(\mathbf{x}_{t}, \omega\right) + \\
\sigma_{s}\left(\mathbf{x}_{t}\right) L_{s}\left(\mathbf{x}_{t}, \omega\right) + \\
L_{d}\left(\mathbf{x}_{d}, \omega\right)
\end{matrix}
\right] dt
$$

## Research Material
Relevant research material, primarily focus on real-time rendering applications:
- Sebastian Hillaire's [publications](https://sebh.github.io/publications/)
- Andrew Schneider's [publications](https://www.schneidervfx.com/)
- 2020 EGSR paper by Sebatian Hillaire [A Scalable and Production Ready Sky and Atmosphere Rendering Technique](https://sebh.github.io/publications/egsr2020.pdf)
- SIGGRAPH 2020 talk by Sebastian Hillarie [Physically Based and Scalable Atmospheres in Unreal Engine](https://www.youtube.com/watch?v=SW30QX1wxTY)
- 2018 Eurographics Talk by Andrew Schneider [Nubis Realtime Volumetric Cloudscapes In A Nutshell](https://www.youtube.com/watch?v=-d8qT5-1LOI)
- [FMX2017 Technical Directing Special: Real-time Volumetric Cloud Rendering](https://www.youtube.com/watch?v=8OrvIQUFptA)
- SIGGRAPH 2015 talk on [Physically Based and Unified Volumetric Rendering in Frostbite](https://www.youtube.com/watch?v=ddfEnuXZijM)
- [The Real-Time Volumetric Cloudscapes of Horizon Zero Dawn](https://www.guerrilla-games.com/read/the-real-time-volumetric-cloudscapes-of-horizon-zero-dawn)
- Scratchapixel article on [Volume Rendering](https://www.scratchapixel.com/lessons/3d-basic-rendering/volume-rendering-for-developers/intro-volume-rendering.html)

Related but not directly relevant:
- 2017 Siggraph Course by authors from Pixar, Sony and Disney on [Production Volume Rendering](https://graphics.pixar.com/library/ProductionVolumeRendering/paper.pdf)