Implements post-process lens distortion effects (#23110)

# Objective

- Implements post-process lens distortion effects based on
`EffectStackPlugin`.

## Solution

- This PR's implementation is based on a simplified special case of the
Brown-Conrady model, where p₁ = p₂ = 0 and control is retained only for
k₁ and k₂.
- Additionally, supports controlling the degree of distortion in the
horizontal and vertical directions based on the direction vector.

## Testing

- These effect components can work independently.
- The example works as expected.
- CI

---

## Showcase

- Barrel distortion
<img width="1918" height="1104" alt="tu"
src="https://github.com/user-attachments/assets/6d1b1660-0892-4433-a152-4ac277b9382c"
/>

- Pincushion distortion
<img width="1935" height="1084" alt="ao"
src="https://github.com/user-attachments/assets/2d3c5373-43a8-427c-bd0a-59ccce4448fc"
/>

- Pincushion distortion with no distortion on the x-axis.
<img width="1921" height="1089" alt="ao_no_x"
src="https://github.com/user-attachments/assets/c1b4b55d-7b7f-4cb7-8459-debe4cf2f283"
/>

- With all effects.
<img width="2559" height="1314" alt="cur"
src="https://github.com/user-attachments/assets/724cfa30-9b36-42b9-a480-0d96720f760b"
/>

Author: Breakdown-Dog

crates/bevy_post_process/src/effect_stack/lens_distortion.rs

@@ -0,0 +1,112 @@
+use bevy_ecs::{
+    component::Component,
+    query::{QueryItem, With},
+    system::lifetimeless::Read,
+};
+use bevy_math::{ops::abs, Vec2};
+use bevy_reflect::Reflect;
+use bevy_render::{
+    extract_component::ExtractComponent, render_resource::ShaderType, sync_component::SyncComponent,
+};
+
+/// Simulates the warping of the image caused by real-world camera lenses.
+///
+/// [Lens distortion] simulates the imperfections of optical systems, where
+/// straight lines in the real world appear curved in the image. This effect
+/// is commonly used to create a sense of unease or disorientation, to mimic
+/// specific camera equipment, or to enhance the scale and immersion of scenes.
+///
+/// Bevy's implementation is based on a simplified special case of the
+/// Brown-Conrady model, where p₁ = p₂ = 0 and control is retained only
+/// for k1 and k2.
+#[derive(Reflect, Component, Clone)]
+pub struct LensDistortion {
+    /// The overall strength of the distortion effect.
+    ///
+    /// Positive values typically produce **barrel distortion** (bulging outwards),
+    /// while negative values produce **pincushion distortion** (pinching inwards).
+    /// This corresponds roughly to the radial distortion coefficient `k1`
+    /// in the simplified model.
+    ///
+    /// The default value is 0.5.
+    pub intensity: f32,
+    /// A global scale factor applied to the final distorted image.
+    ///
+    /// Strong distortion pushes pixels away from the center or pulls them in,
+    /// resulting in visible **stretching artifacts** at the screen edges.
+    /// Increasing this value zooms in to **crop out** these extreme edge artifacts,
+    /// ensuring the screen remains fully covered at the cost of a tighter field of view.
+    ///
+    /// The default value is 1.0(No zoom).
+    pub scale: f32,
+    /// A multiplier that determines how the distortion scales along the X and Y axes.
+    ///
+    /// By default, this should be `Vec2::ONE` for uniform radial distortion.
+    /// Modifying these values allows for anamorphic-like effects where the distortion
+    /// is stronger on one axis than the other. When a component of multiplier is set to 0.0,
+    /// no distortion effect is applied.
+    ///
+    /// The default value is `Vec2::ONE`
+    pub multiplier: Vec2,
+    /// The center point of the distortion effect in UV space `[0.0, 1.0]`.
+    ///
+    /// Distortion radiates outward or inward from this point.
+    ///
+    /// The default value is `Vec2::splat(0.5)`
+    pub center: Vec2,
+    /// Controls the sharpness of the distortion curve near the screen edges.
+    ///
+    /// `edge_curvature` provides indirect control over the k2 parameter.
+    /// The reason for indirect control is that k1 and k2 are typically correlated.
+    /// If k2 did not vary with k1, it would easily cause visual jumping when intensity
+    /// transitions from positive to negative.
+    /// For a simple and natural look in most cases, we recommend setting `edge_curvature` to 0.0.
+    ///
+    /// The default value is 0.0.
+    pub edge_curvature: f32,
+}
+
+impl Default for LensDistortion {
+    fn default() -> Self {
+        Self {
+            intensity: 0.5,
+            scale: 1.0,
+            multiplier: Vec2::ONE,
+            center: Vec2::splat(0.5),
+            edge_curvature: 0.0,
+        }
+    }
+}
+
+impl SyncComponent for LensDistortion {
+    type Target = Self;
+}
+
+impl ExtractComponent for LensDistortion {
+    type QueryData = Read<LensDistortion>;
+    type QueryFilter = With<LensDistortion>;
+    type Out = Self;
+
+    fn extract_component(lens_distortion: QueryItem<'_, '_, Self::QueryData>) -> Option<Self::Out> {
+        // Skip the postprocessing phase entirely if the intensity is negligible.
+        if abs(lens_distortion.intensity) > 1e-4 {
+            Some(lens_distortion.clone())
+        } else {
+            None
+        }
+    }
+}
+
+/// The on-GPU version of the [`LensDistortion`] settings.
+///
+/// See the documentation for [`LensDistortion`] for more information on
+/// each of these fields.
+#[derive(ShaderType, Default)]
+pub struct LensDistortionUniform {
+    pub(super) intensity: f32,
+    pub(super) scale: f32,
+    pub(super) multiplier: Vec2,
+    pub(super) center: Vec2,
+    pub(super) edge_curvature: f32,
+    pub(super) unused: u32,
+}

crates/bevy_post_process/src/effect_stack/lens_distortion.wgsl

@@ -0,0 +1,54 @@
+// The lens distortion postprocessing effect.
+
+#define_import_path bevy_post_process::effect_stack::lens_distortion
+
+// See `bevy_post_process::effect_stack::LensDistortion` for more
+// information on these fields.
+struct LensDistortionSettings {
+    intensity: f32,
+    scale: f32,
+    multiplier: vec2<f32>,
+    center: vec2<f32>,
+    edge_curvature: f32,
+    unused: u32,
+}
+
+const VISUAL_THRESHOLD: f32 = 1e-4;
+const MATH_EPSILON: f32 = 1e-6;
+
+// The settings supplied by the developer.
+@group(0) @binding(6) var<uniform> lens_distortion_settings: LensDistortionSettings;
+
+fn lens_distortion(uv: vec2<f32>) -> vec2<f32>{
+    let intensity = lens_distortion_settings.intensity;
+    if (abs(intensity) < VISUAL_THRESHOLD) {
+        return uv;
+    }
+    let multiplier = lens_distortion_settings.multiplier;
+    let center = lens_distortion_settings.center;
+
+    let uv_centered = uv - center;
+    // Prevent division by zero.
+    let radius = max(length(uv_centered), MATH_EPSILON);
+
+    let direction = uv_centered / radius;
+    let adjust = dot(abs(direction), multiplier);
+
+    // Maintains the correlation between k2 and k1, while ensuring the sign of k2
+    // is determined solely by `edge_curvature` rather than being influenced by intensity.
+    let k1 = intensity * adjust;
+    let k2 = k1 * intensity * lens_distortion_settings.edge_curvature;
+
+    let r2 = radius * radius;
+    let r_distorted = radius * (1.0 + (k1 + k2 * r2) * r2);
+
+    let uv_distorted = direction * r_distorted + center;
+
+    // Compensates for the distortion pushing pixels outside the [0,1] UV bounds.
+    let uv_scaled = (uv_distorted - center) / lens_distortion_settings.scale + center;
+
+    // Discard out-of-bounds pixels to prevent edge bleeding artifacts.
+    let uv_safe = clamp(uv_scaled, vec2<f32>(0.0), vec2<f32>(1.0));
+
+    return uv_safe;
+}

crates/bevy_post_process/src/effect_stack/mod.rs

@@ -3,13 +3,17 @@
 //! Includes:
 //!
 //! - Chromatic Aberration
+//! - Lens Distortion
 //! - Vignette
 
 mod chromatic_aberration;
+mod lens_distortion;
 mod vignette;
 
 use bevy_color::ColorToComponents;
+use bevy_math::Vec2;
 pub use chromatic_aberration::{ChromaticAberration, ChromaticAberrationUniform};
+pub use lens_distortion::{LensDistortion, LensDistortionUniform};
 pub use vignette::{Vignette, VignetteUniform};
 
 use crate::effect_stack::chromatic_aberration::{
@@ -65,6 +69,7 @@ use bevy_core_pipeline::{
 /// Includes:
 ///
 /// - Chromatic Aberration
+/// - Lens Distortion
 /// - Vignette
 #[derive(Default)]
 pub struct EffectStackPlugin;
@@ -107,6 +112,7 @@ pub struct PostProcessingPipelineId(CachedRenderPipelineId);
 pub struct PostProcessingUniformBuffers {
     chromatic_aberration: DynamicUniformBuffer<ChromaticAberrationUniform>,
     vignette: DynamicUniformBuffer<VignetteUniform>,
+    lens_distortion: DynamicUniformBuffer<LensDistortionUniform>,
 }
 
 /// A component, part of the render world, that stores the appropriate byte
@@ -116,11 +122,13 @@ pub struct PostProcessingUniformBuffers {
 pub struct PostProcessingUniformBufferOffsets {
     chromatic_aberration: u32,
     vignette: u32,
+    lens_distortion: u32,
 }
 
 impl Plugin for EffectStackPlugin {
     fn build(&self, app: &mut App) {
         load_shader_library!(app, "chromatic_aberration.wgsl");
+        load_shader_library!(app, "lens_distortion.wgsl");
         load_shader_library!(app, "vignette.wgsl");
 
         embedded_asset!(app, "post_process.wgsl");
@@ -140,6 +148,7 @@ impl Plugin for EffectStackPlugin {
         ));
 
         app.add_plugins(ExtractComponentPlugin::<ChromaticAberration>::default())
+            .add_plugins(ExtractComponentPlugin::<LensDistortion>::default())
             .add_plugins(ExtractComponentPlugin::<Vignette>::default());
 
         let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
@@ -191,6 +200,8 @@ pub fn init_post_processing_pipeline(
                 uniform_buffer::<ChromaticAberrationUniform>(true),
                 // Vignette settings:
                 uniform_buffer::<VignetteUniform>(true),
+                // Lens Distortion settings:
+                uniform_buffer::<LensDistortionUniform>(true),
             ),
         ),
     );
@@ -247,7 +258,7 @@ pub(crate) fn post_processing(
     view: ViewQuery<(
         &ViewTarget,
         &PostProcessingPipelineId,
-        AnyOf<(&ChromaticAberration, &Vignette)>,
+        AnyOf<(&ChromaticAberration, &Vignette, &LensDistortion)>,
         &PostProcessingUniformBufferOffsets,
     )>,
     pipeline_cache: Res<PipelineCache>,
@@ -260,9 +271,12 @@ pub(crate) fn post_processing(
     let (view_target, pipeline_id, post_effects, post_processing_uniform_buffer_offsets) =
         view.into_inner();
 
-    let (maybe_chromatic_aberration, maybe_vignette) = post_effects;
+    let (maybe_chromatic_aberration, maybe_vignette, maybe_lens_distortion) = post_effects;
 
-    if maybe_chromatic_aberration.is_none() && maybe_vignette.is_none() {
+    if maybe_chromatic_aberration.is_none()
+        && maybe_vignette.is_none()
+        && maybe_lens_distortion.is_none()
+    {
         return;
     }
 
@@ -293,6 +307,12 @@ pub(crate) fn post_processing(
         return;
     };
 
+    let Some(lens_distortion_uniform_buffer_binding) =
+        post_processing_uniform_buffers.lens_distortion.binding()
+    else {
+        return;
+    };
+
     // Use the [`PostProcessWrite`] infrastructure, since this is a full-screen pass.
     let post_process = view_target.post_process_write();
 
@@ -320,6 +340,7 @@ pub(crate) fn post_processing(
             &post_processing_pipeline.chromatic_aberration_lut_sampler,
             chromatic_aberration_uniform_buffer_binding,
             vignette_uniform_buffer_binding,
+            lens_distortion_uniform_buffer_binding,
         )),
     );
 
@@ -336,6 +357,7 @@ pub(crate) fn post_processing(
         &[
             post_processing_uniform_buffer_offsets.chromatic_aberration,
             post_processing_uniform_buffer_offsets.vignette,
+            post_processing_uniform_buffer_offsets.lens_distortion,
         ],
     );
     render_pass.draw(0..3, 0..1);
@@ -354,6 +376,7 @@ pub fn prepare_post_processing_pipelines(
         Or<(
             With<ChromaticAberration>,
             With<Vignette>,
+            With<LensDistortion>,
             With<ExtractedCamera>,
         )>,
     >,
@@ -381,15 +404,26 @@ pub fn prepare_post_processing_uniforms(
     render_device: Res<RenderDevice>,
     render_queue: Res<RenderQueue>,
     mut views: Query<
-        (Entity, Option<&ChromaticAberration>, Option<&Vignette>),
-        Or<(With<ChromaticAberration>, With<Vignette>)>,
+        (
+            Entity,
+            Option<&ChromaticAberration>,
+            Option<&Vignette>,
+            Option<&LensDistortion>,
+        ),
+        Or<(
+            With<ChromaticAberration>,
+            With<Vignette>,
+            With<LensDistortion>,
+        )>,
     >,
 ) {
     post_processing_uniform_buffers.chromatic_aberration.clear();
     post_processing_uniform_buffers.vignette.clear();
 
     // Gather up all the postprocessing settings.
-    for (view_entity, maybe_chromatic_aberration, maybe_vignette) in views.iter_mut() {
+    for (view_entity, maybe_chromatic_aberration, maybe_vignette, maybe_lens_distortion) in
+        views.iter_mut()
+    {
         let chromatic_aberration_uniform_buffer_offset =
             if let Some(chromatic_aberration) = maybe_chromatic_aberration {
                 post_processing_uniform_buffers.chromatic_aberration.push(
@@ -425,11 +459,30 @@ pub fn prepare_post_processing_uniforms(
                 .push(&VignetteUniform::default())
         };
 
+        let lens_distortion_uniform_buffer_offset =
+            if let Some(lens_distortion) = maybe_lens_distortion {
+                post_processing_uniform_buffers
+                    .lens_distortion
+                    .push(&LensDistortionUniform {
+                        intensity: lens_distortion.intensity,
+                        scale: lens_distortion.scale.max(1e-6),
+                        multiplier: lens_distortion.multiplier.max(Vec2::ZERO),
+                        center: lens_distortion.center.clamp(Vec2::ZERO, Vec2::ONE),
+                        edge_curvature: lens_distortion.edge_curvature,
+                        unused: 0,
+                    })
+            } else {
+                post_processing_uniform_buffers
+                    .lens_distortion
+                    .push(&LensDistortionUniform::default())
+            };
+
         commands
             .entity(view_entity)
             .insert(PostProcessingUniformBufferOffsets {
                 chromatic_aberration: chromatic_aberration_uniform_buffer_offset,
                 vignette: vignette_uniform_buffer_offset,
+                lens_distortion: lens_distortion_uniform_buffer_offset,
             });
     }
 
@@ -440,4 +493,7 @@ pub fn prepare_post_processing_uniforms(
     post_processing_uniform_buffers
         .vignette
         .write_buffer(&render_device, &render_queue);
+    post_processing_uniform_buffers
+        .lens_distortion
+        .write_buffer(&render_device, &render_queue);
 }

crates/bevy_post_process/src/effect_stack/post_process.wgsl

@@ -2,10 +2,12 @@
 
 #import bevy_core_pipeline::fullscreen_vertex_shader::FullscreenVertexOutput
 #import bevy_post_process::effect_stack::chromatic_aberration::chromatic_aberration
+#import bevy_post_process::effect_stack::lens_distortion::lens_distortion
 #import bevy_post_process::effect_stack::vignette::vignette
 
 @fragment
 fn fragment_main(in: FullscreenVertexOutput) -> @location(0) vec4<f32> {
-    let color = chromatic_aberration(in.uv);
+    let distorted_uv = lens_distortion(in.uv);
+    let color = chromatic_aberration(distorted_uv);
     return vec4(vignette(in.uv, color), 1.0);
 }