[ickshonpe]

Objective

Replace the hardcodf32 z-offsets that we add to the stack index to order each element with local named Z layers that can be ordered relative to each other.

Related issues (doesn't exactly solve) #1275, #24564.

Solution

Add paint layers to bevy_ui_render.

The PaintOrder resource holds the list of paint layers, in the order they’re drawn from back to front..

The built-in layers are identified by the NodePaintLayer enum:

pub enum NodePaintLayer {
    BoxShadow,
    BackgroundColor,
    Border,
    Gradient,
    BorderGradient,
    Image,
    Material,
    TextSelection,
    Text,
    TextStrikethrough,
    TextCursor,
    InlineImage,
}

UiRenderPlugin initializes PaintOrder with all the builtin layers in the correct order.

Custom layers

To create a new PaintLayer, you derive PaintLayer:

#[derive(Debug, Hash, PartialEq, Eq, Clone, Copy, PaintLayer)]
pub struct MyPaintLayer;

Or you can define multiple layers at once with an enum:

#[derive(Debug, Hash, PartialEq, Eq, Clone, Copy, PaintLayer)]
pub enum MyPaintLayers {
    Back,
    Middle,
    Front,
}

Ordering

• insert_before_layer / insert_after_layer place a layer directly below or above an existing layer.
• insert_top / insert_bottom place a layer above or below all the other layers.
• remove_layer removes a layer. A built-in element whose layer is removed isn't drawn.

The insert methods move the layer if it's already present.

The UiMaterial trait has a new paint_layer() method that chooses the layer the layer the material is drawn to.
It defaults to NodePaintLayer::Material.

PaintOrder just newtypes an IndexSet, so you can also use the IndexSet methods to reorder it arbitrarily.

Extraction

Extraction functions should look up the z-offsets for their elements layer with PaintOrder::get_offset, which returns a value in the range 0.0..1.0. The z-offset should be looked up once at the start of the extraction function, and shouldn't be looked up per node if at all possible.

The PaintOrder resource is also extracted separately, so the offsets can be applied in some queue functions instead for some elements. This is because extraction isn't as centralized as it should be.

Changing PaintOrder at all is expensive as it triggers a reextraction of all elements.

Implementation

• The paint_layers module contains all the new functionality.

• The proc macro for the PaintLayer label derive is in a new rendlayers/macros subscrate. It's adapted from bevy_render's macros crate.

• The paint order is global. There's no builtin support for reordering painting per node.

Testing

The UI testbed shouldn't exhibit any changes:

cargo run --example testbed_ui

There are some tests for PaintOrder in the paint_layers module.

AI Disclosure

I used claude to work out some errors with the macro crate to get the imports and paths right so it would compile, and write most of the paint_layers tests.

[ickshonpe]

Closed by accident.