Enum Layer 

#[non_exhaustive]
pub enum Layer {
    World,
    Hud,
    Overlay,
    Debug,
}

A named z-order tier for Surface::on_tier, covering the split most apps with overlapping UI actually need.

Layers are how overlapping UI avoids depending on draw order: a caller who paints a dropdown on Layer::Overlay gets it on top of the active screen regardless of whether the screen or the dropdown drew first this frame, so the two don’t have to agree on an ordering (contrast with painting both through the same layer, where whichever call happens to run last wins).

Layer derives Ord over its declaration order, so Layer::World < Layer::Hud < Layer::Overlay < Layer::Debug holds without spelling out the underlying grid layer ids – the same relationship Surface::on_tier relies on to keep Layer::Debug the top-most tier no matter what else is open.

This is a convention, not a restriction: Surface::on_layer still accepts any u8, and a tile map or sprite-heavy app with its own multi-layer scheme (terrain/items/actors/…) has no reason to route through Layer at all. Layer exists for the overlapping-UI case: chrome, popups, debug HUDs, where a small, shared, named split is worth more than 256 open numeric ids.

Examples

A persistent HUD bar and a dropdown that must paint over it, in either order, because they’re on different tiers rather than racing to draw last:

use retroglyph_core::color::Style;
use retroglyph_core::grid::{Grid, Rect};
use retroglyph_core::surface::{Layer, Surface};

let area = Rect::new(0, 0, 20, 5);
let mut grid = Grid::new(20, 5);
let mut surface = Surface::new(&mut grid, area, Layer::World.as_u8());

// The active screen draws on `World`.
surface.print((0, 0), "screen content", Style::default());

// Chrome draws on `Hud`, above the screen.
surface.on_tier(Layer::Hud).print((0, 0), "File  Edit  View", Style::default());

// A dropdown draws on `Overlay`, above the HUD: painting it before or after the two calls
// above makes no difference, because it's on a higher tier, not drawn later.
surface.on_tier(Layer::Overlay).print((0, 1), "New", Style::default());

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.

World

The active screen: terrain, entities, game/app content. Grid layer 0.

Hud

Persistent chrome: menu bars, status lines, HUD. Grid layer 1.

Overlay

Popups, dropdowns, modals, painted over Layer::World and Layer::Hud regardless of draw order. Grid layer 2.

Debug

Debug and dev tooling. Always the top-most tier, so it stays visible over an open Layer::Overlay rather than being hidden underneath one. Grid layer 3.

retroglyph-ui’ PerfOverlayApp default layer is defined as Layer::Debug.as_u8() for exactly this reason: a perf HUD that a popup could paint over would be useless whenever an app actually has a popup open.

Implementations

impl Layer

pub const fn as_u8(self) -> u8

This tier’s underlying grid layer id, for Surface::on_layer/Grid APIs that take a raw u8.

Trait Implementations

impl Clone for Layer

fn clone(&self) -> Layer

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Layer

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

Formats the value using the given formatter.

impl Default for Layer

fn default() -> Layer

Returns the “default value” for a type.

impl Hash for Layer

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Layer

fn cmp(&self, other: &Layer) -> 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 Layer

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Layer

fn partial_cmp(&self, other: &Layer) -> 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 Copy for Layer

impl Eq for Layer

impl StructuralPartialEq for Layer