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: Plane2dThe plane the camera looks at.
distance: f32How 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: f32Physical 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: boolRound 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: f32The smallest units per pixel zooming reaches (the closest zoom).
max_units_per_pixel: f32The largest units per pixel zooming reaches (the furthest zoom).
follow_time_constant: f32How 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: Rect2dThe 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
impl Camera2d
Sourcepub const DEFAULT_DISTANCE: f32 = 100.0
pub const DEFAULT_DISTANCE: f32 = 100.0
Default distance from the eye to the plane.
Sourcepub const DEFAULT_UNITS_PER_PIXEL: f32 = 0.01
pub const DEFAULT_UNITS_PER_PIXEL: f32 = 0.01
Default zoom: 100 logical pixels per world unit.
Sourcepub const DEFAULT_FOLLOW_TIME_CONSTANT: f32 = 0.25
pub const DEFAULT_FOLLOW_TIME_CONSTANT: f32 = 0.25
Default follow time constant, in seconds.
Sourcepub fn new(plane: Plane2d) -> Self
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.
Sourcepub fn with_centre(self, centre: Vec2) -> Self
pub fn with_centre(self, centre: Vec2) -> Self
Builder: set the centre; see set_centre.
Sourcepub fn with_units_per_pixel(self, units_per_pixel: f32) -> Self
pub fn with_units_per_pixel(self, units_per_pixel: f32) -> Self
Builder: set the zoom; see set_units_per_pixel.
Sourcepub fn with_viewport_size(self, size: Vec2) -> Self
pub fn with_viewport_size(self, size: Vec2) -> Self
Builder: set the viewport size in logical pixels.
Sourcepub fn with_rotation(self, rotation: f32) -> Self
pub fn with_rotation(self, rotation: f32) -> Self
Builder: set the rotation; see set_rotation.
Sourcepub fn with_bounds(self, bounds: Rect2d) -> Self
pub fn with_bounds(self, bounds: Rect2d) -> Self
Builder: keep the visible area inside bounds; see
set_bounds.
Sourcepub fn set_centre(&mut self, centre: Vec2)
pub fn set_centre(&mut self, centre: Vec2)
Move the middle of the screen to centre, then apply the bounds.
Sourcepub fn units_per_pixel(&self) -> f32
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.
Sourcepub fn drawn_units_per_pixel(&self) -> f32
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.
Sourcepub fn set_units_per_pixel(&mut self, units_per_pixel: f32)
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.
Sourcepub fn rotation(&self) -> f32
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.
Sourcepub fn set_rotation(&mut self, rotation: f32)
pub fn set_rotation(&mut self, rotation: f32)
Set the turn about the view axis, then apply the bounds.
Sourcepub fn viewport_size(&self) -> Vec2
pub fn viewport_size(&self) -> Vec2
The viewport size in logical pixels.
Sourcepub fn set_viewport_size(&mut self, size: Vec2)
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.
Sourcepub fn set_bounds(&mut self, bounds: Option<Rect2d>)
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.
Sourcepub fn screen_to_world(&self, screen: Vec2) -> Vec2
pub fn screen_to_world(&self, screen: Vec2) -> Vec2
The plane position under a screen position.
Sourcepub fn world_to_screen(&self, world: Vec2) -> Vec2
pub fn world_to_screen(&self, world: Vec2) -> Vec2
The screen position of a plane position.
Sourcepub fn visible_rect(&self) -> Rect2d
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.
Sourcepub fn pan(&mut self, delta_pixels: Vec2)
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.
Sourcepub fn zoom_at(&mut self, cursor_pixels: Vec2, factor: f32)
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.
Sourcepub fn snap_zoom_to_integer_scale(&mut self, units_per_texel: f32) -> u32
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.
Sourcepub fn stop_following(&mut self)
pub fn stop_following(&mut self)
Stop following. The camera stays where it is.
Sourcepub fn follow_target(&self) -> Option<Vec2>
pub fn follow_target(&self) -> Option<Vec2>
The position being followed, if any.
Sourcepub fn shake(&mut self, amplitude_pixels: f32, duration: f32)
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.
Sourcepub fn shake_offset(&self) -> Vec2
pub fn shake_offset(&self) -> Vec2
The current shake offset in pixels, x right and y down.
Sourcepub fn apply_to(&self, camera: &mut Camera)
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.