Struct Camera 

pub struct Camera { /* private fields */ }

A View and a Projection: where a frame is viewed from, and how that view is projected.

A frame is drawn from the last call to FrameContext::set_camera; each frame needs its own.

Implementations

impl Camera

pub const fn new(view: View, projection: Projection) -> Self

A camera from view and projection.

Examples found in repository

examples/material-playground.rs (lines 788-791)

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

examples/stress-preview.rs (lines 289-292)

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

examples/breakout-game.rs (lines 583-586)

    fn camera() -> Camera {
        Camera::new(
            View::look_at(Vec3::new(0.0, 13.5, 12.5), Vec3::new(0.0, 0.0, 0.5)),
            Projection::perspective(50.0),
        )
    }

examples/isometric-board.rs (lines 384-387)

    fn camera() -> Camera {
        let eye = Vec3::new(9.0, 9.0, 9.0);
        Camera::new(
            View::look_at(eye, Vec3::ZERO),
            Projection::orthographic(11.0),
        )
    }

examples/sprite-adventure.rs (lines 1037-1040)

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

examples/sound-lab.rs (lines 452-458)

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

Additional examples can be found in:

• examples/post-effects.rs
• examples/ui-fonts.rs
• examples/animation.rs
• examples/flock-parallelism.rs

pub const fn view(&self) -> View

The world’s viewpoint.

pub const fn projection(&self) -> Projection

The view’s projection onto the screen.

pub fn ray_through(&self, pixel: Vec2, size: UVec2) -> Ray

The ray through pixel on a surface size across, in world space.

Both are physical pixels, as FrameContext::window_size reports them. The ray starts at the View::eye where the lens foreshortens, and in the view plane where it does not.

Examples found in repository

examples/ui-fonts.rs (line 637)

    fn handle_hail(&mut self, ctx: &mut TickContext<'_, Self>) {
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());
        let Some(station) = hit_station(ray) else {
            return;
        };

        if self.hailed != Some(station) {
            self.hailed = Some(station);
            let look = station.look();
            self.dialogue = Some(Dialogue::start(look.name, look.lines.map(str::to_owned)));
            return;
        }
        let Some(dialogue) = &mut self.dialogue else {
            return;
        };
        if !dialogue.advance() {
            self.dialogue = None;
            self.hailed = None;
        }
    }

    fn draw_station(&self, ctx: &mut FrameContext<'_, Self>, station: StationKind) {
        let look = station.look();
        let center = station.center();
        let front_offset =
            STATION_SIZE.z * 0.5 - STATION_FRONT_SIZE.z * 0.5 + STATION_FRONT_OUTWARD;
        let front = center - Vec3::new(0.0, 0.0, front_offset);
        for (size, position, material) in [
            (STATION_SIZE, center, Material::lit(look.color)),
            (
                STATION_FRONT_SIZE,
                front,
                Material::color(Color::BLACK).emissive(look.glow),
            ),
        ] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    size,
                    Quat::IDENTITY,
                    position,
                ))
                .material(material),
            );
        }
    }

    fn draw_bracket(&self, ctx: &mut FrameContext<'_, Self>, camera: Camera, station: StationKind) {
        let top = station.center() + Vec3::Y * (STATION_SIZE.y * 0.5);
        let window_size = ctx.window_size();
        let Some(pixel) = camera.pixel_of(top, window_size) else {
            return;
        };
        let at = logical(pixel, ctx.pixels_per_point());

        let name = ctx.text_layout(station.look().name, egui::FontId::proportional(BODY_SIZE));
        let (reading_text, number_text) = station.reading(self.elapsed.as_secs_f32());
        let reading = ctx.text_layout(&reading_text, egui::FontId::monospace(BODY_SIZE));
        let number = ctx.text_layout(
            &number_text,
            egui::FontId::new(NUMBER_SIZE, egui::FontFamily::Name(DISPLAY_FAMILY.into())),
        );

        ctx.ui(|ui| bracket(ui.painter(), at, name, reading, number));
    }

    /// A `Prompt` for `Trigger::Hail`, above every `StationKind` but
    /// `hovered`: what a player presses to reach one, apart from a hover.
    fn draw_prompts(
        &self,
        ctx: &mut FrameContext<'_, Self>,
        camera: Camera,
        hovered: Option<StationKind>,
    ) {
        let Some(binding) = ctx.bindings(Trigger::Hail).into_iter().next() else {
            return;
        };
        let hint = prompt(&binding);
        let glyph = ctx.text_layout(&hint.text(), egui::FontId::new(PROMPT_SIZE, hint.family()));
        let window_size = ctx.window_size();
        let pixels_per_point = ctx.pixels_per_point();

        ctx.ui(|ui| {
            let painter = ui.painter();
            for station in StationKind::ALL {
                if Some(station) == hovered {
                    continue;
                }
                let top = station.center() + Vec3::Y * (STATION_SIZE.y * 0.5);
                let Some(pixel) = camera.pixel_of(top, window_size) else {
                    continue;
                };
                let at = logical(pixel, pixels_per_point);
                let at = egui::pos2(at.x, at.y - PROMPT_LIFT);
                prompt_at(painter, at, glyph.clone());
            }
        });
    }

    /// The title, a line and the reading, each in a font this game loaded
    /// rather than egui's own.
    fn panel(&self, ctx: &mut FrameContext<'_, Self>) {
        ctx.ui(|ui| {
            ui.label(styled(
                "a game's own fonts",
                egui::FontId::proportional(HEADING_SIZE),
            ));
            ui.label(styled(
                "drawn in Pixel Operator, the game's proportional font",
                egui::FontId::proportional(BODY_SIZE),
            ));
            ui.label(styled(
                "the readings above each station in Pixel Operator Mono",
                egui::FontId::monospace(BODY_SIZE),
            ));
        });
    }

    fn draw_dialogue(&self, ctx: &mut FrameContext<'_, Self>) {
        let Some(dialogue) = &self.dialogue else {
            return;
        };
        let whole = ctx.text_layout(
            dialogue.current_line(),
            egui::FontId::proportional(BODY_SIZE),
        );
        let size = whole.size();
        ctx.ui(|ui| dialogue.draw(ui, size));
    }

    /// The `StationKind` under the pointer, `None` while the UI holds it.
    fn hovered(ctx: &FrameContext<'_, Self>) -> Option<StationKind> {
        if ctx.ui_wants_pointer() {
            return None;
        }
        hit_station(
            ctx.last_camera()
                .ray_through(ctx.pointer(), ctx.window_size()),
        )
    }

examples/sound-lab.rs (line 486)

    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/isometric-board.rs (line 420)

    fn handle_click(&mut self, ctx: &mut TickContext<'_, Board>) {
        if ctx.ui_wants_pointer() || !ctx.pressed(Button::Select) {
            return;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());
        let (lift, half) = unit_geometry(self.turn);

        if self.current().target.is_none() {
            let center = self.current().position;
            if ray.hit_aabb(center - half, center + half).is_some() {
                self.selected = !self.selected;
                return;
            }
        }
        if !self.selected {
            return;
        }

        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return;
        };
        let Some(tile) = tile_at(ray.at(distance)) else {
            return;
        };
        if tile == self.current().tile || tile == self.other().tile {
            return;
        }

        let destination = tile_center(tile) + Vec3::Y * lift;
        let heading = destination.x - self.current().position.x;
        let current = self.current_mut();
        if heading.abs() > f32::EPSILON {
            current.facing_right = heading > 0.0;
        }
        current.target = Some(destination);
        self.selected = false;
        ctx.play(Sound::Click);
    }

    /// Cursor target, `None` while the UI has the pointer.
    fn hovered(&self, ctx: &FrameContext<'_, Board>) -> Hover {
        if ctx.ui_wants_pointer() {
            return Hover::None;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());

        if self.current().target.is_none() {
            let (_, half) = unit_geometry(self.turn);
            let center = self.current().position;
            if ray.hit_aabb(center - half, center + half).is_some() {
                return Hover::CurrentUnit;
            }
        }
        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return Hover::None;
        };
        match tile_at(ray.at(distance)) {
            Some(tile) => Hover::Tile(tile),
            None => Hover::None,
        }
    }

pub fn pixel_of(&self, point: Vec3, size: UVec2) -> Option<Vec2>

The pixel point draws at, on a surface size across, in physical pixels.

The inverse of Camera::ray_through at the same size, counted from the drawing area’s top left. A point off screen returns a pixel outside the surface, for the caller to clamp. None where point lies at or behind the View::eye, where either side of size is zero, or where the view or the lens has no shape to draw through.

Examples found in repository

examples/stress-preview.rs (line 445)

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

examples/ui-fonts.rs (line 685)

    fn draw_bracket(&self, ctx: &mut FrameContext<'_, Self>, camera: Camera, station: StationKind) {
        let top = station.center() + Vec3::Y * (STATION_SIZE.y * 0.5);
        let window_size = ctx.window_size();
        let Some(pixel) = camera.pixel_of(top, window_size) else {
            return;
        };
        let at = logical(pixel, ctx.pixels_per_point());

        let name = ctx.text_layout(station.look().name, egui::FontId::proportional(BODY_SIZE));
        let (reading_text, number_text) = station.reading(self.elapsed.as_secs_f32());
        let reading = ctx.text_layout(&reading_text, egui::FontId::monospace(BODY_SIZE));
        let number = ctx.text_layout(
            &number_text,
            egui::FontId::new(NUMBER_SIZE, egui::FontFamily::Name(DISPLAY_FAMILY.into())),
        );

        ctx.ui(|ui| bracket(ui.painter(), at, name, reading, number));
    }

    /// A `Prompt` for `Trigger::Hail`, above every `StationKind` but
    /// `hovered`: what a player presses to reach one, apart from a hover.
    fn draw_prompts(
        &self,
        ctx: &mut FrameContext<'_, Self>,
        camera: Camera,
        hovered: Option<StationKind>,
    ) {
        let Some(binding) = ctx.bindings(Trigger::Hail).into_iter().next() else {
            return;
        };
        let hint = prompt(&binding);
        let glyph = ctx.text_layout(&hint.text(), egui::FontId::new(PROMPT_SIZE, hint.family()));
        let window_size = ctx.window_size();
        let pixels_per_point = ctx.pixels_per_point();

        ctx.ui(|ui| {
            let painter = ui.painter();
            for station in StationKind::ALL {
                if Some(station) == hovered {
                    continue;
                }
                let top = station.center() + Vec3::Y * (STATION_SIZE.y * 0.5);
                let Some(pixel) = camera.pixel_of(top, window_size) else {
                    continue;
                };
                let at = logical(pixel, pixels_per_point);
                let at = egui::pos2(at.x, at.y - PROMPT_LIFT);
                prompt_at(painter, at, glyph.clone());
            }
        });
    }

examples/sprite-adventure.rs (line 1653)

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

examples/isometric-board.rs (line 686)

    fn draw_prompt(&self, ctx: &mut FrameContext<'_, Board>, camera: Camera, hover: Hover) {
        let Some(text) = self.click_effect(hover) else {
            return;
        };
        let point = match hover {
            Hover::CurrentUnit => {
                let (lift, _) = unit_geometry(self.turn);
                self.current().position + Vec3::Y * (lift * 2.0 + PROMPT_UNIT_LIFT)
            }
            Hover::Tile(tile) => tile_center(tile) + Vec3::Y * PROMPT_TILE_LIFT,
            Hover::None => return,
        };
        let galley = ctx.text_layout(text, egui::FontId::proportional(PROMPT_SIZE));
        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;
        };
        let at = logical(pixel, pixels_per_point);
        ctx.ui(|ui| {
            let painter = ui.painter();
            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(PROMPT_PADDING * 2.0),
            );
            painter.rect_filled(
                backdrop,
                PROMPT_PADDING,
                egui::Color32::from_black_alpha(PROMPT_BACKDROP),
            );
            painter.galley(pos, galley, PROMPT_TEXT_COLOR);
        });
    }

examples/animation.rs (line 853)

    fn draw_prompts(&self, ctx: &mut FrameContext<'_, Scene>, camera: Camera) {
        let sit_key = ctx
            .bindings(Button::Interact)
            .into_iter()
            .next()
            .map_or_else(|| "interact".to_owned(), |binding| binding.to_string());
        let sit = ctx.text_layout(
            &format!("{sit_key} sits"),
            egui::FontId::proportional(PROMPT_SIZE),
        );
        let hurts = ctx.text_layout("hurts", egui::FontId::proportional(PROMPT_SIZE));
        let walk_closer = ctx.text_layout("walk closer", egui::FontId::proportional(PROMPT_SIZE));

        let mut prompts = vec![(
            SCRUBBED_ELF_POSITION + Vec3::Y * (ELF_HEIGHT + PROMPT_LIFT),
            walk_closer,
        )];
        if !self.elf_animator.state().seated() {
            prompts.push((
                SEAT_POSITION + Vec3::Y * (SEAT_HEAD_HEIGHT + PROMPT_LIFT),
                sit,
            ));
        }
        prompts.extend(HURT_PATCHES.map(|patch| (patch + Vec3::Y * PROMPT_LIFT, hurts.clone())));

        let window_size = ctx.window_size();
        let pixels_per_point = ctx.pixels_per_point();
        ctx.ui(|ui| {
            let painter = ui.painter();
            for (point, galley) in prompts {
                let Some(pixel) = camera.pixel_of(point, window_size) else {
                    continue;
                };
                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(PROMPT_PADDING * 2.0),
                );
                painter.rect_filled(
                    backdrop,
                    PROMPT_PADDING,
                    egui::Color32::from_black_alpha(PANEL_BACKDROP),
                );
                painter.galley(pos, galley, PANEL_TEXT_COLOR);
            }
        });
    }

pub fn pixels_per_meter(&self, point: Vec3, size: UVec2) -> Option<f32>

The pixels a meter across the view covers at the depth of point in front of the View::eye, on a surface size across: the scale.

The scale falls with depth under Lens::Perspective and stays the same at every depth under Lens::Orthographic. None where point lies at or behind the View::eye, where either side of size is zero, or where the view or the lens has no shape to draw through.

pub fn shifted_so( &self, point: Vec3, lands_at: Vec2, size: UVec2, ) -> Option<Camera>

The same camera moved so that point draws at lands_at, on a surface size across.

Required if you want a drag to pan the view. lands_at is a pixel as pixel_of returns one: physical pixels from the drawing area’s top left. The camera is moved and never turned, and it moves in the view plane, so point keeps its depth and the View::eye and View::target move by the same vector. None where point lies at or behind the View::eye, where either side of size is zero, where the view or the lens has no shape to draw through, where lands_at is not finite, or where the camera it would return does not draw point: the View::eye and View::target landed together.

pub fn zoomed_about( &self, point: Vec3, factor: f32, size: UVec2, ) -> Option<Camera>

The same camera zoomed about point, on a surface size across, so that point keeps the pixel it draws at.

Required if you want a wheel to zoom towards what the pointer is over. The distance from the View::eye to point becomes the fraction 1.0 / factor of what it was, so 2.0 halves it, and the direction the view looks and its field of view are left alone. Under Lens::Orthographic the View::eye keeps its own depth: the lens takes that same fraction of its world height and the View::eye moves in the view plane instead. None where point lies at or behind the View::eye, where either side of size is zero, where the view or the lens has no shape to draw through, where factor is not finite or not above zero, or where the camera it would return does not draw point: the View::eye and View::target landed together, or the lens was left with no finite height.

pub fn turned_about(&self, point: Vec3, yaw: f32, pitch: f32) -> Option<Camera>

The same camera turned about point, so that point keeps the pixel it draws at.

Required if you want a drag to orbit the view about what the pointer is over. The View::eye turns about point by pitch radians about the direction across the view to the right, then by yaw radians about the View::up direction, and the direction the view looks turns with it, so the distance from the View::eye to point and the Projection are left alone. None where point lies at or behind the View::eye, where the view has no shape to draw through, where yaw or pitch is not finite, or where the turn takes the direction the view looks past the View::up direction — the pole.

Trait Implementations

impl Clone for Camera

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Camera

impl Debug for Camera

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

Formats the value using the given formatter.

impl Default for Camera

fn default() -> Self

Looks at the origin from 5 meters back and 2 meters up, at 60°.

impl PartialEq for Camera

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Camera