Struct Color 

#[repr(C)]
pub struct Color {
    pub red: f32,
    pub green: f32,
    pub blue: f32,
    pub alpha: f32,
}

A red, green, blue, and opacity color, each a linear value the engine encodes to sRGB on its way to the window.

Nothing clamps a channel: a value past 1.0 is light the frame holds and the tone map brings down, which is what an emissive material or a bright light is written with. 0.0..=1.0 is what the window can show.

Values are linear; the engine writes sRGB-encoded values to the screen. A color channel past 1.0 holds light no screen draws, which FrameContext::set_bloom spreads.

Fields

red: f32

Red.

green: f32

Green.

blue: f32

Blue.

alpha: f32

Opacity: 1.0 is fully opaque, 0.0 is empty.

Implementations

impl Color

pub const BLACK: Self

Opaque black.

pub const WHITE: Self

Opaque white.

pub const fn rgb(red: f32, green: f32, blue: f32) -> Self

An opaque color, each channel a fraction of 1.0.

Examples found in repository

examples/post-effects.rs (line 15)

const GLOW_COLOR: Color = Color::rgb(4.0, 2.2, 0.6);

/// A sphere either side of the glowing cube, and its radius.
const SPHERE_POSITIONS: [Vec3; 2] = [Vec3::new(-1.6, 0.5, 0.4), Vec3::new(1.6, 0.5, -0.4)];
const SPHERE_SUBDIVISIONS: u32 = 3;

const SUN_DIRECTION: Vec3 = Vec3::new(0.5, -1.0, -0.3);
const SUN_COLOR: Color = Color::rgb(0.85, 0.8, 0.7);

const GROUND_COLOR: Color = Color::rgb(0.16, 0.17, 0.15);
const SPHERE_COLOR: Color = Color::rgb(0.5, 0.52, 0.55);

examples/sprite-adventure.rs (line 261)

const SUN_COLOR: Color = Color::rgb(0.92, 0.87, 0.72);
/// The sun's direction: low enough that props cast shadows about their own
/// length, and from over the player's left shoulder, which is where the
/// tileset's own sprites are shaded from.
const SUN_DIRECTION: Vec3 = Vec3::new(0.6, -0.75, 0.4);

// ---------------------------------------------------------------------
// Cave layout
// ---------------------------------------------------------------------

const CAVE_HALF_WIDTH: f32 = 4.0;
/// Room tiling and walls toward the camera, past the wall closing it: under
/// the bottom corners of the frame, wherever the player walks.
const CAVE_NEAR_Z: f32 = 10.0;
const CAVE_FAR_Z: f32 = -6.0;
/// Walkable extent of the room at its far end: the back wall's inner face,
/// less the player's own half-width, so the sprite stops flush against
/// stone.
const CAVE_WALK_FAR_Z: f32 = CAVE_FAR_Z + TILE_SIZE * 0.5 + WALKER_WIDTH * 0.5;
/// Walkable extent at the room's near end: past the plane stepping out
/// crosses, so the last step through the mouth is never clamped away. The
/// near wall itself is what keeps the player from the ledge beyond.
const CAVE_WALK_NEAR_Z: f32 = CAVE_EXIT.z + PLAYER_RADIUS;
/// As many meters as the wall face is tiles tall, so it samples the sheet
/// at the floor's own texels to the meter.
const WALL_HEIGHT: f32 = 3.0;
/// Wall height: over the camera, so it neither looks over them nor down onto
/// their tops.
const WALL_TOP: f32 = CAVE_CAMERA_OFFSET.y + TILE_SIZE * 0.5;
/// Courses that takes; the last one is cut to what is left of it.
const WALL_COURSES: i32 = (WALL_TOP / WALL_HEIGHT) as i32 + 1;
/// The tile row the room's near end is closed along, from each side wall to
/// the mouth in it.
const CAVE_LIP_Z: f32 = 5.0;
/// Height of that wall: one tile, so its top face is at the floor's own
/// texels to the meter, and low enough that it never hides the player.
const CAVE_LIP_HEIGHT: f32 = TILE_SIZE;
/// The cave's own mouth position: in the near wall, its pillars half their
/// depth past it.
const CAVE_EXIT: Vec3 = Vec3::new(0.0, 0.0, CAVE_LIP_Z + MOUTH_PILLAR_SIZE.z * 0.5);
/// Landing position for an entry into the cave: past the [`EXIT`] band, so
/// the entry does not count as another step through the mouth.
const CAVE_SPAWN: Vec3 = Vec3::new(
    CAVE_EXIT.x,
    0.0,
    CAVE_EXIT.z - MOUTH_CROSSING_INSET - PORTAL_CLEARANCE,
);

const DOOR_Z: f32 = 0.0;
/// The near face of the wall the door hangs in: past it the wall is
/// between the camera and the player, and is drawn through.
const DOOR_WALL_NEAR_Z: f32 = DOOR_Z + TILE_SIZE * 0.5;
/// Alpha for that wall and its door once the player has been behind them
/// for [`GHOST_RAMP_TICKS`]: opaque enough for stone in a dark room,
/// translucent enough for the chamber and the player to show through.
const GHOST_ALPHA: f32 = 0.6;
/// The fade of a draw nothing is seen through.
const SOLID: f32 = 1.0;
/// Ticks the wall and door take to fade between [`SOLID`] and
/// [`GHOST_ALPHA`].
const GHOST_RAMP_TICKS: u32 = 6;
/// Span either side of the player the wall is drawn through: wide enough for
/// the sight line to the player, no wider, so no more of the light the
/// stone holds off the chamber passes through it than that line needs.
const GHOST_CORRIDOR_HALF: f32 = 1.5;
/// The door's hinge: `tools/keep_fixture.py`'s box is hinged at its own
/// local origin and spans [`DOOR_WIDTH`] along local `+X`.
const DOOR_HINGE: Vec3 = Vec3::new(-DOOR_WIDTH * 0.5, 0.0, DOOR_Z);
/// Width of that box, as the fixture builds it.
const DOOR_WIDTH: f32 = 1.0;
/// Thickness of it, as the fixture builds it.
const DOOR_THICKNESS: f32 = 0.12;
/// Height of it, as the fixture builds it: the stone over the doorway starts
/// here.
const DOOR_HEIGHT: f32 = 1.9;
/// Half the doorway the door hangs in: one tile wide, on the room's axis.
const DOORWAY_HALF: f32 = TILE_SIZE * 0.5;
/// Span from that axis of the wall the door hangs in: to the side walls'
/// inner faces.
const DOOR_WALL_END: f32 = CAVE_HALF_WIDTH + TILE_SIZE * 0.5;
const INTERACT_POINT: Vec3 = Vec3::new(0.0, 0.0, DOOR_Z);
const INTERACT_RADIUS: f32 = 1.8;

/// The door slab's own color, a deep red the cave's grey stone never is, so
/// the slab reads as a door rather than more wall.
const DOOR_COLOR: Color = Color::rgb(0.58, 0.16, 0.09);
const DOOR_LITNESS: f32 = 0.85;
/// Thickness of the posts and lintel framing the doorway, and how far in
/// front of the wall face they stand, clear of z-fighting with it.
const DOOR_FRAME_THICKNESS: f32 = 0.14;
const DOOR_FRAME_STANDOFF: f32 = 0.03;
/// The frame's own color, visible from the cave's own spawn well before a
/// torch reaches the doorway.
const DOOR_FRAME_COLOR: Color = Color::rgb(0.85, 0.55, 0.2);
const DOOR_FRAME_LITNESS: f32 = 0.9;
/// The frame's own light while the door is closed and within
/// [`INTERACT_RADIUS`]: the cue that it can be opened.
const DOOR_FRAME_GLOW: Color = Color::rgb(1.6, 0.9, 0.35);

const GEM_POSITION: Vec3 = Vec3::new(0.0, 0.5, -4.6);
const GEM_BOB_HEIGHT: f32 = 0.12;
const GEM_SPIN_SPEED: f32 = 1.4;
const PICKUP_RADIUS: f32 = 1.0;
const GEM_COLOR: Color = Color::rgb(0.35, 0.95, 0.85);
/// The gem's own light: what lights the chamber until the door opens on the
/// torches, and gone with the gem once it is taken.
const GEM_LIGHT_COLOR: Color = Color::rgb(0.3, 0.85, 0.78);
/// Reach of it: short of the door wall, so what the wall casts never depends
/// on the gem.
const GEM_LIGHT_RANGE: f32 = 4.0;
/// Lift over the gem, clear of the gem's own facets, which would otherwise
/// shadow the chamber from inside it.
const GEM_LIGHT_LIFT: f32 = 0.7;

/// The two torches' position, `x, z`: flanking the doorway on the near side
/// of the wall, the side the player arrives on.
const TORCH_POSITIONS: [(f32, f32); 2] = [(-3.0, 0.6), (3.0, 0.6)];
const TORCH_STAND_HEIGHT: f32 = 2.0;
/// Thickness of a torch's post: the four texels the sprite draws it as,
/// which is also what it blocks the player as.
const TORCH_STAND_WIDTH: f32 = 0.25;
/// Width of the sprite around that post: its canvas is twice the post,
/// transparent either side.
const TORCH_SPRITE_WIDTH: f32 = TORCH_STAND_WIDTH * 2.0;
const TORCH_LIGHT_RANGE: f32 = 10.0;
/// Height above its flame a torch's light is placed, and how far it is
/// offset from the post toward the room: straight over the post, its own face
/// turns edge-on to the light and goes dark.
const TORCH_LIGHT_LIFT: f32 = 0.7;
const TORCH_LIGHT_STANDOFF: f32 = 0.8;
const TORCH_LIGHT_COLOR: Color = Color::rgb(1.0, 0.6, 0.28);
/// Size of one cell of the flame's loop: a tile, as everything else the
/// tilesets draw.
const FLAME_SIZE: f32 = TILE_SIZE;
/// Lift of the flame's center over the post's top: its own half-height, less
/// the overlap that keeps the two from parting.
const FLAME_LIFT: f32 = FLAME_SIZE * 0.5 - 0.1;
/// The flame's tint, past `1.0`: an additive draw's tint scales its sampled
/// texel, so this lifts the flame's own lit texels out of the cave's dark
/// without a flat color added over its dark, unlit base.
const FLAME_TINT: Color = Color::rgb(2.2, 1.5, 0.7);

examples/stress-preview.rs (line 51)

const ROCK_COLOR: Color = Color::rgb(0.42, 0.4, 0.38);
const GROUND_COLOR: Color = Color::rgb(0.16, 0.17, 0.14);

const SUN_DIRECTION: Vec3 = Vec3::new(-0.35, -1.0, -0.5);
const SUN_COLOR: Color = Color::rgb(0.95, 0.92, 0.85);

/// The sky's own zenith, horizon and nadir colors, and the fraction of its
/// own light it lands on top of the sun's, held low so the sun's shadows
/// still read.
const SKY_ZENITH: Color = Color::rgb(0.25, 0.4, 0.65);
const SKY_HORIZON: Color = Color::rgb(0.75, 0.72, 0.62);
const SKY_NADIR: Color = Color::rgb(0.12, 0.12, 0.1);

examples/isometric-board.rs (line 82)

const LIGHT_TILE: Color = Color::rgb(0.80, 0.76, 0.64);
const DARK_TILE: Color = Color::rgb(0.55, 0.50, 0.40);
/// A reachable tile's own mark, smaller than the tile itself so the
/// checker tone still shows around its edge.
const REACHABLE_MARK: Color = Color::rgb(0.20, 0.85, 0.35);
/// The fraction of a tile's own footprint the reachable mark draws at,
/// small enough that the tile's own checker tone still shows around it.
const REACHABLE_MARK_SCALE: f32 = 0.45;
/// The reachable mark's own lift over the tile's surface, clear of
/// z-fighting with it.
const REACHABLE_MARK_LIFT: f32 = 0.01;
/// The mark under the selected unit, its own color bright enough to read
/// past the sprite's own tint at a distance.
const CURRENT_MARK: Color = Color::rgb(1.0, 0.2, 0.75);
const CURRENT_MARK_SCALE: f32 = 0.85;
/// The mark under the unit whose turn it is while nothing is selected:
/// smaller and dim next to [`CURRENT_MARK`], a hint rather than a claim.
const TURN_MARK: Color = Color::rgb(0.85, 0.75, 0.15);
const TURN_MARK_SCALE: f32 = 0.5;
/// The tile a hover reads while a unit is selected: reachable, or blocked
/// by the other unit standing there.
const HOVER_REACHABLE_TILE: Color = Color::rgb(0.35, 0.75, 0.68);
const HOVER_BLOCKED_TILE: Color = Color::rgb(0.62, 0.28, 0.26);
const BLOCK_IDLE: Color = Color::rgb(0.32, 0.42, 0.58);
/// `BLOCK_IDLE`, scaled toward white to mark the block unit's own turn.
const BLOCK_TURN: Color = Color::rgb(0.42, 0.54, 0.72);
const GROUND_COLOR: Color = Color::rgb(0.15, 0.16, 0.13);
const ROCK_COLOR: Color = Color::rgb(0.42, 0.40, 0.38);
const SUN_COLOR: Color = Color::rgb(0.95, 0.92, 0.85);

/// The current unit's tint, close to white so the sprite's own texture
/// still reads under it, and the light it adds on its own, low enough
/// that the same texture still reads under its bloom too — distinct from
/// `SELECTED_TINT`, so a hover and a selection never read the same.
const HOVER_TINT: Color = Color::rgb(0.9, 1.15, 1.15);
const HOVER_GLOW: Color = Color::rgb(0.02, 0.15, 0.2);

/// The current unit's tint, close to white with more red where
/// `HOVER_TINT` raises green and blue instead, so the sprite's own
/// texture still reads under it, and the light it adds on its own,
/// scaled down the same way `HOVER_GLOW` is — distinct from `HOVER_TINT`.
const SELECTED_TINT: Color = Color::rgb(1.15, 0.95, 0.85);
const SELECTED_GLOW: Color = Color::rgb(0.22, 0.11, 0.0);

/// The unit whose turn it is shows this tint and glow before any hover or
/// selection, so it reads as the one a click selects.
const TURN_TINT: Color = Color::rgb(1.0, 1.0, 0.82);
const TURN_GLOW: Color = Color::rgb(0.08, 0.08, 0.02);

/// The fraction of the frame `set_bloom` spreads, so `HOVER_GLOW` and
/// `SELECTED_GLOW` read as light around the current unit, not only a
/// larger fill.
const BLOOM: f32 = 0.35;

/// The size a world-space prompt naming a click's effect reads at, in
/// logical points.
const PROMPT_SIZE: f32 = 15.0;
/// Height a prompt is lifted over the tile it names, clear of the tile's
/// own top corner under the diagonal view.
const PROMPT_TILE_LIFT: f32 = 0.55;
/// Height a prompt is lifted over the unit it names, past its own height.
const PROMPT_UNIT_LIFT: f32 = 0.25;
/// Margin a prompt's own backdrop keeps past its galley, in logical points.
const PROMPT_PADDING: f32 = 4.0;
/// How much dark a prompt's own backdrop puts behind its text.
const PROMPT_BACKDROP: u8 = 190;
const PROMPT_TEXT_COLOR: egui::Color32 = egui::Color32::from_gray(230);

/// Thirty steps a second, half the engine's default rate; movement stays
/// smooth through `alpha()` interpolation.
const TICK_INTERVAL: Duration = Duration::from_nanos(33_333_333);

/// Faces of a cube, each a normal with its right and up axes — the same
/// layout `mesh::Cube` builds from, shared so a rock's corners hold the
/// same eight positions between the faces that meet there.
const ROCK_FACES: [(Vec3, Vec3, Vec3); 6] = [
    (Vec3::X, Vec3::NEG_Z, Vec3::Y),
    (Vec3::NEG_X, Vec3::Z, Vec3::Y),
    (Vec3::Y, Vec3::X, Vec3::NEG_Z),
    (Vec3::NEG_Y, Vec3::X, Vec3::Z),
    (Vec3::Z, Vec3::X, Vec3::Y),
    (Vec3::NEG_Z, Vec3::NEG_X, Vec3::Y),
];

const ROCK_TRIANGLES: [u32; 6] = [0, 1, 2, 0, 2, 3];

fn main() {
    run(
        Config::new("Mirage: isometric board")
            .with_size(1280, 720)
            .with_assets([SPRITE_SOURCE, CLICK_SOURCE])
            .with_tick_interval(TICK_INTERVAL),
        Board::init,
    );
}

/// A rock built for its own `seed`; each value is its own mesh.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
#[catalog(Self { seed: 0 })]
struct Rock {
    seed: u32,
}

impl Mesh for Rock {
    fn build(&self, _: &Assets) -> MeshData {
        build_rock(self.seed)
    }
}

/// The sprite unit: a quad windowed to the walk sheet's row facing right.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Sprite;

impl Mesh for Sprite {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(SPRITE_TEXTURE).pixelated())
    }
}

// Everything else this game draws: the ground and board tiles are the
// engine's own Plane and Cube, given their color per draw; the block unit
// draws as a plain Cube too.
meshes! { enum Shape { Plane, Cube, Rock, Sprite } }

/// The board's own sky: a dim gradient, so the sun stays the scene's
/// brightest light.
#[derive(Catalog, Clone, Copy, Debug, PartialEq, Eq, Hash)]
enum Sky {
    Day,
}

impl Skyboxes for Sky {
    fn build(&self, _assets: &Assets) -> SkyboxData {
        SkyboxData::gradient(
            Color::rgb(0.55, 0.75, 0.95),
            Color::rgb(0.85, 0.90, 0.95),
            Color::rgb(0.35, 0.33, 0.30),
        )
        .lit_by(0.3)
    }

examples/sound-lab.rs (line 47)

const FLOOR_COLOR: Color = Color::rgb(0.14, 0.14, 0.17);
const WALL_COLOR: Color = Color::rgb(0.22, 0.24, 0.30);
const SUN_COLOR: Color = Color::rgb(0.85, 0.85, 0.90);
const LISTENER_COLOR: Color = Color::rgb(0.85, 0.85, 0.75);
/// Red on the right, white on the left: the pair the engine's own pan
/// reads, set on the ears so the sides are distinct.
const RIGHT_EAR_COLOR: Color = Color::rgb(0.85, 0.2, 0.2);
const LEFT_EAR_COLOR: Color = Color::rgb(0.92, 0.92, 0.88);
const SOURCE_COLORS: [Color; 3] = [
    Color::rgb(0.85, 0.35, 0.35),
    Color::rgb(0.35, 0.75, 0.85),
    Color::rgb(0.85, 0.75, 0.30),
];
const RANGE_COLOR: Color = Color::rgba(1.0, 1.0, 1.0, 0.35);
/// The inner ring drawn around a source, where its level stops being full.
const REFERENCE_COLOR: Color = Color::rgba(1.0, 0.85, 0.35, 0.5);

const SKY_ZENITH: Color = Color::rgb(0.10, 0.11, 0.16);
const SKY_HORIZON: Color = Color::rgb(0.20, 0.20, 0.24);
const SKY_NADIR: Color = Color::rgb(0.06, 0.06, 0.08);
/// The fraction of its own light the sky lands and reflects: dim, so the
/// cubes' own glow and the room's light still read.
const SKY_LIGHT: f32 = 0.2;

/// Two fixed positions holding the same clip at the default instance,
/// read only while [`SoundCheck::merge_demo`] is set.
const MERGE_POS_A: Vec3 = Vec3::new(-4.0, SOURCE_HEIGHT, 4.5);
const MERGE_POS_B: Vec3 = Vec3::new(4.0, SOURCE_HEIGHT, 4.5);
const MERGE_GAIN: f32 = 0.5;
const MERGE_COLOR_A: Color = Color::rgb(0.95, 0.55, 0.15);
const MERGE_COLOR_B: Color = Color::rgb(0.55, 0.4, 0.85);

/// Where [`Sound::Theme`] and [`Sound::ThemeDecoded`] loop from once
/// declared: a few seconds short of the end, so a wrap seeks across most of
/// the clip.
const THEME_LOOP_FROM: Duration = Duration::from_secs(130);

/// Count of sustains the ring declares at once: more than the engine plays,
/// so the least loud of them hold no voice.
const RING_COUNT: u32 = MAX_VOICES as u32 + 8;
/// Radius of the ring they stand on.
const RING_RADIUS: f32 = 4.6;
/// Distance the ring's sustains hold their full level within: over half the
/// radius, so the whole ring is heard from the middle of the room.
const RING_REFERENCE: f32 = 2.5;
/// Gain the loudest of them takes; each one after it is less loud, so the cut
/// falls inside the ring.
const RING_GAIN: f32 = 0.35;
/// Color of the ring's cubes, taken less bright the less loud the sustain a
/// cube stands for.
const RING_COLOR: Color = Color::rgb(0.35, 0.75, 0.95);

/// Every source this example loads, next to `index.html` on the web and
/// under the working directory on the desktop.
const ASSET_FILES: [&str; 9] = [
    "examples/assets/bounce.ogg",
    "examples/assets/break.ogg",
    "examples/assets/serve.ogg",
    "examples/assets/gameover.ogg",
    "examples/assets/lost.ogg",
    "examples/assets/win.ogg",
    "examples/assets/click.ogg",
    "examples/assets/music.ogg",
    "examples/assets/menu_music.ogg",
];

fn main() {
    run(
        Config::new("Mirage: sound lab")
            .with_size(1280, 720)
            .with_assets(ASSET_FILES),
        SoundCheck::init,
    );
}

/// The one sky this room draws, a gradient set each frame.
#[derive(Catalog, Clone, Copy, Debug, Eq, Hash, PartialEq)]
enum Sky {
    Room,
}

impl Skyboxes for Sky {
    fn build(&self, _assets: &Assets) -> SkyboxData {
        match self {
            Self::Room => {
                SkyboxData::gradient(SKY_ZENITH, SKY_HORIZON, SKY_NADIR).lit_by(SKY_LIGHT)
            }
        }
    }
}

/// A source's reference or its range: a flat ring on the ground,
/// unit-sized, drawn that many meters across by its scale.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Ring;

impl Mesh for Ring {
    fn build(&self, _: &Assets) -> MeshData {
        ring_outline()
    }
}

/// The listener's facing marker: a point through `-Z`, unit-sized.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Facing;

impl Mesh for Facing {
    fn build(&self, _: &Assets) -> MeshData {
        facing_marker()
    }
}

// Everything else this game draws is a built-in primitive, given its
// color and placed per draw: the room's floor and walls, a cube drawn for
// a source or the listener, and the listener's ears.
meshes! { enum Shape { Plane, Cube, Ring, Sphere, Facing } }

fn ring_outline() -> MeshData {
    const SEGMENTS: u32 = 48;
    const OUTER: f32 = 1.0;
    const INNER: f32 = 0.94;

    let mut vertices = Vec::with_capacity(SEGMENTS as usize * 4);
    let mut indices = Vec::with_capacity(SEGMENTS as usize * 6);
    for segment in 0..SEGMENTS {
        let a0 = segment as f32 / SEGMENTS as f32 * TAU;
        let a1 = (segment + 1) as f32 / SEGMENTS as f32 * TAU;
        let (u0, v0) = (a0.cos(), a0.sin());
        let (u1, v1) = (a1.cos(), a1.sin());
        let base = vertices.len() as u32;
        vertices.extend([
            Vertex::new(Vec3::new(INNER * u0, 0.0, -INNER * v0), Vec3::Y, Vec2::ZERO),
            Vertex::new(Vec3::new(OUTER * u0, 0.0, -OUTER * v0), Vec3::Y, Vec2::ZERO),
            Vertex::new(Vec3::new(OUTER * u1, 0.0, -OUTER * v1), Vec3::Y, Vec2::ZERO),
            Vertex::new(Vec3::new(INNER * u1, 0.0, -INNER * v1), Vec3::Y, Vec2::ZERO),
        ]);
        indices.extend([base, base + 1, base + 2, base, base + 2, base + 3]);
    }
    MeshData::new(vertices, indices)
}

fn facing_marker() -> MeshData {
    const TIP: Vec3 = Vec3::new(0.0, 0.0, -0.5);
    const BACK: [Vec3; 4] = [
        Vec3::new(-0.5, -0.5, 0.5),
        Vec3::new(0.5, -0.5, 0.5),
        Vec3::new(0.5, 0.5, 0.5),
        Vec3::new(-0.5, 0.5, 0.5),
    ];

    let mut vertices = Vec::with_capacity(BACK.len() * 3);
    for (corner, next) in BACK.iter().zip(BACK.iter().cycle().skip(1)) {
        let normal = (next - corner).cross(TIP - corner).normalize();
        vertices.extend([
            Vertex::new(*corner, normal, Vec2::new(0.0, 1.0)),
            Vertex::new(*next, normal, Vec2::new(1.0, 1.0)),
            Vertex::new(TIP, normal, Vec2::new(0.5, 0.0)),
        ]);
    }
    let indices = (0..vertices.len() as u32).collect();
    MeshData::new(vertices, indices)
}

/// Every sound this game plays. [`Sound::Break`] and [`Sound::Pulse`] read the
/// same source under two names, so sustaining one and playing the other
/// once never share a voice; [`Sound::Theme`] and [`Sound::ThemeDecoded`] do
/// the same for the streamed side against the decoded one, since a clip
/// decodes one way or the other for good, once built.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
enum Sound {
    Bounce,
    Break,
    Serve,
    GameOver,
    Lost,
    Win,
    Click,
    Theme,
    ThemeDecoded,
    MenuTheme,
    Pulse,
}

impl Sound {
    /// The alternatives a one-shot play offers.
    const ONE_SHOTS: [Sound; 7] = [
        Sound::Bounce,
        Sound::Break,
        Sound::Serve,
        Sound::GameOver,
        Sound::Lost,
        Sound::Win,
        Sound::Click,
    ];

    /// The alternatives one source's sustain offers.
    const SOURCE_CHOICES: [Sound; 9] = [
        Sound::Bounce,
        Sound::Break,
        Sound::Serve,
        Sound::GameOver,
        Sound::Lost,
        Sound::Win,
        Sound::Click,
        Sound::Theme,
        Sound::ThemeDecoded,
    ];

    fn label(self) -> &'static str {
        match self {
            Sound::Bounce => "bounce",
            Sound::Break => "break",
            Sound::Serve => "serve",
            Sound::GameOver => "game over",
            Sound::Lost => "lost",
            Sound::Win => "win",
            Sound::Click => "click",
            Sound::Theme => "theme (streamed)",
            Sound::ThemeDecoded => "theme (decoded)",
            Sound::MenuTheme => "menu theme",
            Sound::Pulse => "pulse",
        }
    }
}

impl Sounds for Sound {
    fn build(&self, assets: &Assets) -> SoundData {
        match self {
            Sound::Bounce => assets.sound("bounce"),
            Sound::Break => assets.sound("break"),
            Sound::Serve => assets.sound("serve"),
            Sound::GameOver => assets.sound("gameover"),
            Sound::Lost => assets.sound("lost"),
            Sound::Win => assets.sound("win"),
            Sound::Click => assets.sound("click"),
            Sound::Theme => assets.sound("music").streamed(),
            Sound::ThemeDecoded => assets.sound("music"),
            Sound::MenuTheme => assets.sound("menu_music").streamed(),
            Sound::Pulse => assets.sound("break"),
        }
    }
}

/// The one button this game reads: it holds a source down and moves it.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Button {
    Select,
}

impl InputButtonAction for Button {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Button::Select => vec![MouseButton::Left.into()],
        }
    }
}

/// The listener's walk, in the ground plane.
#[derive(InputAxis2Action, Clone, Copy, PartialEq)]
enum Move {
    Walk,
}

impl InputAxis2Action for Move {
    fn bindings(&self) -> Vec<Axis2Binding> {
        match self {
            Move::Walk => vec![
                Axis2Binding::from(ButtonAxis2 {
                    left: Key::A,
                    right: Key::D,
                    down: Key::S,
                    up: Key::W,
                }),
                Axis2Binding::stick(Stick::Left),
            ],
        }
    }
}

struct Controls;

impl InputActions for Controls {
    type Button = Button;
    type Axis = NoInputAxes;
    type Axis2 = Move;
}

/// One source a drag moves: a cube on the ground, playing a sustained clip
/// with its own gain, reference, range, and pitch.
struct Source {
    position: Vec3,
    sound: Sound,
    gain: f32,
    reference: f32,
    range: f32,
    pitch: f32,
    /// Whether this source sustains at all; off keeps startup silent.
    enabled: bool,
}

impl Source {
    fn new(x: f32, z: f32, sound: Sound, range: f32, enabled: bool) -> Self {
        Self {
            position: Vec3::new(x, SOURCE_HEIGHT, z),
            sound,
            gain: 0.5,
            reference: SOURCE_REFERENCE,
            range,
            pitch: 1.0,
            enabled,
        }
    }

    /// This source's sustained cue, with the loop point that seeks far
    /// where its choice needs one.
    fn cue(&self) -> SoundCue<Sound> {
        let cue = self
            .sound
            .at(self.position)
            .gain(self.gain)
            .reference(self.reference)
            .range(self.range)
            .pitch(self.pitch);
        match self.sound {
            Sound::Theme | Sound::ThemeDecoded => cue.loop_from(THEME_LOOP_FROM),
            _ => cue,
        }
    }
}

struct SoundCheck {
    master_volume: f32,

    picked: Sound,
    one_shot_gain: f32,
    one_shot_pitch: f32,
    one_shot_fade: f32,
    trim_start: f32,
    trim_end: f32,
    one_shot_loop_from: f32,

    theme_on: bool,
    menu_on: bool,
    pulse_on: bool,
    cue_fade: f32,

    /// Sustains [`Sound::Click`] at [`MERGE_POS_A`] and [`MERGE_POS_B`]
    /// both at the default instance: shows the merge each source's own
    /// instance above keeps clear of.
    merge_demo: bool,

    /// Declares [`RING_COUNT`] sustains at once, more than the engine
    /// plays, so that the cap is heard as it allocates by level.
    ring_demo: bool,

    player: Vec2,
    player_prev: Vec2,
    sources: [Source; 3],
    dragging: Option<usize>,

    /// Every catalog value's length, read once at startup.
    durations: HashMap<Sound, Duration>,
}

impl SoundCheck {
    fn init(ctx: &mut InitContext<'_, SoundCheck>) -> Result<Self, Error> {
        let durations = ctx.durations();

        let picked = Sound::Bounce;
        let trim_end = durations.get(&picked).copied().unwrap_or_default();

        Ok(Self {
            master_volume: 1.0,

            picked,
            one_shot_gain: 1.0,
            one_shot_pitch: 1.0,
            one_shot_fade: SoundCue::<Sound>::DEFAULT_FADE.as_secs_f32(),
            trim_start: 0.0,
            trim_end: trim_end.as_secs_f32(),
            one_shot_loop_from: 0.0,

            theme_on: false,
            menu_on: false,
            pulse_on: false,
            cue_fade: 1.0,

            merge_demo: false,
            ring_demo: false,

            player: Vec2::ZERO,
            player_prev: Vec2::ZERO,
            sources: [
                Source::new(-2.5, -2.0, Sound::Bounce, 4.0, false),
                Source::new(2.5, -2.0, Sound::Serve, 4.0, false),
                Source::new(0.0, 2.8, Sound::Theme, 7.0, true),
            ],
            dragging: None,

            durations,
        })
    }

    fn camera(player: Vec2) -> Camera {
        let ground = Vec3::new(player.x, 0.0, player.y);
        Camera::new(
            View::look_at(
                ground + Vec3::new(0.0, CHASE_UP, CHASE_BACK),
                ground + Vec3::Y * 0.5,
            ),
            Projection::perspective(55.0),
        )
    }

    fn handle_walk(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        self.player_prev = self.player;
        if ctx.ui_wants_keyboard() {
            return;
        }
        let walk = ctx.axis2(Move::Walk);
        let world = Vec2::new(walk.x, -walk.y);
        self.player = (self.player + world * WALK_SPEED * ctx.dt().as_secs_f32())
            .clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
    }

    /// Takes hold of the source a click's ray intersects, moves it across
    /// the floor while the button stays down, and frees it on release.
    fn handle_drag(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        // Read before the check below for the UI's own claim on the
        // pointer, so a release over it still frees a source a drag moved
        // there.
        if ctx.released(Button::Select) {
            self.dragging = None;
        }
        if ctx.ui_wants_pointer() {
            return;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());

        if ctx.pressed(Button::Select) {
            self.dragging = self.sources.iter().position(|source| {
                ray.hit_sphere(source.position, SOURCE_PICK_RADIUS)
                    .is_some()
            });
        }

        let Some(index) = self.dragging else {
            return;
        };
        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return;
        };
        let hit = ray.at(distance);
        let dropped =
            Vec2::new(hit.x, hit.z).clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
        self.sources[index].position = Vec3::new(dropped.x, SOURCE_HEIGHT, dropped.y);
    }

    fn draw_room(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    ROOM_HALF * 2.0,
                    1.0,
                    ROOM_HALF * 2.0,
                )))
                .material(Material::lit(FLOOR_COLOR)),
        );

        let side_half = Vec3::new(WALL_THICKNESS * 0.5, WALL_HEIGHT * 0.5, ROOM_HALF);
        for side in [-1.0, 1.0] {
            let x = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    side_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(x, side_half.y, 0.0),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
        let end_half = Vec3::new(ROOM_HALF, WALL_HEIGHT * 0.5, WALL_THICKNESS * 0.5);
        for side in [-1.0, 1.0] {
            let z = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    end_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(0.0, end_half.y, z),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
    }

    fn draw_sources(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        for (index, source) in self.sources.iter().enumerate() {
            let color = SOURCE_COLORS[index];
            let picked_up = self.dragging == Some(index);
            let scale = if picked_up { 1.3 } else { 1.0 };
            let emissive = if source.enabled {
                Color::rgb(color.red * 3.0, color.green * 3.0, color.blue * 3.0)
            } else {
                color.dimmed(0.15)
            };

            for (radius, ring_color) in [
                (source.range, RANGE_COLOR),
                (source.reference, REFERENCE_COLOR),
            ] {
                ctx.draw(
                    Ring.at(Transform::from_scale_rotation_translation(
                        Vec3::new(radius, 1.0, radius),
                        Quat::IDENTITY,
                        Vec3::new(source.position.x, 0.01, source.position.z),
                    ))
                    .material(Material::color(ring_color)),
                );
            }
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0 * scale),
                    Quat::IDENTITY,
                    source.position,
                ))
                .material(Material::shaded(color, 0.6).emissive(emissive)),
            );
        }
    }

examples/material-playground.rs (line 58)

const GROUND_COLOR: Color = Color::rgb(0.24, 0.25, 0.22);
const SHADING_TINT: Color = Color::rgb(0.55, 0.55, 0.6);
const RELIEF_TINT: Color = Color::rgb(0.5, 0.45, 0.35);
const EMISSIVE_BASE: Color = Color::rgb(0.04, 0.04, 0.05);
const EMISSIVE_GLOW: Color = Color::rgb(3.2, 2.2, 0.7);

/// Texel side length of every generated map: coarse enough that each
/// checker cell reads as a distinct part on a sphere or a cube face.
const MAP_SIZE: UVec2 = UVec2::new(64, 64);

/// Checker cell width, in texels, for the shading map.
const SHADING_CELL: u32 = 8;
/// The shading checker's two states: occlusion, roughness and metallic —
/// one square low across all three, the other full across all three.
const SHADING_LOW: [u8; 3] = [70, 40, 15];
const SHADING_HIGH: [u8; 3] = [255, 225, 235];

/// Checker cell width, in texels, for the emissive map.
const EMISSIVE_CELL: u32 = 6;

/// Wave count the relief's texture repeats across its map, and the peak
/// slope of its surface, in height over distance.
const BUMP_WAVES: f32 = 6.0;
const BUMP_SLOPE: f32 = 1.15;

/// `BannerCloth`'s width and height, in meters.
const BANNER_WIDTH: f32 = 1.1;
const BANNER_HEIGHT: f32 = 0.7;

/// Columns `BannerCloth` splits into, so its wave curves smoothly.
const BANNER_COLUMNS: u32 = 10;

/// Where the pillars, the pole, the cloth and the pulsing sphere are
/// placed, added to every one of their own positions: apart from the
/// pairs and the reflection row, so a light's shadow has clear ground to
/// land on.
const OUTPOST: Vec3 = Vec3::new(-4.6, 0.0, -0.8);

const PILLARS: [(Vec3, Vec3); 3] = [
    (Vec3::new(-1.8, 0.6, -0.6), Vec3::new(0.6, 1.2, 0.6)),
    (Vec3::new(0.4, 0.4, -1.6), Vec3::new(0.5, 0.8, 0.5)),
    (Vec3::new(1.7, 0.9, 0.4), Vec3::new(0.55, 1.8, 0.55)),
];

const POLE_POSITION: Vec3 = Vec3::new(-2.6, 1.0, 0.4);
const POLE_SCALE: Vec3 = Vec3::new(0.12, 2.0, 0.12);
const BANNER_MOUNT: Vec3 = Vec3::new(-2.54, 1.55, 0.46);

const FIELD_ORB_POSITION: Vec3 = Vec3::new(1.3, 1.1, 1.6);
const FIELD_ORB_SCALE: f32 = 0.7;

/// The lamp's fixed position and reach, in meters.
const LAMP_POSITION: Vec3 = Vec3::new(2.4, 1.4, -3.0);
const LAMP_RANGE: f32 = 5.0;

/// The spotlight's fixed placement: where it is placed, which way its
/// cone points, its reach in meters and its width in radians.
const SPOT_POSITION: Vec3 = Vec3::new(-3.4, 3.0, 1.6);
const SPOT_DIRECTION: Vec3 = Vec3::new(0.55, -1.0, -1.0);
const SPOT_RANGE: f32 = 7.0;
const SPOT_ANGLE: f32 = 0.5;

/// The camera's vertical field of view, in degrees.
const CAMERA_FOV: f32 = 46.0;
/// Where the camera starts, and the `yaw` and the pitch, in radians, it
/// starts turned to.
const START_EYE: Vec3 = Vec3::new(-0.6, 2.2, 9.0);
const START_YAW: f32 = 0.0;
const START_PITCH: f32 = -0.15;
/// How far short of straight up or down the pitch may turn, in radians,
/// where a turn alone reads as nothing.
const PITCH_LIMIT: f32 = 1.5;
/// The `eye`'s least height above the ground plane, in meters: held above
/// zero so a move can never take it below.
const MIN_EYE_HEIGHT: f32 = 0.3;
/// Radians the pointer's own motion turns the view by, per physical
/// pixel it crosses, before the axis it reads through bounds it: a drag
/// across the whole window turns about a quarter turn.
const LOOK_SENSITIVITY: f32 = core::f32::consts::FRAC_PI_2 / 1280.0;
/// Meters a move key covers per second, at [`Playground::speed_scale`]'s
/// own default.
const MOVE_SPEED: f32 = 4.0;
/// The factor one full wheel step multiplies the move speed apart from.
const SPEED_STEP: f32 = 1.5;
/// The move speed's own least and most, as a factor of [`MOVE_SPEED`].
const MIN_SPEED_SCALE: f32 = 0.2;
const MAX_SPEED_SCALE: f32 = 5.0;

/// Bloom this scene starts at, past the engine's own default: enough that
/// [`EMISSIVE_GLOW`] and the brightest lights scatter right away.
const START_BLOOM: f32 = 0.25;
const START_EXPOSURE: f32 = 1.0;

/// The sky a frame that keeps [`Sky::Default`] draws and is lit by: the
/// same flat grey the engine falls back to when a frame sets none.
const DEFAULT_SKY: Color = Color::rgb(0.1, 0.1, 0.1);

/// The fraction of its own light each loaded sky lands and reflects,
/// through [`SkyboxData::lit_by`]: the bright images fixed low, since an
/// image read too bright under the frame's own lights at its default
/// `1.0`; the dim images fixed more, since the scene read too dark under
/// them at the bright images' value.
const CLEAR_SKY_LIGHT: f32 = 0.35;
const CLASSIC_SKY_LIGHT: f32 = 0.35;
const DAWN_SKY_LIGHT: f32 = 0.3;
const SINISTER_SKY_LIGHT: f32 = 0.6;
const LIGHT_BLUE_STARS_LIGHT: f32 = 0.8;
const BLUE_STARS_LIGHT: f32 = 0.8;

/// The shading pair's plain half: a sphere given the shared shading
/// material and no map.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct ShadingPlain;

impl Mesh for ShadingPlain {
    fn build(&self, assets: &Assets) -> MeshData {
        sphere_with_material(assets, shading_material())
    }
}

/// The shading pair's mapped half: the same sphere and material, with its
/// shading map (occlusion, roughness and metallic) baked in.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct ShadingMapped;

impl Mesh for ShadingMapped {
    fn build(&self, assets: &Assets) -> MeshData {
        sphere_with_material(assets, shading_material()).with_shading(shading_checker())
    }
}

/// The relief pair's plain half.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct ReliefPlain;

impl Mesh for ReliefPlain {
    fn build(&self, assets: &Assets) -> MeshData {
        sphere_with_material(assets, relief_material())
    }
}

/// The relief pair's mapped half: the same sphere and material, with its
/// relief map baked in.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct ReliefMapped;

impl Mesh for ReliefMapped {
    fn build(&self, assets: &Assets) -> MeshData {
        sphere_with_material(assets, relief_material()).with_relief(relief_bumps())
    }
}

/// The emissive pair's plain half.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct EmissivePlain;

impl Mesh for EmissivePlain {
    fn build(&self, assets: &Assets) -> MeshData {
        cube_with_material(assets, emissive_material())
    }
}

/// The emissive pair's mapped half: the same cube and material, with its
/// emissive map baked in.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct EmissiveMapped;

impl Mesh for EmissiveMapped {
    fn build(&self, assets: &Assets) -> MeshData {
        cube_with_material(assets, emissive_material()).with_emissive_map(emissive_checker())
    }
}

/// The front sphere: a draw overrides its material new every frame, in
/// place of a baked one.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct Front;

impl Mesh for Front {
    fn build(&self, assets: &Assets) -> MeshData {
        Sphere {
            subdivisions: SPHERE_SUBDIVISIONS,
        }
        .build(assets)
    }
}

/// `BannerCloth`: a mesh split into columns along its span and placed at
/// its `x = 0` edge, so `Banner`'s wave curves it, not a single flat
/// quad. Its triangles are built twice: once as authored and once in the
/// other order, with the normal turned around, so the cloth draws from
/// both sides however its wave curves it.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct BannerCloth;

impl Mesh for BannerCloth {
    fn build(&self, _: &Assets) -> MeshData {
        banner_mesh()
    }
}

// Everything this game draws: the ground plane, each map pair's plain and
// mapped half, the front sphere with its own live material, the built-in
// primitives the reflection row and the pillars beside it place per draw,
// and the displaced cloth.
meshes! {
    enum Shape {
        Plane,
        Sphere,
        Cube,
        ShadingPlain,
        ShadingMapped,
        ReliefPlain,
        ReliefMapped,
        EmissivePlain,
        EmissiveMapped,
        Front,
        BannerCloth,
    }
}

fn sphere_with_material(assets: &Assets, material: Material) -> MeshData {
    Sphere {
        subdivisions: SPHERE_SUBDIVISIONS,
    }
    .build(assets)
    .with_material(material)
}

fn cube_with_material(assets: &Assets, material: Material) -> MeshData {
    Cube.build(assets).with_material(material)
}

fn shading_material() -> Material {
    Material::lit(SHADING_TINT).roughness(0.5).metallic(0.5)
}

fn relief_material() -> Material {
    Material::lit(RELIEF_TINT).roughness(0.35)
}

fn emissive_material() -> Material {
    Material::color(EMISSIVE_BASE).emissive(EMISSIVE_GLOW)
}

/// A shading map whose checker goes between low occlusion, roughness and
/// metallic and full occlusion, roughness and metallic, so all three read
/// apart across [`ShadingMapped`].
fn shading_checker() -> ShadingData {
    ShadingData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, SHADING_CELL, SHADING_LOW, SHADING_HIGH),
    )
}

/// An emissive map whose checker goes between full glow and none, so
/// [`EMISSIVE_GLOW`] shapes across [`EmissiveMapped`] instead of casting
/// whole.
fn emissive_checker() -> TextureData {
    TextureData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, EMISSIVE_CELL, [0, 0, 0], [255, 255, 255]),
    )
}

fn checker_pixels(size: UVec2, cell: u32, low: [u8; 3], high: [u8; 3]) -> Vec<u8> {
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let on = ((x / cell) + (y / cell)).is_multiple_of(2);
            let [red, green, blue] = if on { high } else { low };
            pixels.extend_from_slice(&[red, green, blue, u8::MAX]);
        }
    }
    pixels
}

/// A relief whose normals turn across a wave that repeats over the map:
/// each texel's slope comes from the partial derivatives of a
/// `sin(u) * sin(v)` height field at `BUMP_SLOPE`'s peak, computed at that
/// texel and not sampled from any other.
fn relief_bumps() -> ReliefData {
    let size = MAP_SIZE;
    let turns = core::f32::consts::TAU * BUMP_WAVES;
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let u = (x as f32 + 0.5) / size.x as f32;
            let v = (y as f32 + 0.5) / size.y as f32;
            let slope_u = BUMP_SLOPE * (turns * u).cos() * (turns * v).sin();
            let slope_v = BUMP_SLOPE * (turns * u).sin() * (turns * v).cos();
            let normal = Vec3::new(-slope_u, -slope_v, 1.0).normalize();
            let encode = |signed: f32| ((signed * 0.5 + 0.5) * 255.0).round() as u8;
            pixels.extend_from_slice(&[encode(normal.x), encode(normal.y), encode(normal.z), 0]);
        }
    }
    ReliefData::normals(size, pixels)
}

/// `BannerCloth`'s vertices and indices, built twice over: the columns as
/// authored, facing `+Z`, and the same columns again facing `-Z`, their
/// triangles in the other order so both draw front side out.
fn banner_mesh() -> MeshData {
    let mut vertices = Vec::with_capacity(((BANNER_COLUMNS + 1) * 4) as usize);
    for normal in [Vec3::Z, Vec3::NEG_Z] {
        for column in 0..=BANNER_COLUMNS {
            let u = column as f32 / BANNER_COLUMNS as f32;
            let x = u * BANNER_WIDTH;
            for v in [0.0, 1.0] {
                vertices.push(Vertex::new(
                    Vec3::new(x, -v * BANNER_HEIGHT, 0.0),
                    normal,
                    Vec2::new(u, v),
                ));
            }
        }
    }

    let side = BANNER_COLUMNS + 1;
    let mut indices = Vec::with_capacity((BANNER_COLUMNS * 12) as usize);
    for column in 0..BANNER_COLUMNS {
        let top_left = column * 2;
        let bottom_left = top_left + 1;
        let top_right = top_left + 2;
        let bottom_right = top_left + 3;
        indices.extend([
            bottom_left,
            bottom_right,
            top_right,
            bottom_left,
            top_right,
            top_left,
        ]);

        let back = side * 2;
        indices.extend([
            back + top_right,
            back + bottom_right,
            back + bottom_left,
            back + top_left,
            back + top_right,
            back + bottom_left,
        ]);
    }

    MeshData::new(vertices, indices)
}

/// Displaced by a wave that grows away from its `x = 0` edge; casts the
/// shadow of where it was placed, unmoved by its own wave. Its one value
/// is the clock its wave slides on.
#[derive(Default, ShaderValues)]
struct Banner {
    time: f32,
}

impl SurfaceStyle for Banner {
    const PASS: DrawPass = DrawPass::Opaque;
    const DISPLACE: Option<&'static str> = Some(include_str!("material_playground_banner.wgsl"));
}

/// A surface that reads no light of the scene's own: it draws its own
/// pulsing tint, added over what is behind it, through the color it pulses
/// through and the clock the pulse is timed by.
#[derive(Default, ShaderValues)]
struct Field {
    tint: Color,
    time: f32,
}

impl SurfaceStyle for Field {
    const PASS: DrawPass = DrawPass::Additive;
    const SURFACE: Option<&'static str> = Some(include_str!("material_playground_field.wgsl"));
}

surface_styles! { enum Looks { Banner, Field } }

/// A whole scene lighting choice: it names a sky and, kept with it, the
/// sun that lights the scene, so a choice cannot leave the two apart.
/// `Dawn`, `Noon`, `Dusk` and `Night` each pair a gradient with a sun of
/// its own color and direction; `Clear`, `Classic`, `ImageDawn` and
/// `Sinister` each pair a loaded image with a sun that fits it, and
/// `LightBlueStars` and `BlueStars` pair a loaded space image with none;
/// `Default` is the engine's own grey sky and white sun.
///
/// [`Skyboxes`] proves every value at startup, so it must be [`Eq`] and
/// [`Hash`] over a fixed [`Skyboxes::catalog`] — a sky and sun a player
/// set to any color and direction live could never meet, since `f32` is
/// neither. This fixed, named set is the shape this file chose in its
/// place: the side area offers it as one row, and shows the chosen sky's
/// own light and its sun's own strength as text, read only, rather than
/// controls a game could not build from. See this example's report for
/// what that choice costs.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
enum Sky {
    Dawn,
    Noon,
    Dusk,
    Night,
    Clear,
    Classic,
    ImageDawn,
    Sinister,
    LightBlueStars,
    BlueStars,
    Default,
}

impl Sky {
    const ALL: [Sky; 11] = [
        Self::Dawn,
        Self::Noon,
        Self::Dusk,
        Self::Night,
        Self::Clear,
        Self::Classic,
        Self::ImageDawn,
        Self::Sinister,
        Self::LightBlueStars,
        Self::BlueStars,
        Self::Default,
    ];

    fn name(self) -> &'static str {
        match self {
            Self::Dawn => "dawn",
            Self::Noon => "noon",
            Self::Dusk => "dusk",
            Self::Night => "night",
            Self::Clear => "clear day",
            Self::Classic => "classic",
            Self::ImageDawn => "dawn image",
            Self::Sinister => "sinister night",
            Self::LightBlueStars => "light blue stars",
            Self::BlueStars => "blue stars",
            Self::Default => "default",
        }
    }

    /// The fraction of its own light this sky lands and reflects, through
    /// [`SkyboxData::lit_by`]: fixed per choice, so a bright one does not
    /// read too bright, and a dark one does not read too dark, under the
    /// frame's own lights.
    fn light(self) -> f32 {
        match self {
            Self::Dawn => 0.4,
            Self::Noon => 0.5,
            Self::Dusk => 0.35,
            Self::Night => 0.3,
            Self::Clear => CLEAR_SKY_LIGHT,
            Self::Classic => CLASSIC_SKY_LIGHT,
            Self::ImageDawn => DAWN_SKY_LIGHT,
            Self::Sinister => SINISTER_SKY_LIGHT,
            Self::LightBlueStars => LIGHT_BLUE_STARS_LIGHT,
            Self::BlueStars => BLUE_STARS_LIGHT,
            Self::Default => 1.0,
        }
    }

    /// The sun this choice pairs with its sky: direction, color and
    /// strength resolved together, so a choice cannot leave them apart.
    /// `None` for the two space images, which pair with no sun at all.
    fn sun(self) -> Option<(Vec3, Color, f32)> {
        match self {
            Self::Dawn => Some((
                Vec3::new(-1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.7, 0.45),
                1.4,
            )),
            Self::Noon => Some((
                Vec3::new(-0.15, -1.0, -0.1),
                Color::rgb(1.0, 1.0, 0.98),
                1.6,
            )),
            Self::Dusk => Some((
                Vec3::new(1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.55, 0.25),
                1.2,
            )),
            Self::Night => Some((
                Vec3::new(-0.3, -0.7, -0.6),
                Color::rgb(0.55, 0.65, 0.85),
                0.15,
            )),
            Self::Clear => Some((
                Vec3::new(-0.2, -1.0, -0.15),
                Color::rgb(1.0, 0.98, 0.9),
                1.5,
            )),
            Self::Classic => Some((
                Vec3::new(-0.4, -0.9, -0.2),
                Color::rgb(1.0, 0.95, 0.85),
                1.3,
            )),
            Self::ImageDawn => Some((Vec3::new(-1.0, -0.2, 0.1), Color::rgb(1.0, 0.75, 0.5), 1.1)),
            Self::Sinister => Some((Vec3::new(0.4, -0.5, -0.7), Color::rgb(0.4, 0.5, 0.75), 0.1)),
            Self::LightBlueStars | Self::BlueStars => None,
            Self::Default => Some((Vec3::new(-0.4, -1.0, -0.6), Color::WHITE, 1.0)),
        }
    }

    /// The color the sky reads under the horizon, through
    /// [`SkyboxData::with_ground`]: the floor as lit under this choice's own
    /// sun and [`Self::light`], so it moves with them, not only with the
    /// image. `None` for the gradient skies and `Default`, which need no
    /// ground, and for the two space images, which hold space below the
    /// horizon as well.
    fn ground(self) -> Option<Color> {
        match self {
            Self::Clear => Some(Color::rgb(0.501, 0.517, 0.449)),
            Self::Classic => Some(Color::rgb(0.420, 0.405, 0.379)),
            Self::ImageDawn => Some(Color::rgb(0.073, 0.053, 0.032)),
            Self::Sinister => Some(Color::rgb(0.012, 0.014, 0.020)),
            Self::Dawn
            | Self::Noon
            | Self::Dusk
            | Self::Night
            | Self::LightBlueStars
            | Self::BlueStars
            | Self::Default => None,
        }
    }
}

impl Catalog for Sky {
    fn catalog() -> Vec<Self> {
        Self::ALL.to_vec()
    }
}

impl Skyboxes for Sky {
    fn build(&self, assets: &Assets) -> SkyboxData {
        let sky = match self {
            Self::Dawn => SkyboxData::gradient(
                Color::rgb(0.55, 0.55, 0.75),
                Color::rgb(0.95, 0.6, 0.35),
                Color::rgb(0.12, 0.08, 0.06),
            ),
            Self::Noon => SkyboxData::gradient(
                Color::rgb(0.2, 0.45, 0.85),
                Color::rgb(0.75, 0.82, 0.9),
                Color::rgb(0.3, 0.3, 0.28),
            ),
            Self::Dusk => SkyboxData::gradient(
                Color::rgb(0.18, 0.1, 0.3),
                Color::rgb(0.85, 0.35, 0.2),
                Color::rgb(0.03, 0.02, 0.03),
            ),
            Self::Night => SkyboxData::gradient(
                Color::rgb(0.02, 0.02, 0.06),
                Color::rgb(0.05, 0.05, 0.1),
                Color::rgb(0.0, 0.0, 0.0),
            ),
            Self::Clear => assets.skybox("sky-clear"),
            Self::Classic => assets.skybox("sky-classic"),
            Self::ImageDawn => assets.skybox("sky-dawn"),
            Self::Sinister => assets.skybox("sky-sinister"),
            Self::LightBlueStars => assets.skybox("sky-stars-lightblue"),
            Self::BlueStars => assets.skybox("sky-stars-blue"),
            Self::Default => SkyboxData::gradient(DEFAULT_SKY, DEFAULT_SKY, DEFAULT_SKY),
        };
        let sky = match self.ground() {
            Some(ground) => sky.with_ground(ground),
            None => sky,
        };

        sky.lit_by(self.light())
    }
}

/// `color` scaled by `strength`, the value a [`Light`] reads.
fn scaled(color: Color, strength: f32) -> Color {
    Color::rgb(
        color.red * strength,
        color.green * strength,
        color.blue * strength,
    )
}

/// One light's color and strength, held apart from the position that
/// names it, plus whether it casts.
#[derive(Clone, Copy)]
struct Glow {
    color: Color,
    strength: f32,
    shadow: bool,
}

impl Glow {
    /// `color` scaled by `strength`, the value a [`Light`] reads.
    fn scaled(self) -> Color {
        scaled(self.color, self.strength)
    }
}

/// Every key and button this game reads apart from the UI: held, `Look`
/// turns the camera by the pointer's own motion, `Forward`/`Back`/
/// `Left`/`Right` move it along the view and to its side, and `Up`/
/// `Down` move it along the world's own up.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Move {
    Forward,
    Back,
    Left,
    Right,
    Up,
    Down,
    Look,
}

impl InputButtonAction for Move {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Self::Forward => vec![Key::W.into()],
            Self::Back => vec![Key::S.into()],
            Self::Left => vec![Key::A.into()],
            Self::Right => vec![Key::D.into()],
            Self::Up => vec![Key::Space.into()],
            Self::Down => vec![Key::LeftShift.into()],
            Self::Look => vec![MouseButton::Right.into()],
        }
    }
}

/// The pointer's own motion, read only while [`Move::Look`] is held.
#[derive(InputAxis2Action, Clone, Copy, PartialEq)]
enum Turn {
    Look,
}

impl InputAxis2Action for Turn {
    fn bindings(&self) -> Vec<Axis2Binding> {
        match self {
            Self::Look => vec![Axis2Binding::pointer().scale(LOOK_SENSITIVITY)],
        }
    }
}

/// How far the wheel moved this frame, read to scale the move speed.
#[derive(InputAxisAction, Clone, Copy, PartialEq)]
enum Speed {
    Wheel,
}

impl InputAxisAction for Speed {
    fn bindings(&self) -> Vec<AxisBinding> {
        match self {
            Self::Wheel => vec![AxisBinding::from(WheelDelta::Up).scale(4.0)],
        }
    }
}

struct Controls;

impl InputActions for Controls {
    type Button = Move;
    type Axis = Speed;
    type Axis2 = Turn;
}

struct Playground {
    eye: Vec3,
    yaw: f32,
    pitch: f32,
    speed_scale: f32,

    sky: Sky,
    sun_shadow: bool,

    lamp: Glow,
    spotlight: Glow,

    front_tint: Color,
    front_roughness: f32,
    front_metallic: f32,
    shading_map_on: bool,
    relief_map_on: bool,
    emissive_map_on: bool,

    exposure: f32,
    bloom: f32,
}

impl Playground {
    fn init(ctx: &mut InitContext<'_, Self>) -> Result<Self, Error> {
        let _ = ctx;
        Ok(Self {
            eye: START_EYE,
            yaw: START_YAW,
            pitch: START_PITCH,
            speed_scale: 1.0,

            sky: Sky::Default,
            sun_shadow: true,

            lamp: Glow {
                color: Color::rgb(0.9, 0.55, 0.3),
                strength: 3.0,
                shadow: false,
            },
            spotlight: Glow {
                color: Color::rgb(0.4, 0.6, 1.0),
                strength: 6.0,
                shadow: true,
            },

            front_tint: Color::rgb(0.7, 0.25, 0.2),
            front_roughness: 0.4,
            front_metallic: 0.0,
            shading_map_on: true,
            relief_map_on: true,
            emissive_map_on: true,

            exposure: START_EXPOSURE,
            bloom: START_BLOOM,
        })
    }

    /// This frame's forward direction, from `yaw` (turning around the
    /// world's own up) and `pitch` (turning up or down).
    fn forward(&self) -> Vec3 {
        Vec3::new(
            -self.pitch.cos() * self.yaw.sin(),
            self.pitch.sin(),
            -self.pitch.cos() * self.yaw.cos(),
        )
    }

    /// The camera this frame draws from: `eye` looking along `forward`.
    fn camera(&self) -> Camera {
        Camera::new(
            View::look_at(self.eye, self.eye + self.forward()),
            Projection::perspective(CAMERA_FOV),
        )
    }

    /// A held `Move::Look` (the right mouse button) turns the camera by
    /// the pointer's own motion, the same way it moves: dragging right
    /// turns the view right and left turns it left, dragging down turns
    /// it to look further down at the scene, dragging up back toward the
    /// horizon. `W`/`A`/`S`/`D` move along the view and to its side,
    /// `Space`/`Left Shift` up and down, and the wheel scales how far
    /// each move goes. The `eye` is held above the ground plane wherever
    /// it moves.
    fn fly_camera(&mut self, ctx: &mut FrameContext<'_, Self>) {
        if !ctx.ui_wants_pointer() && ctx.down(Move::Look) {
            let look = ctx.axis2(Turn::Look);
            self.yaw -= look.x;
            self.pitch = (self.pitch + look.y).clamp(-PITCH_LIMIT, PITCH_LIMIT);
        }

        let wheel = ctx.axis(Speed::Wheel);
        if !ctx.ui_wants_pointer() && wheel != 0.0 {
            self.speed_scale =
                (self.speed_scale * SPEED_STEP.powf(wheel)).clamp(MIN_SPEED_SCALE, MAX_SPEED_SCALE);
        }

        let forward = self.forward();
        let right = Vec3::new(self.yaw.cos(), 0.0, -self.yaw.sin());
        let mut move_by = Vec3::ZERO;
        if ctx.down(Move::Forward) {
            move_by += forward;
        }
        if ctx.down(Move::Back) {
            move_by -= forward;
        }
        if ctx.down(Move::Right) {
            move_by += right;
        }
        if ctx.down(Move::Left) {
            move_by -= right;
        }
        if ctx.down(Move::Up) {
            move_by += Vec3::Y;
        }
        if ctx.down(Move::Down) {
            move_by -= Vec3::Y;
        }
        if move_by.length_squared() > 1.0 {
            move_by = move_by.normalize();
        }

        self.eye += move_by * MOVE_SPEED * self.speed_scale * ctx.dt().as_secs_f32();
        self.eye.y = self.eye.y.max(MIN_EYE_HEIGHT);
    }

    /// The material [`Front`] draws with, resolved new from its sliders
    /// every frame — the override [`Instance::material`] takes, in place
    /// of a baked one.
    fn front_material(&self) -> Material {
        Material::lit(self.front_tint)
            .roughness(self.front_roughness)
            .metallic(self.front_metallic)
    }

    /// Every draw this game makes: the ground, each map pair, the front
    /// sphere, the reflection row and the pillars beside it.
    fn draw_scene(&self, ctx: &mut FrameContext<'_, Self>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );

        Self::draw_pair(
            ctx,
            SHADING_Z,
            SPHERE_RADIUS,
            ShadingPlain.at(Vec3::ZERO).into_set(),
            ShadingMapped.at(Vec3::ZERO).into_set(),
            self.shading_map_on,
        );
        Self::draw_pair(
            ctx,
            RELIEF_Z,
            SPHERE_RADIUS,
            ReliefPlain.at(Vec3::ZERO).into_set(),
            ReliefMapped.at(Vec3::ZERO).into_set(),
            self.relief_map_on,
        );
        Self::draw_pair(
            ctx,
            EMISSIVE_Z,
            CUBE_SIZE / 2.0,
            EmissivePlain.at(Vec3::ZERO).into_set(),
            EmissiveMapped.at(Vec3::ZERO).into_set(),
            self.emissive_map_on,
        );

        ctx.draw(
            Front
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FRONT_SCALE),
                    Quat::IDENTITY,
                    FRONT_POSITION,
                ))
                .material(self.front_material()),
        );

        self.draw_reflect_row(ctx);
        self.draw_outpost(ctx);
    }

    /// One pair at depth `z`, its centers `height` above the ground: `plain`
    /// on the left always, and on the right `mapped` where `mapped_on` is
    /// set, `plain` again where it is not — the same position drawing the
    /// same base material with and without the map.
    fn draw_pair(
        ctx: &mut FrameContext<'_, Self>,
        z: f32,
        height: f32,
        plain: Instance<Shape, Looks>,
        mapped: Instance<Shape, Looks>,
        mapped_on: bool,
    ) {
        ctx.draw(plain.clone().at(Vec3::new(-PAIR_HALF_SPACING, height, z)));
        let right = if mapped_on { mapped } else { plain };
        ctx.draw(right.at(Vec3::new(PAIR_HALF_SPACING, height, z)));
    }

    /// A row of built-in `Sphere` draws at rising roughness, each
    /// `metallic(1.0)` with its tint white, so what draws is the sky's own
    /// reflection alone.
    fn draw_reflect_row(&self, ctx: &mut FrameContext<'_, Self>) {
        let start = -REFLECT_ROW_SPACING * (REFLECT_ROW_COUNT as f32 - 1.0) / 2.0;
        for index in 0..REFLECT_ROW_COUNT {
            let x = start + index as f32 * REFLECT_ROW_SPACING;
            let roughness = index as f32 / (REFLECT_ROW_COUNT as f32 - 1.0);
            ctx.draw(
                Sphere {
                    subdivisions: SPHERE_SUBDIVISIONS,
                }
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(REFLECT_ROW_RADIUS * 2.0),
                    Quat::IDENTITY,
                    Vec3::new(x, REFLECT_ROW_RADIUS, REFLECT_ROW_Z),
                ))
                .material(
                    Material::lit(Color::WHITE)
                        .roughness(roughness)
                        .metallic(1.0),
                ),
            );
        }
    }

    /// Three pillars and a pole a light can shadow, beside `Banner`'s
    /// displaced cloth and `Field`'s pulsing sphere — [`OUTPOST`] moves the
    /// whole group clear of the rest of the scene.
    fn draw_outpost(&self, ctx: &mut FrameContext<'_, Self>) {
        let clock = ctx.elapsed().as_secs_f32();

        for &(position, scale) in &PILLARS {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    scale,
                    Quat::IDENTITY,
                    OUTPOST + position,
                ))
                .material(Material::lit(Color::rgb(0.55, 0.5, 0.45))),
            );
        }

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                POLE_SCALE,
                Quat::IDENTITY,
                OUTPOST + POLE_POSITION,
            ))
            .material(Material::lit(Color::rgb(0.3, 0.24, 0.18))),
        );

        ctx.set_surface_style(Banner { time: clock });
        ctx.draw(
            BannerCloth
                .at(Transform::from_translation(OUTPOST + BANNER_MOUNT))
                .material(Material::lit(Color::rgb(0.75, 0.12, 0.12)))
                .surface_style::<Banner>(),
        );

        ctx.set_surface_style(Field {
            tint: Color::rgb(0.25, 0.75, 1.0),
            time: clock,
        });
        ctx.draw(
            Sphere { subdivisions: 2 }
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FIELD_ORB_SCALE),
                    Quat::IDENTITY,
                    OUTPOST + FIELD_ORB_POSITION,
                ))
                .material(Material::color(Color::BLACK))
                .surface_style::<Field>(),
        );
    }

    /// This frame's sun, lamp and spotlight, each `.shadow()` where its own
    /// flag is set. The sun's direction, color and strength come from the
    /// chosen [`Sky`], and is absent where the choice pairs with none; only
    /// its shadow flag is the player's own.
    fn lights(&self) -> Vec<Light> {
        let lamp = Light::point(LAMP_POSITION, self.lamp.scaled(), LAMP_RANGE);
        let spotlight = Light::spot(Spot {
            position: SPOT_POSITION,
            direction: SPOT_DIRECTION,
            color: self.spotlight.scaled(),
            range: SPOT_RANGE,
            angle: SPOT_ANGLE,
        });

        let mut lights = vec![
            if self.lamp.shadow {
                lamp.shadow()
            } else {
                lamp
            },
            if self.spotlight.shadow {
                spotlight.shadow()
            } else {
                spotlight
            },
        ];

        if let Some((direction, color, strength)) = self.sky.sun() {
            let sun = Light::directional(direction, scaled(color, strength));
            lights.push(if self.sun_shadow { sun.shadow() } else { sun });
        }

        lights
    }

    /// Every live knob, in a side area of fixed width so the scene stays
    /// visible beside it — the default sky reads as flat grey, so a
    /// control added straight to the bare UI layer would read as a slab
    /// across the window.
    fn controls(&mut self, ctx: &mut FrameContext<'_, Self>) {
        let tonemap = ctx.config().tonemap();
        let antialiasing = ctx.config().antialiasing();
        let shadow_resolution = ctx.config().shadow_resolution();

        ctx.ui(|ui| {
            egui::Panel::right("controls")
                .resizable(false)
                .default_size(300.0)
                .show(ui, |ui| {
                    egui::ScrollArea::vertical().show(ui, |ui| {
                        ui.label(
                            "right mouse button to look, W/A/S/D to move, \
                             space/shift up and down, wheel to scale speed",
                        );
                        ui.separator();
                        self.lighting_controls(ui);
                        ui.separator();
                        self.light_controls(ui);
                        ui.separator();
                        self.material_controls(ui);
                        ui.separator();
                        ui.label(format!(
                            "tone map {tonemap:?} \u{b7} antialiasing {antialiasing} \u{b7} \
                             shadow {shadow_resolution}px: set at startup, not live"
                        ));
                        ui.add(egui::Slider::new(&mut self.exposure, 0.1..=3.0).text("exposure"));
                        ui.add(egui::Slider::new(&mut self.bloom, 0.0..=1.0).text("bloom"));
                    });
                });
        });
    }

    fn lighting_controls(&mut self, ui: &mut egui::Ui) {
        ui.heading("lighting");
        for choice in Sky::ALL {
            ui.radio_value(&mut self.sky, choice, choice.name());
        }
        ui.label(format!("sky light {:.2}: set at startup", self.sky.light()));

        match self.sky.sun() {
            Some((_, color, strength)) => {
                color_swatch(ui, "sun", color);
                ui.label(format!("sun strength {strength:.2}: set by the choice"));
                ui.checkbox(&mut self.sun_shadow, "sun shadow");
            }
            None => {
                ui.label("no sun: set by the choice");
            }
        }
    }

    fn light_controls(&mut self, ui: &mut egui::Ui) {
        ui.heading("lights");
        glow_controls(ui, "lamp", &mut self.lamp);
        glow_controls(ui, "spotlight", &mut self.spotlight);
    }

    fn material_controls(&mut self, ui: &mut egui::Ui) {
        ui.heading("material");
        color_row(ui, "tint", &mut self.front_tint);
        ui.add(egui::Slider::new(&mut self.front_roughness, 0.0..=1.0).text("roughness"));
        ui.add(egui::Slider::new(&mut self.front_metallic, 0.0..=1.0).text("metallic"));
        ui.checkbox(
            &mut self.shading_map_on,
            "shading map: occlusion \u{b7} roughness \u{b7} metallic",
        );
        ui.checkbox(&mut self.relief_map_on, "relief map: bump normals");
        ui.checkbox(&mut self.emissive_map_on, "emissive map: per-texel glow");
    }
}

/// One light's own controls: a color, its strength and a shadow flag.
fn glow_controls(ui: &mut egui::Ui, label: &str, glow: &mut Glow) {
    ui.label(label);
    color_row(ui, "color", &mut glow.color);
    ui.add(egui::Slider::new(&mut glow.strength, 0.0..=8.0).text("strength"));
    ui.checkbox(&mut glow.shadow, "shadow");
}

/// One named control over `color`'s red, green and blue channels; alpha
/// stays `1.0`.
fn color_row(ui: &mut egui::Ui, label: &str, color: &mut Color) {
    let mut rgb = [color.red, color.green, color.blue];
    ui.horizontal(|ui| {
        ui.label(label);
        if ui.color_edit_button_rgb(&mut rgb).changed() {
            *color = Color::rgb(rgb[0], rgb[1], rgb[2]);
        }
    });
}

Additional examples can be found in:

• examples/ui-fonts.rs
• examples/animation.rs
• examples/flock-parallelism.rs
• examples/breakout-game.rs

pub const fn rgba(red: f32, green: f32, blue: f32, alpha: f32) -> Self

A color with opacity alpha, each channel and alpha a fraction of 1.0.

Examples found in repository

examples/sound-lab.rs (line 60)

const RANGE_COLOR: Color = Color::rgba(1.0, 1.0, 1.0, 0.35);
/// The inner ring drawn around a source, where its level stops being full.
const REFERENCE_COLOR: Color = Color::rgba(1.0, 0.85, 0.35, 0.5);

examples/sprite-adventure.rs (line 174)

const WATER_COLOR: Color = Color::rgba(0.06, 0.20, 0.27, 0.92);

pub const fn with_alpha(self, alpha: f32) -> Self

The same channels at opacity alpha, a fraction of 1.0.

Examples found in repository

examples/breakout-game.rs (line 675)

    fn draw_sparks(&self, ctx: &mut FrameContext<'_, Breakout>) {
        for spark in &self.sparks {
            let age = (spark.age / SPARK_LIFETIME).clamp(0.0, 1.0);
            let fade = 1.0 - age;
            let size = SPARK_SIZE_START.lerp(SPARK_SIZE_END, age);
            ctx.draw(
                Quad.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(size),
                    Quat::IDENTITY,
                    spark.position,
                ))
                .billboard()
                .roll(spark.roll + spark.age * SPARK_SPIN_SPEED)
                .material(
                    Material::color(spark.color.with_alpha(fade))
                        .emissive(spark.color.dimmed(SPARK_EMISSIVE_PEAK))
                        .additive(),
                ),
            );
        }
    }

    /// Draws the ball's ghost trail, each ghost smaller and more transparent
    /// than the one ahead of it; each ghost's position interpolates between
    /// its own last two resolved ticks by the same `alpha` the ball itself
    /// draws at, and its radius clamps to what the ball's own radius has
    /// left over its distance from the head, so a ghost still close to the
    /// ball never draws past its edge.
    fn draw_trail(&self, ctx: &mut FrameContext<'_, Breakout>, alpha: f32) {
        let head = self.ball_trail[1].lerp(self.ball_trail[0], alpha);
        for i in 0..TRAIL_LEN {
            let position = self.ball_trail[i + 1].lerp(self.ball_trail[i], alpha);
            let age = (i + 1) as f32 / TRAIL_LEN as f32;
            let fade = (1.0 - age).max(TRAIL_ALPHA_FLOOR);
            let radius = (BALL_RADIUS * TRAIL_SCALE_MIN.lerp(TRAIL_SCALE_MAX, fade))
                .min((BALL_RADIUS - head.distance(position)).max(0.0));
            let scale = Vec3::splat(radius * 2.0);
            ctx.draw(
                Sphere { subdivisions: 2 }
                    .at(Transform::from_scale_rotation_translation(
                        scale,
                        Quat::IDENTITY,
                        position,
                    ))
                    .material(
                        Material::color(BALL_GLOW.with_alpha(fade))
                            .emissive(BALL_EMISSIVE.dimmed(TRAIL_EMISSIVE_PEAK)),
                    ),
            );
        }
    }

pub const fn dimmed(self, factor: f32) -> Self

Its red, green, and blue scaled by factor, a fraction of each channel’s own value, keeping its opacity.

Examples found in repository

examples/breakout-game.rs (line 595)

    fn paddle_face_material(&self) -> Material {
        let t = (self.paddle_flash / PADDLE_FLASH).clamp(0.0, 1.0);
        let flash = PADDLE_FLASH_EMISSIVE.dimmed(t);
        let emissive = Color::rgb(
            PADDLE_AMBIENT_EMISSIVE.red + flash.red,
            PADDLE_AMBIENT_EMISSIVE.green + flash.green,
            PADDLE_AMBIENT_EMISSIVE.blue + flash.blue,
        );
        Material::lit(PADDLE_BASE).emissive(emissive)
    }

    fn draw_court(&self, ctx: &mut FrameContext<'_, Breakout>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    COURT_HALF_WIDTH * 2.0,
                    1.0,
                    COURT_HALF_DEPTH * 2.0,
                )))
                .material(Material::lit(FLOOR_COLOR)),
        );

        let side_half = Vec3::new(WALL_THICKNESS * 0.5, WALL_HEIGHT * 0.5, COURT_HALF_DEPTH);
        for side in [-1.0, 1.0] {
            let x = side * (COURT_HALF_WIDTH - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    side_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(x, side_half.y, 0.0),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }

        let top_half = Vec3::new(COURT_HALF_WIDTH, WALL_HEIGHT * 0.5, WALL_THICKNESS * 0.5);
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                top_half * 2.0,
                Quat::IDENTITY,
                Vec3::new(0.0, top_half.y, -COURT_HALF_DEPTH + WALL_THICKNESS * 0.5),
            ))
            .material(Material::lit(WALL_COLOR)),
        );
    }

    fn draw_bricks(&self, ctx: &mut FrameContext<'_, Breakout>) {
        let scale = Vec3::new(
            BRICK_HALF_WIDTH * 2.0,
            BRICK_HALF_HEIGHT * 2.0,
            BRICK_HALF_DEPTH * 2.0,
        );
        for brick in self.bricks.iter().filter(|brick| brick.hits_remaining > 0) {
            let health = f32::from(brick.hits_remaining) / f32::from(BRICK_HITS);
            let color = BRICK_ROW_COLORS[brick.row].dimmed(0.4 + 0.6 * health);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    scale,
                    Quat::IDENTITY,
                    brick.position,
                ))
                .material(Material::shaded(color, health)),
            );
        }
    }

    /// Draws the live spark burst: additive, tumbling by roll as they age,
    /// shrinking and fading out over their lifetime.
    fn draw_sparks(&self, ctx: &mut FrameContext<'_, Breakout>) {
        for spark in &self.sparks {
            let age = (spark.age / SPARK_LIFETIME).clamp(0.0, 1.0);
            let fade = 1.0 - age;
            let size = SPARK_SIZE_START.lerp(SPARK_SIZE_END, age);
            ctx.draw(
                Quad.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(size),
                    Quat::IDENTITY,
                    spark.position,
                ))
                .billboard()
                .roll(spark.roll + spark.age * SPARK_SPIN_SPEED)
                .material(
                    Material::color(spark.color.with_alpha(fade))
                        .emissive(spark.color.dimmed(SPARK_EMISSIVE_PEAK))
                        .additive(),
                ),
            );
        }
    }

    /// Draws the ball's ghost trail, each ghost smaller and more transparent
    /// than the one ahead of it; each ghost's position interpolates between
    /// its own last two resolved ticks by the same `alpha` the ball itself
    /// draws at, and its radius clamps to what the ball's own radius has
    /// left over its distance from the head, so a ghost still close to the
    /// ball never draws past its edge.
    fn draw_trail(&self, ctx: &mut FrameContext<'_, Breakout>, alpha: f32) {
        let head = self.ball_trail[1].lerp(self.ball_trail[0], alpha);
        for i in 0..TRAIL_LEN {
            let position = self.ball_trail[i + 1].lerp(self.ball_trail[i], alpha);
            let age = (i + 1) as f32 / TRAIL_LEN as f32;
            let fade = (1.0 - age).max(TRAIL_ALPHA_FLOOR);
            let radius = (BALL_RADIUS * TRAIL_SCALE_MIN.lerp(TRAIL_SCALE_MAX, fade))
                .min((BALL_RADIUS - head.distance(position)).max(0.0));
            let scale = Vec3::splat(radius * 2.0);
            ctx.draw(
                Sphere { subdivisions: 2 }
                    .at(Transform::from_scale_rotation_translation(
                        scale,
                        Quat::IDENTITY,
                        position,
                    ))
                    .material(
                        Material::color(BALL_GLOW.with_alpha(fade))
                            .emissive(BALL_EMISSIVE.dimmed(TRAIL_EMISSIVE_PEAK)),
                    ),
            );
        }
    }

examples/sprite-adventure.rs (line 1694)

    fn draw_gem(&self, ctx: &mut FrameContext<'_, Keep>) {
        let t = self.simulated.as_secs_f32();
        let bob = (t * 2.0).sin() * GEM_BOB_HEIGHT;
        ctx.light(
            Light::point(
                GEM_POSITION + Vec3::Y * (bob + GEM_LIGHT_LIFT),
                GEM_LIGHT_COLOR,
                GEM_LIGHT_RANGE,
            )
            .shadow(),
        );
        ctx.draw(
            Gem.at(Transform::from_scale_rotation_translation(
                Vec3::ONE,
                Quat::from_rotation_y(t * GEM_SPIN_SPEED),
                GEM_POSITION + Vec3::Y * bob,
            ))
            .material(Material::shaded(GEM_COLOR, 0.7).emissive(GEM_COLOR.dimmed(1.6))),
        );
    }

examples/sound-lab.rs (line 555)

    fn draw_sources(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        for (index, source) in self.sources.iter().enumerate() {
            let color = SOURCE_COLORS[index];
            let picked_up = self.dragging == Some(index);
            let scale = if picked_up { 1.3 } else { 1.0 };
            let emissive = if source.enabled {
                Color::rgb(color.red * 3.0, color.green * 3.0, color.blue * 3.0)
            } else {
                color.dimmed(0.15)
            };

            for (radius, ring_color) in [
                (source.range, RANGE_COLOR),
                (source.reference, REFERENCE_COLOR),
            ] {
                ctx.draw(
                    Ring.at(Transform::from_scale_rotation_translation(
                        Vec3::new(radius, 1.0, radius),
                        Quat::IDENTITY,
                        Vec3::new(source.position.x, 0.01, source.position.z),
                    ))
                    .material(Material::color(ring_color)),
                );
            }
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0 * scale),
                    Quat::IDENTITY,
                    source.position,
                ))
                .material(Material::shaded(color, 0.6).emissive(emissive)),
            );
        }
    }

    /// The listener: a cube drawn from the ground up to [`EYE_HEIGHT`],
    /// an ear pair set on ± `view`'s right, and a marker at the front that
    /// shows its fixed `-Z` facing.
    fn draw_listener(&self, ctx: &mut FrameContext<'_, SoundCheck>, view: View) {
        let head = view.eye();
        let ground = Vec3::new(head.x, 0.0, head.z);

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LISTENER_WIDTH, head.y, LISTENER_DEPTH),
                Quat::IDENTITY,
                ground + Vec3::Y * head.y * 0.5,
            ))
            .material(Material::lit(LISTENER_COLOR)),
        );

        let right = listener_right(view) * EAR_OFFSET;
        for (offset, color) in [(right, RIGHT_EAR_COLOR), (-right, LEFT_EAR_COLOR)] {
            ctx.draw(
                Sphere { subdivisions: 1 }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(EAR_SIZE),
                        Quat::IDENTITY,
                        head + offset,
                    ))
                    .material(Material::lit(color)),
            );
        }

        ctx.draw(
            Facing
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FACING_MARKER_SIZE),
                    Quat::IDENTITY,
                    head + Vec3::NEG_Z * (FACING_MARKER_SIZE * 0.5),
                ))
                .material(Material::lit(LISTENER_COLOR)),
        );
    }

    fn draw_merge_markers(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.merge_demo {
            return;
        }
        for (position, color) in [(MERGE_POS_A, MERGE_COLOR_A), (MERGE_POS_B, MERGE_COLOR_B)] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0),
                    Quat::IDENTITY,
                    position,
                ))
                .material(Material::lit(color)),
            );
        }
    }

    /// Draws the ring, each cube as dim as the gain its sustain is declared
    /// at.
    fn draw_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let over = 1.0 - nth as f32 / RING_COUNT as f32;
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF),
                    Quat::IDENTITY,
                    ring_place(nth),
                ))
                .material(Material::lit(RING_COLOR.dimmed(over))),
            );
        }
    }

Trait Implementations

impl Clone for Color

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Color

impl Debug for Color

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

Formats the value using the given formatter.

impl Default for Color

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for Color

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

Equality operator ==.

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

Inequality operator !=.

impl Pod for Color

impl StructuralPartialEq for Color

impl Zeroable for Color

fn zeroed() -> Self

Calls zeroed.