Merge remote-tracking branch 'origin/main' into pcss

Cargo.toml

@@ -2970,6 +2970,29 @@ description = "Shows off rendering for all math primitives as both Meshes and Gi
 category = "Math"
 wasm = true
 
+# Math
+[[example]]
+name = "sampling_primitives"
+path = "examples/math/sampling_primitives.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.sampling_primitives]
+name = "Sampling Primitives"
+description = "Demonstrates all the primitives which can be sampled."
+category = "Math"
+wasm = true
+
+[[example]]
+name = "random_sampling"
+path = "examples/math/random_sampling.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.random_sampling]
+name = "Random Sampling"
+description = "Demonstrates how to sample random points from mathematical primitives"
+category = "Math"
+wasm = true
+
 # Gizmos
 [[example]]
 name = "2d_gizmos"
@@ -3038,6 +3061,17 @@ description = "Demonstrates visibility ranges"
 category = "3D Rendering"
 wasm = true
 
+[[example]]
+name = "ssr"
+path = "examples/3d/ssr.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.ssr]
+name = "Screen Space Reflections"
+description = "Demonstrates screen space reflections with water ripples"
+category = "3D Rendering"
+wasm = false
+
 [[example]]
 name = "color_grading"
 path = "examples/3d/color_grading.rs"

assets/shaders/water_material.wgsl

@@ -0,0 +1,59 @@
+// A shader that creates water ripples by overlaying 4 normal maps on top of one
+// another.
+//
+// This is used in the `ssr` example. It only supports deferred rendering.
+
+#import bevy_pbr::{
+    pbr_deferred_functions::deferred_output,
+    pbr_fragment::pbr_input_from_standard_material,
+    prepass_io::{VertexOutput, FragmentOutput},
+}
+#import bevy_render::globals::Globals
+
+// Parameters to the water shader.
+struct WaterSettings {
+    // How much to displace each octave each frame, in the u and v directions.
+    // Two octaves are packed into each `vec4`.
+    octave_vectors: array<vec4<f32>, 2>,
+    // How wide the waves are in each octave.
+    octave_scales: vec4<f32>,
+    // How high the waves are in each octave.
+    octave_strengths: vec4<f32>,
+}
+
+@group(0) @binding(1) var<uniform> globals: Globals;
+
+@group(2) @binding(100) var water_normals_texture: texture_2d<f32>;
+@group(2) @binding(101) var water_normals_sampler: sampler;
+@group(2) @binding(102) var<uniform> water_settings: WaterSettings;
+
+// Samples a single octave of noise and returns the resulting normal.
+fn sample_noise_octave(uv: vec2<f32>, strength: f32) -> vec3<f32> {
+    let N = textureSample(water_normals_texture, water_normals_sampler, uv).rbg * 2.0 - 1.0;
+    // This isn't slerp, but it's good enough.
+    return normalize(mix(vec3(0.0, 1.0, 0.0), N, strength)); 
+}
+
+// Samples all four octaves of noise and returns the resulting normal.
+fn sample_noise(uv: vec2<f32>, time: f32) -> vec3<f32> {
+    let uv0 = uv * water_settings.octave_scales[0] + water_settings.octave_vectors[0].xy * time;
+    let uv1 = uv * water_settings.octave_scales[1] + water_settings.octave_vectors[0].zw * time;
+    let uv2 = uv * water_settings.octave_scales[2] + water_settings.octave_vectors[1].xy * time;
+    let uv3 = uv * water_settings.octave_scales[3] + water_settings.octave_vectors[1].zw * time;
+    return normalize(
+        sample_noise_octave(uv0, water_settings.octave_strengths[0]) +
+        sample_noise_octave(uv1, water_settings.octave_strengths[1]) +
+        sample_noise_octave(uv2, water_settings.octave_strengths[2]) +
+        sample_noise_octave(uv3, water_settings.octave_strengths[3])
+    );
+}
+
+@fragment
+fn fragment(in: VertexOutput, @builtin(front_facing) is_front: bool) -> FragmentOutput {
+    // Create the PBR input.
+    var pbr_input = pbr_input_from_standard_material(in, is_front);
+    // Bump the normal.
+    pbr_input.N = sample_noise(in.uv, globals.time);
+    // Send the rest to the deferred shader.
+    return deferred_output(in, pbr_input);
+}

crates/bevy_color/src/color_ops.rs

@@ -42,6 +42,19 @@ pub trait Mix: Sized {
     }
 }
 
+/// Trait for returning a grayscale color of a provided lightness.
+pub trait Gray: Mix + Sized {
+    /// A pure black color.
+    const BLACK: Self;
+    /// A pure white color.
+    const WHITE: Self;
+
+    /// Returns a grey color with the provided lightness from (0.0 - 1.0). 0 is black, 1 is white.
+    fn gray(lightness: f32) -> Self {
+        Self::BLACK.mix(&Self::WHITE, lightness)
+    }
+}
+
 /// Methods for manipulating alpha values.
 pub trait Alpha: Sized {
     /// Return a new version of this color with the given alpha value.
@@ -112,6 +125,8 @@ pub(crate) fn lerp_hue(a: f32, b: f32, t: f32) -> f32 {
 
 #[cfg(test)]
 mod tests {
+    use std::fmt::Debug;
+
     use super::*;
     use crate::{testing::assert_approx_eq, Hsla};
 
@@ -145,4 +160,25 @@ mod tests {
         assert_approx_eq!(lerp_hue(350., 10., 0.5), 0., 0.001);
         assert_approx_eq!(lerp_hue(350., 10., 0.75), 5., 0.001);
     }
+
+    fn verify_gray<Col>()
+    where
+        Col: Gray + Debug + PartialEq,
+    {
+        assert_eq!(Col::gray(0.), Col::BLACK);
+        assert_eq!(Col::gray(1.), Col::WHITE);
+    }
+
+    #[test]
+    fn test_gray() {
+        verify_gray::<crate::Hsla>();
+        verify_gray::<crate::Hsva>();
+        verify_gray::<crate::Hwba>();
+        verify_gray::<crate::Laba>();
+        verify_gray::<crate::Lcha>();
+        verify_gray::<crate::LinearRgba>();
+        verify_gray::<crate::Oklaba>();
+        verify_gray::<crate::Oklcha>();
+        verify_gray::<crate::Xyza>();
+    }
 }

crates/bevy_color/src/hsla.rs

@@ -1,5 +1,5 @@
 use crate::{
-    Alpha, ColorToComponents, Hsva, Hue, Hwba, Lcha, LinearRgba, Luminance, Mix, Srgba,
+    Alpha, ColorToComponents, Gray, Hsva, Hue, Hwba, Lcha, LinearRgba, Luminance, Mix, Srgba,
     StandardColor, Xyza,
 };
 use bevy_math::{Vec3, Vec4};
@@ -119,6 +119,11 @@ impl Mix for Hsla {
     }
 }
 
+impl Gray for Hsla {
+    const BLACK: Self = Self::new(0., 0., 0., 1.);
+    const WHITE: Self = Self::new(0., 0., 1., 1.);
+}
+
 impl Alpha for Hsla {
     #[inline]
     fn with_alpha(&self, alpha: f32) -> Self {

crates/bevy_color/src/hsva.rs

@@ -1,5 +1,5 @@
 use crate::{
-    Alpha, ColorToComponents, Hue, Hwba, Lcha, LinearRgba, Mix, Srgba, StandardColor, Xyza,
+    Alpha, ColorToComponents, Gray, Hue, Hwba, Lcha, LinearRgba, Mix, Srgba, StandardColor, Xyza,
 };
 use bevy_math::{Vec3, Vec4};
 use bevy_reflect::prelude::*;
@@ -89,6 +89,11 @@ impl Mix for Hsva {
     }
 }
 
+impl Gray for Hsva {
+    const BLACK: Self = Self::new(0., 0., 0., 1.);
+    const WHITE: Self = Self::new(0., 0., 1., 1.);
+}
+
 impl Alpha for Hsva {
     #[inline]
     fn with_alpha(&self, alpha: f32) -> Self {

crates/bevy_color/src/hwba.rs

@@ -2,7 +2,9 @@
 //! in [_HWB - A More Intuitive Hue-Based Color Model_] by _Smith et al_.
 //!
 //! [_HWB - A More Intuitive Hue-Based Color Model_]: https://web.archive.org/web/20240226005220/http://alvyray.com/Papers/CG/HWB_JGTv208.pdf
-use crate::{Alpha, ColorToComponents, Hue, Lcha, LinearRgba, Mix, Srgba, StandardColor, Xyza};
+use crate::{
+    Alpha, ColorToComponents, Gray, Hue, Lcha, LinearRgba, Mix, Srgba, StandardColor, Xyza,
+};
 use bevy_math::{Vec3, Vec4};
 use bevy_reflect::prelude::*;
 
@@ -91,6 +93,11 @@ impl Mix for Hwba {
     }
 }
 
+impl Gray for Hwba {
+    const BLACK: Self = Self::new(0., 0., 1., 1.);
+    const WHITE: Self = Self::new(0., 1., 0., 1.);
+}
+
 impl Alpha for Hwba {
     #[inline]
     fn with_alpha(&self, alpha: f32) -> Self {

crates/bevy_color/src/laba.rs

@@ -1,5 +1,5 @@
 use crate::{
-    impl_componentwise_vector_space, Alpha, ColorToComponents, Hsla, Hsva, Hwba, LinearRgba,
+    impl_componentwise_vector_space, Alpha, ColorToComponents, Gray, Hsla, Hsva, Hwba, LinearRgba,
     Luminance, Mix, Oklaba, Srgba, StandardColor, Xyza,
 };
 use bevy_math::{Vec3, Vec4};
@@ -101,6 +101,11 @@ impl Mix for Laba {
     }
 }
 
+impl Gray for Laba {
+    const BLACK: Self = Self::new(0., 0., 0., 1.);
+    const WHITE: Self = Self::new(1., 0., 0., 1.);
+}
+
 impl Alpha for Laba {
     #[inline]
     fn with_alpha(&self, alpha: f32) -> Self {

crates/bevy_color/src/lcha.rs

@@ -1,5 +1,6 @@
 use crate::{
-    Alpha, ColorToComponents, Hue, Laba, LinearRgba, Luminance, Mix, Srgba, StandardColor, Xyza,
+    Alpha, ColorToComponents, Gray, Hue, Laba, LinearRgba, Luminance, Mix, Srgba, StandardColor,
+    Xyza,
 };
 use bevy_math::{Vec3, Vec4};
 use bevy_reflect::prelude::*;
@@ -122,6 +123,11 @@ impl Mix for Lcha {
     }
 }
 
+impl Gray for Lcha {
+    const BLACK: Self = Self::new(0.0, 0.0, 0.0000136603785, 1.0);
+    const WHITE: Self = Self::new(1.0, 0.0, 0.0000136603785, 1.0);
+}
+
 impl Alpha for Lcha {
     #[inline]
     fn with_alpha(&self, alpha: f32) -> Self {

crates/bevy_color/src/linear_rgba.rs

@@ -1,6 +1,6 @@
 use crate::{
     color_difference::EuclideanDistance, impl_componentwise_vector_space, Alpha, ColorToComponents,
-    Luminance, Mix, StandardColor,
+    Gray, Luminance, Mix, StandardColor,
 };
 use bevy_math::{Vec3, Vec4};
 use bevy_reflect::prelude::*;
@@ -121,18 +121,6 @@ impl LinearRgba {
         }
     }
 
-    /// Construct a new [`LinearRgba`] color with the same value for all channels and an alpha of 1.0.
-    ///
-    /// A value of 0.0 is black, and a value of 1.0 is white.
-    pub const fn gray(value: f32) -> Self {
-        Self {
-            red: value,
-            green: value,
-            blue: value,
-            alpha: 1.0,
-        }
-    }
-
     /// Return a copy of this color with the red channel set to the given value.
     pub const fn with_red(self, red: f32) -> Self {
         Self { red, ..self }
@@ -236,6 +224,11 @@ impl Mix for LinearRgba {
     }
 }
 
+impl Gray for LinearRgba {
+    const BLACK: Self = Self::BLACK;
+    const WHITE: Self = Self::WHITE;
+}
+
 impl Alpha for LinearRgba {
     #[inline]
     fn with_alpha(&self, alpha: f32) -> Self {

crates/bevy_color/src/oklaba.rs

@@ -1,6 +1,6 @@
 use crate::{
     color_difference::EuclideanDistance, impl_componentwise_vector_space, Alpha, ColorToComponents,
-    Hsla, Hsva, Hwba, Lcha, LinearRgba, Luminance, Mix, Srgba, StandardColor, Xyza,
+    Gray, Hsla, Hsva, Hwba, Lcha, LinearRgba, Luminance, Mix, Srgba, StandardColor, Xyza,
 };
 use bevy_math::{Vec3, Vec4};
 use bevy_reflect::prelude::*;
@@ -101,6 +101,11 @@ impl Mix for Oklaba {
     }
 }
 
+impl Gray for Oklaba {
+    const BLACK: Self = Self::new(0., 0., 0., 1.);
+    const WHITE: Self = Self::new(1.0, 0.0, 0.000000059604645, 1.0);
+}
+
 impl Alpha for Oklaba {
     #[inline]
     fn with_alpha(&self, alpha: f32) -> Self {

crates/bevy_color/src/oklcha.rs

@@ -1,6 +1,6 @@
 use crate::{
-    color_difference::EuclideanDistance, Alpha, ColorToComponents, Hsla, Hsva, Hue, Hwba, Laba,
-    Lcha, LinearRgba, Luminance, Mix, Oklaba, Srgba, StandardColor, Xyza,
+    color_difference::EuclideanDistance, Alpha, ColorToComponents, Gray, Hsla, Hsva, Hue, Hwba,
+    Laba, Lcha, LinearRgba, Luminance, Mix, Oklaba, Srgba, StandardColor, Xyza,
 };
 use bevy_math::{Vec3, Vec4};
 use bevy_reflect::prelude::*;
@@ -119,6 +119,11 @@ impl Mix for Oklcha {
     }
 }
 
+impl Gray for Oklcha {
+    const BLACK: Self = Self::new(0., 0., 0., 1.);
+    const WHITE: Self = Self::new(1.0, 0.000000059604645, 90.0, 1.0);
+}
+
 impl Alpha for Oklcha {
     #[inline]
     fn with_alpha(&self, alpha: f32) -> Self {

crates/bevy_color/src/srgba.rs

@@ -1,6 +1,6 @@
 use crate::color_difference::EuclideanDistance;
 use crate::{
-    impl_componentwise_vector_space, Alpha, ColorToComponents, LinearRgba, Luminance, Mix,
+    impl_componentwise_vector_space, Alpha, ColorToComponents, Gray, LinearRgba, Luminance, Mix,
     StandardColor, Xyza,
 };
 use bevy_math::{Vec3, Vec4};
@@ -314,6 +314,11 @@ impl EuclideanDistance for Srgba {
     }
 }
 
+impl Gray for Srgba {
+    const BLACK: Self = Self::BLACK;
+    const WHITE: Self = Self::WHITE;
+}
+
 impl ColorToComponents for Srgba {
     fn to_f32_array(self) -> [f32; 4] {
         [self.red, self.green, self.blue, self.alpha]

crates/bevy_color/src/xyza.rs

@@ -1,5 +1,5 @@
 use crate::{
-    impl_componentwise_vector_space, Alpha, ColorToComponents, LinearRgba, Luminance, Mix,
+    impl_componentwise_vector_space, Alpha, ColorToComponents, Gray, LinearRgba, Luminance, Mix,
     StandardColor,
 };
 use bevy_math::{Vec3, Vec4};
@@ -144,6 +144,11 @@ impl Mix for Xyza {
     }
 }
 
+impl Gray for Xyza {
+    const BLACK: Self = Self::new(0., 0., 0., 1.);
+    const WHITE: Self = Self::new(0.95047, 1.0, 1.08883, 1.0);
+}
+
 impl ColorToComponents for Xyza {
     fn to_f32_array(self) -> [f32; 4] {
         [self.x, self.y, self.z, self.alpha]

crates/bevy_core_pipeline/src/bloom/mod.rs

@@ -2,7 +2,7 @@ mod downsampling_pipeline;
 mod settings;
 mod upsampling_pipeline;
 
-use bevy_color::LinearRgba;
+use bevy_color::{Gray, LinearRgba};
 pub use settings::{BloomCompositeMode, BloomPrefilterSettings, BloomSettings};
 
 use crate::{