#[non_exhaustive]pub struct Camera {
pub pose: Pose,
pub projection: Projection,
pub exposure: PhysicalExposure,
pub aspect: f32,
}Expand description
The viewport camera: where it is, how it projects, and how it exposes.
pose places the eye in f64 world space and orients it.
projection maps view space to the screen, and
aspect is the viewport’s width over height, set each
frame from the viewport size. exposure carries the
physical camera settings and the focus distance.
Build an orbit camera with Camera::orbit or a pointed one with
Camera::look_at. The camera itself does not orbit: orbit controllers
keep the centre and distance, and write the camera’s pose. The focus
distance doubles as the orbit distance, so target is the
orbit centre of a camera an orbit controller drives.
All matrices are right-handed (wgpu NDC convention).
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.pose: PoseEye position and orientation.
projection: ProjectionProjection.
exposure: PhysicalExposurePhysical exposure settings and focus distance. The renderer reads
exposure from DisplaySettings::exposure, not from here; set it
from PhysicalExposure::to_exposure_mode.
aspect: f32Viewport width / height ratio, updated each frame from the viewport rect.
Implementations§
Source§impl Camera
impl Camera
Sourcepub const MIN_DISTANCE: f32 = 0.01
pub const MIN_DISTANCE: f32 = 0.01
Minimum orbit distance the zoom helpers clamp to.
Sourcepub const MAX_DISTANCE: f32 = 1.0e6
pub const MAX_DISTANCE: f32 = 1.0e6
Maximum orbit distance the zoom helpers clamp to.
Sourcepub fn new(pose: Pose) -> Camera
pub fn new(pose: Pose) -> Camera
A camera with the given pose, the default perspective projection and the default exposure.
Sourcepub fn orbit(
centre: impl Into<DVec3>,
distance: f32,
orientation: Quat,
) -> Camera
pub fn orbit( centre: impl Into<DVec3>, distance: f32, orientation: Quat, ) -> Camera
An orbit camera: the eye sits distance from centre along the
orientation’s local +Z (eye = centre + orientation * (Z * distance)),
looking at centre, which is also the focus point.
Sourcepub fn look_at(
eye: impl Into<DVec3>,
target: impl Into<DVec3>,
up: Vec3,
) -> Camera
pub fn look_at( eye: impl Into<DVec3>, target: impl Into<DVec3>, up: Vec3, ) -> Camera
A camera at eye looking at target, with up as close to the
screen’s up as it can be. target is the focus point.
Sourcepub fn with_projection(self, projection: Projection) -> Camera
pub fn with_projection(self, projection: Projection) -> Camera
Builder: set the projection.
Sourcepub fn with_aspect(self, aspect: f32) -> Camera
pub fn with_aspect(self, aspect: f32) -> Camera
Builder: set the aspect ratio (width / height).
Sourcepub fn orthographic(self) -> Camera
pub fn orthographic(self) -> Camera
Builder: switch to the orthographic projection that frames the same
height at the focus distance; see set_orthographic.
Sourcepub fn with_fov_y(self, fov_y: f32) -> Camera
pub fn with_fov_y(self, fov_y: f32) -> Camera
Builder: set the vertical field of view; see set_fov_y.
Sourcepub fn with_exposure(self, exposure: PhysicalExposure) -> Camera
pub fn with_exposure(self, exposure: PhysicalExposure) -> Camera
Builder: set the exposure.
Sourcepub fn orientation(&self) -> Quat
pub fn orientation(&self) -> Quat
Camera orientation in f32.
Examples found in repository?
38fn main() {
39 // 1. RESOLVE: feed native-shaped events into ViewportInput for one frame.
40 let mut input = ViewportInput::from_preset(BindingPreset::Viewer);
41 input.begin_frame(ViewportContext::new(
42 InputOwnership::full_window(),
43 [800.0, 600.0],
44 ));
45
46 // In the primitives preset, plain left-drag (no modifiers) orbits. Drive it
47 // by hand: place the pointer, press the button there (that sets the drag
48 // origin), then move across the viewport to accumulate the drag delta.
49 input.push_event(ViewportEvent::PointerMoved {
50 position: [400.0, 300.0].into(),
51 });
52 input.push_event(ViewportEvent::MouseButton {
53 button: MouseButton::Left,
54 state: ButtonState::Pressed,
55 });
56 input.push_event(ViewportEvent::PointerMoved {
57 position: [460.0, 300.0].into(),
58 });
59
60 let frame: ActionFrame = input.resolve();
61
62 // 2. APPLY: hand the resolved frame to your controller.
63 let mut camera = Camera::default();
64 let before = camera.orientation();
65
66 let mut controller = HalfSpeedOrbit;
67 controller.apply(&mut camera, &frame, 1.0 / 60.0);
68
69 println!("resolved orbit delta : {:?}", frame.navigation.orbit);
70 println!("camera orientation before : {before:?}");
71 println!("camera orientation after : {:?}", camera.orientation());
72 println!(
73 "moved: {}",
74 before.abs_diff_eq(camera.orientation(), 1e-6) == false
75 );
76}Sourcepub fn target_at(&self, distance: f32) -> DVec3
pub fn target_at(&self, distance: f32) -> DVec3
The point distance in front of the eye along the view direction.
Sourcepub fn target(&self) -> DVec3
pub fn target(&self) -> DVec3
The focus point: focus_distance in front of
the eye. For a camera an orbit controller drives, the orbit centre.
Sourcepub fn focus_distance(&self) -> f32
pub fn focus_distance(&self) -> f32
Distance from the eye to the focus point.
Sourcepub fn set_focus_distance(&mut self, distance: f32)
pub fn set_focus_distance(&mut self, distance: f32)
Set the focus distance without moving the camera.
Sourcepub fn set_pose(&mut self, pose: Pose)
pub fn set_pose(&mut self, pose: Pose)
Replace the pose. The projection is left alone, so an orthographic height stays as it is.
Sourcepub fn lerp(a: &Camera, b: &Camera, t: f32) -> Camera
pub fn lerp(a: &Camera, b: &Camera, t: f32) -> Camera
The camera t of the way from a to b, with t clamped to
0..=1: t = 0 returns a and t = 1 returns b exactly.
The eye position is lerped and the orientation slerped, with no orbit centre involved. The aspect and the exposure (focus distance included) are lerped.
When both projections are orthographic the height is lerped, and when
both are perspective the field of view is; near and far planes are
lerped when both cameras set them, and otherwise taken from a below
t = 0.5 and from b at or above it. When the projections differ in
kind, or either is a matrix projection, the result takes a’s
projection unchanged below t = 0.5 and b’s at or above it: there
is no smooth blend between orthographic and perspective here, and a
host that wants one builds it itself.
Sourcepub fn orbit_target(&self) -> CameraTarget
pub fn orbit_target(&self) -> CameraTarget
The camera’s orbit view: its focus point, focus distance and orientation.
Sourcepub fn set_orbit(
&mut self,
centre: impl Into<DVec3>,
distance: f32,
orientation: Quat,
)
pub fn set_orbit( &mut self, centre: impl Into<DVec3>, distance: f32, orientation: Quat, )
Place the camera on an orbit: the pose of Camera::orbit, with the
focus distance set to distance. An orthographic view height scales
with the change in distance, so zooming frames the same way in both
projections.
Sourcepub fn set_orbit_centre(&mut self, centre: impl Into<DVec3>)
pub fn set_orbit_centre(&mut self, centre: impl Into<DVec3>)
Move the orbit centre to centre, keeping the distance and
orientation. Goes through set_orbit, so an
orthographic height is rescaled if the focus distance differs from the
distance kept.
Sourcepub fn set_orbit_distance(&mut self, distance: f32)
pub fn set_orbit_distance(&mut self, distance: f32)
Move the eye to distance from the orbit centre, keeping the centre
and orientation. The distance is clamped to
[MIN_DISTANCE, MAX_DISTANCE]. An orthographic height scales with the
change in distance, as in set_orbit.
Sourcepub fn set_orbit_orientation(&mut self, orientation: Quat)
pub fn set_orbit_orientation(&mut self, orientation: Quat)
Turn the camera to orientation (normalised) about the orbit centre,
keeping the centre and distance. Goes through
set_orbit, so an orthographic height is rescaled
if the focus distance changes.
Sourcepub fn set_orbit_target(&mut self, target: CameraTarget)
pub fn set_orbit_target(&mut self, target: CameraTarget)
set_orbit from a CameraTarget. An orthographic
height scales with the change in distance.
Sourcepub fn fov_y(&self) -> f32
pub fn fov_y(&self) -> f32
Vertical angle that frames the view at the focus distance: a perspective camera’s field of view, or the matching angle for an orthographic one.
Sourcepub fn set_fov_y(&mut self, fov_y: f32)
pub fn set_fov_y(&mut self, fov_y: f32)
Set the vertical field of view in radians. An orthographic camera
takes the height that angle frames at the focus distance, so on an
orthographic camera this changes the zoom; use
set_ortho_height to set it directly. A
matrix projection is left alone.
Sourcepub fn is_orthographic(&self) -> bool
pub fn is_orthographic(&self) -> bool
Whether the projection is orthographic.
Sourcepub fn set_ortho_height(&mut self, height: f32)
pub fn set_ortho_height(&mut self, height: f32)
Set the orthographic view height in world units, leaving the pose and focus distance alone. A perspective camera becomes orthographic with that height, keeping its near and far planes; a matrix projection is left alone.
Sourcepub fn set_orthographic(&mut self, orthographic: bool)
pub fn set_orthographic(&mut self, orthographic: bool)
Switch between perspective and orthographic, keeping the framing at the focus distance. A matrix projection is left alone.
Sourcepub fn set_aspect_ratio(&mut self, width: f32, height: f32)
pub fn set_aspect_ratio(&mut self, width: f32, height: f32)
Set the aspect ratio from pixel dimensions. A zero or negative height
gives 1.0.
Sourcepub fn set_clip_planes(&mut self, znear: f32, zfar: f32)
pub fn set_clip_planes(&mut self, znear: f32, zfar: f32)
Set the near and far plane distances. On a matrix projection, sets the culling range.
Sourcepub fn depth_range(&self) -> (f32, f32)
pub fn depth_range(&self) -> (f32, f32)
(near, far) distances the camera culls between; see
Projection::depth_range.
Sourcepub fn view_height_at(&self, depth: f32) -> f32
pub fn view_height_at(&self, depth: f32) -> f32
World-space height of the view at view depth depth.
Sourcepub fn view_matrix(&self) -> Mat4
pub fn view_matrix(&self) -> Mat4
Right-handed view matrix (world -> camera space), in f32 world coordinates. Far from the world origin its translation loses precision; the renderer rebuilds it from the f64 eye.
Sourcepub fn proj_matrix(&self) -> Mat4
pub fn proj_matrix(&self) -> Mat4
The projection matrix the renderer draws with; see
Projection::proj_matrix.
Sourcepub fn culling_proj_matrix(&self) -> Mat4
pub fn culling_proj_matrix(&self) -> Mat4
The finite culling projection; see Projection::culling_proj_matrix.
Sourcepub fn view_proj_matrix(&self) -> Mat4
pub fn view_proj_matrix(&self) -> Mat4
proj_matrix times the view matrix. Unproject
screen points with screen_ray rather than through
its inverse at depth 0 and 1.
Sourcepub fn culling_view_proj_matrix(&self) -> Mat4
pub fn culling_view_proj_matrix(&self) -> Mat4
culling_proj_matrix times the view matrix.
Sourcepub fn frustum(&self) -> Frustum
pub fn frustum(&self) -> Frustum
The view frustum of culling_view_proj_matrix
in world space, built relative to the eye; see
Frustum::from_eye_relative.
Sourcepub fn screen_ray(&self, ndc: Vec2) -> (Vec3, Vec3)
pub fn screen_ray(&self, ndc: Vec2) -> (Vec3, Vec3)
The world-space ray through a point on screen, as (origin, direction)
with a unit direction.
ndc is the point in normalised device coordinates: -1..1 left to
right and bottom to top. A perspective ray starts at the eye; an
orthographic ray starts on the near plane and runs along
forward.
Sourcepub fn frame_sphere(&mut self, centre: impl Into<DVec3>, radius: f32)
pub fn frame_sphere(&mut self, centre: impl Into<DVec3>, radius: f32)
Frame a bounding sphere, keeping the orientation. Goes through
set_orbit, so an orthographic height scales with
the change in distance; set it afterwards with
set_ortho_height to fix the zoom.
Sourcepub fn frame_aabb(&mut self, aabb: &Aabb)
pub fn frame_aabb(&mut self, aabb: &Aabb)
Frame an AABB, keeping the orientation. An orthographic height scales
with the change in distance, as in frame_sphere.
Sourcepub fn fit_sphere_target(
&self,
centre: impl Into<DVec3>,
radius: f32,
) -> CameraTarget
pub fn fit_sphere_target( &self, centre: impl Into<DVec3>, radius: f32, ) -> CameraTarget
The CameraTarget that frames a bounding sphere, keeping the
orientation.
Sourcepub fn fit_aabb_target(&self, aabb: &Aabb) -> CameraTarget
pub fn fit_aabb_target(&self, aabb: &Aabb) -> CameraTarget
The CameraTarget that frames an AABB, keeping the orientation.
Sourcepub fn fit_sphere(&self, centre: impl Into<DVec3>, radius: f32) -> (DVec3, f32)
pub fn fit_sphere(&self, centre: impl Into<DVec3>, radius: f32) -> (DVec3, f32)
(centre, distance) that frames a bounding sphere, keeping the
orientation. Pads by 1.2x so the object does not touch the edges.