Struct Vec2 

#[repr(C)]
pub struct Vec2 {
    pub x: f32,
    pub y: f32,
}

A 2-dimensional vector.

Fields

x: f32

y: f32

Implementations

impl Vec2

pub const ZERO: Vec2

All zeroes.

pub const ONE: Vec2

All ones.

pub const NEG_ONE: Vec2

All negative ones.

pub const MIN: Vec2

All f32::MIN.

pub const MAX: Vec2

All f32::MAX.

pub const NAN: Vec2

All f32::NAN.

pub const INFINITY: Vec2

All f32::INFINITY.

pub const NEG_INFINITY: Vec2

All f32::NEG_INFINITY.

pub const X: Vec2

A unit vector pointing along the positive X axis.

pub const Y: Vec2

A unit vector pointing along the positive Y axis.

pub const NEG_X: Vec2

A unit vector pointing along the negative X axis.

pub const NEG_Y: Vec2

A unit vector pointing along the negative Y axis.

pub const AXES: [Vec2; 2]

The unit axes.

pub const USES_CORE_SIMD: bool = false

Vec2 uses Rust Portable SIMD

pub const USES_NEON: bool = false

Vec2 uses Arm NEON

pub const USES_SCALAR_MATH: bool = true

Vec2 uses scalar math

pub const USES_SSE2: bool = false

Vec2 uses Intel SSE2

pub const USES_WASM_SIMD: bool = false

Vec2 uses WebAssembly 128-bit SIMD

pub const USES_WASM32_SIMD: bool = false

👎Deprecated since 0.31.0:

Renamed to USES_WASM_SIMD

pub const fn new(x: f32, y: f32) -> Vec2

Creates a new vector.

Examples found in repository

examples/animation.rs (line 165)

const BUTTERFLY_RADIUS: Vec2 = Vec2::new(1.8, 1.4);

examples/stress-preview.rs (line 560)

fn push_face(vertices: &mut Vec<Vertex>, indices: &mut Vec<u32>, a: Vec3, b: Vec3, c: Vec3) {
    let normal = (b - a).cross(c - a).normalize();
    let uvs = [
        Vec2::new(0.0, 1.0),
        Vec2::new(0.5, 0.0),
        Vec2::new(1.0, 1.0),
    ];
    let base = vertices.len() as u32;
    for (point, uv) in [a, b, c].into_iter().zip(uvs) {
        vertices.push(Vertex::new(point, normal, uv));
    }
    indices.extend([base, base + 1, base + 2]);
}

examples/sprite-adventure.rs (line 488)

    fn push_out(self, point: Vec2, radius: f32) -> Vec2 {
        let delta = point - self.center;
        let escape = self.half + Vec2::splat(radius) - delta.abs();

        if escape.min_element() <= 0.0 {
            point
        } else if escape.x < escape.y {
            let x = self.center.x + delta.x.signum() * (self.half.x + radius);
            Vec2::new(x, point.y)
        } else {
            let z = self.center.y + delta.y.signum() * (self.half.y + radius);
            Vec2::new(point.x, z)
        }
    }
}

/// A cave mouth's opening: where it is, and which way along `Z` the room
/// it leads out of lies.
#[derive(Clone, Copy)]
struct Mouth {
    at: Vec3,
    room_side: f32,
}

impl Mouth {
    /// True where `position` lies between the pillars and past the plane
    /// in front of the opening — where the only two outcomes are stepping
    /// through and being held.
    fn holds(&self, position: Vec3) -> bool {
        let plane = self.at.z + self.room_side * MOUTH_CROSSING_INSET;

        (position.x - self.at.x).abs() < MOUTH_OPENING_HALF
            && (plane - position.z) * self.room_side > 0.0
    }

    /// Position of each of the two pillars flanking the opening.
    fn pillars(&self) -> impl Iterator<Item = Vec3> + Clone {
        let at = self.at;

        SIDES
            .into_iter()
            .map(move |side| at + Vec3::X * (side * MOUTH_PILLAR_OFFSET))
    }

    /// True when the camera looks into this mouth: it always lies on `+Z`
    /// of the player, so the mouth whose room lies that way is the one seen
    /// from the room's side, and the one to fill with a lintel and the dark
    /// under it. The other is looked through from behind, and leaves its
    /// opening clear for the room to show through.
    fn looked_into(&self) -> bool {
        self.room_side > 0.0
    }
}

// ---------------------------------------------------------------------
// The water style
// ---------------------------------------------------------------------

/// The pond's whole look, over the one value it reads: how far its ripple
/// has traveled.
#[derive(Default, ShaderValues)]
struct Water {
    time: f32,
}

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

surface_styles! { enum Looks { Water } }

// ---------------------------------------------------------------------
// Meshes
// ---------------------------------------------------------------------

/// The player's current area; never both drawn in one frame.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Area {
    Overworld,
    Cave,
}

/// The overworld's ground tile, its texture the only thing that separates a
/// draw of it from another.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Ground;

impl Mesh for Ground {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(GROUND_SHEET).pixelated())
    }
}

/// The shoreline sprite laid over the pond's styled water, cutout so the
/// water shows through its cleared middle.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Shore;

impl Mesh for Shore {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(POND_SHEET).pixelated())
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A crate prop, its texture drawn over a cube.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Crate;

impl Mesh for Crate {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(CRATE_TEXTURE).pixelated())
    }
}

/// The well's rim.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Well;

impl Mesh for Well {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(WELL_SHEET).pixelated())
    }
}

/// The well's mouth, laid flat over the rim's top face.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct WellMouth;

impl Mesh for WellMouth {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(WELL_SHEET).pixelated())
    }
}

/// A stone box: the mouth's pillars and lintel.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Stone;

impl Mesh for Stone {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(STONE_SHEET).pixelated())
    }
}

/// A bush sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Bush;

impl Mesh for Bush {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(BUSH_SPRITE).pixelated())
            .with_relief(assets.relief(BUSH_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A rock sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Rock;

impl Mesh for Rock {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(ROCK_SPRITE).pixelated())
            .with_relief(assets.relief(ROCK_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A torch's post sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Torch;

impl Mesh for Torch {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(TORCH_SPRITE).pixelated())
            .with_relief(assets.relief(TORCH_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A torch's flame sprite, added over the dark rather than lit.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Flame;

impl Mesh for Flame {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(FLAME_SHEET).pixelated())
            .with_material(Material::color(FLAME_TINT).additive())
    }
}

/// The player's sprite, cutout with its own relief, its sheet shared
/// with `examples/isometric-board.rs`.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Walker;

impl Mesh for Walker {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(WALKER_SHEET).pixelated())
            .with_relief(assets.relief(WALKER_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// The cave floor tile.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct CaveFloor;

impl Mesh for CaveFloor {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(CAVE_SHEET).pixelated())
    }
}

/// The cave wall face.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct CaveWall;

impl Mesh for CaveWall {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(CAVE_SHEET).pixelated())
    }
}

/// The loaded door, drawn as its source authored it.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Door;

impl Mesh for Door {
    fn build(&self, assets: &Assets) -> MeshData {
        assets.mesh(DOOR_MESH)
    }
}

/// The loaded gem, repainted whole per draw so its glow color shifts.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Gem;

impl Mesh for Gem {
    fn build(&self, assets: &Assets) -> MeshData {
        assets.mesh(GEM_MESH)
    }
}

// Everything this game can draw: the meshes above, plus the styled water,
// the dark filling a looked-into mouth's opening, and the door's own frame,
// which draw the bare engine primitives Plane, Quad and Cube.
meshes! {
    enum Shape {
        Ground, Shore, Crate, Well, WellMouth, Stone, Bush, Rock, Torch,
        Flame, Walker, CaveFloor, CaveWall, Door, Gem, Plane, Quad, Cube,
    }
}

/// The interact click and the gem's chime, shared with the other examples.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
enum Sound {
    Interact,
    Gem,
}

impl Sounds for Sound {
    fn build(&self, assets: &Assets) -> SoundData {
        match self {
            Sound::Interact => assets.sound("click"),
            Sound::Gem => assets.sound("win"),
        }
    }
}

// ---------------------------------------------------------------------
// Input
// ---------------------------------------------------------------------

/// Player movement: `WASD`, arrows, or a stick — the strongest reading is
/// kept.
#[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::from(ButtonAxis2 {
                    left: Key::Left,
                    right: Key::Right,
                    down: Key::Down,
                    up: Key::Up,
                }),
                Axis2Binding::stick(Stick::Left),
            ],
        }
    }
}

/// The two verbs this game reads as an edge: interacting with the door, and
/// a reset of the world to every saved key's fallback.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Button {
    Interact,
    Reset,
}

impl InputButtonAction for Button {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Button::Interact => vec![Key::E.into(), Pad::West.into()],
            Button::Reset => vec![Key::R.into()],
        }
    }
}

struct Controls;

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

// ---------------------------------------------------------------------
// Save data
// ---------------------------------------------------------------------

/// The player's last position, read at startup and saved on area
/// transition and gem pickup.
#[derive(Saves, Clone, Copy)]
enum Position {
    X,
    Z,
}

impl SaveKey for Position {
    type Value = f64;

    fn fallback(&self) -> f64 {
        match self {
            Position::X => PLAYER_SPAWN.x as f64,
            Position::Z => PLAYER_SPAWN.z as f64,
        }
    }
}

/// The area the player is in, and whether the gem is taken.
#[derive(Saves, Clone, Copy)]
enum Flag {
    InCave,
    GemTaken,
}

impl SaveKey for Flag {
    type Value = bool;

    fn fallback(&self) -> bool {
        false
    }
}

// ---------------------------------------------------------------------
// The player's facing
// ---------------------------------------------------------------------

/// The player's last facing: also its row in the sheet, top to bottom.
#[derive(Clone, Copy, PartialEq)]
enum Facing {
    Toward = 0,
    Right = 1,
    Away = 2,
    Left = 3,
}

impl Facing {
    /// The facing `heading` points in, favoring its larger axis; `None` at
    /// rest, so the caller can keep the last facing.
    fn from_heading(heading: Vec2) -> Option<Self> {
        if heading == Vec2::ZERO {
            return None;
        }
        Some(if heading.x.abs() > heading.y.abs() {
            if heading.x > 0.0 {
                Self::Right
            } else {
                Self::Left
            }
        } else if heading.y > 0.0 {
            Self::Away
        } else {
            Self::Toward
        })
    }
}

// ---------------------------------------------------------------------
// The game
// ---------------------------------------------------------------------

/// The ground tile at `col, row`: the path's dirt along [`PATH_COLUMN`],
/// the verges that edge it, and a hashed grass variant everywhere else.
fn ground_cell(col: i32, row: i32) -> Frame {
    let (column, sheet_row) = match col - PATH_COLUMN {
        0 => (PATH_DIRT + row.rem_euclid(2) as u32, PATH_ROW),
        -1 => (PATH_WEST_VERGE, PATH_ROW),
        1 => (PATH_EAST_VERGE, PATH_ROW),
        _ => (
            (col * 31 + row * 17).rem_euclid(GROUND_COLUMNS as i32) as u32,
            GRASS_ROW,
        ),
    };

    Sheet::new(UVec2::new(GROUND_COLUMNS, GROUND_ROWS)).cell_at(UVec2::new(column, sheet_row))
}

/// The stone sheet's plain masonry, laid `tiles` times across: the sampler
/// wraps, so a window wider than the sheet repeats the course.
fn masonry(tiles: f32) -> Frame {
    let course = 1.0 / STONE_ROWS as f32;

    Frame::rect(Vec2::new(0.0, 1.0 - course), Vec2::new(tiles, 1.0))
}

/// The wall or door's alpha `fraction` of the way from [`SOLID`] to
/// [`GHOST_ALPHA`].
fn ghost_alpha(fraction: f32) -> f32 {
    SOLID + (GHOST_ALPHA - SOLID) * fraction
}

/// The wall face in column `variant`, windowed to the meters `standing` of
/// one course, measured up from that course's own base: every row of the
/// cave sheet below the floor's covers [`WALL_HEIGHT`], so a course keeps
/// the floor's texels to the meter however it is cut.
fn cave_wall_face(variant: u32, standing: Range<f32>) -> Frame {
    let cell = Vec2::new(1.0 / CAVE_COLUMNS as f32, 1.0 / CAVE_ROWS as f32);
    let left = (variant % CAVE_COLUMNS) as f32 * cell.x;
    let face = (CAVE_FLOOR_ROW + 1) as f32 * cell.y;
    let up_from_base = |height: f32| 1.0 - (1.0 - face) * (height / WALL_HEIGHT);

    Frame::rect(
        Vec2::new(left, up_from_base(standing.end)),
        Vec2::new(left + cell.x, up_from_base(standing.start)),
    )
}

/// The logical point egui paints the physical pixel `pixel` at.
fn logical(pixel: Vec2, pixels_per_point: f32) -> egui::Pos2 {
    let point = pixel / pixels_per_point;
    egui::pos2(point.x, point.y)
}

fn main() {
    run(
        Config::new("Mirage: sprite adventure")
            .with_size(1280, 720)
            .with_assets([
                MODEL,
                WALKER_SOURCE,
                WALKER_RELIEF_SOURCE,
                GROUND_SOURCE,
                BUSH_SOURCE,
                BUSH_RELIEF_SOURCE,
                ROCK_SOURCE,
                ROCK_RELIEF_SOURCE,
                TORCH_RELIEF_SOURCE,
                CRATE_SOURCE,
                WELL_SOURCE,
                STONE_SOURCE,
                CAVE_SOURCE,
                POND_SOURCE,
                TORCH_SOURCE,
                FLAME_SOURCE,
                INTERACT_SOUND,
                GEM_SOUND,
            ]),
        Keep::init,
    );
}

struct Keep {
    area: Area,
    position: Vec3,
    previous: Vec3,
    facing: Facing,
    walk_ticks: u32,
    simulated: Duration,
    door_opening: bool,
    /// Ticks the door has been opening for, at a cap of
    /// [`DOOR_SWING_TICKS`]: how long its world prompt reads "opening" once
    /// it starts.
    swing_ticks: u32,
    gem_taken: bool,
    /// How far the door wall's fade from [`SOLID`] to [`GHOST_ALPHA`] has
    /// run as of the last tick: `0.0` to `1.0`.
    ghost: f32,
    /// Set by the panel's reset button, since its click lands in a frame
    /// rather than a tick; read and cleared on the next tick.
    reset_requested: bool,
}

impl Keep {
    /// Prepares every startup-cataloged mesh and resumes wherever the last
    /// run left the player.
    fn init(ctx: &mut InitContext<'_, Keep>) -> Result<Self, Error> {
        let startup = ctx.startup();
        let gem_taken = startup.saved(Flag::GemTaken);
        let area = if startup.saved(Flag::InCave) {
            Area::Cave
        } else {
            Area::Overworld
        };
        let position = Vec3::new(
            startup.saved(Position::X) as f32,
            0.0,
            startup.saved(Position::Z) as f32,
        );

        Ok(Self {
            area,
            position,
            previous: position,
            facing: Facing::Toward,
            walk_ticks: 0,
            simulated: Duration::ZERO,
            door_opening: gem_taken,
            swing_ticks: if gem_taken { DOOR_SWING_TICKS } else { 0 },
            gem_taken,
            ghost: 0.0,
            reset_requested: false,
        })
    }

    fn camera(position: Vec3, offset: Vec3) -> Camera {
        Camera::new(
            View::look_at(position + offset, position),
            Projection::perspective(CAMERA_FOV),
        )
    }

    /// Obstacles from the overworld's props: the crates, turned as they are
    /// drawn, the well's rim, the open water the shoreline rings, the
    /// mouth's pillars, and each flora's base.
    fn overworld_obstacles() -> impl Iterator<Item = Obstacle> + Clone {
        CRATE_POSITIONS
            .into_iter()
            .map(|(x, z, turn)| {
                Obstacle::footprint(Vec2::new(x, z), Vec2::splat(CRATE_SIZE * turned_span(turn)))
            })
            .chain([
                Obstacle::footprint(WELL_POSITION.xz(), WELL_SIZE.xz()),
                Obstacle::footprint(POND_CENTER.xz(), Vec2::splat(POND_WATER_HALF * 2.0)),
            ])
            .chain(
                ENTRANCE
                    .pillars()
                    .map(|at| Obstacle::footprint(at.xz(), MOUTH_PILLAR_SIZE.xz())),
            )
            .chain(FLORA.into_iter().map(|(x, z, rock)| {
                let base = if rock { ROCK_FOOTPRINT } else { BUSH_FOOTPRINT };
                Obstacle::footprint(Vec2::new(x, z), Vec2::splat(base))
            }))
    }

    /// Obstacles from the cave: the torch posts, its own mouth's pillars,
    /// the runs of wall either side of the doorway and of the mouth, and the
    /// `door` leaf.
    fn cave_obstacles(door: Obstacle) -> impl Iterator<Item = Obstacle> + Clone {
        TORCH_POSITIONS
            .into_iter()
            .map(|(x, z)| Obstacle::footprint(Vec2::new(x, z), Vec2::splat(TORCH_STAND_WIDTH)))
            .chain(
                EXIT.pillars()
                    .map(|at| Obstacle::footprint(at.xz(), MOUTH_PILLAR_SIZE.xz())),
            )
            .chain(SIDES.into_iter().flat_map(|side| {
                [
                    Self::wall_run(side, DOOR_Z),
                    Self::wall_run(side, CAVE_LIP_Z),
                ]
            }))
            .chain([door])
    }

    /// One of the two runs of wall either side of a one-tile opening on the
    /// room's axis, at `z`.
    fn wall_run(side: f32, z: f32) -> Obstacle {
        Obstacle::footprint(
            Vec2::new(side * (DOORWAY_HALF + DOOR_WALL_END) * 0.5, z),
            Vec2::new(DOOR_WALL_END - DOORWAY_HALF, TILE_SIZE),
        )
    }

    /// Obstacle from the door leaf's own footprint: the box over its four
    /// corners, swung back against the wall once the door is opened.
    fn door_obstacle(&self) -> Obstacle {
        let hinge = DOOR_HINGE.xz();
        let across = DOOR_THICKNESS * 0.5;
        let corner = |along: f32, aside: f32| {
            let (x, z) = if self.door_opening {
                (aside, -along)
            } else {
                (along, aside)
            };
            hinge + Vec3::new(x, 0.0, z).xz()
        };

        Obstacle::over([
            corner(0.0, -across),
            corner(0.0, across),
            corner(DOOR_WIDTH, -across),
            corner(DOOR_WIDTH, across),
        ])
    }

    /// Pushes the player out of every obstacle their circle has walked into,
    /// over as many passes as it takes for one to leave them where the last
    /// one did — overlapping obstacles need more than one.
    fn push_out_of(&mut self, obstacles: impl Iterator<Item = Obstacle> + Clone) {
        /// Passes an overlap is given to settle before the frame takes what
        /// it has; ones this game builds settle in two.
        const PASSES: u32 = 4;

        let mut standing = self.position.xz();
        for _ in 0..PASSES {
            let settled = obstacles.clone().fold(standing, |point, obstacle| {
                obstacle.push_out(point, PLAYER_RADIUS)
            });
            if settled == standing {
                break;
            }
            standing = settled;
        }

        self.position.x = standing.x;
        self.position.z = standing.y;
    }

    fn tick_overworld(&mut self, ctx: &mut TickContext<'_, Keep>) {
        self.push_out_of(Self::overworld_obstacles());
        self.position.x = self.position.x.clamp(-CLEARING_HALF, CLEARING_HALF);
        self.position.z = self.position.z.clamp(-CLEARING_HALF, CLEARING_HALF);

        if ENTRANCE.holds(self.position) {
            if ENTRANCE.holds(self.previous) {
                self.position.z = self.previous.z;
            } else {
                self.enter_cave(ctx);
            }
        }
    }

    fn tick_cave(&mut self, ctx: &mut TickContext<'_, Keep>) {
        self.push_out_of(Self::cave_obstacles(self.door_obstacle()));
        self.position.x = self.position.x.clamp(-CAVE_HALF_WIDTH, CAVE_HALF_WIDTH);
        self.position.z = self.position.z.clamp(CAVE_WALK_FAR_Z, CAVE_WALK_NEAR_Z);

        let target = if self.position.z < DOOR_WALL_NEAR_Z {
            1.0
        } else {
            0.0
        };
        let step = 1.0 / GHOST_RAMP_TICKS as f32;
        self.ghost += (target - self.ghost).clamp(-step, step);

        if !self.door_opening
            && ctx.pressed(Button::Interact)
            && self.position.distance(INTERACT_POINT) < INTERACT_RADIUS
        {
            self.door_opening = true;
            self.swing_ticks = 0;
            ctx.play(Sound::Interact);
        }
        if self.door_opening && self.swing_ticks < DOOR_SWING_TICKS {
            self.swing_ticks += 1;
        }

        if !self.gem_taken && self.position.distance(GEM_POSITION) < PICKUP_RADIUS {
            self.gem_taken = true;
            ctx.play(Sound::Gem);
            ctx.save(Flag::GemTaken, true);
            ctx.save(Position::X, self.position.x as f64);
            ctx.save(Position::Z, self.position.z as f64);
        }

        if EXIT.holds(self.position) {
            if EXIT.holds(self.previous) {
                self.position.z = self.previous.z;
            } else {
                self.exit_cave(ctx);
            }
        }
    }

    /// Puts the player back at [`PLAYER_SPAWN`] with the cave and the gem
    /// returned to their saved fallbacks, all in this tick: a reset saves
    /// every key's own fallback, since there is nothing to clear it to.
    fn reset(&mut self, ctx: &mut TickContext<'_, Keep>) {
        ctx.save(Position::X, Position::X.fallback());
        ctx.save(Position::Z, Position::Z.fallback());
        ctx.save(Flag::InCave, Flag::InCave.fallback());
        ctx.save(Flag::GemTaken, Flag::GemTaken.fallback());

        self.area = Area::Overworld;
        self.position = PLAYER_SPAWN;
        self.previous = PLAYER_SPAWN;
        self.gem_taken = false;
        self.door_opening = false;
        self.swing_ticks = 0;
        self.ghost = 0.0;
    }

    /// Steps into the cave at [`CAVE_SPAWN`], saving the transition.
    fn enter_cave(&mut self, ctx: &mut TickContext<'_, Keep>) {
        self.area = Area::Cave;
        self.position = CAVE_SPAWN;
        self.previous = CAVE_SPAWN;
        ctx.save(Flag::InCave, true);
        ctx.save(Position::X, CAVE_SPAWN.x as f64);
        ctx.save(Position::Z, CAVE_SPAWN.z as f64);
    }

    /// Steps back out to the mouth at [`RETURN_SPAWN`], saving the
    /// transition.
    fn exit_cave(&mut self, ctx: &mut TickContext<'_, Keep>) {
        self.area = Area::Overworld;
        self.position = RETURN_SPAWN;
        self.previous = RETURN_SPAWN;
        ctx.save(Flag::InCave, false);
        ctx.save(Position::X, RETURN_SPAWN.x as f64);
        ctx.save(Position::Z, RETURN_SPAWN.z as f64);
    }

    fn draw_ground(&self, ctx: &mut FrameContext<'_, Keep>) {
        for col in -GROUND_DRAW_HALF..=GROUND_DRAW_HALF {
            for row in -GROUND_DRAW_HALF..=GROUND_DRAW_HALF {
                ctx.draw(
                    Ground
                        .at(Vec3::new(
                            col as f32 * TILE_SIZE,
                            0.0,
                            row as f32 * TILE_SIZE,
                        ))
                        .frame(ground_cell(col, row)),
                );
            }
        }
    }

    /// Two staggered rows of bushes around the clearing, open where the path
    /// leaves it, drawn between the camera and the ground's edge. The rows
    /// running along `Z` skip their two ends, which the rows running along
    /// `X` already cover.
    fn draw_hedgerow(&self, ctx: &mut FrameContext<'_, Keep>) {
        for (row, half) in [HEDGE_INNER_HALF, HEDGE_OUTER_HALF].into_iter().enumerate() {
            let row = row as i32;
            // The inner row covers both corners; the outer one is half a
            // span in from each, backing the gaps the inner row leaves.
            let spans = ((2.0 * half / HEDGE_STEP).round() as i32).max(1);
            let span = 2.0 * half / spans as f32;
            let steps = spans - row;
            for step in 0..=steps {
                let along = -half + (step as f32 + 0.5 * row as f32) * span;
                let scale = if (step + row) % 2 == 0 { 1.0 } else { 0.8 };
                let (width, height) = (BUSH_WIDTH * scale, BUSH_HEIGHT * scale);
                // The path leaves through the rows running along `X`, so only
                // those two open around it.
                let gated = along.abs() < HEDGE_GATE_HALF;
                let corner = step == 0 || step == steps;
                let places = [
                    (along, -half, gated),
                    (along, half, gated),
                    (-half, along, corner),
                    (half, along, corner),
                ];
                for (x, z, skip) in places {
                    if skip {
                        continue;
                    }
                    ctx.draw(
                        Bush.at(Transform::from_scale_rotation_translation(
                            Vec3::new(width, height, width),
                            Quat::IDENTITY,
                            Vec3::new(x, height * 0.5, z),
                        ))
                        .upright(),
                    );
                }
            }
        }
    }

    /// The pond: a square of styled water, and the shoreline sprite laid over
    /// it, which rings the open middle and hides the water's own edges.
    fn draw_pond(&self, ctx: &mut FrameContext<'_, Keep>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(POND_WATER_HALF * 2.0),
                    Quat::IDENTITY,
                    POND_CENTER,
                ))
                .material(Material::shaded(WATER_COLOR, WATER_LITNESS))
                .surface_style::<Water>(),
        );
        ctx.draw(
            Shore
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(POND_HALF * 2.0),
                    Quat::IDENTITY,
                    Vec3::new(POND_CENTER.x, 0.0, POND_CENTER.z),
                ))
                .frame(Sheet::new(UVec2::new(POND_CELLS, 1)).cell(POND_SHORE_CELL)),
        );
    }

    fn draw_crates(&self, ctx: &mut FrameContext<'_, Keep>) {
        for &(x, z, turn) in &CRATE_POSITIONS {
            ctx.draw(Crate.at(Transform::from_scale_rotation_translation(
                Vec3::splat(CRATE_SIZE),
                Quat::from_rotation_y(turn),
                Vec3::new(x, CRATE_SIZE * 0.5, z),
            )));
        }
    }

    /// The well: its rim in grey masonry, and the mouth cell laid over the
    /// rim's top face.
    fn draw_well(&self, ctx: &mut FrameContext<'_, Keep>) {
        let cells = Sheet::new(UVec2::new(WELL_CELLS, 1));
        ctx.draw(
            Well.at(Transform::from_scale_rotation_translation(
                WELL_SIZE,
                Quat::IDENTITY,
                WELL_POSITION + Vec3::Y * (WELL_SIZE.y * 0.5),
            ))
            .frame(cells.cell(WELL_RIM_CELL)),
        );
        ctx.draw(
            WellMouth
                .at(Transform::from_scale_rotation_translation(
                    Vec3::new(WELL_SIZE.x, 1.0, WELL_SIZE.z),
                    Quat::IDENTITY,
                    WELL_POSITION + Vec3::Y * (WELL_SIZE.y + WELL_MOUTH_LIFT),
                ))
                .frame(cells.cell(WELL_MOUTH_CELL)),
        );
    }

    fn draw_flora(&self, ctx: &mut FrameContext<'_, Keep>) {
        for &(x, z, rock) in &FLORA {
            let (width, height) = if rock {
                (ROCK_WIDTH, ROCK_HEIGHT)
            } else {
                (BUSH_WIDTH, BUSH_HEIGHT)
            };
            let standing = Transform::from_scale_rotation_translation(
                Vec3::new(width, height, width),
                Quat::IDENTITY,
                Vec3::new(x, height * 0.5, z),
            );
            let flora: Instance<Shape, _> = if rock {
                Rock.at(standing).into_set()
            } else {
                Bush.at(standing).into_set()
            };
            ctx.draw(flora.upright());
        }
    }

    /// One stone box drawn on the ground at `at`, `size` across, sampling
    /// the part of the sheet `frame` covers.
    fn draw_stone(ctx: &mut FrameContext<'_, Keep>, at: Vec3, size: Vec3, frame: Frame) {
        ctx.draw(
            Stone
                .at(Transform::from_scale_rotation_translation(
                    size,
                    Quat::IDENTITY,
                    at + Vec3::Y * (size.y * 0.5),
                ))
                .frame(frame),
        );
    }

    /// Two stone pillars drawn where `mouth` blocks the player, each a
    /// capital over its own course of masonry, and, on the one the camera
    /// looks into, the lintel across their tops and the dark filling
    /// the opening under it.
    fn draw_mouth(ctx: &mut FrameContext<'_, Keep>, mouth: Mouth) {
        for at in mouth.pillars() {
            Self::draw_stone(ctx, at, MOUTH_PILLAR_SIZE, Frame::default());
        }
        if !mouth.looked_into() {
            return;
        }

        Self::draw_stone(
            ctx,
            mouth.at + Vec3::Y * MOUTH_PILLAR_SIZE.y,
            MOUTH_LINTEL_SIZE,
            masonry(MOUTH_LINTEL_TILES),
        );
        ctx.draw(
            Quad.at(Transform::from_scale_rotation_translation(
                Vec3::new(MOUTH_PILLAR_OFFSET * 2.0, MOUTH_DARK_HEIGHT, 1.0),
                Quat::IDENTITY,
                mouth.at + Vec3::Y * (MOUTH_DARK_HEIGHT * 0.5),
            ))
            .material(Material::color(Color::BLACK)),
        );
    }

    fn draw_cave_floor(&self, ctx: &mut FrameContext<'_, Keep>) {
        let half = CAVE_HALF_WIDTH as i32;
        let near = CAVE_NEAR_Z as i32;
        let far = CAVE_FAR_Z as i32;
        for col in -half..=half {
            for row in far..=near {
                let variant = (col * 13 + row * 7).rem_euclid(CAVE_COLUMNS as i32) as u32;
                ctx.draw(
                    CaveFloor
                        .at(Vec3::new(
                            col as f32 * TILE_SIZE,
                            0.0,
                            row as f32 * TILE_SIZE,
                        ))
                        .frame(
                            Sheet::new(UVec2::new(CAVE_COLUMNS, CAVE_ROWS))
                                .cell_at(UVec2::new(variant, CAVE_FLOOR_ROW)),
                        ),
                );
            }
        }
    }

    /// The wall drawn at `at` over the meters `standing`, in courses
    /// [`WALL_HEIGHT`] tall from the floor up, each cut to the part of it the
    /// span leaves; its faces are picked by `seed` and its stone faded to
    /// `fade`, which is `1.0` wherever it is solid.
    fn draw_wall(
        ctx: &mut FrameContext<'_, Keep>,
        at: Vec2,
        standing: Range<f32>,
        seed: i32,
        fade: f32,
    ) {
        for course in 0..WALL_COURSES {
            let base = course as f32 * WALL_HEIGHT;
            let low = (standing.start - base).max(0.0);
            let high = (standing.end - base).min(WALL_HEIGHT);
            if high <= low {
                continue;
            }

            let variant = (seed + course).rem_euclid(CAVE_COLUMNS as i32) as u32;
            ctx.draw(
                CaveWall
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::new(TILE_SIZE, high - low, TILE_SIZE),
                        Quat::IDENTITY,
                        Vec3::new(at.x, base + (low + high) * 0.5, at.y),
                    ))
                    .frame(cave_wall_face(variant, low..high))
                    .faded(fade),
            );
        }
    }

    /// The room's two side walls and its back wall, full height, and the low
    /// wall closing its near end between the side walls and the mouth. The
    /// back wall stops short of the corners the side walls already fill, and
    /// the near one leaves the mouth's own tile open.
    fn draw_cave_walls(&self, ctx: &mut FrameContext<'_, Keep>) {
        let half = CAVE_HALF_WIDTH as i32 + 1;
        let near = CAVE_NEAR_Z as i32;
        let far = CAVE_FAR_Z as i32;

        for row in far..=near {
            let z = row as f32 * TILE_SIZE;
            let west = Vec2::new(-half as f32 * TILE_SIZE, z);
            let east = Vec2::new(half as f32 * TILE_SIZE, z);
            Self::draw_wall(ctx, west, 0.0..WALL_TOP, row * 5, SOLID);
            Self::draw_wall(ctx, east, 0.0..WALL_TOP, row * 5 + 1, SOLID);
        }
        for col in (-half + 1)..half {
            let x = col as f32 * TILE_SIZE;
            let back = Vec2::new(x, far as f32 * TILE_SIZE);
            Self::draw_wall(ctx, back, 0.0..WALL_TOP, col * 5 + 2, SOLID);
            if col != 0 {
                let lip = Vec2::new(x, CAVE_LIP_Z);
                Self::draw_wall(ctx, lip, 0.0..CAVE_LIP_HEIGHT, col * 5 + 4, SOLID);
            }
        }
    }

    /// The wall the door hangs in, run across the room between the side walls
    /// with one tile left open on the room's axis for the doorway and stone
    /// filling the column over the door. A player behind the wall is drawn
    /// through the stacks between them and the camera, at `seen_through`,
    /// faded by `ghost`; the rest of it stays solid, and keeps casting.
    fn draw_door_wall(ctx: &mut FrameContext<'_, Keep>, seen_through: Option<f32>, ghost: f32) {
        let stone = |x: f32| match seen_through {
            Some(at) if (x - at).abs() < GHOST_CORRIDOR_HALF => ghost_alpha(ghost),
            _ => SOLID,
        };
        let half = CAVE_HALF_WIDTH as i32;

        for col in (-half..=half).filter(|&col| col != 0) {
            let x = col as f32 * TILE_SIZE;
            Self::draw_wall(
                ctx,
                Vec2::new(x, DOOR_Z),
                0.0..WALL_TOP,
                col * 5 + 3,
                stone(x),
            );
        }
        Self::draw_wall(
            ctx,
            Vec2::new(0.0, DOOR_Z),
            DOOR_HEIGHT..WALL_TOP,
            3,
            stone(0.0),
        );
    }

    /// The two torches: an upright cutout post apiece, the flame's loop
    /// burning over its binding, and the light that flame casts.
    fn draw_torches(&self, ctx: &mut FrameContext<'_, Keep>) {
        let elapsed = self.simulated.as_secs_f32();
        let loop_cells = Sheet::new(UVec2::new(FLAME_CELLS, 1));

        for (index, &(x, z)) in TORCH_POSITIONS.iter().enumerate() {
            let base = Vec3::new(x, 0.0, z);
            ctx.draw(
                Torch
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::new(TORCH_SPRITE_WIDTH, TORCH_STAND_HEIGHT, 1.0),
                        Quat::IDENTITY,
                        base + Vec3::Y * (TORCH_STAND_HEIGHT * 0.5),
                    ))
                    .upright(),
            );

            let phase = index as f32 * 2.1;
            let flicker = (elapsed * FLAME_FLICKER_SPEED + phase).sin();
            let flame_pos =
                base + Vec3::Y * (TORCH_STAND_HEIGHT + FLAME_LIFT + flicker * FLAME_BOB);

            let light_pos = flame_pos + Vec3::new(0.0, TORCH_LIGHT_LIFT, TORCH_LIGHT_STANDOFF);
            ctx.light(Light::point(light_pos, TORCH_LIGHT_COLOR, TORCH_LIGHT_RANGE).shadow());
            // The pair burn an even share of the loop apart.
            let offset = index as u32 * FLAME_CELLS / TORCH_POSITIONS.len() as u32;
            ctx.draw(
                Flame
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(FLAME_SIZE),
                        Quat::IDENTITY,
                        flame_pos,
                    ))
                    .billboard()
                    .roll(flicker * FLAME_ROLL)
                    .frame(loop_cells.cell((elapsed * FLAME_RATE) as u32 + offset)),
            );
        }
    }

    /// The door at its hinge — swung back against the wall once opened —
    /// drawn through alongside its wall, faded by `ghost`.
    fn draw_door(&self, ctx: &mut FrameContext<'_, Keep>, ghost: f32) {
        let fade = ghost_alpha(ghost);
        let swung = if self.door_opening {
            Quat::from_rotation_y(core::f32::consts::FRAC_PI_2)
        } else {
            Quat::IDENTITY
        };

        ctx.draw(
            Door.at(Transform::from_rotation_translation(swung, DOOR_HINGE))
                .material(Material::shaded(DOOR_COLOR, DOOR_LITNESS))
                .faded(fade),
        );
    }

    /// The posts and lintel framing the doorway, in a color the stone never
    /// is, standing clear of the wall so the opening reads as a door from
    /// across the chamber. Glowing of their own while the door is closed and
    /// within [`INTERACT_RADIUS`], the cue that it opens.
    fn draw_door_frame(&self, ctx: &mut FrameContext<'_, Keep>, ghost: f32) {
        let reachable =
            !self.door_opening && self.position.distance(INTERACT_POINT) < INTERACT_RADIUS;
        let material =
            Material::shaded(DOOR_FRAME_COLOR, DOOR_FRAME_LITNESS).emissive(if reachable {
                DOOR_FRAME_GLOW
            } else {
                Color::BLACK
            });
        let fade = ghost_alpha(ghost);
        let z = DOOR_WALL_NEAR_Z + DOOR_FRAME_STANDOFF;
        let jamb_height = DOOR_HEIGHT + DOOR_FRAME_THICKNESS;

        for side in SIDES {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::new(DOOR_FRAME_THICKNESS, jamb_height, DOOR_FRAME_THICKNESS),
                    Quat::IDENTITY,
                    Vec3::new(
                        side * (DOORWAY_HALF + DOOR_FRAME_THICKNESS * 0.5),
                        jamb_height * 0.5,
                        z,
                    ),
                ))
                .material(material)
                .faded(fade),
            );
        }
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(
                    DOOR_WIDTH + DOOR_FRAME_THICKNESS * 2.0,
                    DOOR_FRAME_THICKNESS,
                    DOOR_FRAME_THICKNESS,
                ),
                Quat::IDENTITY,
                Vec3::new(0.0, DOOR_HEIGHT + DOOR_FRAME_THICKNESS * 0.5, z),
            ))
            .material(material)
            .faded(fade),
        );
    }

    /// A world prompt over the door: what opens it while the player is
    /// within [`INTERACT_RADIUS`] and it is closed, and that it swings while
    /// it does; gone once it has swung [`DOOR_SWING_TICKS`]. Laid out and
    /// placed like `examples/animation.rs`'s own prompt.
    fn draw_door_prompt(&self, ctx: &mut FrameContext<'_, Keep>, camera: Camera) {
        let near = self.position.distance(INTERACT_POINT) < INTERACT_RADIUS;
        let swinging = self.door_opening && self.swing_ticks < DOOR_SWING_TICKS;
        let text = if swinging {
            "opening"
        } else if near && !self.door_opening {
            "e opens the door"
        } else {
            return;
        };

        let galley = ctx.text_layout(text, egui::FontId::proportional(DOOR_PROMPT_SIZE));
        let point = INTERACT_POINT + Vec3::Y * (DOOR_HEIGHT + DOOR_PROMPT_LIFT);
        let window_size = ctx.window_size();
        let pixels_per_point = ctx.pixels_per_point();
        let Some(pixel) = camera.pixel_of(point, window_size) else {
            return;
        };

        ctx.ui(|ui| {
            let painter = ui.painter();
            let at = logical(pixel, pixels_per_point);
            let ink = galley.mesh_bounds;
            let pos = egui::pos2(at.x - ink.center().x, at.y - ink.center().y);
            let backdrop = egui::Rect::from_center_size(
                at,
                ink.size() + egui::Vec2::splat(DOOR_PROMPT_PADDING * 2.0),
            );
            painter.rect_filled(
                backdrop,
                DOOR_PROMPT_PADDING,
                egui::Color32::from_black_alpha(DOOR_PROMPT_BACKDROP),
            );
            painter.galley(pos, galley, DOOR_PROMPT_COLOR);
        });
    }

    /// The gem, spinning and bobbing over the chamber's floor, and the light
    /// it casts over it.
    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))),
        );
    }

    /// The player: upright so it always faces the camera about `+Y`,
    /// windowed to its facing's row and the walk cycle's current frame.
    fn draw_walker(&self, ctx: &mut FrameContext<'_, Keep>, ground: Vec3) {
        let step = if self.walk_ticks > 0 {
            (self.walk_ticks / TICKS_PER_WALK_FRAME) % WALKER_COLUMNS
        } else {
            0
        };
        let cell = Sheet::new(UVec2::new(WALKER_COLUMNS, WALKER_ROWS))
            .cell_at(UVec2::new(step, self.facing as u32));
        let size = Vec2::new(WALKER_WIDTH, WALKER_HEIGHT);

        ctx.draw(
            Walker
                .at(Transform::from_scale_rotation_translation(
                    size.extend(1.0),
                    Quat::IDENTITY,
                    ground + Vec3::Y * (WALKER_HEIGHT * 0.5),
                ))
                .upright()
                .frame(cell),
        );
    }

examples/sound-lab.rs (line 201)

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);
    }

examples/material-playground.rs (line 370)

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)
}

examples/isometric-board.rs (line 746)

fn build_rock(seed: u32) -> MeshData {
    let corners: [Vec3; 8] = core::array::from_fn(|index| {
        let sign = Vec3::new(
            if index & 1 == 0 { -0.5 } else { 0.5 },
            if index & 2 == 0 { -0.5 } else { 0.5 },
            if index & 4 == 0 { -0.5 } else { 0.5 },
        );
        sign + corner_offset(seed, index as u32)
    });
    let corner_at = |sign: Vec3| corners[corner_index(sign)];

    let mut vertices = Vec::with_capacity(ROCK_FACES.len() * 4);
    let mut indices = Vec::with_capacity(ROCK_FACES.len() * 6);
    for (face, &(normal, right, up)) in ROCK_FACES.iter().enumerate() {
        let quad = [
            corner_at(normal - right - up),
            corner_at(normal + right - up),
            corner_at(normal + right + up),
            corner_at(normal - right + up),
        ];
        let normal = (quad[1] - quad[0]).cross(quad[3] - quad[0]).normalize();
        let uvs = [
            Vec2::new(0.0, 1.0),
            Vec2::new(1.0, 1.0),
            Vec2::new(1.0, 0.0),
            Vec2::new(0.0, 0.0),
        ];
        vertices.extend(
            quad.into_iter()
                .zip(uvs)
                .map(|(corner, uv)| Vertex::new(corner, normal, uv)),
        );
        let base = face as u32 * 4;
        indices.extend(ROCK_TRIANGLES.map(|index| base + index));
    }
    MeshData::new(vertices, indices)
}

pub const fn splat(v: f32) -> Vec2

Creates a vector with all elements set to v.

Examples found in repository

examples/sound-lab.rs (line 469)

    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);
    }

examples/sprite-adventure.rs (line 482)

    fn push_out(self, point: Vec2, radius: f32) -> Vec2 {
        let delta = point - self.center;
        let escape = self.half + Vec2::splat(radius) - delta.abs();

        if escape.min_element() <= 0.0 {
            point
        } else if escape.x < escape.y {
            let x = self.center.x + delta.x.signum() * (self.half.x + radius);
            Vec2::new(x, point.y)
        } else {
            let z = self.center.y + delta.y.signum() * (self.half.y + radius);
            Vec2::new(point.x, z)
        }
    }
}

/// A cave mouth's opening: where it is, and which way along `Z` the room
/// it leads out of lies.
#[derive(Clone, Copy)]
struct Mouth {
    at: Vec3,
    room_side: f32,
}

impl Mouth {
    /// True where `position` lies between the pillars and past the plane
    /// in front of the opening — where the only two outcomes are stepping
    /// through and being held.
    fn holds(&self, position: Vec3) -> bool {
        let plane = self.at.z + self.room_side * MOUTH_CROSSING_INSET;

        (position.x - self.at.x).abs() < MOUTH_OPENING_HALF
            && (plane - position.z) * self.room_side > 0.0
    }

    /// Position of each of the two pillars flanking the opening.
    fn pillars(&self) -> impl Iterator<Item = Vec3> + Clone {
        let at = self.at;

        SIDES
            .into_iter()
            .map(move |side| at + Vec3::X * (side * MOUTH_PILLAR_OFFSET))
    }

    /// True when the camera looks into this mouth: it always lies on `+Z`
    /// of the player, so the mouth whose room lies that way is the one seen
    /// from the room's side, and the one to fill with a lintel and the dark
    /// under it. The other is looked through from behind, and leaves its
    /// opening clear for the room to show through.
    fn looked_into(&self) -> bool {
        self.room_side > 0.0
    }
}

// ---------------------------------------------------------------------
// The water style
// ---------------------------------------------------------------------

/// The pond's whole look, over the one value it reads: how far its ripple
/// has traveled.
#[derive(Default, ShaderValues)]
struct Water {
    time: f32,
}

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

surface_styles! { enum Looks { Water } }

// ---------------------------------------------------------------------
// Meshes
// ---------------------------------------------------------------------

/// The player's current area; never both drawn in one frame.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Area {
    Overworld,
    Cave,
}

/// The overworld's ground tile, its texture the only thing that separates a
/// draw of it from another.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Ground;

impl Mesh for Ground {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(GROUND_SHEET).pixelated())
    }
}

/// The shoreline sprite laid over the pond's styled water, cutout so the
/// water shows through its cleared middle.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Shore;

impl Mesh for Shore {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(POND_SHEET).pixelated())
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A crate prop, its texture drawn over a cube.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Crate;

impl Mesh for Crate {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(CRATE_TEXTURE).pixelated())
    }
}

/// The well's rim.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Well;

impl Mesh for Well {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(WELL_SHEET).pixelated())
    }
}

/// The well's mouth, laid flat over the rim's top face.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct WellMouth;

impl Mesh for WellMouth {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(WELL_SHEET).pixelated())
    }
}

/// A stone box: the mouth's pillars and lintel.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Stone;

impl Mesh for Stone {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(STONE_SHEET).pixelated())
    }
}

/// A bush sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Bush;

impl Mesh for Bush {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(BUSH_SPRITE).pixelated())
            .with_relief(assets.relief(BUSH_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A rock sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Rock;

impl Mesh for Rock {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(ROCK_SPRITE).pixelated())
            .with_relief(assets.relief(ROCK_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A torch's post sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Torch;

impl Mesh for Torch {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(TORCH_SPRITE).pixelated())
            .with_relief(assets.relief(TORCH_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A torch's flame sprite, added over the dark rather than lit.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Flame;

impl Mesh for Flame {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(FLAME_SHEET).pixelated())
            .with_material(Material::color(FLAME_TINT).additive())
    }
}

/// The player's sprite, cutout with its own relief, its sheet shared
/// with `examples/isometric-board.rs`.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Walker;

impl Mesh for Walker {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(WALKER_SHEET).pixelated())
            .with_relief(assets.relief(WALKER_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// The cave floor tile.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct CaveFloor;

impl Mesh for CaveFloor {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(CAVE_SHEET).pixelated())
    }
}

/// The cave wall face.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct CaveWall;

impl Mesh for CaveWall {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(CAVE_SHEET).pixelated())
    }
}

/// The loaded door, drawn as its source authored it.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Door;

impl Mesh for Door {
    fn build(&self, assets: &Assets) -> MeshData {
        assets.mesh(DOOR_MESH)
    }
}

/// The loaded gem, repainted whole per draw so its glow color shifts.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Gem;

impl Mesh for Gem {
    fn build(&self, assets: &Assets) -> MeshData {
        assets.mesh(GEM_MESH)
    }
}

// Everything this game can draw: the meshes above, plus the styled water,
// the dark filling a looked-into mouth's opening, and the door's own frame,
// which draw the bare engine primitives Plane, Quad and Cube.
meshes! {
    enum Shape {
        Ground, Shore, Crate, Well, WellMouth, Stone, Bush, Rock, Torch,
        Flame, Walker, CaveFloor, CaveWall, Door, Gem, Plane, Quad, Cube,
    }
}

/// The interact click and the gem's chime, shared with the other examples.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
enum Sound {
    Interact,
    Gem,
}

impl Sounds for Sound {
    fn build(&self, assets: &Assets) -> SoundData {
        match self {
            Sound::Interact => assets.sound("click"),
            Sound::Gem => assets.sound("win"),
        }
    }
}

// ---------------------------------------------------------------------
// Input
// ---------------------------------------------------------------------

/// Player movement: `WASD`, arrows, or a stick — the strongest reading is
/// kept.
#[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::from(ButtonAxis2 {
                    left: Key::Left,
                    right: Key::Right,
                    down: Key::Down,
                    up: Key::Up,
                }),
                Axis2Binding::stick(Stick::Left),
            ],
        }
    }
}

/// The two verbs this game reads as an edge: interacting with the door, and
/// a reset of the world to every saved key's fallback.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Button {
    Interact,
    Reset,
}

impl InputButtonAction for Button {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Button::Interact => vec![Key::E.into(), Pad::West.into()],
            Button::Reset => vec![Key::R.into()],
        }
    }
}

struct Controls;

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

// ---------------------------------------------------------------------
// Save data
// ---------------------------------------------------------------------

/// The player's last position, read at startup and saved on area
/// transition and gem pickup.
#[derive(Saves, Clone, Copy)]
enum Position {
    X,
    Z,
}

impl SaveKey for Position {
    type Value = f64;

    fn fallback(&self) -> f64 {
        match self {
            Position::X => PLAYER_SPAWN.x as f64,
            Position::Z => PLAYER_SPAWN.z as f64,
        }
    }
}

/// The area the player is in, and whether the gem is taken.
#[derive(Saves, Clone, Copy)]
enum Flag {
    InCave,
    GemTaken,
}

impl SaveKey for Flag {
    type Value = bool;

    fn fallback(&self) -> bool {
        false
    }
}

// ---------------------------------------------------------------------
// The player's facing
// ---------------------------------------------------------------------

/// The player's last facing: also its row in the sheet, top to bottom.
#[derive(Clone, Copy, PartialEq)]
enum Facing {
    Toward = 0,
    Right = 1,
    Away = 2,
    Left = 3,
}

impl Facing {
    /// The facing `heading` points in, favoring its larger axis; `None` at
    /// rest, so the caller can keep the last facing.
    fn from_heading(heading: Vec2) -> Option<Self> {
        if heading == Vec2::ZERO {
            return None;
        }
        Some(if heading.x.abs() > heading.y.abs() {
            if heading.x > 0.0 {
                Self::Right
            } else {
                Self::Left
            }
        } else if heading.y > 0.0 {
            Self::Away
        } else {
            Self::Toward
        })
    }
}

// ---------------------------------------------------------------------
// The game
// ---------------------------------------------------------------------

/// The ground tile at `col, row`: the path's dirt along [`PATH_COLUMN`],
/// the verges that edge it, and a hashed grass variant everywhere else.
fn ground_cell(col: i32, row: i32) -> Frame {
    let (column, sheet_row) = match col - PATH_COLUMN {
        0 => (PATH_DIRT + row.rem_euclid(2) as u32, PATH_ROW),
        -1 => (PATH_WEST_VERGE, PATH_ROW),
        1 => (PATH_EAST_VERGE, PATH_ROW),
        _ => (
            (col * 31 + row * 17).rem_euclid(GROUND_COLUMNS as i32) as u32,
            GRASS_ROW,
        ),
    };

    Sheet::new(UVec2::new(GROUND_COLUMNS, GROUND_ROWS)).cell_at(UVec2::new(column, sheet_row))
}

/// The stone sheet's plain masonry, laid `tiles` times across: the sampler
/// wraps, so a window wider than the sheet repeats the course.
fn masonry(tiles: f32) -> Frame {
    let course = 1.0 / STONE_ROWS as f32;

    Frame::rect(Vec2::new(0.0, 1.0 - course), Vec2::new(tiles, 1.0))
}

/// The wall or door's alpha `fraction` of the way from [`SOLID`] to
/// [`GHOST_ALPHA`].
fn ghost_alpha(fraction: f32) -> f32 {
    SOLID + (GHOST_ALPHA - SOLID) * fraction
}

/// The wall face in column `variant`, windowed to the meters `standing` of
/// one course, measured up from that course's own base: every row of the
/// cave sheet below the floor's covers [`WALL_HEIGHT`], so a course keeps
/// the floor's texels to the meter however it is cut.
fn cave_wall_face(variant: u32, standing: Range<f32>) -> Frame {
    let cell = Vec2::new(1.0 / CAVE_COLUMNS as f32, 1.0 / CAVE_ROWS as f32);
    let left = (variant % CAVE_COLUMNS) as f32 * cell.x;
    let face = (CAVE_FLOOR_ROW + 1) as f32 * cell.y;
    let up_from_base = |height: f32| 1.0 - (1.0 - face) * (height / WALL_HEIGHT);

    Frame::rect(
        Vec2::new(left, up_from_base(standing.end)),
        Vec2::new(left + cell.x, up_from_base(standing.start)),
    )
}

/// The logical point egui paints the physical pixel `pixel` at.
fn logical(pixel: Vec2, pixels_per_point: f32) -> egui::Pos2 {
    let point = pixel / pixels_per_point;
    egui::pos2(point.x, point.y)
}

fn main() {
    run(
        Config::new("Mirage: sprite adventure")
            .with_size(1280, 720)
            .with_assets([
                MODEL,
                WALKER_SOURCE,
                WALKER_RELIEF_SOURCE,
                GROUND_SOURCE,
                BUSH_SOURCE,
                BUSH_RELIEF_SOURCE,
                ROCK_SOURCE,
                ROCK_RELIEF_SOURCE,
                TORCH_RELIEF_SOURCE,
                CRATE_SOURCE,
                WELL_SOURCE,
                STONE_SOURCE,
                CAVE_SOURCE,
                POND_SOURCE,
                TORCH_SOURCE,
                FLAME_SOURCE,
                INTERACT_SOUND,
                GEM_SOUND,
            ]),
        Keep::init,
    );
}

struct Keep {
    area: Area,
    position: Vec3,
    previous: Vec3,
    facing: Facing,
    walk_ticks: u32,
    simulated: Duration,
    door_opening: bool,
    /// Ticks the door has been opening for, at a cap of
    /// [`DOOR_SWING_TICKS`]: how long its world prompt reads "opening" once
    /// it starts.
    swing_ticks: u32,
    gem_taken: bool,
    /// How far the door wall's fade from [`SOLID`] to [`GHOST_ALPHA`] has
    /// run as of the last tick: `0.0` to `1.0`.
    ghost: f32,
    /// Set by the panel's reset button, since its click lands in a frame
    /// rather than a tick; read and cleared on the next tick.
    reset_requested: bool,
}

impl Keep {
    /// Prepares every startup-cataloged mesh and resumes wherever the last
    /// run left the player.
    fn init(ctx: &mut InitContext<'_, Keep>) -> Result<Self, Error> {
        let startup = ctx.startup();
        let gem_taken = startup.saved(Flag::GemTaken);
        let area = if startup.saved(Flag::InCave) {
            Area::Cave
        } else {
            Area::Overworld
        };
        let position = Vec3::new(
            startup.saved(Position::X) as f32,
            0.0,
            startup.saved(Position::Z) as f32,
        );

        Ok(Self {
            area,
            position,
            previous: position,
            facing: Facing::Toward,
            walk_ticks: 0,
            simulated: Duration::ZERO,
            door_opening: gem_taken,
            swing_ticks: if gem_taken { DOOR_SWING_TICKS } else { 0 },
            gem_taken,
            ghost: 0.0,
            reset_requested: false,
        })
    }

    fn camera(position: Vec3, offset: Vec3) -> Camera {
        Camera::new(
            View::look_at(position + offset, position),
            Projection::perspective(CAMERA_FOV),
        )
    }

    /// Obstacles from the overworld's props: the crates, turned as they are
    /// drawn, the well's rim, the open water the shoreline rings, the
    /// mouth's pillars, and each flora's base.
    fn overworld_obstacles() -> impl Iterator<Item = Obstacle> + Clone {
        CRATE_POSITIONS
            .into_iter()
            .map(|(x, z, turn)| {
                Obstacle::footprint(Vec2::new(x, z), Vec2::splat(CRATE_SIZE * turned_span(turn)))
            })
            .chain([
                Obstacle::footprint(WELL_POSITION.xz(), WELL_SIZE.xz()),
                Obstacle::footprint(POND_CENTER.xz(), Vec2::splat(POND_WATER_HALF * 2.0)),
            ])
            .chain(
                ENTRANCE
                    .pillars()
                    .map(|at| Obstacle::footprint(at.xz(), MOUTH_PILLAR_SIZE.xz())),
            )
            .chain(FLORA.into_iter().map(|(x, z, rock)| {
                let base = if rock { ROCK_FOOTPRINT } else { BUSH_FOOTPRINT };
                Obstacle::footprint(Vec2::new(x, z), Vec2::splat(base))
            }))
    }

    /// Obstacles from the cave: the torch posts, its own mouth's pillars,
    /// the runs of wall either side of the doorway and of the mouth, and the
    /// `door` leaf.
    fn cave_obstacles(door: Obstacle) -> impl Iterator<Item = Obstacle> + Clone {
        TORCH_POSITIONS
            .into_iter()
            .map(|(x, z)| Obstacle::footprint(Vec2::new(x, z), Vec2::splat(TORCH_STAND_WIDTH)))
            .chain(
                EXIT.pillars()
                    .map(|at| Obstacle::footprint(at.xz(), MOUTH_PILLAR_SIZE.xz())),
            )
            .chain(SIDES.into_iter().flat_map(|side| {
                [
                    Self::wall_run(side, DOOR_Z),
                    Self::wall_run(side, CAVE_LIP_Z),
                ]
            }))
            .chain([door])
    }

pub fn map<F>(self, f: F) -> Vec2

where F: FnMut(f32) -> f32,

Returns a vector containing each element of self modified by a mapping function f.

pub fn select(mask: BVec2, if_true: Vec2, if_false: Vec2) -> Vec2

Creates a vector from the elements in if_true and if_false, selecting which to use for each element of self.

A true element in the mask uses the corresponding element from if_true, and false uses the element from if_false.

pub const fn from_array(a: [f32; 2]) -> Vec2

Creates a new vector from an array.

pub const fn to_array(&self) -> [f32; 2]

Converts self to [x, y]

pub const fn from_slice(slice: &[f32]) -> Vec2

Creates a vector from the first 2 values in slice.

Panics

Panics if slice is less than 2 elements long.

pub fn write_to_slice(self, slice: &mut [f32])

Writes the elements of self to the first 2 elements in slice.

Panics

Panics if slice is less than 2 elements long.

pub const fn extend(self, z: f32) -> Vec3

Creates a 3D vector from self and the given z value.

Examples found in repository

examples/sprite-adventure.rs (line 1713)

    fn draw_walker(&self, ctx: &mut FrameContext<'_, Keep>, ground: Vec3) {
        let step = if self.walk_ticks > 0 {
            (self.walk_ticks / TICKS_PER_WALK_FRAME) % WALKER_COLUMNS
        } else {
            0
        };
        let cell = Sheet::new(UVec2::new(WALKER_COLUMNS, WALKER_ROWS))
            .cell_at(UVec2::new(step, self.facing as u32));
        let size = Vec2::new(WALKER_WIDTH, WALKER_HEIGHT);

        ctx.draw(
            Walker
                .at(Transform::from_scale_rotation_translation(
                    size.extend(1.0),
                    Quat::IDENTITY,
                    ground + Vec3::Y * (WALKER_HEIGHT * 0.5),
                ))
                .upright()
                .frame(cell),
        );
    }

pub fn with_x(self, x: f32) -> Vec2

Creates a 2D vector from self with the given value of x.

pub fn with_y(self, y: f32) -> Vec2

Creates a 2D vector from self with the given value of y.

pub fn dot(self, rhs: Vec2) -> f32

Computes the dot product of self and rhs.

pub fn dot_into_vec(self, rhs: Vec2) -> Vec2

Returns a vector where every component is the dot product of self and rhs.

pub fn min(self, rhs: Vec2) -> Vec2

Returns a vector containing the minimum values for each element of self and rhs.

In other words this computes [min(x, rhs.x), min(self.y, rhs.y), ..].

NaN propogation does not follow IEEE 754-2008 semantics for minNum and may differ on different SIMD architectures.

Examples found in repository

examples/sprite-adventure.rs (line 469)

    fn over(corners: [Vec2; 4]) -> Self {
        let [first, rest @ ..] = corners;
        let low = rest.iter().fold(first, |low, &corner| low.min(corner));
        let high = rest.iter().fold(first, |high, &corner| high.max(corner));

        Self {
            center: (low + high) * 0.5,
            half: (high - low) * 0.5,
        }
    }

pub fn max(self, rhs: Vec2) -> Vec2

Returns a vector containing the maximum values for each element of self and rhs.

In other words this computes [max(self.x, rhs.x), max(self.y, rhs.y), ..].

NaN propogation does not follow IEEE 754-2008 semantics for maxNum and may differ on different SIMD architectures.

Examples found in repository

examples/sprite-adventure.rs (line 470)

    fn over(corners: [Vec2; 4]) -> Self {
        let [first, rest @ ..] = corners;
        let low = rest.iter().fold(first, |low, &corner| low.min(corner));
        let high = rest.iter().fold(first, |high, &corner| high.max(corner));

        Self {
            center: (low + high) * 0.5,
            half: (high - low) * 0.5,
        }
    }

pub fn clamp(self, min: Vec2, max: Vec2) -> Vec2

Component-wise clamping of values, similar to f32::clamp.

Each element in min must be less-or-equal to the corresponding element in max.

NaN propogation does not follow IEEE 754-2008 semantics and may differ on different SIMD architectures.

Panics

Will panic if min is greater than max when glam_assert is enabled.

Examples found in repository

examples/sound-lab.rs (line 469)

    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);
    }

pub fn min_element(self) -> f32

Returns the horizontal minimum of self.

In other words this computes min(x, y, ..).

NaN propogation does not follow IEEE 754-2008 semantics and may differ on different SIMD architectures.

Examples found in repository

examples/sprite-adventure.rs (line 484)

    fn push_out(self, point: Vec2, radius: f32) -> Vec2 {
        let delta = point - self.center;
        let escape = self.half + Vec2::splat(radius) - delta.abs();

        if escape.min_element() <= 0.0 {
            point
        } else if escape.x < escape.y {
            let x = self.center.x + delta.x.signum() * (self.half.x + radius);
            Vec2::new(x, point.y)
        } else {
            let z = self.center.y + delta.y.signum() * (self.half.y + radius);
            Vec2::new(point.x, z)
        }
    }

pub fn max_element(self) -> f32

Returns the horizontal maximum of self.

In other words this computes max(x, y, ..).

NaN propogation does not follow IEEE 754-2008 semantics and may differ on different SIMD architectures.

pub fn min_position(self) -> usize

Returns the index of the first minimum element of self.

pub fn max_position(self) -> usize

Returns the index of the first maximum element of self.

pub fn element_sum(self) -> f32

Returns the sum of all elements of self.

In other words, this computes self.x + self.y + ...

pub fn element_product(self) -> f32

Returns the product of all elements of self.

In other words, this computes self.x * self.y * ...

pub fn cmpeq(self, rhs: Vec2) -> BVec2

Returns a vector mask containing the result of a == comparison for each element of self and rhs.

In other words, this computes [self.x == rhs.x, self.y == rhs.y, ..] for all elements.

pub fn cmpne(self, rhs: Vec2) -> BVec2

Returns a vector mask containing the result of a != comparison for each element of self and rhs.

In other words this computes [self.x != rhs.x, self.y != rhs.y, ..] for all elements.

pub fn cmpge(self, rhs: Vec2) -> BVec2

Returns a vector mask containing the result of a >= comparison for each element of self and rhs.

In other words this computes [self.x >= rhs.x, self.y >= rhs.y, ..] for all elements.

pub fn cmpgt(self, rhs: Vec2) -> BVec2

Returns a vector mask containing the result of a > comparison for each element of self and rhs.

In other words this computes [self.x > rhs.x, self.y > rhs.y, ..] for all elements.

pub fn cmple(self, rhs: Vec2) -> BVec2

Returns a vector mask containing the result of a <= comparison for each element of self and rhs.

In other words this computes [self.x <= rhs.x, self.y <= rhs.y, ..] for all elements.

pub fn cmplt(self, rhs: Vec2) -> BVec2

Returns a vector mask containing the result of a < comparison for each element of self and rhs.

In other words this computes [self.x < rhs.x, self.y < rhs.y, ..] for all elements.

pub fn abs(self) -> Vec2

Returns a vector containing the absolute value of each element of self.

Examples found in repository

examples/sprite-adventure.rs (line 482)

    fn push_out(self, point: Vec2, radius: f32) -> Vec2 {
        let delta = point - self.center;
        let escape = self.half + Vec2::splat(radius) - delta.abs();

        if escape.min_element() <= 0.0 {
            point
        } else if escape.x < escape.y {
            let x = self.center.x + delta.x.signum() * (self.half.x + radius);
            Vec2::new(x, point.y)
        } else {
            let z = self.center.y + delta.y.signum() * (self.half.y + radius);
            Vec2::new(point.x, z)
        }
    }

pub fn signum(self) -> Vec2

Returns a vector with elements representing the sign of self.

• 1.0 if the number is positive, +0.0 or INFINITY
• -1.0 if the number is negative, -0.0 or NEG_INFINITY
• NAN if the number is NAN

pub fn copysign(self, rhs: Vec2) -> Vec2

Returns a vector with signs of rhs and the magnitudes of self.

pub fn is_negative_bitmask(self) -> u32

Returns a bitmask with the lowest 2 bits set to the sign bits from the elements of self.

A negative element results in a 1 bit and a positive element in a 0 bit. Element x goes into the first lowest bit, element y into the second, etc.

An element is negative if it has a negative sign, including -0.0, NaNs with negative sign bit and negative infinity.

pub fn is_negative_mask(self) -> BVec2

Returns a mask indicating which components are negative.

An element is negative if it has a negative sign, including -0.0, NaNs with negative sign bit and negative infinity.

pub fn is_finite(self) -> bool

Returns true if, and only if, all elements are finite. If any element is either NaN, positive or negative infinity, this will return false.

pub fn is_finite_mask(self) -> BVec2

Performs is_finite on each element of self, returning a vector mask of the results.

In other words, this computes [x.is_finite(), y.is_finite(), ...].

pub fn is_nan(self) -> bool

Returns true if any elements are NaN.

pub fn is_nan_mask(self) -> BVec2

Performs is_nan on each element of self, returning a vector mask of the results.

In other words, this computes [x.is_nan(), y.is_nan(), ...].

pub fn length(self) -> f32

Computes the length of self.

pub fn length_squared(self) -> f32

Computes the squared length of self.

This is faster than length() as it avoids a square root operation.

pub fn length_recip(self) -> f32

Computes 1.0 / length().

For valid results, self must not be of length zero.

pub fn distance(self, rhs: Vec2) -> f32

Computes the Euclidean distance between two points in space.

pub fn distance_squared(self, rhs: Vec2) -> f32

Compute the squared euclidean distance between two points in space.

pub fn div_euclid(self, rhs: Vec2) -> Vec2

Returns the element-wise quotient of [Euclidean division] of self by rhs.

pub fn rem_euclid(self, rhs: Vec2) -> Vec2

Returns the element-wise remainder of Euclidean division of self by rhs.

pub fn normalize(self) -> Vec2

Returns self normalized to length 1.0.

For valid results, self must be finite and not of length zero, nor very close to zero.

See also Self::try_normalize() and Self::normalize_or_zero().

Panics

Will panic if the resulting normalized vector is not finite when glam_assert is enabled.

pub fn try_normalize(self) -> Option<Vec2>

Returns self normalized to length 1.0 if possible, else returns None.

In particular, if the input is zero (or very close to zero), or non-finite, the result of this operation will be None.

See also Self::normalize_or_zero().

pub fn normalize_or(self, fallback: Vec2) -> Vec2

Returns self normalized to length 1.0 if possible, else returns a fallback value.

In particular, if the input is zero (or very close to zero), or non-finite, the result of this operation will be the fallback value.

See also Self::try_normalize().

pub fn normalize_or_zero(self) -> Vec2

Returns self normalized to length 1.0 if possible, else returns zero.

In particular, if the input is zero (or very close to zero), or non-finite, the result of this operation will be zero.

See also Self::try_normalize().

pub fn normalize_and_length(self) -> (Vec2, f32)

Returns self normalized to length 1.0 and the length of self.

If self is zero length then (Self::X, 0.0) is returned.

pub fn is_normalized(self) -> bool

Returns whether self is length 1.0 or not.

Uses a precision threshold of approximately 1e-4.

pub fn project_onto(self, rhs: Vec2) -> Vec2

Returns the vector projection of self onto rhs.

rhs must be of non-zero length.

Panics

Will panic if rhs is zero length when glam_assert is enabled.

pub fn reject_from(self, rhs: Vec2) -> Vec2

Returns the vector rejection of self from rhs.

The vector rejection is the vector perpendicular to the projection of self onto rhs, in rhs words the result of self - self.project_onto(rhs).

rhs must be of non-zero length.

Panics

Will panic if rhs has a length of zero when glam_assert is enabled.

pub fn project_onto_normalized(self, rhs: Vec2) -> Vec2

Returns the vector projection of self onto rhs.

rhs must be normalized.

Panics

Will panic if rhs is not normalized when glam_assert is enabled.

pub fn reject_from_normalized(self, rhs: Vec2) -> Vec2

Returns the vector rejection of self from rhs.

The vector rejection is the vector perpendicular to the projection of self onto rhs, in rhs words the result of self - self.project_onto(rhs).

rhs must be normalized.

Panics

Will panic if rhs is not normalized when glam_assert is enabled.

pub fn round(self) -> Vec2

Returns a vector containing the nearest integer to a number for each element of self. Round half-way cases away from 0.0.

pub fn floor(self) -> Vec2

Returns a vector containing the largest integer less than or equal to a number for each element of self.

pub fn ceil(self) -> Vec2

Returns a vector containing the smallest integer greater than or equal to a number for each element of self.

pub fn trunc(self) -> Vec2

Returns a vector containing the integer part each element of self. This means numbers are always truncated towards zero.

pub fn step(self, rhs: Vec2) -> Vec2

Returns a vector containing 0.0 if rhs < self and 1.0 otherwise.

Similar to glsl’s step(edge, x), which translates into edge.step(x)

pub fn saturate(self) -> Vec2

Returns a vector containing all elements of self clamped to the range of [0, 1].

pub fn fract(self) -> Vec2

Returns a vector containing the fractional part of the vector as self - self.trunc().

Note that this differs from the GLSL implementation of fract which returns self - self.floor().

Note that this is fast but not precise for large numbers.

pub fn fract_gl(self) -> Vec2

Returns a vector containing the fractional part of the vector as self - self.floor().

Note that this differs from the Rust implementation of fract which returns self - self.trunc().

Note that this is fast but not precise for large numbers.

pub fn exp(self) -> Vec2

Returns a vector containing e^self (the exponential function) for each element of self.

pub fn exp2(self) -> Vec2

Returns a vector containing 2^self for each element of self.

pub fn ln(self) -> Vec2

Returns a vector containing the natural logarithm for each element of self. This returns NaN when the element is negative and negative infinity when the element is zero.

pub fn log2(self) -> Vec2

Returns a vector containing the base 2 logarithm for each element of self. This returns NaN when the element is negative and negative infinity when the element is zero.

pub fn powf(self, n: f32) -> Vec2

Returns a vector containing each element of self raised to the power of n.

pub fn sqrt(self) -> Vec2

Returns a vector containing the square root for each element of self. This returns NaN when the element is negative.

pub fn cos(self) -> Vec2

Returns a vector containing the cosine for each element of self.

pub fn sin(self) -> Vec2

Returns a vector containing the sine for each element of self.

pub fn sin_cos(self) -> (Vec2, Vec2)

Returns a tuple of two vectors containing the sine and cosine for each element of self.

pub fn recip(self) -> Vec2

Returns a vector containing the reciprocal 1.0/n of each element of self.

pub fn lerp(self, rhs: Vec2, s: f32) -> Vec2

Performs a linear interpolation between self and rhs based on the value s.

When s is 0.0, the result will be equal to self. When s is 1.0, the result will be equal to rhs. When s is outside of range [0, 1], the result is linearly extrapolated.

Examples found in repository

examples/sound-lab.rs (line 981)

    fn frame(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) {
        ctx.set_volume(self.master_volume);

        let player = self.player_prev.lerp(self.player, ctx.alpha());
        let ear = Vec3::new(player.x, EYE_HEIGHT, player.y);
        let listener = View::look_at(ear, ear + Vec3::NEG_Z);
        ctx.set_listener(listener);

        ctx.set_camera(Self::camera(player));
        ctx.set_skybox(Sky::Room);
        ctx.set_bloom(0.2);
        ctx.light(Light::directional(Vec3::new(-0.4, -1.0, -0.5), SUN_COLOR).shadow());

        self.draw_room(ctx);
        self.draw_sources(ctx);
        self.draw_listener(ctx, listener);
        self.draw_merge_markers(ctx);
        self.draw_ring(ctx);

        self.sustain_cues(ctx);
        for (index, source) in self.sources.iter().enumerate() {
            if source.enabled {
                ctx.sustain(source.cue().instance(index as u32));
            }
        }
        if self.merge_demo {
            ctx.sustain(Sound::Click.at(MERGE_POS_A).gain(MERGE_GAIN));
            ctx.sustain(Sound::Click.at(MERGE_POS_B).gain(MERGE_GAIN));
        }
        self.sustain_ring(ctx);

        self.side_panel(ctx);
        let (play_once, play_many) = self.one_shot_panel(ctx);

        if play_once {
            ctx.play(self.one_shot_cue());
        }
        if play_many {
            for _ in 0..32 {
                ctx.play(self.one_shot_cue());
            }
        }
    }

pub fn move_towards(self, rhs: Vec2, d: f32) -> Vec2

Moves towards rhs based on the value d.

When d is 0.0, the result will be equal to self. When d is equal to self.distance(rhs), the result will be equal to rhs. Will not go past rhs.

pub fn midpoint(self, rhs: Vec2) -> Vec2

Calculates the midpoint between self and rhs.

The midpoint is the average of, or halfway point between, two vectors. a.midpoint(b) should yield the same result as a.lerp(b, 0.5) while being slightly cheaper to compute.

pub fn abs_diff_eq(self, rhs: Vec2, max_abs_diff: f32) -> bool

Returns true if the absolute difference of all elements between self and rhs is less than or equal to max_abs_diff.

This can be used to compare if two vectors contain similar elements. It works best when comparing with a known value. The max_abs_diff that should be used used depends on the values being compared against.

For more see comparing floating point numbers.

pub fn clamp_length(self, min: f32, max: f32) -> Vec2

Returns a vector with a length no less than min and no more than max.

Panics

Will panic if min is greater than max, or if either min or max is negative, when glam_assert is enabled.

pub fn clamp_length_max(self, max: f32) -> Vec2

Returns a vector with a length no more than max.

Panics

Will panic if max is negative when glam_assert is enabled.

Examples found in repository

examples/animation.rs (line 693)

    fn advance(&mut self, ctx: &mut TickContext<'_, Scene>) -> f32 {
        let control = ctx.axis2(Move::Walk).clamp_length_max(1.0);
        let turn = Quat::from_rotation_y(self.camera_yaw);
        let heading = turn * Vec3::X * control.x + turn * Vec3::NEG_Z * control.y;
        let dt = ctx.dt().as_secs_f32();
        if let Some(direction) = heading.try_normalize() {
            let wanted = direction.x.atan2(direction.z);
            let turn = (wanted - self.elf_yaw + core::f32::consts::PI).rem_euclid(TAU)
                - core::f32::consts::PI;
            self.elf_yaw += turn.clamp(-TURN_RATE * dt, TURN_RATE * dt);
        }
        let cap = if ctx.down(Button::Run) { 1.0 } else { WALK_CAP };
        self.elf_pos += heading * cap * ELF_SPEED * dt;
        heading.length() * cap
    }

examples/input-lab.rs (line 497)

fn axis2_dot(ui: &mut egui::Ui, value: Vec2) {
    let square_side = 36.0;
    let radius = 4.0;
    let (column, _response) = ui.allocate_exact_size(
        egui::vec2(VALUE_COLUMN_WIDTH, square_side),
        egui::Sense::hover(),
    );
    let rect = egui::Rect::from_center_size(column.center(), egui::Vec2::splat(square_side));
    let painter = ui.painter();
    painter.rect_filled(rect, 2.0, egui::Color32::from_gray(35));

    let shown = value.clamp_length_max(1.0);
    let reach = rect.width() * 0.5 - READING_MARGIN - radius;
    let point = rect.center() + egui::vec2(shown.x, -shown.y) * reach;
    painter.circle_filled(point, radius, highlight_color(value != Vec2::ZERO));
    painter.rect_stroke(
        rect,
        2.0,
        egui::Stroke::new(1.0, egui::Color32::from_gray(120)),
        egui::StrokeKind::Inside,
    );

    ui.label(format!("{:.2}, {:.2}", value.x, value.y));
}

pub fn clamp_length_min(self, min: f32) -> Vec2

Returns a vector with a length no less than min.

Panics

Will panic if min is negative when glam_assert is enabled.

pub fn mul_add(self, a: Vec2, b: Vec2) -> Vec2

Fused multiply-add. Computes (self * a) + b element-wise with only one rounding error, yielding a more accurate result than an unfused multiply-add.

Using mul_add may be more performant than an unfused multiply-add if the target architecture has a dedicated fma CPU instruction. However, this is not always true, and will be heavily dependant on designing algorithms with specific target hardware in mind.

pub fn reflect(self, normal: Vec2) -> Vec2

Returns the reflection vector for a given incident vector self and surface normal normal.

normal must be normalized.

Panics

Will panic if normal is not normalized when glam_assert is enabled.

pub fn refract(self, normal: Vec2, eta: f32) -> Vec2

Returns the refraction direction for a given incident vector self, surface normal normal and ratio of indices of refraction, eta. When total internal reflection occurs, a zero vector will be returned.

self and normal must be normalized.

Panics

Will panic if self or normal is not normalized when glam_assert is enabled.

pub fn from_angle(angle: f32) -> Vec2

Creates a 2D vector containing [angle.cos(), angle.sin()]. This can be used in conjunction with the rotate() method, e.g. Vec2::from_angle(PI).rotate(Vec2::Y) will create the vector [-1, 0] and rotate Vec2::Y around it returning -Vec2::Y.

pub fn to_angle(self) -> f32

Returns the angle (in radians) of this vector in the range [-π, +π].

The input does not need to be a unit vector however it must be non-zero.

pub fn angle_to(self, rhs: Vec2) -> f32

Returns the angle of rotation (in radians) from self to rhs in the range [-π, +π].

The inputs do not need to be unit vectors however they must be non-zero.

The returned angle can be used with rotate_angle(), e.g. self.rotate_angle(self.angle_to(rhs)) will be equal to rhs.

Panics

Will panic if self or rhs has zero length when glam_assert is enabled.

pub fn perp(self) -> Vec2

Returns a vector that is equal to self rotated by 90 degrees.

pub fn perp_dot(self, rhs: Vec2) -> f32

The perpendicular dot product of self and rhs. Also known as the wedge product, 2D cross product, and determinant.

pub fn rotate(self, rhs: Vec2) -> Vec2

Returns rhs rotated by the angle of self. If self is normalized, then this just rotation. This is what you usually want. Otherwise, it will be like a rotation with a multiplication by self’s length.

This can be used in conjunction with the from_angle() method, e.g. Vec2::from_angle(PI).rotate(Vec2::Y) will create the vector [-1, 0] and rotate Vec2::Y around it returning -Vec2::Y.

pub fn rotate_angle(self, angle: f32) -> Vec2

Rotates self by angle (in radians), equivalent to self.rotate(Vec2::from_angle(angle)).

pub fn rotate_towards(self, rhs: Vec2, max_angle: f32) -> Vec2

Rotates towards rhs up to max_angle (in radians).

When max_angle is 0.0, the result will be equal to self. When max_angle is equal to self.angle_between(rhs), the result will be parallel to rhs. If max_angle is negative, rotates towards the exact opposite of rhs. Will not go past the target.

pub fn as_dvec2(self) -> DVec2

Casts all elements of self to f64.

pub fn as_i8vec2(self) -> I8Vec2

Casts all elements of self to i8.

pub fn as_u8vec2(self) -> U8Vec2

Casts all elements of self to u8.

pub fn as_i16vec2(self) -> I16Vec2

Casts all elements of self to i16.

pub fn as_u16vec2(self) -> U16Vec2

Casts all elements of self to u16.

pub fn as_ivec2(self) -> IVec2

Casts all elements of self to i32.

pub fn as_uvec2(self) -> UVec2

Casts all elements of self to u32.

pub fn as_i64vec2(self) -> I64Vec2

Casts all elements of self to i64.

pub fn as_u64vec2(self) -> U64Vec2

Casts all elements of self to u64.

pub fn as_isizevec2(self) -> ISizeVec2

Casts all elements of self to isize.

pub fn as_usizevec2(self) -> USizeVec2

Casts all elements of self to usize.

Trait Implementations

impl Add for Vec2

type Output = Vec2

The resulting type after applying the + operator.

fn add(self, rhs: Vec2) -> Vec2

Performs the + operation.

impl Add<&Vec2> for Vec2

type Output = Vec2

The resulting type after applying the + operator.

fn add(self, rhs: &Vec2) -> Vec2

Performs the + operation.

impl Add<&Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the + operator.

fn add(self, rhs: &Vec2) -> Vec2

Performs the + operation.

impl Add<&f32> for Vec2

type Output = Vec2

The resulting type after applying the + operator.

fn add(self, rhs: &f32) -> Vec2

Performs the + operation.

impl Add<&f32> for &Vec2

type Output = Vec2

The resulting type after applying the + operator.

fn add(self, rhs: &f32) -> Vec2

Performs the + operation.

impl Add<Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the + operator.

fn add(self, rhs: Vec2) -> Vec2

Performs the + operation.

impl Add<f32> for Vec2

type Output = Vec2

The resulting type after applying the + operator.

fn add(self, rhs: f32) -> Vec2

Performs the + operation.

impl Add<f32> for &Vec2

type Output = Vec2

The resulting type after applying the + operator.

fn add(self, rhs: f32) -> Vec2

Performs the + operation.

impl AddAssign for Vec2

fn add_assign(&mut self, rhs: Vec2)

Performs the += operation.

impl AddAssign<&Vec2> for Vec2

fn add_assign(&mut self, rhs: &Vec2)

Performs the += operation.

impl AddAssign<&f32> for Vec2

fn add_assign(&mut self, rhs: &f32)

Performs the += operation.

impl AddAssign<f32> for Vec2

fn add_assign(&mut self, rhs: f32)

Performs the += operation.

impl AsMut<[f32; 2]> for Vec2

fn as_mut(&mut self) -> &mut [f32; 2]

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<[f32; 2]> for Vec2

fn as_ref(&self) -> &[f32; 2]

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Vec2

fn clone(&self) -> Vec2

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Vec2

impl Debug for Vec2

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

Formats the value using the given formatter.

impl Default for Vec2

fn default() -> Vec2

Returns the “default value” for a type.

impl Display for Vec2

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

Formats the value using the given formatter.

impl Div for Vec2

type Output = Vec2

The resulting type after applying the / operator.

fn div(self, rhs: Vec2) -> Vec2

Performs the / operation.

impl Div<&Vec2> for Vec2

type Output = Vec2

The resulting type after applying the / operator.

fn div(self, rhs: &Vec2) -> Vec2

Performs the / operation.

impl Div<&Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the / operator.

fn div(self, rhs: &Vec2) -> Vec2

Performs the / operation.

impl Div<&f32> for Vec2

type Output = Vec2

The resulting type after applying the / operator.

fn div(self, rhs: &f32) -> Vec2

Performs the / operation.

impl Div<&f32> for &Vec2

type Output = Vec2

The resulting type after applying the / operator.

fn div(self, rhs: &f32) -> Vec2

Performs the / operation.

impl Div<Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the / operator.

fn div(self, rhs: Vec2) -> Vec2

Performs the / operation.

impl Div<f32> for Vec2

type Output = Vec2

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> Vec2

Performs the / operation.

impl Div<f32> for &Vec2

type Output = Vec2

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> Vec2

Performs the / operation.

impl DivAssign for Vec2

fn div_assign(&mut self, rhs: Vec2)

Performs the /= operation.

impl DivAssign<&Vec2> for Vec2

fn div_assign(&mut self, rhs: &Vec2)

Performs the /= operation.

impl DivAssign<&f32> for Vec2

fn div_assign(&mut self, rhs: &f32)

Performs the /= operation.

impl DivAssign<f32> for Vec2

fn div_assign(&mut self, rhs: f32)

Performs the /= operation.

impl From<(f32, f32)> for Vec2

fn from(t: (f32, f32)) -> Vec2

Converts to this type from the input type.

impl From<BVec2> for Vec2

fn from(v: BVec2) -> Vec2

Converts to this type from the input type.

impl From<Vec2> for DVec2

fn from(v: Vec2) -> DVec2

Converts to this type from the input type.

impl From<[f32; 2]> for Vec2

fn from(a: [f32; 2]) -> Vec2

Converts to this type from the input type.

impl Index<usize> for Vec2

type Output = f32

The returned type after indexing.

fn index(&self, index: usize) -> &<Vec2 as Index<usize>>::Output

Performs the indexing (container[index]) operation.

impl IndexMut<usize> for Vec2

fn index_mut(&mut self, index: usize) -> &mut <Vec2 as Index<usize>>::Output

Performs the mutable indexing (container[index]) operation.

impl Mul for Vec2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: Vec2) -> Vec2

Performs the * operation.

impl Mul<&Vec2> for Vec2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec2) -> Vec2

Performs the * operation.

impl Mul<&Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec2) -> Vec2

Performs the * operation.

impl Mul<&Vec2> for Mat2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec2) -> Vec2

Performs the * operation.

impl Mul<&Vec2> for &Mat2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec2) -> Vec2

Performs the * operation.

impl Mul<&f32> for Vec2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: &f32) -> Vec2

Performs the * operation.

impl Mul<&f32> for &Vec2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: &f32) -> Vec2

Performs the * operation.

impl Mul<Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: Vec2) -> Vec2

Performs the * operation.

impl Mul<Vec2> for Mat2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: Vec2) -> <Mat2 as Mul<Vec2>>::Output

Performs the * operation.

impl Mul<Vec2> for &Mat2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: Vec2) -> Vec2

Performs the * operation.

impl Mul<f32> for Vec2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Vec2

Performs the * operation.

impl Mul<f32> for &Vec2

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Vec2

Performs the * operation.

impl MulAssign for Vec2

fn mul_assign(&mut self, rhs: Vec2)

Performs the *= operation.

impl MulAssign<&Vec2> for Vec2

fn mul_assign(&mut self, rhs: &Vec2)

Performs the *= operation.

impl MulAssign<&f32> for Vec2

fn mul_assign(&mut self, rhs: &f32)

Performs the *= operation.

impl MulAssign<f32> for Vec2

fn mul_assign(&mut self, rhs: f32)

Performs the *= operation.

impl Neg for Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn neg(self) -> Vec2

Performs the unary - operation.

impl Neg for &Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn neg(self) -> Vec2

Performs the unary - operation.

impl PartialEq for Vec2

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

Equality operator ==.

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

Inequality operator !=.

impl Pod for Vec2

impl Product for Vec2

fn product<I>(iter: I) -> Vec2

where I: Iterator<Item = Vec2>,

Takes an iterator and generates Self from the elements by multiplying the items.

impl<'a> Product<&'a Vec2> for Vec2

fn product<I>(iter: I) -> Vec2

where I: Iterator<Item = &'a Vec2>,

Takes an iterator and generates Self from the elements by multiplying the items.

impl Rem for Vec2

type Output = Vec2

The resulting type after applying the % operator.

fn rem(self, rhs: Vec2) -> Vec2

Performs the % operation.

impl Rem<&Vec2> for Vec2

type Output = Vec2

The resulting type after applying the % operator.

fn rem(self, rhs: &Vec2) -> Vec2

Performs the % operation.

impl Rem<&Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the % operator.

fn rem(self, rhs: &Vec2) -> Vec2

Performs the % operation.

impl Rem<&f32> for Vec2

type Output = Vec2

The resulting type after applying the % operator.

fn rem(self, rhs: &f32) -> Vec2

Performs the % operation.

impl Rem<&f32> for &Vec2

type Output = Vec2

The resulting type after applying the % operator.

fn rem(self, rhs: &f32) -> Vec2

Performs the % operation.

impl Rem<Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the % operator.

fn rem(self, rhs: Vec2) -> Vec2

Performs the % operation.

impl Rem<f32> for Vec2

type Output = Vec2

The resulting type after applying the % operator.

fn rem(self, rhs: f32) -> Vec2

Performs the % operation.

impl Rem<f32> for &Vec2

type Output = Vec2

The resulting type after applying the % operator.

fn rem(self, rhs: f32) -> Vec2

Performs the % operation.

impl RemAssign for Vec2

fn rem_assign(&mut self, rhs: Vec2)

Performs the %= operation.

impl RemAssign<&Vec2> for Vec2

fn rem_assign(&mut self, rhs: &Vec2)

Performs the %= operation.

impl RemAssign<&f32> for Vec2

fn rem_assign(&mut self, rhs: &f32)

Performs the %= operation.

impl RemAssign<f32> for Vec2

fn rem_assign(&mut self, rhs: f32)

Performs the %= operation.

impl StructuralPartialEq for Vec2

impl Sub for Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn sub(self, rhs: Vec2) -> Vec2

Performs the - operation.

impl Sub<&Vec2> for Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn sub(self, rhs: &Vec2) -> Vec2

Performs the - operation.

impl Sub<&Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn sub(self, rhs: &Vec2) -> Vec2

Performs the - operation.

impl Sub<&f32> for Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn sub(self, rhs: &f32) -> Vec2

Performs the - operation.

impl Sub<&f32> for &Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn sub(self, rhs: &f32) -> Vec2

Performs the - operation.

impl Sub<Vec2> for &Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn sub(self, rhs: Vec2) -> Vec2

Performs the - operation.

impl Sub<f32> for Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn sub(self, rhs: f32) -> Vec2

Performs the - operation.

impl Sub<f32> for &Vec2

type Output = Vec2

The resulting type after applying the - operator.

fn sub(self, rhs: f32) -> Vec2

Performs the - operation.

impl SubAssign for Vec2

fn sub_assign(&mut self, rhs: Vec2)

Performs the -= operation.

impl SubAssign<&Vec2> for Vec2

fn sub_assign(&mut self, rhs: &Vec2)

Performs the -= operation.

impl SubAssign<&f32> for Vec2

fn sub_assign(&mut self, rhs: &f32)

Performs the -= operation.

impl SubAssign<f32> for Vec2

fn sub_assign(&mut self, rhs: f32)

Performs the -= operation.

impl Sum for Vec2

fn sum<I>(iter: I) -> Vec2

where I: Iterator<Item = Vec2>,

Takes an iterator and generates Self from the elements by “summing up” the items.

impl<'a> Sum<&'a Vec2> for Vec2

fn sum<I>(iter: I) -> Vec2

where I: Iterator<Item = &'a Vec2>,

Takes an iterator and generates Self from the elements by “summing up” the items.

impl Vec2Swizzles for Vec2

type Vec3 = Vec3

type Vec4 = Vec4

fn xx(self) -> Vec2

fn yx(self) -> Vec2

fn yy(self) -> Vec2

fn xxx(self) -> Vec3

fn xxy(self) -> Vec3

fn xyx(self) -> Vec3

fn xyy(self) -> Vec3

fn yxx(self) -> Vec3

fn yxy(self) -> Vec3

fn yyx(self) -> Vec3

fn yyy(self) -> Vec3

fn xxxx(self) -> Vec4

fn xxxy(self) -> Vec4

fn xxyx(self) -> Vec4

fn xxyy(self) -> Vec4

fn xyxx(self) -> Vec4

fn xyxy(self) -> Vec4

fn xyyx(self) -> Vec4

fn xyyy(self) -> Vec4

fn yxxx(self) -> Vec4

fn yxxy(self) -> Vec4

fn yxyx(self) -> Vec4

fn yxyy(self) -> Vec4

fn yyxx(self) -> Vec4

fn yyxy(self) -> Vec4

fn yyyx(self) -> Vec4

fn yyyy(self) -> Vec4

fn xy(self) -> Self

impl Zeroable for Vec2

fn zeroed() -> Self

Calls zeroed.