Struct Scope

pub struct Scope<N>
where
    N: Copy + RealField,
{ /* private fields */ }

Scope defining enclosing viewing frustum.

Implements Default and can be created with Scope::default().

Implementations

impl<N> Scope<N>

where N: Copy + RealField,

pub const fn fov(&self) -> Fixed<N>

Fixed quantity wrt field of view, see Self::set_fov().

pub fn set_fov(&mut self, fov: impl Into<Fixed<N>>)

Sets fixed quantity wrt field of view.

Default is fixed vertical field of view of π/4.

use nalgebra::Point2;
use trackball::Scope;

// Current screen size.
let max = Point2::new(800, 600);
// Default scope with fixed vertical field of view of π/4:
//
//   * Increasing width increases horizontal field of view (more can be seen).
//   * Increasing height scales scope zooming in as vertical field of view is fixed.
let mut scope = Scope::default();
// Unfix vertical field of view by fixing current unit per pixel on focus plane at distance
// from eye of one, that is effectively `upp` divided by `zat` to make it scale-independant:
//
//   * Increasing width increases horizontal field of view (more can be seen).
//   * Increasing height increases vertical field of view (more can be seen).
scope.set_fov(scope.fov().to_upp(&max.cast::<f32>()));

Examples found in repository

examples/scaling_modes.rs (line 86)

fn setup(
	mut windows: Query<&mut Window>,
	mut commands: Commands,
	mut meshes: ResMut<Assets<Mesh>>,
	mut materials: ResMut<Assets<StandardMaterial>>,
) {
	// circular base
	commands.spawn((
		Mesh3d(meshes.add(Circle::new(4.0))),
		MeshMaterial3d(materials.add(Color::WHITE)),
		Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
	));
	// cube
	commands.spawn((
		Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
		MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
		Transform::from_xyz(0.0, 0.5, 0.0),
	));
	// light
	commands.spawn((
		PointLight {
			shadows_enabled: true,
			..default()
		},
		Transform::from_xyz(4.0, 8.0, 4.0),
	));

	// Windows
	let mut window1 = windows.single_mut().unwrap();
	"Fixed Vertical Field of View (Perspective vs Orthographic)".clone_into(&mut window1.title);
	let res = &window1.resolution;
	let max = Vec2::new(res.width() * 0.5, res.height()).into();
	// Left and right camera orientation.
	let [target, eye, up] = [Vec3::Y * 0.5, Vec3::new(-2.5, 4.5, 9.0) * 1.2, Vec3::Y];
	// Spawn a 2nd window.
	let window2 = commands
		.spawn(Window {
			title: "Fixed Horizontal Field of View (Perspective vs Orthographic)".to_owned(),
			..default()
		})
		.id();
	// Spawn a 3rd window.
	let window3 = commands
		.spawn(Window {
			title: "Fixed Unit Per Pixels (Perspective vs Orthographic)".to_owned(),
			..default()
		})
		.id();

	// Cameras
	let mut order = 0;
	let fov = Fixed::default();
	for (fov, window) in [
		(fov, WindowRef::Primary),
		(fov.to_hor(&max), WindowRef::Entity(window2)),
		(fov.to_upp(&max), WindowRef::Entity(window3)),
	] {
		let mut scope = Scope::default();
		scope.set_fov(fov);
		// Left trackball controller and camera 3D bundle.
		let left = commands
			.spawn((
				TrackballController::default(),
				Camera {
					target: RenderTarget::Window(window),
					// Renders the right camera after the left camera,
					// which has a default priority of 0.
					order,
					..default()
				},
				Camera3d::default(),
				LeftCamera,
			))
			.id();
		order += 1;
		// Right trackball controller and camera 3D bundle.
		let right = commands
			.spawn((
				TrackballController::default(),
				Camera {
					target: RenderTarget::Window(window),
					// Renders the right camera after the left camera,
					// which has a default priority of 0.
					order,
					// Don't clear on the second camera
					// because the first camera already cleared the window.
					clear_color: ClearColorConfig::None,
					..default()
				},
				Camera3d::default(),
				RightCamera,
			))
			.id();
		order += 1;
		// Insert left trackball camera and make it sensitive to right trackball controller as well.
		commands.entity(left).insert(
			TrackballCamera::look_at(target, eye, up)
				.with_scope(scope)
				.add_controller(right, true),
		);
		// Set orthographic projection mode for right camera.
		scope.set_ortho(true);
		// Insert right trackball camera and make it sensitive to left trackball controller as well.
		commands.entity(right).insert(
			TrackballCamera::look_at(target, eye, up)
				.with_scope(scope)
				.add_controller(left, true),
		);
	}
}

pub fn clip_planes(&self, zat: N) -> (N, N)

Clip plane distances from eye regardless of Self::scale() wrt to distance between eye and target.

Default is (1e-1, 1e+3) measured from eye.

pub const fn set_clip_planes(&mut self, znear: N, zfar: N)

Sets clip plane distances from target or eye whether Self::scale().

Default is (1e-1, 1e+3) measured from eye.

pub const fn scale(&self) -> bool

Object inspection mode.

Scales clip plane distances by measuring from target instead of eye. Default is false.

pub const fn set_scale(&mut self, oim: bool)

Sets object inspection mode.

Scales clip plane distances by measuring from target instead of eye. Default is false.

pub const fn ortho(&self) -> bool

Orthographic projection mode.

Computes scale-identical orthographic instead of perspective projection. Default is false.

pub const fn set_ortho(&mut self, opm: bool)

Sets orthographic projection mode.

Computes scale-identical orthographic instead of perspective projection. Default is false.

Examples found in repository

examples/scaling_modes.rs (line 129)

fn setup(
	mut windows: Query<&mut Window>,
	mut commands: Commands,
	mut meshes: ResMut<Assets<Mesh>>,
	mut materials: ResMut<Assets<StandardMaterial>>,
) {
	// circular base
	commands.spawn((
		Mesh3d(meshes.add(Circle::new(4.0))),
		MeshMaterial3d(materials.add(Color::WHITE)),
		Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
	));
	// cube
	commands.spawn((
		Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
		MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
		Transform::from_xyz(0.0, 0.5, 0.0),
	));
	// light
	commands.spawn((
		PointLight {
			shadows_enabled: true,
			..default()
		},
		Transform::from_xyz(4.0, 8.0, 4.0),
	));

	// Windows
	let mut window1 = windows.single_mut().unwrap();
	"Fixed Vertical Field of View (Perspective vs Orthographic)".clone_into(&mut window1.title);
	let res = &window1.resolution;
	let max = Vec2::new(res.width() * 0.5, res.height()).into();
	// Left and right camera orientation.
	let [target, eye, up] = [Vec3::Y * 0.5, Vec3::new(-2.5, 4.5, 9.0) * 1.2, Vec3::Y];
	// Spawn a 2nd window.
	let window2 = commands
		.spawn(Window {
			title: "Fixed Horizontal Field of View (Perspective vs Orthographic)".to_owned(),
			..default()
		})
		.id();
	// Spawn a 3rd window.
	let window3 = commands
		.spawn(Window {
			title: "Fixed Unit Per Pixels (Perspective vs Orthographic)".to_owned(),
			..default()
		})
		.id();

	// Cameras
	let mut order = 0;
	let fov = Fixed::default();
	for (fov, window) in [
		(fov, WindowRef::Primary),
		(fov.to_hor(&max), WindowRef::Entity(window2)),
		(fov.to_upp(&max), WindowRef::Entity(window3)),
	] {
		let mut scope = Scope::default();
		scope.set_fov(fov);
		// Left trackball controller and camera 3D bundle.
		let left = commands
			.spawn((
				TrackballController::default(),
				Camera {
					target: RenderTarget::Window(window),
					// Renders the right camera after the left camera,
					// which has a default priority of 0.
					order,
					..default()
				},
				Camera3d::default(),
				LeftCamera,
			))
			.id();
		order += 1;
		// Right trackball controller and camera 3D bundle.
		let right = commands
			.spawn((
				TrackballController::default(),
				Camera {
					target: RenderTarget::Window(window),
					// Renders the right camera after the left camera,
					// which has a default priority of 0.
					order,
					// Don't clear on the second camera
					// because the first camera already cleared the window.
					clear_color: ClearColorConfig::None,
					..default()
				},
				Camera3d::default(),
				RightCamera,
			))
			.id();
		order += 1;
		// Insert left trackball camera and make it sensitive to right trackball controller as well.
		commands.entity(left).insert(
			TrackballCamera::look_at(target, eye, up)
				.with_scope(scope)
				.add_controller(right, true),
		);
		// Set orthographic projection mode for right camera.
		scope.set_ortho(true);
		// Insert right trackball camera and make it sensitive to left trackball controller as well.
		commands.entity(right).insert(
			TrackballCamera::look_at(target, eye, up)
				.with_scope(scope)
				.add_controller(left, true),
		);
	}
}

pub fn projection_and_upp( &self, zat: N, max: &OPoint<N, Const<2>>, ) -> (Matrix<N, Const<4>, Const<4>, ArrayStorage<N, 4, 4>>, N)

Projection transformation and unit per pixel on focus plane wrt distance between eye and target and maximum position in screen space.

pub fn cast<M>(self) -> Scope<M>

where M: Copy + RealField, N: SubsetOf<M>,

Casts components to another type, e.g., between f32 and f64.

Trait Implementations

impl<N> Clone for Scope<N>

where N: Clone + Copy + RealField,

fn clone(&self) -> Scope<N>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<N> Debug for Scope<N>

where N: Debug + Copy + RealField,

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

Formats the value using the given formatter.

impl<N> Default for Scope<N>

where N: Copy + RealField,

fn default() -> Scope<N>

Returns the “default value” for a type.

impl<'de, N> Deserialize<'de> for Scope<N>

where N: Copy + RealField + Deserialize<'de>,

fn deserialize<__D>( __deserializer: __D, ) -> Result<Scope<N>, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<N> PartialEq for Scope<N>

where N: PartialEq + Copy + RealField,

fn eq(&self, other: &Scope<N>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<N> Serialize for Scope<N>

where N: Copy + RealField + Serialize,

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<N> Copy for Scope<N>

where N: Copy + RealField,

impl<N> Eq for Scope<N>

where N: Eq + Copy + RealField,

impl<N> StructuralPartialEq for Scope<N>

where N: Copy + RealField,