bevy_pbr/volumetric_fog/
mod.rs

1//! Volumetric fog and volumetric lighting, also known as light shafts or god
2//! rays.
3//!
4//! This module implements a more physically-accurate, but slower, form of fog
5//! than the [`crate::fog`] module does. Notably, this *volumetric fog* allows
6//! for light beams from directional lights to shine through, creating what is
7//! known as *light shafts* or *god rays*.
8//!
9//! To add volumetric fog to a scene, add [`bevy_light::VolumetricFog`] to the
10//! camera, and add [`bevy_light::VolumetricLight`] to directional lights that you wish to
11//! be volumetric. [`bevy_light::VolumetricFog`] feature numerous settings that
12//! allow you to define the accuracy of the simulation, as well as the look of
13//! the fog. Currently, only interaction with directional lights that have
14//! shadow maps is supported. Note that the overhead of the effect scales
15//! directly with the number of directional lights in use, so apply
16//! [`bevy_light::VolumetricLight`] sparingly for the best results.
17//!
18//! The overall algorithm, which is implemented as a postprocessing effect, is a
19//! combination of the techniques described in [Scratchapixel] and [this blog
20//! post]. It uses raymarching in screen space, transformed into shadow map
21//! space for sampling and combined with physically-based modeling of absorption
22//! and scattering. Bevy employs the widely-used [Henyey-Greenstein phase
23//! function] to model asymmetry; this essentially allows light shafts to fade
24//! into and out of existence as the user views them.
25//!
26//! [Scratchapixel]: https://www.scratchapixel.com/lessons/3d-basic-rendering/volume-rendering-for-developers/intro-volume-rendering.html
27//!
28//! [this blog post]: https://www.alexandre-pestana.com/volumetric-lights/
29//!
30//! [Henyey-Greenstein phase function]: https://www.pbr-book.org/4ed/Volume_Scattering/Phase_Functions#TheHenyeyndashGreensteinPhaseFunction
31
32use bevy_app::{App, Plugin};
33use bevy_asset::{embedded_asset, Assets, Handle};
34use bevy_core_pipeline::core_3d::{
35    graph::{Core3d, Node3d},
36    prepare_core_3d_depth_textures,
37};
38use bevy_ecs::{resource::Resource, schedule::IntoScheduleConfigs as _};
39use bevy_light::FogVolume;
40use bevy_math::{
41    primitives::{Cuboid, Plane3d},
42    Vec2, Vec3,
43};
44use bevy_mesh::{Mesh, Meshable};
45use bevy_render::{
46    render_graph::{RenderGraphExt, ViewNodeRunner},
47    render_resource::SpecializedRenderPipelines,
48    sync_component::SyncComponentPlugin,
49    ExtractSchedule, Render, RenderApp, RenderStartup, RenderSystems,
50};
51use render::{VolumetricFogNode, VolumetricFogPipeline, VolumetricFogUniformBuffer};
52
53use crate::{graph::NodePbr, volumetric_fog::render::init_volumetric_fog_pipeline};
54
55pub mod render;
56
57/// A plugin that implements volumetric fog.
58pub struct VolumetricFogPlugin;
59
60#[derive(Resource)]
61pub struct FogAssets {
62    plane_mesh: Handle<Mesh>,
63    cube_mesh: Handle<Mesh>,
64}
65
66impl Plugin for VolumetricFogPlugin {
67    fn build(&self, app: &mut App) {
68        embedded_asset!(app, "volumetric_fog.wgsl");
69
70        let mut meshes = app.world_mut().resource_mut::<Assets<Mesh>>();
71        let plane_mesh = meshes.add(Plane3d::new(Vec3::Z, Vec2::ONE).mesh());
72        let cube_mesh = meshes.add(Cuboid::new(1.0, 1.0, 1.0).mesh());
73
74        app.add_plugins(SyncComponentPlugin::<FogVolume>::default());
75
76        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
77            return;
78        };
79
80        render_app
81            .insert_resource(FogAssets {
82                plane_mesh,
83                cube_mesh,
84            })
85            .init_resource::<SpecializedRenderPipelines<VolumetricFogPipeline>>()
86            .init_resource::<VolumetricFogUniformBuffer>()
87            .add_systems(RenderStartup, init_volumetric_fog_pipeline)
88            .add_systems(ExtractSchedule, render::extract_volumetric_fog)
89            .add_systems(
90                Render,
91                (
92                    render::prepare_volumetric_fog_pipelines.in_set(RenderSystems::Prepare),
93                    render::prepare_volumetric_fog_uniforms.in_set(RenderSystems::Prepare),
94                    render::prepare_view_depth_textures_for_volumetric_fog
95                        .in_set(RenderSystems::Prepare)
96                        .before(prepare_core_3d_depth_textures),
97                ),
98            )
99            .add_render_graph_node::<ViewNodeRunner<VolumetricFogNode>>(
100                Core3d,
101                NodePbr::VolumetricFog,
102            )
103            .add_render_graph_edges(
104                Core3d,
105                // Volumetric fog should run after the main pass but before bloom, so
106                // we order if at the start of post processing.
107                (
108                    Node3d::EndMainPass,
109                    NodePbr::VolumetricFog,
110                    Node3d::StartMainPassPostProcessing,
111                ),
112            );
113    }
114}
bevy_pbr/volumetric_fog/mod.rs

bevy_pbr/volumetric_fog/
mod.rs
