stress_preview/

stress-preview.rs

//! Many rock draws, values of one mesh type keyed by a seed and batched by
//! it, scattered from the field's center out to its own edge. A panel
//! raises or lowers the load: how many instances the field draws, how many
//! distinct seed values among them, the sun's own shadow, and whether a
//! control turns a fraction of the field each frame, and reports what a
//! frame costs alongside how many of its instances lie in the camera's
//! view.
//!
//! `cargo run --example stress-preview`. The camera starts outside the
//! field's edge looking across it toward the horizon, and orbits the
//! field's center on its own until `WASD`, the arrows, the wheel or a drag
//! first move it, at which point the orbit stops for good: `WASD` or the
//! arrows pan across the field, the wheel raises or lowers the camera, and
//! holding the left mouse button and dragging turns it, so turning away
//! from the field faces open ground and turning back faces it again.

use core::time::Duration;

use mirage_engine::prelude::*;
use mirage_engine::rayon::prelude::*;

/// Instance count the field starts at.
const DEFAULT_INSTANCE_COUNT: u32 = 5_000;
/// Least and most instances the slider allows.
const MIN_INSTANCE_COUNT: u32 = 500;
const MAX_INSTANCE_COUNT: u32 = 500_000;

/// Distinct seed values the field starts drawing.
const DEFAULT_SEED_COUNT: u32 = 8;
/// Least and most seed values the slider allows, which sets how many
/// batches the field draws in.
const MIN_SEED_COUNT: u32 = 1;
const MAX_SEED_COUNT: u32 = 64;

/// Meters from the center the field scatters over, out to the horizon
/// under the camera's orbit.
const FIELD_RADIUS: f32 = 400.0;
/// Nearest a rock is placed to the center, so the middle stays clear.
const FIELD_INNER_RADIUS: f32 = 4.0;

/// One rock's side count.
const ROCK_SIDES: u32 = 7;
/// Its base radius and height, in meters, before either is displaced.
const ROCK_BASE_RADIUS: f32 = 0.5;
const ROCK_HEIGHT: f32 = 1.4;
/// How far each base corner, and the whole rock's height, are displaced by
/// an integer-hash of its seed, as a fraction of the base value.
const ROCK_RADIAL_DISPLACEMENT: f32 = 0.3;
const ROCK_HEIGHT_DISPLACEMENT: f32 = 0.3;

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

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

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

/// One instance in every `MOVING_STRIDE` is the fraction a control turns
/// each frame.
const MOVING_STRIDE: u32 = 5;
/// Radians a moving rock turns per second.
const MOVING_SPEED: f32 = 0.6;

/// The camera's height above the ground and its distance from the center,
/// placed outside the field's own edge so its shallow angle down to the
/// center keeps the horizon in frame; its vertical field of view in
/// degrees, and the radians it turns per second.
const CAMERA_HEIGHT: f32 = 40.0;
const CAMERA_ORBIT_RADIUS: f32 = 440.0;
const CAMERA_FOV: f32 = 55.0;
const CAMERA_ANGULAR_SPEED: f32 = 0.05;

/// Items the camera's view test samples at most, stepping over the field
/// instead of a test per item where it holds more.
const MAX_IN_VIEW_SAMPLES: u32 = 50_000;

/// Meters a player's pan covers per second.
const PAN_SPEED: f32 = 30.0;
/// Meters one wheel step raises or lowers the camera.
const WHEEL_STEP: f32 = 3.0;
/// The camera's least and most height above the ground once the player
/// holds it.
const MIN_CAMERA_HEIGHT: f32 = 2.0;
const MAX_CAMERA_HEIGHT: f32 = 250.0;
/// Radians a drag turns the view by, per physical pixel it crosses.
const LOOK_SENSITIVITY: f32 = core::f32::consts::FRAC_PI_2 / 1280.0;
/// How far short of straight up or down the pitch may turn, in radians.
const PITCH_LIMIT: f32 = 1.5;

/// Frames the average frame time is taken over.
const FRAME_TIME_SAMPLES: usize = 60;

/// The control panel's padding, in points.
const PANEL_PADDING: i8 = 8;

fn main() {
    run(
        Config::new("Mirage: stress preview").with_size(1280, 720),
        StressPreview::init,
    );
}

/// One generated rock: a cone of [`ROCK_SIDES`] sides, whose base corners
/// and height are each displaced by an integer-hash of `seed`.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
#[catalog(Self { seed: 0 }, Self { seed: 1 }, Self { seed: 2 })]
struct Rock {
    seed: u32,
}

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

// Everything this game draws: the generated rock field and the ground
// plane under it.
meshes! { enum Shape { Rock, Plane } }

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

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

/// `WASD`/arrows pan the camera across the field; the pointer's own motion
/// turns it, read only while [`Drag::Turn`] is held.
#[derive(InputAxis2Action, Clone, Copy, PartialEq)]
enum Motion {
    Pan,
    Look,
}

impl InputAxis2Action for Motion {
    fn bindings(&self) -> Vec<Axis2Binding> {
        match self {
            Self::Pan => 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,
                }),
            ],
            Self::Look => vec![Axis2Binding::pointer().scale(LOOK_SENSITIVITY)],
        }
    }
}

/// Held, turns the camera by the pointer's own motion while dragging.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Drag {
    Turn,
}

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

/// How far the wheel moved this frame, which raises or lowers the camera.
#[derive(InputAxisAction, Clone, Copy, PartialEq)]
enum Height {
    Wheel,
}

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

struct Controls;

impl InputActions for Controls {
    type Button = Drag;
    type Axis = Height;
    type Axis2 = Motion;
}

/// One entry of the field: which rock it draws, where it stands, the
/// turn it starts at, and whether it is one the moving control turns
/// further each frame.
struct FieldEntry {
    seed: u32,
    position: Vec3,
    phase: f32,
    moving: bool,
}

/// The load a player sets: how many instances the field draws, how many
/// distinct seed values among them, and the two controls beside them.
struct Settings {
    instance_count: u32,
    seed_count: u32,
    sun_shadow: bool,
    moving: bool,
}

impl Default for Settings {
    fn default() -> Self {
        Self {
            instance_count: DEFAULT_INSTANCE_COUNT,
            seed_count: DEFAULT_SEED_COUNT,
            sun_shadow: true,
            moving: true,
        }
    }
}

/// Frame time averaged over the last [`FRAME_TIME_SAMPLES`] frames, in
/// milliseconds.
struct FrameTimer {
    samples: [f32; FRAME_TIME_SAMPLES],
    filled: usize,
    next: usize,
}

impl FrameTimer {
    fn new() -> Self {
        Self {
            samples: [0.0; FRAME_TIME_SAMPLES],
            filled: 0,
            next: 0,
        }
    }

    fn record(&mut self, dt: Duration) {
        self.samples[self.next] = dt.as_secs_f32() * 1000.0;
        self.next = (self.next + 1) % self.samples.len();
        self.filled = (self.filled + 1).min(self.samples.len());
    }

    /// The average over every sample kept so far, `0.0` before the first.
    fn average_ms(&self) -> f32 {
        if self.filled == 0 {
            return 0.0;
        }
        self.samples[..self.filled].iter().sum::<f32>() / self.filled as f32
    }
}

/// The camera once the player has taken it over: an `eye` turned by `yaw`
/// (around the world's own up) and `pitch` (up or down).
struct Player {
    eye: Vec3,
    yaw: f32,
    pitch: f32,
}

impl Player {
    /// This camera's forward direction, from `yaw` and `pitch`.
    fn forward(&self) -> Vec3 {
        Vec3::new(
            -self.pitch.cos() * self.yaw.sin(),
            self.pitch.sin(),
            -self.pitch.cos() * self.yaw.cos(),
        )
    }

    fn camera(&self) -> Camera {
        Camera::new(
            View::look_at(self.eye, self.eye + self.forward()),
            Projection::perspective(CAMERA_FOV),
        )
    }
}

struct StressPreview {
    settings: Settings,
    applied_instance_count: u32,
    applied_seed_count: u32,
    field: Vec<FieldEntry>,
    frame_times: FrameTimer,
    /// Set at the instant a pan, a wheel step or a drag first moves the
    /// camera; from then on the orbit never runs again.
    player: Option<Player>,
}

impl StressPreview {
    fn init(_ctx: &mut InitContext<'_, Self>) -> Result<Self, Error> {
        let settings = Settings::default();
        let field = build_field(settings.instance_count, settings.seed_count);
        Ok(Self {
            applied_instance_count: settings.instance_count,
            applied_seed_count: settings.seed_count,
            settings,
            field,
            frame_times: FrameTimer::new(),
            player: None,
        })
    }

    /// Rebuilds the field where the instance count or the seed count
    /// changed since the last frame.
    fn apply_settings(&mut self) {
        if self.settings.instance_count == self.applied_instance_count
            && self.settings.seed_count == self.applied_seed_count
        {
            return;
        }
        self.field = build_field(self.settings.instance_count, self.settings.seed_count);
        self.applied_instance_count = self.settings.instance_count;
        self.applied_seed_count = self.settings.seed_count;
    }

    /// The camera's place along the orbit at `elapsed`, before the player
    /// takes it over.
    fn orbit_eye(elapsed: f32) -> Vec3 {
        let angle = elapsed * CAMERA_ANGULAR_SPEED;
        Vec3::new(
            angle.cos() * CAMERA_ORBIT_RADIUS,
            CAMERA_HEIGHT,
            angle.sin() * CAMERA_ORBIT_RADIUS,
        )
    }

    /// The frame's camera: the orbit at `elapsed`, or the player's own
    /// place once they have taken over.
    fn camera(&self, elapsed: f32) -> Camera {
        match &self.player {
            Some(player) => player.camera(),
            None => Camera::new(
                View::look_at(Self::orbit_eye(elapsed), Vec3::ZERO),
                Projection::perspective(CAMERA_FOV),
            ),
        }
    }

    /// Reads the pan, wheel and drag controls, taking the camera over from
    /// the orbit at the first frame any of them moves it.
    fn handle_camera(&mut self, ctx: &mut FrameContext<'_, Self>, elapsed: f32) {
        if ctx.ui_wants_pointer() || ctx.ui_wants_keyboard() {
            return;
        }
        let pan = ctx.axis2(Motion::Pan);
        let wheel = ctx.axis(Height::Wheel);
        let look = if ctx.down(Drag::Turn) {
            ctx.axis2(Motion::Look)
        } else {
            Vec2::ZERO
        };
        if pan == Vec2::ZERO && wheel == 0.0 && look == Vec2::ZERO {
            return;
        }

        let player = self.player.get_or_insert_with(|| {
            let eye = Self::orbit_eye(elapsed);
            let forward = (Vec3::ZERO - eye).normalize();
            Player {
                eye,
                yaw: (-forward.x).atan2(-forward.z),
                pitch: forward.y.asin(),
            }
        });

        player.yaw -= look.x;
        player.pitch = (player.pitch + look.y).clamp(-PITCH_LIMIT, PITCH_LIMIT);

        let forward = Vec3::new(-player.yaw.sin(), 0.0, -player.yaw.cos());
        let right = Vec3::new(player.yaw.cos(), 0.0, -player.yaw.sin());
        player.eye += (forward * pan.y + right * pan.x) * PAN_SPEED * ctx.dt().as_secs_f32();
        player.eye.y =
            (player.eye.y + wheel * WHEEL_STEP).clamp(MIN_CAMERA_HEIGHT, MAX_CAMERA_HEIGHT);
    }

    fn draw_ground(ctx: &mut FrameContext<'_, Self>) {
        let side = (FIELD_RADIUS + FIELD_INNER_RADIUS) * 2.2;
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(side, 1.0, side)))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );
    }

    fn draw_field(&self, ctx: &mut FrameContext<'_, Self>, elapsed: f32) {
        for entry in &self.field {
            let yaw = if self.settings.moving && entry.moving {
                entry.phase + elapsed * MOVING_SPEED
            } else {
                entry.phase
            };
            ctx.draw(
                Rock { seed: entry.seed }.at(Transform::from_scale_rotation_translation(
                    Vec3::ONE,
                    Quat::from_rotation_y(yaw),
                    entry.position,
                )),
            );
        }
    }

    /// How many field items lie in the camera's view at `window_size`:
    /// every item where the field holds at most [`MAX_IN_VIEW_SAMPLES`],
    /// otherwise one item stepped at a time and the count scaled back up
    /// to the whole field; `true` in the second place where the count
    /// came from such a step.
    ///
    /// Each item is tested on the engine's own workers: a parallel iterator
    /// reaches them with nothing configured for it.
    fn count_in_view(&self, camera: &Camera, window_size: UVec2) -> (usize, bool) {
        let stride = (self.field.len() as u32 / MAX_IN_VIEW_SAMPLES).max(1) as usize;
        let tested = self.field.par_iter().step_by(stride);
        let tested_count = self.field.len().div_ceil(stride);
        let in_view = tested
            .filter(|entry| Self::in_view(camera, entry.position, window_size))
            .count();
        let estimate = in_view
            .checked_mul(self.field.len())
            .and_then(|scaled| scaled.checked_div(tested_count))
            .unwrap_or(in_view);
        (estimate, stride > 1)
    }

    /// Whether `position` draws inside `window_size`, the frame's own
    /// bound of what the camera's view holds.
    fn in_view(camera: &Camera, position: Vec3, window_size: UVec2) -> bool {
        camera.pixel_of(position, window_size).is_some_and(|pixel| {
            pixel.x >= 0.0
                && pixel.y >= 0.0
                && pixel.x < window_size.x as f32
                && pixel.y < window_size.y as f32
        })
    }

    /// The load controls, and this frame's own cost, reported below them.
    fn controls(&mut self, ctx: &mut FrameContext<'_, Self>, camera: &Camera) {
        let submitted = self.field.len();
        let seeds = self.applied_seed_count;
        let average_ms = self.frame_times.average_ms();
        let fps = if average_ms > 0.0 {
            1000.0 / average_ms
        } else {
            0.0
        };
        let elapsed = ctx.elapsed().as_secs_f32();
        let (in_view, sampled) = self.count_in_view(camera, ctx.window_size());

        ctx.ui(|ui| {
            egui::Frame::new()
                .fill(egui::Color32::from_gray(24))
                .inner_margin(PANEL_PADDING)
                .corner_radius(f32::from(PANEL_PADDING))
                .show(ui, |ui| {
                    ui.add(
                        egui::Slider::new(
                            &mut self.settings.instance_count,
                            MIN_INSTANCE_COUNT..=MAX_INSTANCE_COUNT,
                        )
                        .text("instance count"),
                    );
                    ui.add(
                        egui::Slider::new(
                            &mut self.settings.seed_count,
                            MIN_SEED_COUNT..=MAX_SEED_COUNT,
                        )
                        .text("distinct seeds"),
                    );
                    ui.checkbox(&mut self.settings.sun_shadow, "sun shadow");
                    ui.checkbox(&mut self.settings.moving, "moving fraction");
                    ui.separator();
                    ui.label(format!("instances submitted {submitted}"));
                    if sampled {
                        ui.label(format!("in view, sampled {in_view}"));
                    } else {
                        ui.label(format!("instances in view {in_view}"));
                    }
                    ui.label(format!("distinct seeds {seeds}"));
                    ui.label(format!("frame time {average_ms:.2}ms, {fps:.0} fps"));
                    ui.label(format!("elapsed {elapsed:.1}s"));
                });
        });
    }
}

/// `instance_count` field values, each drawing one of `seed_count`
/// distinct seed values in a cycle, and scattered from
/// [`FIELD_INNER_RADIUS`] out to [`FIELD_RADIUS`]; each built from an
/// integer-hash of its own index.
fn build_field(instance_count: u32, seed_count: u32) -> Vec<FieldEntry> {
    (0..instance_count)
        .map(|index| {
            let angle = hash_unit(index, 0) * core::f32::consts::TAU;
            let spread = hash_unit(index, 1).sqrt();
            let distance = FIELD_INNER_RADIUS + spread * (FIELD_RADIUS - FIELD_INNER_RADIUS);
            FieldEntry {
                seed: index % seed_count,
                position: Vec3::new(angle.cos() * distance, 0.0, angle.sin() * distance),
                phase: hash_unit(index, 2) * core::f32::consts::TAU,
                moving: index % MOVING_STRIDE == 0,
            }
        })
        .collect()
}

/// A rock built from `seed`: a cone of [`ROCK_SIDES`] sides, each base
/// corner and the apex height displaced by an integer-hash of `seed`.
fn build_rock(seed: u32) -> MeshData {
    let height = ROCK_HEIGHT * (1.0 + hash_signed(seed, ROCK_SIDES) * ROCK_HEIGHT_DISPLACEMENT);
    let apex = Vec3::Y * height;
    let base: Vec<Vec3> = (0..ROCK_SIDES)
        .map(|corner| {
            let angle = core::f32::consts::TAU * corner as f32 / ROCK_SIDES as f32;
            let radius =
                ROCK_BASE_RADIUS * (1.0 + hash_signed(seed, corner) * ROCK_RADIAL_DISPLACEMENT);
            Vec3::new(angle.cos() * radius, 0.0, angle.sin() * radius)
        })
        .collect();

    let mut vertices = Vec::with_capacity(base.len() * 6);
    let mut indices = Vec::with_capacity(base.len() * 6);
    for corner in 0..base.len() {
        let next = (corner + 1) % base.len();
        push_face(&mut vertices, &mut indices, base[corner], apex, base[next]);
        push_face(
            &mut vertices,
            &mut indices,
            base[corner],
            base[next],
            Vec3::ZERO,
        );
    }

    MeshData::new(vertices, indices).with_material(Material::lit(ROCK_COLOR))
}

/// One triangle, shaded flat, over `a`, `b`, `c`, in the order that faces
/// outward: counter-clockwise as seen from the side its own normal points
/// to.
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]);
}

/// An integer-hash of `seed` and `salt`.
fn hash(seed: u32, salt: u32) -> u32 {
    let mut x = seed ^ salt.wrapping_mul(0x9E37_79B9);
    x ^= x >> 16;
    x = x.wrapping_mul(0x7FEB_352D);
    x ^= x >> 15;
    x = x.wrapping_mul(0x846C_A68B);
    x ^= x >> 16;
    x
}

/// `hash`, scaled to `0.0..1.0`.
fn hash_unit(seed: u32, salt: u32) -> f32 {
    hash(seed, salt) as f32 / u32::MAX as f32
}

/// `hash`, scaled to `-1.0..1.0`.
fn hash_signed(seed: u32, salt: u32) -> f32 {
    hash_unit(seed, salt) * 2.0 - 1.0
}

impl Game for StressPreview {
    type Meshes = Shape;
    type Sounds = NoSounds;
    type InputActions = Controls;
    type Skyboxes = Sky;
    type SurfaceStyles = NoSurfaceStyles;
    type PostEffects = NoPostEffects;

    fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}

    fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
        self.apply_settings();
        self.frame_times.record(ctx.dt());

        let elapsed = ctx.elapsed().as_secs_f32();
        self.handle_camera(ctx, elapsed);
        let camera = self.camera(elapsed);
        ctx.set_camera(camera);
        ctx.set_skybox(Sky::Day);

        let sun = Light::directional(SUN_DIRECTION, SUN_COLOR);
        ctx.light(if self.settings.sun_shadow {
            sun.shadow()
        } else {
            sun
        });

        Self::draw_ground(ctx);
        self.draw_field(ctx, elapsed);
        self.controls(ctx, &camera);
    }
}