Per-Object Motion Blur

Cargo.toml

@@ -620,6 +620,17 @@ description = "Loads and renders a glTF file as a scene"
 category = "3D Rendering"
 wasm = true
 
+[[example]]
+name = "motion_blur"
+path = "examples/3d/motion_blur.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.motion_blur]
+name = "Motion Blur"
+description = "Demonstrates per-pixel motion blur"
+category = "3D Rendering"
+wasm = false
+
 [[example]]
 name = "tonemapping"
 path = "examples/3d/tonemapping.rs"

crates/bevy_core_pipeline/src/core_3d/mod.rs

@@ -14,6 +14,7 @@ pub mod graph {
         pub const MAIN_OPAQUE_PASS: &str = "main_opaque_pass";
         pub const MAIN_TRANSPARENT_PASS: &str = "main_transparent_pass";
         pub const END_MAIN_PASS: &str = "end_main_pass";
+        pub const MOTION_BLUR: &str = "motion_blur";
         pub const BLOOM: &str = "bloom";
         pub const TONEMAPPING: &str = "tonemapping";
         pub const FXAA: &str = "fxaa";

crates/bevy_core_pipeline/src/lib.rs

@@ -8,6 +8,7 @@ pub mod core_2d;
 pub mod core_3d;
 pub mod fullscreen_vertex_shader;
 pub mod fxaa;
+pub mod motion_blur;
 pub mod msaa_writeback;
 pub mod prepass;
 mod skybox;
@@ -42,6 +43,7 @@ use crate::{
     core_3d::Core3dPlugin,
     fullscreen_vertex_shader::FULLSCREEN_SHADER_HANDLE,
     fxaa::FxaaPlugin,
+    motion_blur::MotionBlurPlugin,
     msaa_writeback::MsaaWritebackPlugin,
     prepass::{DepthPrepass, NormalPrepass},
     tonemapping::TonemappingPlugin,
@@ -79,6 +81,7 @@ impl Plugin for CorePipelinePlugin {
                 BloomPlugin,
                 FxaaPlugin,
                 CASPlugin,
+                MotionBlurPlugin,
             ));
     }
 }

crates/bevy_core_pipeline/src/motion_blur/mod.rs

@@ -0,0 +1,129 @@
+//! Per-object motion blur.
+//!
+//! Add the [`MotionBlurBundle`] to a camera to enable motion blur.
+
+use crate::core_3d;
+use bevy_app::{App, Plugin};
+use bevy_asset::{load_internal_asset, Handle};
+use bevy_ecs::{bundle::Bundle, component::Component, schedule::IntoSystemConfigs};
+use bevy_render::{
+    extract_component::{ExtractComponent, ExtractComponentPlugin, UniformComponentPlugin},
+    render_graph::{RenderGraphApp, ViewNodeRunner},
+    render_resource::{Shader, ShaderType, SpecializedRenderPipelines},
+    renderer::RenderDevice,
+    Render, RenderApp, RenderSet,
+};
+
+pub mod node;
+pub mod pipeline;
+
+#[derive(Bundle, Default)]
+pub struct MotionBlurBundle {
+    pub motion_blur: MotionBlur,
+    pub depth_prepass: crate::prepass::DepthPrepass,
+    pub motion_vector_prepass: crate::prepass::MotionVectorPrepass,
+}
+
+/// A component that enables and configures motion blur when added to a camera.
+#[derive(Component, Clone, Copy, Debug, ExtractComponent, ShaderType)]
+pub struct MotionBlur {
+    /// Camera shutter angle from 0 to 1 (0-100%), which determines the strength of the blur.
+    ///
+    /// The shutter angle describes the fraction of a frame that a camera's shutter is open and
+    /// exposing the film/sensor. For 24fps cinematic film, a shutter angle of 0.5 (180 degrees) is
+    /// common. This means that the shutter was open for half of the frame, or 1/48th of a second.
+    /// The lower the shutter angle, the less exposure time and thus less blur. A value greater than
+    /// one is unrealistic and results in an object's blur stretching further than it traveled in
+    /// that frame.
+    pub shutter_angle: f32,
+    /// The upper limit for how many samples will be taken per-pixel. The number of samples taken
+    /// depends on the speed of an object.
+    pub max_samples: u32,
+    /// Motion blur will consider fragments closer to the camera than the fragment being blurred,
+    /// but only by this small amount.
+    ///
+    /// Without considering depth, fast moving objects moving behind a stationary object will sample
+    /// this stationary object, and cause it to incorrectly smear into the moving object. To solve
+    /// this, per-object motion blur can filter out samples by depth, ignoring fragments that are
+    /// closer to the camera than the fragment being blurred.
+    ///
+    /// However, it's desireable to add some tolerance to this comparison. Consider blurring the
+    /// edge of the sphere. When sampling fragments to create blur at the edge of the sphere,
+    /// sampling the center of the sphere will fail because the center of the sphere is closer to
+    /// the camera than the edge is! The `depth_bias` adds tolerance to allow for cases like this.
+    ///
+    /// You can effectively disable this by setting the bias to -1.0. This will result in streaking,
+    /// which may be artistically desired.
+    pub depth_bias: f32,
+    #[cfg(all(feature = "webgl", target_arch = "wasm32"))]
+    // WebGL2 structs must be 16 byte aligned.
+    pub _webgl2_padding: bevy_math::Vec3,
+}
+
+impl Default for MotionBlur {
+    fn default() -> Self {
+        Self {
+            shutter_angle: 1.0,
+            max_samples: 8,
+            depth_bias: -0.001,
+            #[cfg(all(feature = "webgl", target_arch = "wasm32"))]
+            _webgl2_padding: bevy_math::Vec3::default(),
+        }
+    }
+}
+
+pub const MOTION_BLUR_SHADER_HANDLE: Handle<Shader> =
+    Handle::weak_from_u128(987457899187986082347921);
+
+/// Adds support for per-object motion blur to the app.
+pub struct MotionBlurPlugin;
+impl Plugin for MotionBlurPlugin {
+    fn build(&self, app: &mut App) {
+        load_internal_asset!(
+            app,
+            MOTION_BLUR_SHADER_HANDLE,
+            "motion_blur.wgsl",
+            Shader::from_wgsl
+        );
+
+        app.add_plugins((
+            ExtractComponentPlugin::<MotionBlur>::default(),
+            UniformComponentPlugin::<MotionBlur>::default(),
+        ));
+
+        let Ok(render_app) = app.get_sub_app_mut(RenderApp) else {
+            return;
+        };
+
+        render_app
+            .init_resource::<SpecializedRenderPipelines<pipeline::MotionBlurPipeline>>()
+            .add_systems(
+                Render,
+                (pipeline::prepare_motion_blur_pipelines.in_set(RenderSet::Prepare),),
+            );
+
+        render_app
+            .add_render_graph_node::<ViewNodeRunner<node::MotionBlurNode>>(
+                core_3d::graph::NAME,
+                core_3d::graph::node::MOTION_BLUR,
+            )
+            .add_render_graph_edges(
+                core_3d::graph::NAME,
+                &[
+                    core_3d::graph::node::END_MAIN_PASS,
+                    core_3d::graph::node::MOTION_BLUR,
+                    core_3d::graph::node::BLOOM, // we want blurred areas to bloom and tonemap properly.
+                ],
+            );
+    }
+
+    fn finish(&self, app: &mut App) {
+        let Ok(render_app) = app.get_sub_app_mut(RenderApp) else {
+            return;
+        };
+
+        let render_device = render_app.world.resource::<RenderDevice>().clone();
+
+        render_app.insert_resource(pipeline::MotionBlurPipeline::new(&render_device));
+    }
+}

crates/bevy_core_pipeline/src/motion_blur/motion_blur.wgsl

@@ -0,0 +1,83 @@
+#import bevy_pbr::prepass_utils
+#import bevy_pbr::utils
+#import bevy_core_pipeline::fullscreen_vertex_shader FullscreenVertexOutput
+
+#ifdef MULTISAMPLED
+@group(0) @binding(0) var screen_texture: texture_2d<f32>;
+@group(0) @binding(1) var motion_vectors: texture_multisampled_2d<f32>;
+@group(0) @binding(2) var depth: texture_depth_multisampled_2d;
+#else
+@group(0) @binding(0) var screen_texture: texture_2d<f32>;
+@group(0) @binding(1) var motion_vectors: texture_2d<f32>;
+@group(0) @binding(2) var depth: texture_depth_2d;
+#endif
+@group(0) @binding(3) var texture_sampler: sampler;
+struct PostProcessSettings {
+    shutter_angle: f32,
+    max_samples: u32,
+    depth_bias: f32,
+#ifdef SIXTEEN_BYTE_ALIGNMENT
+    // WebGL2 structs must be 16 byte aligned.
+    _webgl2_padding: vec3<f32>
+#endif
+}
+@group(0) @binding(4) var<uniform> settings: PostProcessSettings;
+
+@fragment
+fn fragment(
+    #ifdef MULTISAMPLED
+        @builtin(sample_index) sample_index: u32,
+    #endif
+    in: FullscreenVertexOutput
+) -> @location(0) vec4<f32> {
+#ifndef MULTISAMPLED
+    let sample_index = 0u;
+#endif    
+    let shutter_angle = settings.shutter_angle;
+    let texture_size = vec2<f32>(textureDimensions(screen_texture));
+    let frag_coords = vec2<i32>(in.uv * texture_size);
+
+    let motion_vector = textureLoad(motion_vectors, frag_coords, i32(sample_index)).rg;
+    let exposure_vector = shutter_angle * motion_vector;
+    let speed = length(exposure_vector * texture_size);
+    let n_samples = i32(clamp(speed * 2.0, 1.0, f32(settings.max_samples)));
+
+    let this_depth = textureLoad(depth, frag_coords, i32(sample_index));
+    let base_color = textureSample(screen_texture, texture_sampler, in.uv);
+    var weight_total = 0.0;
+    var accumulator = vec4<f32>(0.0);
+
+    for (var i = 0; i < n_samples; i++) {
+        var offset = vec2<f32>(0.0);
+        if speed > 1.0 && n_samples > 1 {
+            offset = exposure_vector * ((f32(i) + noise(in.uv)) / f32(n_samples) - 0.5);
+        }
+        let sample_uv = in.uv + offset;
+        let sample_coords = vec2<i32>(sample_uv * texture_size);
+
+        // If depth is not considered during sampling, you can end up sampling objects in front of a
+        // fast moving object, which will cause the (possibly stationary) objects in front of that
+        // fast moving object to smear. To prevent this, we check the depth of the fragment we are
+        // sampling. If it is closer to the camera than this fragment (plus the user-defined bias),
+        // we discard it. If the bias is too small, fragments from the same object will be filtered
+        // out.
+        let sample_depth = textureLoad(depth, sample_coords, i32(sample_index));
+        let weight = step(settings.depth_bias, this_depth - sample_depth);
+
+        weight_total += weight;
+        accumulator += weight * textureSample(screen_texture, texture_sampler, sample_uv);
+    }
+
+    // Avoid black pixels by falling back to the unblurred fragment color
+    if weight_total == 0.0 {
+        accumulator =  base_color;
+        weight_total = 1.0;
+    }
+
+    return accumulator / weight_total;
+}
+
+fn noise(frag_coord: vec2<f32>) -> f32 {
+    let k1 = vec2<f32>(23.14069263277926, 2.665144142690225);
+    return fract(cos(dot(frag_coord, k1)) * 12345.6789);
+}

crates/bevy_core_pipeline/src/motion_blur/node.rs

@@ -0,0 +1,108 @@
+use bevy_ecs::{query::QueryItem, world::World};
+use bevy_render::{
+    extract_component::ComponentUniforms,
+    render_graph::{NodeRunError, RenderGraphContext, ViewNode},
+    render_resource::{
+        BindGroupDescriptor, BindGroupEntry, BindingResource, Operations, PipelineCache,
+        RenderPassColorAttachment, RenderPassDescriptor,
+    },
+    renderer::RenderContext,
+    view::{Msaa, ViewTarget},
+};
+
+use crate::prepass::ViewPrepassTextures;
+
+use super::{
+    pipeline::{MotionBlurPipeline, MotionBlurPipelineId},
+    MotionBlur,
+};
+
+#[derive(Default)]
+pub struct MotionBlurNode;
+
+impl ViewNode for MotionBlurNode {
+    type ViewQuery = (
+        &'static ViewTarget,
+        &'static MotionBlurPipelineId,
+        &'static ViewPrepassTextures,
+    );
+    fn run(
+        &self,
+        _graph: &mut RenderGraphContext,
+        render_context: &mut RenderContext,
+        (view_target, pipeline_id, prepass_textures): QueryItem<Self::ViewQuery>,
+        world: &World,
+    ) -> Result<(), NodeRunError> {
+        let motion_blur_pipeline = world.resource::<MotionBlurPipeline>();
+        let pipeline_cache = world.resource::<PipelineCache>();
+        let settings_uniforms = world.resource::<ComponentUniforms<MotionBlur>>();
+        let Some(pipeline) = pipeline_cache.get_render_pipeline(pipeline_id.0) else {
+            return Ok(());
+        };
+
+        let Some(settings_binding) = settings_uniforms.uniforms().binding() else {
+            return Ok(());
+        };
+        let (Some(prepass_motion_vectors_texture), Some(prepass_depth_texture)) =
+            (&prepass_textures.motion_vectors, &prepass_textures.depth)
+        else {
+            return Ok(());
+        };
+
+        let post_process = view_target.post_process_write();
+
+        let msaa = world.resource::<Msaa>();
+        let layout = if msaa.samples() == 1 {
+            &motion_blur_pipeline.layout
+        } else {
+            &motion_blur_pipeline.layout_msaa
+        };
+
+        let bind_group = render_context
+            .render_device()
+            .create_bind_group(&BindGroupDescriptor {
+                label: Some("motion_blur_bind_group"),
+                layout,
+                entries: &[
+                    BindGroupEntry {
+                        binding: 0,
+                        resource: BindingResource::TextureView(post_process.source),
+                    },
+                    BindGroupEntry {
+                        binding: 1,
+                        resource: BindingResource::TextureView(
+                            &prepass_motion_vectors_texture.default_view,
+                        ),
+                    },
+                    BindGroupEntry {
+                        binding: 2,
+                        resource: BindingResource::TextureView(&prepass_depth_texture.default_view),
+                    },
+                    BindGroupEntry {
+                        binding: 3,
+                        resource: BindingResource::Sampler(&motion_blur_pipeline.sampler),
+                    },
+                    BindGroupEntry {
+                        binding: 4,
+                        resource: settings_binding.clone(),
+                    },
+                ],
+            });
+
+        let mut render_pass = render_context.begin_tracked_render_pass(RenderPassDescriptor {
+            label: Some("motion_blur_pass"),
+            color_attachments: &[Some(RenderPassColorAttachment {
+                view: post_process.destination,
+                resolve_target: None,
+                ops: Operations::default(),
+            })],
+            depth_stencil_attachment: None,
+        });
+
+        render_pass.set_render_pipeline(pipeline);
+        render_pass.set_bind_group(0, &bind_group, &[]);
+        render_pass.draw(0..3, 0..1);
+
+        Ok(())
+    }
+}