Skip to main content

Camera2d

Struct Camera2d 

Source
pub struct Camera2d {
    pub plane: Plane2d,
    pub distance: f32,
    pub pixels_per_point: f32,
    pub snap_to_pixels: bool,
    pub snap_zoom_to_texel: Option<f32>,
    pub depth_range: Option<[f32; 2]>,
    pub min_units_per_pixel: f32,
    pub max_units_per_pixel: f32,
    pub follow_time_constant: f32,
    pub dead_zone: Rect2d,
    /* private fields */
}
Expand description

A flat orthographic camera described in 2D terms.

The view is a centre on a Plane2d, a zoom as units_per_pixel (world units across one logical pixel), and a rotation about the view axis. apply_to writes the orthographic pose and projection into a Camera the host owns, and camera builds a new one; give the renderer that each frame.

On top of the view sit a follow target with damping and a dead zone, optional world bounds the visible area is kept inside, a decaying screen shake, and pixel snapping for pixel art. update advances the follow and the shake once per frame.

The stored zoom is never snapped. With snap_zoom_to_texel set, the camera written out uses the nearest zoom that shows a whole number of device pixels per texel (drawn_units_per_pixel), so small wheel steps still add up to the next scale.

screen_to_world, world_to_screen and visible_rect describe the view at the drawn zoom, without the shake offset or the position snapping that apply_to adds.

Fields§

§plane: Plane2d

The plane the camera looks at.

§distance: f32

How far the eye sits in front of the plane, in world units. Content between the eye and the far plane draws, so keep it larger than the highest layer above the plane. Defaults to 100.0.

§pixels_per_point: f32

Physical pixels per logical pixel, for pixel snapping and snap_zoom_to_integer_scale. Defaults to 1.0. Keep it at 1.0 for a viewport presented at a reference size, whose scene target has one pixel per point.

§snap_to_pixels: bool

Round the written camera position so the plane origin lands on a whole device pixel, which keeps pixel art from shimmering as the camera moves. Off by default. A host that moves the camera after apply_to (a blend or its own shake) leaves this off and calls snap_camera_to_pixels last instead.

§snap_zoom_to_texel: Option<f32>

World units per texel of the art, to keep the drawn zoom at a whole number of device pixels per texel: the written camera uses the nearest such zoom, at least one device pixel per texel, while units_per_pixel keeps the unsnapped value. None (the default) draws at the stored zoom.

§depth_range: Option<[f32; 2]>

Near and far plane distances along the view direction, measured from the eye, for the written projection. None (the default) keeps the projection’s automatic planes, which reach about max(1000, 3 * distance) from the eye. The far plane is never nearer than three times distance, which keeps the plane itself in view.

§min_units_per_pixel: f32

The smallest units per pixel zooming reaches (the closest zoom).

§max_units_per_pixel: f32

The largest units per pixel zooming reaches (the furthest zoom).

§follow_time_constant: f32

How quickly the camera catches up with its follow target: the time in seconds for the distance left outside the dead zone to fall to about 37%. Zero or less snaps straight to it. Defaults to 0.25.

§dead_zone: Rect2d

The area around the screen centre the follow target can move in without the camera moving, in pixel offsets from the centre with x right and y down. Defaults to an empty rectangle at the centre, so the camera keeps the target centred.

Implementations§

Source§

impl Camera2d

Source

pub const DEFAULT_DISTANCE: f32 = 100.0

Default distance from the eye to the plane.

Source

pub const DEFAULT_UNITS_PER_PIXEL: f32 = 0.01

Default zoom: 100 logical pixels per world unit.

Source

pub const DEFAULT_FOLLOW_TIME_CONSTANT: f32 = 0.25

Default follow time constant, in seconds.

Source

pub fn new(plane: Plane2d) -> Self

A camera on plane, centred on the origin at the default zoom, for a 1 by 1 pixel viewport: call set_viewport_size before producing a camera.

Source

pub fn with_centre(self, centre: Vec2) -> Self

Builder: set the centre; see set_centre.

Source

pub fn with_units_per_pixel(self, units_per_pixel: f32) -> Self

Builder: set the zoom; see set_units_per_pixel.

Source

pub fn with_viewport_size(self, size: Vec2) -> Self

Builder: set the viewport size in logical pixels.

Source

pub fn with_rotation(self, rotation: f32) -> Self

Builder: set the rotation; see set_rotation.

Source

pub fn with_bounds(self, bounds: Rect2d) -> Self

Builder: keep the visible area inside bounds; see set_bounds.

Source

pub fn centre(&self) -> Vec2

The plane position at the middle of the screen.

Source

pub fn set_centre(&mut self, centre: Vec2)

Move the middle of the screen to centre, then apply the bounds.

Source

pub fn units_per_pixel(&self) -> f32

World units across one logical pixel. Smaller is closer. This is the stored zoom, never snapped; see drawn_units_per_pixel.

Source

pub fn drawn_units_per_pixel(&self) -> f32

The zoom the written camera draws at: units_per_pixel, or with snap_zoom_to_texel set the nearest zoom that shows a whole number of device pixels per texel.

Source

pub fn set_units_per_pixel(&mut self, units_per_pixel: f32)

Set the zoom about the screen centre, clamped to [min_units_per_pixel, max_units_per_pixel], then apply the bounds.

Source

pub fn rotation(&self) -> f32

The turn of the view about the view axis, in radians. Positive turns the camera counter-clockwise on the plane, so the content appears to turn clockwise.

Source

pub fn set_rotation(&mut self, rotation: f32)

Set the turn about the view axis, then apply the bounds.

Source

pub fn viewport_size(&self) -> Vec2

The viewport size in logical pixels.

Source

pub fn set_viewport_size(&mut self, size: Vec2)

Set the viewport size in logical pixels, keeping the centre and zoom, then apply the bounds. Call it whenever the viewport resizes.

This is the size the scene draws at, which sets the written camera’s aspect and height: for a viewport presented at a reference size, pass the reference size (and keep pixels_per_point at 1.0), not the window’s.

Source

pub fn bounds(&self) -> Option<Rect2d>

The area the visible rectangle is kept inside, if any.

Source

pub fn set_bounds(&mut self, bounds: Option<Rect2d>)

Keep the visible area inside bounds (in plane units), or remove the limit with None. Along an axis where the view is wider than the bounds, the view centres on them instead. The shake offset is not limited.

Source

pub fn screen_to_world(&self, screen: Vec2) -> Vec2

The plane position under a screen position.

Source

pub fn world_to_screen(&self, world: Vec2) -> Vec2

The screen position of a plane position.

Source

pub fn visible_rect(&self) -> Rect2d

The plane area the viewport shows: exact at rotation 0, and the bounding rectangle of the turned view otherwise.

Source

pub fn pan(&mut self, delta_pixels: Vec2)

Move the view as if the content were dragged by delta_pixels (x right, y down): the centre moves the other way by the delta times units_per_pixel.

Source

pub fn zoom_at(&mut self, cursor_pixels: Vec2, factor: f32)

Zoom by factor about a screen position: above 1 zooms in, below 1 zooms out, and the plane point under cursor_pixels stays under it (unless the zoom limits or the bounds move it). The factor applies to the stored zoom, so with snap_zoom_to_texel set, small steps add up until the drawn scale changes.

Source

pub fn snap_zoom_to_integer_scale(&mut self, units_per_texel: f32) -> u32

Set the stored zoom so that one texel of art drawn at units_per_texel world units covers a whole number of device pixels, the nearest to the current zoom and at least one. Returns that number. The centre stays.

This rewrites the zoom, so calling it every frame rounds small wheel steps back to the same scale. To keep every frame on a whole scale while zooming, set snap_zoom_to_texel instead.

Source

pub fn follow(&mut self, target: Vec2)

Follow target, a plane position. Call it each frame the target moves; update moves the camera toward it once it leaves the dead_zone.

Source

pub fn stop_following(&mut self)

Stop following. The camera stays where it is.

Source

pub fn follow_target(&self) -> Option<Vec2>

The position being followed, if any.

Source

pub fn shake(&mut self, amplitude_pixels: f32, duration: f32)

Start a shake: a random offset of up to amplitude_pixels that decays to nothing over duration seconds. It moves only the written camera, never the centre. A weaker shake does not cut short a stronger one still running.

Source

pub fn shake_offset(&self) -> Vec2

The current shake offset in pixels, x right and y down.

Source

pub fn update(&mut self, dt: f32)

Advance the follow and the shake by dt seconds.

Source

pub fn apply_to(&self, camera: &mut Camera)

Write this view into camera: an orthographic projection as tall as the viewport height times drawn_units_per_pixel, with depth_range as its planes when set, and a pose looking along the plane’s view direction from distance in front of it, moved by the shake offset and, with snap_to_pixels, snapped to whole device pixels. The aspect comes from the viewport size and the focus distance is set to distance; the exposure is otherwise left alone.

The viewport size is the size the scene draws at: the reference size for a viewport presented at one (see set_viewport_size).

The camera is the host’s to change afterwards: blend it, shake it, then call snap_camera_to_pixels last if it should stay on the pixel grid.

Source

pub fn camera(&self) -> Camera

A new camera with this view written into it; see apply_to.

Trait Implementations§

Source§

impl Clone for Camera2d

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for Camera2d

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for Camera2d

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.