[Merged by Bors] - Allow unbatched render phases to use unstable sorts

crates/bevy_core_pipeline/Cargo.toml

@@ -28,4 +28,4 @@ bevy_transform = { path = "../bevy_transform", version = "0.8.0-dev" }
 bevy_utils = { path = "../bevy_utils", version = "0.8.0-dev" }
 
 serde = { version = "1", features = ["derive"] }
-
+radsort = "0.1"

crates/bevy_core_pipeline/src/core_2d/mod.rs

@@ -90,6 +90,11 @@ impl PhaseItem for Transparent2d {
     fn draw_function(&self) -> DrawFunctionId {
         self.draw_function
     }
+
+    #[inline]
+    fn sort(items: &mut [Self]) {
+        items.sort_by_key(|item| item.sort_key());
+    }
 }
 
 impl EntityPhaseItem for Transparent2d {

crates/bevy_core_pipeline/src/core_3d/mod.rs

@@ -98,6 +98,11 @@ impl PhaseItem for Opaque3d {
     fn draw_function(&self) -> DrawFunctionId {
         self.draw_function
     }
+
+    #[inline]
+    fn sort(items: &mut [Self]) {
+        radsort::sort_by_key(items, |item| item.distance);
+    }
 }
 
 impl EntityPhaseItem for Opaque3d {
@@ -133,6 +138,11 @@ impl PhaseItem for AlphaMask3d {
     fn draw_function(&self) -> DrawFunctionId {
         self.draw_function
     }
+
+    #[inline]
+    fn sort(items: &mut [Self]) {
+        radsort::sort_by_key(items, |item| item.distance);
+    }
 }
 
 impl EntityPhaseItem for AlphaMask3d {
@@ -168,6 +178,11 @@ impl PhaseItem for Transparent3d {
     fn draw_function(&self) -> DrawFunctionId {
         self.draw_function
     }
+
+    #[inline]
+    fn sort(items: &mut [Self]) {
+        radsort::sort_by_key(items, |item| item.distance);
+    }
 }
 
 impl EntityPhaseItem for Transparent3d {

crates/bevy_pbr/Cargo.toml

@@ -28,3 +28,4 @@ bevy_window = { path = "../bevy_window", version = "0.8.0-dev" }
 bitflags = "1.2"
 # direct dependency required for derive macro
 bytemuck = { version = "1", features = ["derive"] }
+radsort = "0.1"

crates/bevy_pbr/src/render/light.rs

@@ -1421,6 +1421,11 @@ impl PhaseItem for Shadow {
     fn draw_function(&self) -> DrawFunctionId {
         self.draw_function
     }
+
+    #[inline]
+    fn sort(items: &mut [Self]) {
+        radsort::sort_by_key(items, |item| item.distance);
+    }
 }
 
 impl EntityPhaseItem for Shadow {

crates/bevy_render/src/render_phase/draw.rs

@@ -35,13 +35,30 @@ pub trait Draw<P: PhaseItem>: Send + Sync + 'static {
 /// Afterwards it will be sorted and rendered automatically  in the
 /// [`RenderStage::PhaseSort`](crate::RenderStage::PhaseSort) stage and
 /// [`RenderStage::Render`](crate::RenderStage::Render) stage, respectively.
-pub trait PhaseItem: Send + Sync + 'static {
+pub trait PhaseItem: Sized + Send + Sync + 'static {
     /// The type used for ordering the items. The smallest values are drawn first.
     type SortKey: Ord;
     /// Determines the order in which the items are drawn during the corresponding [`RenderPhase`](super::RenderPhase).
     fn sort_key(&self) -> Self::SortKey;
     /// Specifies the [`Draw`] function used to render the item.
     fn draw_function(&self) -> DrawFunctionId;
+
+    /// Sorts a slice of phase items into render order.  Generally if the same type
+    /// implements [`BatchedPhaseItem`], this should use a stable sort like [`slice::sort_by_key`].
+    /// In almost all other cases, this should not be altered from the default,
+    /// which uses a unstable sort, as this provides the best balance of CPU and GPU
+    /// performance.
+    ///
+    /// Implementers can optionally not sort the list at all. This is generally advisable if and
+    /// only if the renderer supports a depth prepass, which is by default not supported by
+    /// the rest of Bevy's first party rendering crates. Even then, this may have a negative
+    /// impact on GPU-side performance due to overdraw.
+    ///
+    /// It's advised to always profile for performance changes when changing this implementation.
+    #[inline]
+    fn sort(items: &mut [Self]) {
+        items.sort_unstable_by_key(|item| item.sort_key());
+    }
 }
 
 // TODO: make this generic?
@@ -170,6 +187,9 @@ pub trait CachedRenderPipelinePhaseItem: PhaseItem {
 ///
 /// Batching is an optimization that regroups multiple items in the same vertex buffer
 /// to render them in a single draw call.
+///
+/// If this is implemented on a type, the implementation of [`PhaseItem::sort`] should
+/// be changed to implement a stable sort, or incorrect/suboptimal batching may result.
 pub trait BatchedPhaseItem: EntityPhaseItem {
     /// Range in the vertex buffer of this item
     fn batch_range(&self) -> &Option<Range<u32>>;

crates/bevy_render/src/render_phase/mod.rs

@@ -29,7 +29,7 @@ impl<I: PhaseItem> RenderPhase<I> {
 
     /// Sorts all of its [`PhaseItems`](PhaseItem).
     pub fn sort(&mut self) {
-        self.items.sort_by_key(|d| d.sort_key());
+        I::sort(&mut self.items);
     }
 }