Enum SceneLayer 

#[non_exhaustive]
pub enum SceneLayer {
    Under,
    Interleaved,
    Over,
}

Which paint band a lightweight SceneItem sits in, relative to the heavyweight widget tier.

The band is the leading digit of PaintKey, so it decides both what is drawn on top and what the pointer picks — one rule, not two.

band	rank	where it paints
Under	RANK_UNDER	in SceneView::paint, a backdrop beneath every card
Interleaved	RANK_WIDGET	among the cards, ordered against them by z
Over	RANK_OVER	in SceneView::post_paint, above every card

Within a band, set_z orders items among themselves; in Interleaved that same z is compared against the cards’ z.

What Interleaved orders against, and what it does not

Cards, and only cards — the heavyweight widget children, which are what the arena’s child walk contains. It is not an ordering against the other two bands, and in particular not against Under: the whole of the Under band is painted inside SceneView::paint, which runs before the first child, so every Under item is below every interleaved one no matter what the two zs say. Likewise every Over item is above every interleaved one.

The consequence worth stating outright, because it surprises: in a scene with no heavyweight children at all, an interleaved item is on top of everything. There is nothing in the child walk for it to sit between, and its z is compared against an empty set. A lightweight-only page that wants ink under some of its content wants Under plus a z, or wants the content it is drawing on to be cards.

Why Interleaved is not free

Under and Over cost nothing: the render walker offers a paint position before and after a node’s child subtree, and those are the two bands. There is no third position between two children, so an interleaved item is painted by a node of its own that the view materialises and slots into the z-sorted child list.

That node is paint only. It is event_pass_through, so the pointer still resolves through the lightweight hit snapshot exactly as it does for the other two bands, and it is left out of SceneView::accessibility_children, so the item keeps the same synthetic SyntheticKind::SceneItem node it had in Under — same off-screen culling, same reparenting, same rotor category. Choosing this band changes what the item is painted between and nothing else.

What it does cost is one arena node per interleaved item. Ink is the case this exists for (“this stroke is above note A and below note B”), and a page of ink wants a GroupItem per layer rather than a band per stroke — see docs/ink.md.

#[non_exhaustive]: this enum has now grown a variant once, and the reason it could is that the render walker’s two paint positions were never the whole answer. A downstream match gets a _ arm today rather than a break the next time.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Under

Painted under the heavyweight widget children (the default).

Interleaved

Painted among the heavyweight widget children, ordered against them by z — and against nothing else: still above every Under item and below every Over one, and on top of everything in a scene that has no heavyweight children. See the type docs for that and for what it costs.

Over

Painted over the heavyweight widget children.

Trait Implementations

impl Clone for SceneLayer

fn clone(&self) -> SceneLayer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for SceneLayer

impl Debug for SceneLayer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SceneLayer

fn default() -> SceneLayer

Returns the “default value” for a type.

impl Eq for SceneLayer

impl PartialEq for SceneLayer

fn eq(&self, other: &SceneLayer) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for SceneLayer