[Merged by Bors] - Standard Material Blend Modes

Cargo.toml

@@ -293,6 +293,16 @@ description = "A scene showcasing the built-in 3D shapes"
 category = "3D Rendering"
 wasm = true
 
+[[example]]
+name = "blend_modes"
+path = "examples/3d/blend_modes.rs"
+
+[package.metadata.example.blend_modes]
+name = "Blend Modes"
+description = "Showcases different blend modes"
+category = "3D Rendering"
+wasm = true
+
 [[example]]
 name = "lighting"
 path = "examples/3d/lighting.rs"

crates/bevy_pbr/src/alpha.rs

@@ -23,6 +23,30 @@ pub enum AlphaMode {
     /// Standard alpha-blending is used to blend the fragment's color
     /// with the color behind it.
     Blend,
+    /// Similar to [`AlphaMode::Blend`], however assumes RGB channel values are
+    /// [premultiplied](https://en.wikipedia.org/wiki/Alpha_compositing#Straight_versus_premultiplied).
+    ///
+    /// For fixed RGB values, behaves more like [`AlphaMode::Blend`] for
+    /// alpha values closer to 1.0, and more like [`AlphaMode::Add`] for
+    /// alpha values closer to 0.0.
+    ///
+    /// Can be used to avoid “border” or “outline” artifacts that can occur
+    /// when using plain alpha-blended textures.
+    Premultiplied,
+    /// Combines the color of the fragments with the colors behind them in an
+    /// additive process, (i.e. like light) producing lighter results.
+    ///
+    /// Black produces no effect. Alpha values can be used to modulate the result.
+    ///
+    /// Useful for effects like holograms, ghosts, lasers and other energy beams.
+    Add,
+    /// Combines the color of the fragments with the colors behind them in an
+    /// multiplicative process, (i.e. like pigments) producing darker results.
+    ///
+    /// White produces no effect. Alpha values can be used to modulate the result.
+    ///
+    /// Useful for effects like stained glass, window tint film and some colored liquids.
+    Multiply,
 }
 
 impl Eq for AlphaMode {}

crates/bevy_pbr/src/material.rs

@@ -384,8 +384,14 @@ pub fn queue_material_meshes<M: Material>(
                             MeshPipelineKey::from_primitive_topology(mesh.primitive_topology)
                                 | view_key;
                         let alpha_mode = material.properties.alpha_mode;
-                        if let AlphaMode::Blend = alpha_mode {
-                            mesh_key |= MeshPipelineKey::TRANSPARENT_MAIN_PASS;
+                        if let AlphaMode::Blend | AlphaMode::Premultiplied | AlphaMode::Add =
+                            alpha_mode
+                        {
+                            // Blend, Premultiplied and Add all share the same pipeline key
+                            // They're made distinct in the PBR shader, via `premultiply_alpha()`
+                            mesh_key |= MeshPipelineKey::BLEND_PREMULTIPLIED_ALPHA;
+                        } else if let AlphaMode::Multiply = alpha_mode {
+                            mesh_key |= MeshPipelineKey::BLEND_MULTIPLY;
                         }
 
                         let pipeline_id = pipelines.specialize(
@@ -424,7 +430,10 @@ pub fn queue_material_meshes<M: Material>(
                                     distance,
                                 });
                             }
-                            AlphaMode::Blend => {
+                            AlphaMode::Blend
+                            | AlphaMode::Premultiplied
+                            | AlphaMode::Add
+                            | AlphaMode::Multiply => {
                                 transparent_phase.add(Transparent3d {
                                     entity: *visible_entity,
                                     draw_function: draw_transparent_pbr,

crates/bevy_pbr/src/pbr_material.rs

@@ -295,9 +295,13 @@ bitflags::bitflags! {
         const OCCLUSION_TEXTURE          = (1 << 3);
         const DOUBLE_SIDED               = (1 << 4);
         const UNLIT                      = (1 << 5);
-        const ALPHA_MODE_OPAQUE          = (1 << 6);
-        const ALPHA_MODE_MASK            = (1 << 7);
-        const ALPHA_MODE_BLEND           = (1 << 8);
+        const ALPHA_MODE_RESERVED_BITS   = (0b111 << 6); // ← Bitmask reserving three bits for the `AlphaMode`
+        const ALPHA_MODE_OPAQUE          = (0 << 6);     // ← Values are just sequential values bitshifted into
+        const ALPHA_MODE_MASK            = (1 << 6);     //   the bitmask, and can range from 0 to 7.
+        const ALPHA_MODE_BLEND           = (2 << 6);     //
+        const ALPHA_MODE_PREMULTIPLIED   = (3 << 6);     //
+        const ALPHA_MODE_ADD             = (4 << 6);     //   Right now only values 0–5 are used, which still gives
+        const ALPHA_MODE_MULTIPLY        = (5 << 6);     // ← us "room" for two more modes without adding more bits
         const TWO_COMPONENT_NORMAL_MAP   = (1 << 9);
         const FLIP_NORMAL_MAP_Y          = (1 << 10);
         const NONE                       = 0;
@@ -377,6 +381,9 @@ impl AsBindGroupShaderType<StandardMaterialUniform> for StandardMaterial {
                 flags |= StandardMaterialFlags::ALPHA_MODE_MASK;
             }
             AlphaMode::Blend => flags |= StandardMaterialFlags::ALPHA_MODE_BLEND,
+            AlphaMode::Premultiplied => flags |= StandardMaterialFlags::ALPHA_MODE_PREMULTIPLIED,
+            AlphaMode::Add => flags |= StandardMaterialFlags::ALPHA_MODE_ADD,
+            AlphaMode::Multiply => flags |= StandardMaterialFlags::ALPHA_MODE_MULTIPLY,
         };
 
         StandardMaterialUniform {

crates/bevy_pbr/src/render/mesh.rs

@@ -515,10 +515,13 @@ bitflags::bitflags! {
     /// MSAA uses the highest 3 bits for the MSAA log2(sample count) to support up to 128x MSAA.
     pub struct MeshPipelineKey: u32 {
         const NONE                        = 0;
-        const TRANSPARENT_MAIN_PASS       = (1 << 0);
-        const HDR                         = (1 << 1);
-        const TONEMAP_IN_SHADER           = (1 << 2);
-        const DEBAND_DITHER               = (1 << 3);
+        const BLEND_RESERVED_BITS         = 0b11; // ← Bitmask reserving two bits for the blend state
+        const BLEND_OPAQUE                = 0;    // ← Values are just sequential within the mask, and can range from 0 to 3
+        const BLEND_PREMULTIPLIED_ALPHA   = 1;    //
+        const BLEND_MULTIPLY              = 2;    // ← We still have room for one more value without adding more bits
+        const HDR                         = (1 << 2);
+        const TONEMAP_IN_SHADER           = (1 << 3);
+        const DEBAND_DITHER               = (1 << 4);
         const MSAA_RESERVED_BITS          = Self::MSAA_MASK_BITS << Self::MSAA_SHIFT_BITS;
         const PRIMITIVE_TOPOLOGY_RESERVED_BITS = Self::PRIMITIVE_TOPOLOGY_MASK_BITS << Self::PRIMITIVE_TOPOLOGY_SHIFT_BITS;
     }
@@ -620,12 +623,30 @@ impl SpecializedMeshPipeline for MeshPipeline {
         let vertex_buffer_layout = layout.get_layout(&vertex_attributes)?;
 
         let (label, blend, depth_write_enabled);
-        if key.contains(MeshPipelineKey::TRANSPARENT_MAIN_PASS) {
-            label = "transparent_mesh_pipeline".into();
-            blend = Some(BlendState::ALPHA_BLENDING);
+        let pass = key.intersection(MeshPipelineKey::BLEND_RESERVED_BITS);
+        if pass == MeshPipelineKey::BLEND_PREMULTIPLIED_ALPHA {
+            label = "premultiplied_alpha_mesh_pipeline".into();
+            blend = Some(BlendState::PREMULTIPLIED_ALPHA_BLENDING);
+            shader_defs.push("PREMULTIPLY_ALPHA".to_string());
+            shader_defs.push("BLEND_PREMULTIPLIED_ALPHA".to_string());
             // For the transparent pass, fragments that are closer will be alpha blended
             // but their depth is not written to the depth buffer
             depth_write_enabled = false;
+        } else if pass == MeshPipelineKey::BLEND_MULTIPLY {
+            label = "multiply_mesh_pipeline".into();
+            blend = Some(BlendState {
+                color: BlendComponent {
+                    src_factor: BlendFactor::Dst,
+                    dst_factor: BlendFactor::OneMinusSrcAlpha,
+                    operation: BlendOperation::Add,
+                },
+                alpha: BlendComponent::OVER,
+            });
+            shader_defs.push("PREMULTIPLY_ALPHA".to_string());
+            shader_defs.push("BLEND_MULTIPLY".to_string());
+            // For the multiply pass, fragments that are closer will be alpha blended
+            // but their depth is not written to the depth buffer
+            depth_write_enabled = false;
         } else {
             label = "opaque_mesh_pipeline".into();
             blend = Some(BlendState::REPLACE);

crates/bevy_pbr/src/render/pbr.wgsl

@@ -100,6 +100,9 @@ fn fragment(in: FragmentInput) -> @location(0) vec4<f32> {
 #endif
 #ifdef DEBAND_DITHER
         output_color = dither(output_color, in.frag_coord.xy);
+#endif
+#ifdef PREMULTIPLY_ALPHA
+        output_color = premultiply_alpha(material.flags, output_color);
 #endif
     return output_color;
 }

crates/bevy_pbr/src/render/pbr_functions.wgsl

@@ -7,10 +7,11 @@
 
 fn alpha_discard(material: StandardMaterial, output_color: vec4<f32>) -> vec4<f32>{
     var color = output_color;
-    if ((material.flags & STANDARD_MATERIAL_FLAGS_ALPHA_MODE_OPAQUE) != 0u) {
+    let alpha_mode = (material.flags & STANDARD_MATERIAL_FLAGS_ALPHA_MODE_RESERVED_BITS);
+    if (alpha_mode == STANDARD_MATERIAL_FLAGS_ALPHA_MODE_OPAQUE) {
         // NOTE: If rendering as opaque, alpha should be ignored so set to 1.0
         color.a = 1.0;
-    } else if ((material.flags & STANDARD_MATERIAL_FLAGS_ALPHA_MODE_MASK) != 0u) {
+    } else if (alpha_mode == STANDARD_MATERIAL_FLAGS_ALPHA_MODE_MASK) {
         if (color.a >= material.alpha_cutoff) {
             // NOTE: If rendering as masked alpha and >= the cutoff, render as fully opaque
             color.a = 1.0;
@@ -268,3 +269,66 @@ fn dither(color: vec4<f32>, pos: vec2<f32>) -> vec4<f32> {
 }
 #endif
 
+#ifdef PREMULTIPLY_ALPHA
+fn premultiply_alpha(standard_material_flags: u32, color: vec4<f32>) -> vec4<f32> {
+// `Blend`, `Premultiplied` and `Alpha` all share the same `BlendState`. Depending
+// on the alpha mode, we premultiply the color channels by the alpha channel value,
+// (and also optionally replace the alpha value with 0.0) so that the result produces
+// the desired blend mode when sent to the blending operation.
+#ifdef BLEND_PREMULTIPLIED_ALPHA
+    // For `BlendState::PREMULTIPLIED_ALPHA_BLENDING` the blend function is:
+    //
+    //     result = 1 * src_color + (1 - src_alpha) * dst_color
+    let alpha_mode = standard_material_flags & STANDARD_MATERIAL_FLAGS_ALPHA_MODE_RESERVED_BITS;
+    if (alpha_mode == STANDARD_MATERIAL_FLAGS_ALPHA_MODE_BLEND) {
+        // Here, we premultiply `src_color` by `src_alpha` (ahead of time, here in the shader)
+        //
+        //     src_color *= src_alpha
+        //
+        // We end up with:
+        //
+        //     result = 1 * (src_alpha * src_color) + (1 - src_alpha) * dst_color
+        //     result = src_alpha * src_color + (1 - src_alpha) * dst_color
+        //
+        // Which is the blend operation for regular alpha blending `BlendState::ALPHA_BLENDING`
+        return vec4<f32>(color.rgb * color.a, color.a);
+    } if (alpha_mode == STANDARD_MATERIAL_FLAGS_ALPHA_MODE_ADD) {
+        // Here, we premultiply `src_color` by `src_alpha`, and replace `src_alpha` with 0.0:
+        //
+        //     src_color *= src_alpha
+        //     src_alpha = 0.0
+        //
+        // We end up with:
+        //
+        //     result = 1 * (src_alpha * src_color) + (1 - 0) * dst_color
+        //     result = src_alpha * src_color + 1 * dst_color
+        //
+        // Which is the blend operation for additive blending
+        return vec4<f32>(color.rgb * color.a, 0.0);
+    } else {
+        // Here, we don't do anything, so that we get premultiplied alpha blending. (As expected)
+        return color.rgba;
+    }
+#endif
+// `Multiply` uses its own `BlendState`, but we still need to premultiply here in the
+// shader so that we get correct results as we tweak the alpha channel
+#ifdef BLEND_MULTIPLY
+    // The blend function is:
+    //
+    //     result = dst_color * src_color + (1 - src_alpha) * dst_color
+    //
+    // We premultiply `src_color` by `src_alpha`:
+    //
+    //     src_color *= src_alpha
+    //
+    // We end up with:
+    //
+    //     result = dst_color * (src_color * src_alpha) + (1 - src_alpha) * dst_color
+    //     result = src_alpha * (src_color * dst_color) + (1 - src_alpha) * dst_color
+    //
+    // Which is the blend operation for multiplicative blending with arbitrary mixing
+    // controlled by the source alpha channel
+    return vec4<f32>(color.rgb * color.a, color.a);
+#endif
+}
+#endif

crates/bevy_pbr/src/render/pbr_types.wgsl

@@ -17,9 +17,13 @@ let STANDARD_MATERIAL_FLAGS_METALLIC_ROUGHNESS_TEXTURE_BIT: u32 = 4u;
 let STANDARD_MATERIAL_FLAGS_OCCLUSION_TEXTURE_BIT: u32          = 8u;
 let STANDARD_MATERIAL_FLAGS_DOUBLE_SIDED_BIT: u32               = 16u;
 let STANDARD_MATERIAL_FLAGS_UNLIT_BIT: u32                      = 32u;
-let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_OPAQUE: u32              = 64u;
-let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_MASK: u32                = 128u;
-let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_BLEND: u32               = 256u;
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_RESERVED_BITS: u32       = 448u; // (0b111 << 6)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_OPAQUE: u32              = 0u;   // (0 << 6)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_MASK: u32                = 64u;  // (1 << 6)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_BLEND: u32               = 128u; // (2 << 6)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_PREMULTIPLIED: u32       = 192u; // (3 << 6)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_ADD: u32                 = 256u; // (4 << 6)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_MULTIPLY: u32            = 320u; // (5 << 6)
 let STANDARD_MATERIAL_FLAGS_TWO_COMPONENT_NORMAL_MAP: u32       = 512u;
 let STANDARD_MATERIAL_FLAGS_FLIP_NORMAL_MAP_Y: u32              = 1024u;