Standard Material Blend Modes (#6644)

# Objective

- This PR adds support for blend modes to the PBR `StandardMaterial`.

<img width="1392" alt="Screenshot 2022-11-18 at 20 00 56" src="https://user-images.githubusercontent.com/418473/202820627-0636219a-a1e5-437a-b08b-b08c6856bf9c.png">

<img width="1392" alt="Screenshot 2022-11-18 at 20 01 01" src="https://user-images.githubusercontent.com/418473/202820615-c8d43301-9a57-49c4-bd21-4ae343c3e9ec.png">

## Solution

- The existing `AlphaMode` enum is extended, adding three more modes: `AlphaMode::Premultiplied`, `AlphaMode::Add` and `AlphaMode::Multiply`;
- All new modes are rendered in the existing `Transparent3d` phase;
- The existing mesh flags for alpha mode are reorganized for a more compact/efficient representation, and new values are added;
- `MeshPipelineKey::TRANSPARENT_MAIN_PASS` is refactored into `MeshPipelineKey::BLEND_BITS`.
  -  `AlphaMode::Opaque` and `AlphaMode::Mask(f32)` share a single opaque pipeline key: `MeshPipelineKey::BLEND_OPAQUE`;
  - `Blend`, `Premultiplied` and `Add` share a single premultiplied alpha pipeline key, `MeshPipelineKey::BLEND_PREMULTIPLIED_ALPHA`. In the shader, color values are premultiplied accordingly (or not) depending on the blend mode to produce the three different results after PBR/tone mapping/dithering;
  - `Multiply` uses its own independent pipeline key, `MeshPipelineKey::BLEND_MULTIPLY`;
- Example and documentation are provided.
---

## Changelog

### Added

- Added support for additive and multiplicative blend modes in the PBR `StandardMaterial`, via `AlphaMode::Add` and `AlphaMode::Multiply`;
- Added support for premultiplied alpha in the PBR `StandardMaterial`, via `AlphaMode::Premultiplied`;

Cargo.toml

@@ -297,6 +297,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 otherwise constant 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 a
+    /// 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

@@ -415,8 +415,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(
@@ -455,7 +461,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

@@ -298,16 +298,25 @@ 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 TWO_COMPONENT_NORMAL_MAP   = (1 << 9);
-        const FLIP_NORMAL_MAP_Y          = (1 << 10);
+        const TWO_COMPONENT_NORMAL_MAP   = (1 << 6);
+        const FLIP_NORMAL_MAP_Y          = (1 << 7);
+        const ALPHA_MODE_RESERVED_BITS   = (Self::ALPHA_MODE_MASK_BITS << Self::ALPHA_MODE_SHIFT_BITS); // ← Bitmask reserving bits for the `AlphaMode`
+        const ALPHA_MODE_OPAQUE          = (0 << Self::ALPHA_MODE_SHIFT_BITS);                          // ← Values are just sequential values bitshifted into
+        const ALPHA_MODE_MASK            = (1 << Self::ALPHA_MODE_SHIFT_BITS);                          //   the bitmask, and can range from 0 to 7.
+        const ALPHA_MODE_BLEND           = (2 << Self::ALPHA_MODE_SHIFT_BITS);                          //
+        const ALPHA_MODE_PREMULTIPLIED   = (3 << Self::ALPHA_MODE_SHIFT_BITS);                          //
+        const ALPHA_MODE_ADD             = (4 << Self::ALPHA_MODE_SHIFT_BITS);                          //   Right now only values 0–5 are used, which still gives
+        const ALPHA_MODE_MULTIPLY        = (5 << Self::ALPHA_MODE_SHIFT_BITS);                          // ← us "room" for two more modes without adding more bits
         const NONE                       = 0;
         const UNINITIALIZED              = 0xFFFF;
     }
 }
 
+impl StandardMaterialFlags {
+    const ALPHA_MODE_MASK_BITS: u32 = 0b111;
+    const ALPHA_MODE_SHIFT_BITS: u32 = 32 - Self::ALPHA_MODE_MASK_BITS.count_ones();
+}
+
 /// The GPU representation of the uniform data of a [`StandardMaterial`].
 #[derive(Clone, Default, ShaderType)]
 pub struct StandardMaterialUniform {
@@ -380,6 +389,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/prepass/mod.rs

@@ -527,7 +527,10 @@ pub fn queue_prepass_material_meshes<M: Material>(
             match alpha_mode {
                 AlphaMode::Opaque => {}
                 AlphaMode::Mask(_) => mesh_key |= MeshPipelineKey::ALPHA_MASK,
-                AlphaMode::Blend => continue,
+                AlphaMode::Blend
+                | AlphaMode::Premultiplied
+                | AlphaMode::Add
+                | AlphaMode::Multiply => continue,
             }
 
             let pipeline_id = pipelines.specialize(
@@ -566,7 +569,10 @@ pub fn queue_prepass_material_meshes<M: Material>(
                         distance,
                     });
                 }
-                AlphaMode::Blend => {}
+                AlphaMode::Blend
+                | AlphaMode::Premultiplied
+                | AlphaMode::Add
+                | AlphaMode::Multiply => {}
             }
         }
     }

crates/bevy_pbr/src/render/mesh.rs

@@ -557,13 +557,16 @@ 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 DEPTH_PREPASS               = (1 << 4);
-        const NORMAL_PREPASS              = (1 << 5);
-        const ALPHA_MASK                  = (1 << 6);
+        const HDR                         = (1 << 0);
+        const TONEMAP_IN_SHADER           = (1 << 1);
+        const DEBAND_DITHER               = (1 << 2);
+        const DEPTH_PREPASS               = (1 << 3);
+        const NORMAL_PREPASS              = (1 << 4);
+        const ALPHA_MASK                  = (1 << 5);
+        const BLEND_RESERVED_BITS         = Self::BLEND_MASK_BITS << Self::BLEND_SHIFT_BITS; // ← Bitmask reserving bits for the blend state
+        const BLEND_OPAQUE                = (0 << Self::BLEND_SHIFT_BITS);                   // ← Values are just sequential within the mask, and can range from 0 to 3
+        const BLEND_PREMULTIPLIED_ALPHA   = (1 << Self::BLEND_SHIFT_BITS);                   //
+        const BLEND_MULTIPLY              = (2 << Self::BLEND_SHIFT_BITS);                   // ← We still have room for one more value without adding more bits
         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;
     }
@@ -573,7 +576,11 @@ impl MeshPipelineKey {
     const MSAA_MASK_BITS: u32 = 0b111;
     const MSAA_SHIFT_BITS: u32 = 32 - Self::MSAA_MASK_BITS.count_ones();
     const PRIMITIVE_TOPOLOGY_MASK_BITS: u32 = 0b111;
-    const PRIMITIVE_TOPOLOGY_SHIFT_BITS: u32 = Self::MSAA_SHIFT_BITS - 3;
+    const PRIMITIVE_TOPOLOGY_SHIFT_BITS: u32 =
+        Self::MSAA_SHIFT_BITS - Self::PRIMITIVE_TOPOLOGY_MASK_BITS.count_ones();
+    const BLEND_MASK_BITS: u32 = 0b11;
+    const BLEND_SHIFT_BITS: u32 =
+        Self::PRIMITIVE_TOPOLOGY_SHIFT_BITS - Self::BLEND_MASK_BITS.count_ones();
 
     pub fn from_msaa_samples(msaa_samples: u32) -> Self {
         let msaa_bits =
@@ -677,12 +684,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".into());
+            shader_defs.push("BLEND_PREMULTIPLIED_ALPHA".into());
             // 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".into());
+            shader_defs.push("BLEND_MULTIPLY".into());
+            // 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

@@ -106,6 +106,9 @@ fn fragment(in: FragmentInput) -> @location(0) vec4<f32> {
     // SRGB; the GPU will assume our output is linear and will apply an SRGB conversion.
     output_rgb = pow(output_rgb, vec3<f32>(2.2));
     output_color = vec4(output_rgb, output_color.a);
+#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 // DEBAND_DITHER
 
+#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);
+    } else 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,11 +17,17 @@ 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_TWO_COMPONENT_NORMAL_MAP: u32       = 512u;
-let STANDARD_MATERIAL_FLAGS_FLIP_NORMAL_MAP_Y: u32              = 1024u;
+let STANDARD_MATERIAL_FLAGS_TWO_COMPONENT_NORMAL_MAP: u32       = 64u;
+let STANDARD_MATERIAL_FLAGS_FLIP_NORMAL_MAP_Y: u32              = 128u;
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_RESERVED_BITS: u32       = 3758096384u; // (0b111u32 << 29)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_OPAQUE: u32              = 0u;          // (0u32 << 29)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_MASK: u32                = 536870912u;  // (1u32 << 29)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_BLEND: u32               = 1073741824u; // (2u32 << 29)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_PREMULTIPLIED: u32       = 1610612736u; // (3u32 << 29)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_ADD: u32                 = 2147483648u; // (4u32 << 29)
+let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_MULTIPLY: u32            = 2684354560u; // (5u32 << 29)
+// ↑ To calculate/verify the values above, use the following playground:
+// https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=7792f8dd6fc6a8d4d0b6b1776898a7f4
 
 // Creates a StandardMaterial with default values
 fn standard_material_new() -> StandardMaterial {