Struct PaintKey 

pub struct PaintKey { /* private fields */ }

Where an entry sits in a SceneView’s single paint order.

rank	contents
RANK_UNDER	lightweight items in SceneLayer::Under
RANK_WIDGET	heavyweight widget entries, and lightweight items in SceneLayer::Interleaved
RANK_OVER	lightweight items in SceneLayer::Over

Within a rank, ascending z; ties broken by seq, the entry’s ItemId — which is a process-monotone counter, so ties resolve in insertion order. A higher key paints later, is therefore on top, and therefore wins the pointer.

SceneLayer is not a separate concept any more: it is the leading digit of this key.

Why the tie-break is load-bearing

Paint sorts ascending and stably over an id-ordered candidate list, so the newest of two equal-z items paints last and is on top. The hit snapshots used to sort descending and stably over that same ascending list, which leaves equal-z ties in ascending order — so the first match was the oldest, i.e. the bottom-most, item. Paint and hit were exactly inverted on ties. Comparing whole keys fixes that by construction: a descending sort on (rank, z, seq) really does put the topmost entry first.

NaN

A non-finite z is normalised to 0.0 at construction, so the ordering is total and sort_by is not order-dependent. The old sites compared with partial_cmp(..).unwrap_or(Equal), which is not a total order.

Implementations

impl PaintKey

pub fn new(rank: u8, z: f32, seq: u64) -> Self

Build a key. z is normalised (NaN → 0.0) so the ordering is total.

pub const fn rank(self) -> u8

The tier / band digit — one of RANK_UNDER, RANK_WIDGET, RANK_OVER.

pub const fn z(self) -> f32

The entry’s z-order within its rank.

pub const fn seq(self) -> u64

The insertion tie-break — the entry’s ItemId as a number.

Stable only as long as the id is. A SceneListAdapter re-mints ids on a structural DataChange, so equal-z ordering inside an adapter-owned run does shuffle on an append. That is a property of the adapter, not a guarantee this key makes.

pub const fn is_above_widgets(self) -> bool

True when this key can never lose to a heavyweight entry.

pub const fn bottom() -> Self

A floor below every real key — “admit everything”.

z is -inf rather than a finite sentinel so that a real entry sitting at f32::MIN is still admitted, and Ord compares z with total_cmp, under which -inf is below every finite value.

pub const fn rank_floor(rank: u8) -> Self

A floor admitting exactly the entries at rank and above.

The coarse form of a floor, and the one the dispatch path uses: “a card won the arena’s walk, so only the band that outranks every card may still take this event”. The fine form — one specific entry’s key — is what the accepts_child_hit veto needs, because an Interleaved entry is above some cards and below others.

Trait Implementations

impl Clone for PaintKey

fn clone(&self) -> PaintKey

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for PaintKey

impl Debug for PaintKey

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

Formats the value using the given formatter.

impl Eq for PaintKey

impl Ord for PaintKey

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for PaintKey

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for PaintKey

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for PaintKey