From 1d5145fd64679544ea730565860d8e8e589322a5 Mon Sep 17 00:00:00 2001
From: Robert Bragg <robert@sixbynine.org>
Date: Sat, 5 Mar 2022 03:37:23 +0000
Subject: [PATCH] StandardMaterial: expose a cull_mode option (#3982)

This makes it possible for materials to configure front or
back face culling, or disable culling.

Initially I looked at specializing the Mesh which currently
controls this state but conceptually it seems more appropriate
to control this at the material level, not the mesh level.

_Just for reference this also seems to be consistent with Unity
where materials/shaders can configure the culling mode between
front/back/off - as opposed to configuring any culling state
when importing a mesh._

After some archaeology, trying to understand how this might
relate to the existing 'double_sided' option, it was determined
that double_sided is a more high level lighting option originally
from Filament that will cause the normals for back faces to be
flipped.

For sake of avoiding complexity, but keeping control this
currently keeps the options orthogonal, and adds some clarifying
documentation for `double_sided`. This won't affect any existing
apps since there hasn't been a way to disable backface culling
up until now, so the option was essentially redundant.

double_sided support could potentially be updated to imply
disabling of backface culling.

For reference https://github.com/bevyengine/bevy/pull/3734/commits also looks at exposing cull mode control. I think the main difference here is that this patch handles RenderPipelineDescriptor specialization directly within the StandardMaterial implementation instead of communicating info back to the Mesh via the `queue_material_meshes` system.

With the way material.rs builds up the final RenderPipelineDescriptor first by calling specialize for the MeshPipeline followed by specialize for the material then it seems like we have a natural place to override anything in the descriptor that's first configured for the mesh state.
---
 crates/bevy_pbr/src/pbr_material.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/crates/bevy_pbr/src/pbr_material.rs b/crates/bevy_pbr/src/pbr_material.rs
index eaf45397a78a4..803960a647844 100644
--- a/crates/bevy_pbr/src/pbr_material.rs
+++ b/crates/bevy_pbr/src/pbr_material.rs
@@ -48,7 +48,15 @@ pub struct StandardMaterial {
     pub reflectance: f32,
     pub normal_map_texture: Option<Handle<Image>>,
     pub occlusion_texture: Option<Handle<Image>>,
+    /// Support two-sided lighting by automatically flipping the normals for "back" faces
+    /// within the PBR lighting shader.
+    /// Defaults to false.
+    /// This does not automatically configure backface culling, which can be done via
+    /// `cull_mode`.
     pub double_sided: bool,
+    /// Whether to cull the "front", "back" or neither side of a mesh
+    /// defaults to `Face::Back`
+    pub cull_mode: Option<Face>,
     pub unlit: bool,
     pub alpha_mode: AlphaMode,
 }
@@ -77,6 +85,7 @@ impl Default for StandardMaterial {
             occlusion_texture: None,
             normal_map_texture: None,
             double_sided: false,
+            cull_mode: Some(Face::Back),
             unlit: false,
             alpha_mode: AlphaMode::Opaque,
         }
@@ -154,6 +163,7 @@ pub struct GpuStandardMaterial {
     pub flags: StandardMaterialFlags,
     pub base_color_texture: Option<Handle<Image>>,
     pub alpha_mode: AlphaMode,
+    pub cull_mode: Option<Face>,
 }
 
 impl RenderAsset for StandardMaterial {
@@ -321,6 +331,7 @@ impl RenderAsset for StandardMaterial {
             has_normal_map,
             base_color_texture: material.base_color_texture,
             alpha_mode: material.alpha_mode,
+            cull_mode: material.cull_mode,
         })
     }
 }
@@ -328,6 +339,7 @@ impl RenderAsset for StandardMaterial {
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub struct StandardMaterialKey {
     normal_map: bool,
+    cull_mode: Option<Face>,
 }
 
 impl SpecializedMaterial for StandardMaterial {
@@ -336,6 +348,7 @@ impl SpecializedMaterial for StandardMaterial {
     fn key(render_asset: &<Self as RenderAsset>::PreparedAsset) -> Self::Key {
         StandardMaterialKey {
             normal_map: render_asset.has_normal_map,
+            cull_mode: render_asset.cull_mode,
         }
     }
 
@@ -352,6 +365,7 @@ impl SpecializedMaterial for StandardMaterial {
                 .shader_defs
                 .push(String::from("STANDARDMATERIAL_NORMAL_MAP"));
         }
+        descriptor.primitive.cull_mode = key.cull_mode;
         if let Some(label) = &mut descriptor.label {
             *label = format!("pbr_{}", *label).into();
         }