Trait SortedPhaseItem

pub trait SortedPhaseItem: PhaseItem {
    type SortKey: Ord;

    // Required methods
    fn sort_key(&self) -> Self::SortKey;
    fn indexed(&self) -> bool;

    // Provided method
    fn sort(items: &mut [Self]) { ... }
}

Represents phase items that must be sorted. The SortKey specifies the order that these items are drawn in. These are placed into a single array, and the array as a whole is then sorted.

An example of a sorted phase item is Transparent3d, which must be sorted back to front in order to correctly render with the painter’s algorithm.

Required Associated Types

type SortKey: Ord

The type used for ordering the items. The smallest values are drawn first. This order can be calculated using the ViewRangefinder3d, based on the view-space Z value of the corresponding view matrix.

Required Methods

fn sort_key(&self) -> Self::SortKey

Determines the order in which the items are drawn.

fn indexed(&self) -> bool

Whether this phase item targets indexed meshes (those with both vertex and index buffers as opposed to just vertex buffers).

Bevy needs this information in order to properly group phase items together for multi-draw indirect, because the GPU layout of indirect commands differs between indexed and non-indexed meshes.

If you’re implementing a custom phase item that doesn’t describe a mesh, you can safely return false here.

Provided Methods

fn sort(items: &mut [Self])

Sorts a slice of phase items into render order. Generally if the same type is batched 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 an 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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors