bevy_pbr/
lib.rs

1#![expect(missing_docs, reason = "Not all docs are written yet, see #3492.")]
2#![cfg_attr(docsrs, feature(doc_auto_cfg))]
3#![forbid(unsafe_code)]
4#![doc(
5    html_logo_url = "https://bevyengine.org/assets/icon.png",
6    html_favicon_url = "https://bevyengine.org/assets/icon.png"
7)]
8
9extern crate alloc;
10
11#[cfg(feature = "meshlet")]
12mod meshlet;
13pub mod wireframe;
14
15/// Experimental features that are not yet finished. Please report any issues you encounter!
16///
17/// Expect bugs, missing features, compatibility issues, low performance, and/or future breaking changes.
18#[cfg(feature = "meshlet")]
19pub mod experimental {
20    /// Render high-poly 3d meshes using an efficient GPU-driven method.
21    /// See [`MeshletPlugin`](meshlet::MeshletPlugin) and [`MeshletMesh`](meshlet::MeshletMesh) for details.
22    pub mod meshlet {
23        pub use crate::meshlet::*;
24    }
25}
26
27mod atmosphere;
28mod cluster;
29mod components;
30pub mod decal;
31pub mod deferred;
32mod extended_material;
33mod fog;
34mod light;
35mod light_probe;
36mod lightmap;
37mod material;
38mod material_bind_groups;
39mod mesh_material;
40mod parallax;
41mod pbr_material;
42mod prepass;
43mod render;
44mod ssao;
45mod ssr;
46mod volumetric_fog;
47
48use bevy_color::{Color, LinearRgba};
49
50pub use atmosphere::*;
51pub use cluster::*;
52pub use components::*;
53pub use decal::clustered::ClusteredDecalPlugin;
54pub use extended_material::*;
55pub use fog::*;
56pub use light::*;
57pub use light_probe::*;
58pub use lightmap::*;
59pub use material::*;
60pub use material_bind_groups::*;
61pub use mesh_material::*;
62pub use parallax::*;
63pub use pbr_material::*;
64pub use prepass::*;
65pub use render::*;
66pub use ssao::*;
67pub use ssr::*;
68pub use volumetric_fog::{FogVolume, VolumetricFog, VolumetricFogPlugin, VolumetricLight};
69
70/// The PBR prelude.
71///
72/// This includes the most common types in this crate, re-exported for your convenience.
73pub mod prelude {
74    #[doc(hidden)]
75    pub use crate::{
76        fog::{DistanceFog, FogFalloff},
77        light::{light_consts, AmbientLight, DirectionalLight, PointLight, SpotLight},
78        light_probe::{environment_map::EnvironmentMapLight, LightProbe},
79        material::{Material, MaterialPlugin},
80        mesh_material::MeshMaterial3d,
81        parallax::ParallaxMappingMethod,
82        pbr_material::StandardMaterial,
83        ssao::ScreenSpaceAmbientOcclusionPlugin,
84    };
85}
86
87pub mod graph {
88    use bevy_render::render_graph::RenderLabel;
89
90    /// Render graph nodes specific to 3D PBR rendering.
91    #[derive(Debug, Hash, PartialEq, Eq, Clone, RenderLabel)]
92    pub enum NodePbr {
93        /// Label for the shadow pass node that draws meshes that were visible
94        /// from the light last frame.
95        EarlyShadowPass,
96        /// Label for the shadow pass node that draws meshes that became visible
97        /// from the light this frame.
98        LateShadowPass,
99        /// Label for the screen space ambient occlusion render node.
100        ScreenSpaceAmbientOcclusion,
101        DeferredLightingPass,
102        /// Label for the volumetric lighting pass.
103        VolumetricFog,
104        /// Label for the shader that transforms and culls meshes that were
105        /// visible last frame.
106        EarlyGpuPreprocess,
107        /// Label for the shader that transforms and culls meshes that became
108        /// visible this frame.
109        LateGpuPreprocess,
110        /// Label for the screen space reflections pass.
111        ScreenSpaceReflections,
112        /// Label for the node that builds indirect draw parameters for meshes
113        /// that were visible last frame.
114        EarlyPrepassBuildIndirectParameters,
115        /// Label for the node that builds indirect draw parameters for meshes
116        /// that became visible this frame.
117        LatePrepassBuildIndirectParameters,
118        /// Label for the node that builds indirect draw parameters for the main
119        /// rendering pass, containing all meshes that are visible this frame.
120        MainBuildIndirectParameters,
121        ClearIndirectParametersMetadata,
122    }
123}
124
125use crate::{deferred::DeferredPbrLightingPlugin, graph::NodePbr};
126use bevy_app::prelude::*;
127use bevy_asset::{load_internal_asset, weak_handle, AssetApp, Assets, Handle};
128use bevy_core_pipeline::core_3d::graph::{Core3d, Node3d};
129use bevy_ecs::prelude::*;
130use bevy_image::Image;
131use bevy_render::{
132    alpha::AlphaMode,
133    camera::{sort_cameras, CameraUpdateSystem, Projection},
134    extract_component::ExtractComponentPlugin,
135    extract_resource::ExtractResourcePlugin,
136    render_graph::RenderGraph,
137    render_resource::Shader,
138    sync_component::SyncComponentPlugin,
139    view::VisibilitySystems,
140    ExtractSchedule, Render, RenderApp, RenderDebugFlags, RenderSet,
141};
142
143use bevy_transform::TransformSystem;
144
145pub const PBR_TYPES_SHADER_HANDLE: Handle<Shader> =
146    weak_handle!("b0330585-2335-4268-9032-a6c4c2d932f6");
147pub const PBR_BINDINGS_SHADER_HANDLE: Handle<Shader> =
148    weak_handle!("13834c18-c7ec-4c4b-bbbd-432c3ba4cace");
149pub const UTILS_HANDLE: Handle<Shader> = weak_handle!("0a32978f-2744-4608-98b6-4c3000a0638d");
150pub const CLUSTERED_FORWARD_HANDLE: Handle<Shader> =
151    weak_handle!("f8e3b4c6-60b7-4b23-8b2e-a6b27bb4ddce");
152pub const PBR_LIGHTING_HANDLE: Handle<Shader> =
153    weak_handle!("de0cf697-2876-49a0-aa0f-f015216f70c2");
154pub const PBR_TRANSMISSION_HANDLE: Handle<Shader> =
155    weak_handle!("22482185-36bb-4c16-9b93-a20e6d4a2725");
156pub const SHADOWS_HANDLE: Handle<Shader> = weak_handle!("ff758c5a-3927-4a15-94c3-3fbdfc362590");
157pub const SHADOW_SAMPLING_HANDLE: Handle<Shader> =
158    weak_handle!("f6bf5843-54bc-4e39-bd9d-56bfcd77b033");
159pub const PBR_FRAGMENT_HANDLE: Handle<Shader> =
160    weak_handle!("1bd3c10d-851b-400c-934a-db489d99cc50");
161pub const PBR_SHADER_HANDLE: Handle<Shader> = weak_handle!("0eba65ed-3e5b-4752-93ed-e8097e7b0c84");
162pub const PBR_PREPASS_SHADER_HANDLE: Handle<Shader> =
163    weak_handle!("9afeaeab-7c45-43ce-b322-4b97799eaeb9");
164pub const PBR_FUNCTIONS_HANDLE: Handle<Shader> =
165    weak_handle!("815b8618-f557-4a96-91a5-a2fb7e249fb0");
166pub const PBR_AMBIENT_HANDLE: Handle<Shader> = weak_handle!("4a90b95b-112a-4a10-9145-7590d6f14260");
167pub const PARALLAX_MAPPING_SHADER_HANDLE: Handle<Shader> =
168    weak_handle!("6cf57d9f-222a-429a-bba4-55ba9586e1d4");
169pub const VIEW_TRANSFORMATIONS_SHADER_HANDLE: Handle<Shader> =
170    weak_handle!("ec047703-cde3-4876-94df-fed121544abb");
171pub const PBR_PREPASS_FUNCTIONS_SHADER_HANDLE: Handle<Shader> =
172    weak_handle!("77b1bd3a-877c-4b2c-981b-b9c68d1b774a");
173pub const PBR_DEFERRED_TYPES_HANDLE: Handle<Shader> =
174    weak_handle!("43060da7-a717-4240-80a8-dbddd92bd25d");
175pub const PBR_DEFERRED_FUNCTIONS_HANDLE: Handle<Shader> =
176    weak_handle!("9dc46746-c51d-45e3-a321-6a50c3963420");
177pub const RGB9E5_FUNCTIONS_HANDLE: Handle<Shader> =
178    weak_handle!("90c19aa3-6a11-4252-8586-d9299352e94f");
179const MESHLET_VISIBILITY_BUFFER_RESOLVE_SHADER_HANDLE: Handle<Shader> =
180    weak_handle!("69187376-3dea-4d0f-b3f5-185bde63d6a2");
181
182pub const TONEMAPPING_LUT_TEXTURE_BINDING_INDEX: u32 = 26;
183pub const TONEMAPPING_LUT_SAMPLER_BINDING_INDEX: u32 = 27;
184
185/// Sets up the entire PBR infrastructure of bevy.
186pub struct PbrPlugin {
187    /// Controls if the prepass is enabled for the [`StandardMaterial`].
188    /// For more information about what a prepass is, see the [`bevy_core_pipeline::prepass`] docs.
189    pub prepass_enabled: bool,
190    /// Controls if [`DeferredPbrLightingPlugin`] is added.
191    pub add_default_deferred_lighting_plugin: bool,
192    /// Controls if GPU [`MeshUniform`] building is enabled.
193    ///
194    /// This requires compute shader support and so will be forcibly disabled if
195    /// the platform doesn't support those.
196    pub use_gpu_instance_buffer_builder: bool,
197    /// Debugging flags that can optionally be set when constructing the renderer.
198    pub debug_flags: RenderDebugFlags,
199}
200
201impl Default for PbrPlugin {
202    fn default() -> Self {
203        Self {
204            prepass_enabled: true,
205            add_default_deferred_lighting_plugin: true,
206            use_gpu_instance_buffer_builder: true,
207            debug_flags: RenderDebugFlags::default(),
208        }
209    }
210}
211
212impl Plugin for PbrPlugin {
213    fn build(&self, app: &mut App) {
214        load_internal_asset!(
215            app,
216            PBR_TYPES_SHADER_HANDLE,
217            "render/pbr_types.wgsl",
218            Shader::from_wgsl
219        );
220        load_internal_asset!(
221            app,
222            PBR_BINDINGS_SHADER_HANDLE,
223            "render/pbr_bindings.wgsl",
224            Shader::from_wgsl
225        );
226        load_internal_asset!(app, UTILS_HANDLE, "render/utils.wgsl", Shader::from_wgsl);
227        load_internal_asset!(
228            app,
229            CLUSTERED_FORWARD_HANDLE,
230            "render/clustered_forward.wgsl",
231            Shader::from_wgsl
232        );
233        load_internal_asset!(
234            app,
235            PBR_LIGHTING_HANDLE,
236            "render/pbr_lighting.wgsl",
237            Shader::from_wgsl
238        );
239        load_internal_asset!(
240            app,
241            PBR_TRANSMISSION_HANDLE,
242            "render/pbr_transmission.wgsl",
243            Shader::from_wgsl
244        );
245        load_internal_asset!(
246            app,
247            SHADOWS_HANDLE,
248            "render/shadows.wgsl",
249            Shader::from_wgsl
250        );
251        load_internal_asset!(
252            app,
253            PBR_DEFERRED_TYPES_HANDLE,
254            "deferred/pbr_deferred_types.wgsl",
255            Shader::from_wgsl
256        );
257        load_internal_asset!(
258            app,
259            PBR_DEFERRED_FUNCTIONS_HANDLE,
260            "deferred/pbr_deferred_functions.wgsl",
261            Shader::from_wgsl
262        );
263        load_internal_asset!(
264            app,
265            SHADOW_SAMPLING_HANDLE,
266            "render/shadow_sampling.wgsl",
267            Shader::from_wgsl
268        );
269        load_internal_asset!(
270            app,
271            PBR_FUNCTIONS_HANDLE,
272            "render/pbr_functions.wgsl",
273            Shader::from_wgsl
274        );
275        load_internal_asset!(
276            app,
277            RGB9E5_FUNCTIONS_HANDLE,
278            "render/rgb9e5.wgsl",
279            Shader::from_wgsl
280        );
281        load_internal_asset!(
282            app,
283            PBR_AMBIENT_HANDLE,
284            "render/pbr_ambient.wgsl",
285            Shader::from_wgsl
286        );
287        load_internal_asset!(
288            app,
289            PBR_FRAGMENT_HANDLE,
290            "render/pbr_fragment.wgsl",
291            Shader::from_wgsl
292        );
293        load_internal_asset!(app, PBR_SHADER_HANDLE, "render/pbr.wgsl", Shader::from_wgsl);
294        load_internal_asset!(
295            app,
296            PBR_PREPASS_FUNCTIONS_SHADER_HANDLE,
297            "render/pbr_prepass_functions.wgsl",
298            Shader::from_wgsl
299        );
300        load_internal_asset!(
301            app,
302            PBR_PREPASS_SHADER_HANDLE,
303            "render/pbr_prepass.wgsl",
304            Shader::from_wgsl
305        );
306        load_internal_asset!(
307            app,
308            PARALLAX_MAPPING_SHADER_HANDLE,
309            "render/parallax_mapping.wgsl",
310            Shader::from_wgsl
311        );
312        load_internal_asset!(
313            app,
314            VIEW_TRANSFORMATIONS_SHADER_HANDLE,
315            "render/view_transformations.wgsl",
316            Shader::from_wgsl
317        );
318        // Setup dummy shaders for when MeshletPlugin is not used to prevent shader import errors.
319        load_internal_asset!(
320            app,
321            MESHLET_VISIBILITY_BUFFER_RESOLVE_SHADER_HANDLE,
322            "meshlet/dummy_visibility_buffer_resolve.wgsl",
323            Shader::from_wgsl
324        );
325
326        app.register_asset_reflect::<StandardMaterial>()
327            .register_type::<AmbientLight>()
328            .register_type::<CascadeShadowConfig>()
329            .register_type::<Cascades>()
330            .register_type::<CascadesVisibleEntities>()
331            .register_type::<VisibleMeshEntities>()
332            .register_type::<ClusterConfig>()
333            .register_type::<CubemapVisibleEntities>()
334            .register_type::<DirectionalLight>()
335            .register_type::<DirectionalLightShadowMap>()
336            .register_type::<NotShadowCaster>()
337            .register_type::<NotShadowReceiver>()
338            .register_type::<PointLight>()
339            .register_type::<PointLightShadowMap>()
340            .register_type::<SpotLight>()
341            .register_type::<ShadowFilteringMethod>()
342            .init_resource::<AmbientLight>()
343            .init_resource::<GlobalVisibleClusterableObjects>()
344            .init_resource::<DirectionalLightShadowMap>()
345            .init_resource::<PointLightShadowMap>()
346            .register_type::<DefaultOpaqueRendererMethod>()
347            .init_resource::<DefaultOpaqueRendererMethod>()
348            .add_plugins((
349                MeshRenderPlugin {
350                    use_gpu_instance_buffer_builder: self.use_gpu_instance_buffer_builder,
351                    debug_flags: self.debug_flags,
352                },
353                MaterialPlugin::<StandardMaterial> {
354                    prepass_enabled: self.prepass_enabled,
355                    debug_flags: self.debug_flags,
356                    ..Default::default()
357                },
358                ScreenSpaceAmbientOcclusionPlugin,
359                ExtractResourcePlugin::<AmbientLight>::default(),
360                FogPlugin,
361                ExtractResourcePlugin::<DefaultOpaqueRendererMethod>::default(),
362                ExtractComponentPlugin::<ShadowFilteringMethod>::default(),
363                LightmapPlugin,
364                LightProbePlugin,
365                PbrProjectionPlugin,
366                GpuMeshPreprocessPlugin {
367                    use_gpu_instance_buffer_builder: self.use_gpu_instance_buffer_builder,
368                },
369                VolumetricFogPlugin,
370                ScreenSpaceReflectionsPlugin,
371                ClusteredDecalPlugin,
372            ))
373            .add_plugins((
374                decal::ForwardDecalPlugin,
375                SyncComponentPlugin::<DirectionalLight>::default(),
376                SyncComponentPlugin::<PointLight>::default(),
377                SyncComponentPlugin::<SpotLight>::default(),
378                ExtractComponentPlugin::<AmbientLight>::default(),
379            ))
380            .add_plugins(AtmospherePlugin)
381            .configure_sets(
382                PostUpdate,
383                (
384                    SimulationLightSystems::AddClusters,
385                    SimulationLightSystems::AssignLightsToClusters,
386                )
387                    .chain(),
388            )
389            .configure_sets(
390                PostUpdate,
391                SimulationLightSystems::UpdateDirectionalLightCascades
392                    .ambiguous_with(SimulationLightSystems::UpdateDirectionalLightCascades),
393            )
394            .configure_sets(
395                PostUpdate,
396                SimulationLightSystems::CheckLightVisibility
397                    .ambiguous_with(SimulationLightSystems::CheckLightVisibility),
398            )
399            .add_systems(
400                PostUpdate,
401                (
402                    add_clusters
403                        .in_set(SimulationLightSystems::AddClusters)
404                        .after(CameraUpdateSystem),
405                    assign_objects_to_clusters
406                        .in_set(SimulationLightSystems::AssignLightsToClusters)
407                        .after(TransformSystem::TransformPropagate)
408                        .after(VisibilitySystems::CheckVisibility)
409                        .after(CameraUpdateSystem),
410                    clear_directional_light_cascades
411                        .in_set(SimulationLightSystems::UpdateDirectionalLightCascades)
412                        .after(TransformSystem::TransformPropagate)
413                        .after(CameraUpdateSystem),
414                    update_directional_light_frusta
415                        .in_set(SimulationLightSystems::UpdateLightFrusta)
416                        // This must run after CheckVisibility because it relies on `ViewVisibility`
417                        .after(VisibilitySystems::CheckVisibility)
418                        .after(TransformSystem::TransformPropagate)
419                        .after(SimulationLightSystems::UpdateDirectionalLightCascades)
420                        // We assume that no entity will be both a directional light and a spot light,
421                        // so these systems will run independently of one another.
422                        // FIXME: Add an archetype invariant for this https://github.com/bevyengine/bevy/issues/1481.
423                        .ambiguous_with(update_spot_light_frusta),
424                    update_point_light_frusta
425                        .in_set(SimulationLightSystems::UpdateLightFrusta)
426                        .after(TransformSystem::TransformPropagate)
427                        .after(SimulationLightSystems::AssignLightsToClusters),
428                    update_spot_light_frusta
429                        .in_set(SimulationLightSystems::UpdateLightFrusta)
430                        .after(TransformSystem::TransformPropagate)
431                        .after(SimulationLightSystems::AssignLightsToClusters),
432                    (
433                        check_dir_light_mesh_visibility,
434                        check_point_light_mesh_visibility,
435                    )
436                        .in_set(SimulationLightSystems::CheckLightVisibility)
437                        .after(VisibilitySystems::CalculateBounds)
438                        .after(TransformSystem::TransformPropagate)
439                        .after(SimulationLightSystems::UpdateLightFrusta)
440                        // NOTE: This MUST be scheduled AFTER the core renderer visibility check
441                        // because that resets entity `ViewVisibility` for the first view
442                        // which would override any results from this otherwise
443                        .after(VisibilitySystems::CheckVisibility)
444                        .before(VisibilitySystems::MarkNewlyHiddenEntitiesInvisible),
445                ),
446            );
447
448        if self.add_default_deferred_lighting_plugin {
449            app.add_plugins(DeferredPbrLightingPlugin);
450        }
451
452        // Initialize the default material handle.
453        app.world_mut()
454            .resource_mut::<Assets<StandardMaterial>>()
455            .insert(
456                &Handle::<StandardMaterial>::default(),
457                StandardMaterial {
458                    base_color: Color::srgb(1.0, 0.0, 0.5),
459                    ..Default::default()
460                },
461            );
462
463        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
464            return;
465        };
466
467        // Extract the required data from the main world
468        render_app
469            .add_systems(
470                ExtractSchedule,
471                (
472                    extract_clusters,
473                    extract_lights,
474                    late_sweep_material_instances,
475                ),
476            )
477            .add_systems(
478                Render,
479                (
480                    prepare_lights
481                        .in_set(RenderSet::ManageViews)
482                        .after(sort_cameras),
483                    prepare_clusters.in_set(RenderSet::PrepareResources),
484                ),
485            )
486            .init_resource::<LightMeta>()
487            .init_resource::<RenderMaterialBindings>();
488
489        render_app.world_mut().add_observer(add_light_view_entities);
490        render_app
491            .world_mut()
492            .add_observer(remove_light_view_entities);
493        render_app.world_mut().add_observer(extracted_light_removed);
494
495        let early_shadow_pass_node = EarlyShadowPassNode::from_world(render_app.world_mut());
496        let late_shadow_pass_node = LateShadowPassNode::from_world(render_app.world_mut());
497        let mut graph = render_app.world_mut().resource_mut::<RenderGraph>();
498        let draw_3d_graph = graph.get_sub_graph_mut(Core3d).unwrap();
499        draw_3d_graph.add_node(NodePbr::EarlyShadowPass, early_shadow_pass_node);
500        draw_3d_graph.add_node(NodePbr::LateShadowPass, late_shadow_pass_node);
501        draw_3d_graph.add_node_edges((
502            NodePbr::EarlyShadowPass,
503            NodePbr::LateShadowPass,
504            Node3d::StartMainPass,
505        ));
506    }
507
508    fn finish(&self, app: &mut App) {
509        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
510            return;
511        };
512
513        // Extract the required data from the main world
514        render_app
515            .init_resource::<ShadowSamplers>()
516            .init_resource::<GlobalClusterableObjectMeta>()
517            .init_resource::<FallbackBindlessResources>();
518    }
519}
520
521/// Camera projection PBR functionality.
522#[derive(Default)]
523pub struct PbrProjectionPlugin;
524impl Plugin for PbrProjectionPlugin {
525    fn build(&self, app: &mut App) {
526        app.add_systems(
527            PostUpdate,
528            build_directional_light_cascades
529                .in_set(SimulationLightSystems::UpdateDirectionalLightCascades)
530                .after(clear_directional_light_cascades),
531        );
532    }
533}
bevy_pbr/lib.rs

bevy_pbr/
lib.rs
