three-rs 0.3.0

A port of three.js core and its WebGPURenderer to Rust on wgpu, graded against three.js's own end-to-end pixel comparison.
Documentation
//! Port of `three.js/src/cameras/OrthographicCamera.js` — the renderer's
//! internal `QuadMesh` camera, `new OrthographicCamera( -1, 1, 1, -1, 0, 1 )`.

use crate::core::Object3D;
use crate::math::{Box3, CoordinateSystem, Matrix4, Vector3};

use super::CameraView;

/// three.js' `OrthographicCamera`: a camera whose projection keeps an
/// object's size on screen constant regardless of its distance, unlike
/// [`PerspectiveCamera`](super::PerspectiveCamera). It holds an [`Object3D`]
/// by value rather than a [`ObjectRef`](crate::core::ObjectRef) — see
/// `docs/scene-graph.md`, "What a node *is*".
#[derive(Clone)]
pub struct OrthographicCamera {
    /// The transform half of the camera: three.js' `Camera extends Object3D`.
    pub object: Object3D,
    /// The left plane of the camera's frustum.
    pub left: f64,
    /// The right plane of the camera's frustum.
    pub right: f64,
    /// The top plane of the camera's frustum.
    pub top: f64,
    /// The bottom plane of the camera's frustum.
    pub bottom: f64,
    /// The camera's near plane. Unlike a perspective camera's, `0.0` is a
    /// valid value here.
    pub near: f64,
    /// The camera's far plane, greater than [`near`](Self::near).
    pub far: f64,
    /// The zoom factor of the camera.
    pub zoom: f64,
    /// `OrthographicCamera.view`, set by
    /// [`set_view_offset`](Self::set_view_offset).
    pub view: Option<CameraView>,
    /// The coordinate system [`update_projection_matrix`](Self::update_projection_matrix)
    /// builds the projection for.
    pub coordinate_system: CoordinateSystem,
    /// `Camera.projectionMatrix`.
    pub projection_matrix: Matrix4,
    /// `Camera.projectionMatrixInverse`.
    pub projection_matrix_inverse: Matrix4,
    /// `Camera.matrixWorldInverse`.
    pub matrix_world_inverse: Matrix4,
}

impl OrthographicCamera {
    /// `new OrthographicCamera( left, right, top, bottom, near, far )`.
    pub fn new(left: f64, right: f64, top: f64, bottom: f64, near: f64, far: f64) -> Self {
        let mut camera = Self {
            object: Object3D::default(),
            left,
            right,
            top,
            bottom,
            near,
            far,
            zoom: 1.0,
            view: None,
            coordinate_system: CoordinateSystem::WebGpu,
            projection_matrix: Matrix4::identity(),
            projection_matrix_inverse: Matrix4::identity(),
            matrix_world_inverse: Matrix4::identity(),
        };
        camera.update_projection_matrix();
        camera.update_matrix_world();
        camera
    }

    /// `OrthographicCamera.setViewOffset()`: this camera renders the window
    /// `x, y, width, height` of a `full_width` × `full_height` frame. Unlike
    /// the perspective camera's, it leaves the frustum's planes alone and
    /// only narrows the projection — there is no `aspect` to overwrite.
    pub fn set_view_offset(
        &mut self,
        full_width: f64,
        full_height: f64,
        x: f64,
        y: f64,
        width: f64,
        height: f64,
    ) {
        self.view = Some(CameraView {
            enabled: true,
            full_width,
            full_height,
            offset_x: x,
            offset_y: y,
            width,
            height,
        });

        self.update_projection_matrix();
    }

    /// `OrthographicCamera.clearViewOffset()`.
    pub fn clear_view_offset(&mut self) {
        if let Some(view) = self.view.as_mut() {
            view.enabled = false;
        }

        self.update_projection_matrix();
    }

    /// `OrthographicCamera.updateProjectionMatrix()`.
    pub fn update_projection_matrix(&mut self) {
        let dx = (self.right - self.left) / (2.0 * self.zoom);
        let dy = (self.top - self.bottom) / (2.0 * self.zoom);
        let cx = (self.right + self.left) / 2.0;
        let cy = (self.top + self.bottom) / 2.0;

        let mut left = cx - dx;
        let mut right = cx + dx;
        let mut top = cy + dy;
        let mut bottom = cy - dy;

        if let Some(view) = self.view.filter(|view| view.enabled) {
            let scale_w = (self.right - self.left) / view.full_width / self.zoom;
            let scale_h = (self.top - self.bottom) / view.full_height / self.zoom;

            left += scale_w * view.offset_x;
            right = left + scale_w * view.width;
            top -= scale_h * view.offset_y;
            bottom = top - scale_h * view.height;
        }

        self.projection_matrix.make_orthographic(
            left,
            right,
            top,
            bottom,
            self.near,
            self.far,
            self.coordinate_system,
        );

        self.projection_matrix_inverse = self.projection_matrix;
        self.projection_matrix_inverse.invert();
    }

    /// Frame `box_` from the direction the camera already looks in, with
    /// `margin` of the frame left as slack (`0.0` is tight, `0.1` leaves 10 % of
    /// the half-frame free on the tightest side). Not a three.js method — see
    /// issue #51.
    ///
    /// An orthographic frame has no distance term, so this is the box's extent
    /// in the camera's own basis: `left`/`right` and `top`/`bottom` come from the
    /// lateral extents, and `near`/`far` from the extent along the view
    /// direction. The current frame's aspect ratio is kept by widening whichever
    /// pair is the less demanding of the two — the box is framed, never
    /// stretched — and the current `zoom` is folded into the planes, so the
    /// projection matrix comes out the same whatever the zoom was.
    ///
    /// The camera is also moved to stand one box diagonal clear of the near face,
    /// so `near` is positive and the whole box is between the planes.
    pub fn fit(&mut self, box_: &Box3, margin: f64) {
        if box_.is_empty() {
            return;
        }

        self.update_matrix_world();

        let (right, up, forward) = super::view_basis(&self.object.matrix_world);
        let offsets = super::corner_offsets(box_, &right, &up, &forward);

        let mut half_width = 0.0_f64;
        let mut half_height = 0.0_f64;
        let mut near_depth = f64::INFINITY;
        let mut far_depth = f64::NEG_INFINITY;

        for offset in &offsets {
            half_width = half_width.max(offset.x.abs());
            half_height = half_height.max(offset.y.abs());
            near_depth = near_depth.min(offset.z);
            far_depth = far_depth.max(offset.z);
        }

        // The margin grows the frame, so the tightest corner lands at
        // `1 - margin` in normalised device coordinates instead of at 1.
        let slack = (1.0 - margin).clamp(f64::EPSILON, 1.0);
        half_width /= slack;
        half_height /= slack;

        // Keep the frame's shape: widen the pair that has room to spare.
        let aspect = if self.top != self.bottom {
            (self.right - self.left) / (self.top - self.bottom)
        } else {
            1.0
        };
        if half_width < half_height * aspect {
            half_width = half_height * aspect;
        } else if aspect != 0.0 {
            half_height = half_width / aspect;
        }

        self.left = -half_width * self.zoom;
        self.right = half_width * self.zoom;
        self.top = half_height * self.zoom;
        self.bottom = -half_height * self.zoom;

        // One box diagonal of clearance in front, so `near` is positive whatever
        // the view direction is.
        let clearance = {
            let diagonal = box_.get_size().length();
            if diagonal > 0.0 {
                diagonal
            } else {
                1.0
            }
        };
        let distance = clearance - near_depth;
        self.near = clearance;
        self.far = distance + far_depth;
        if self.far <= self.near {
            // A box with no depth along the view direction.
            self.far = self.near * 2.0;
        }
        self.update_projection_matrix();

        let center = box_.get_center();
        let mut position = Vector3::ZERO;
        position
            .copy(&forward)
            .multiply_scalar(-distance)
            .add(&center);
        self.object.position = position;
        self.update_matrix_world();
    }

    /// `Object3D.lookAt()` for a camera: the matrix looks *from* the camera
    /// position *at* the target (`PerspectiveCamera::look_at` is the same on
    /// its node).
    pub fn look_at(&mut self, target: &Vector3) {
        let mut m = Matrix4::identity();
        m.look_at(&self.object.position, target, &self.object.up);
        self.object.quaternion.set_from_rotation_matrix(&m);
        self.object.sync_rotation_from_quaternion();
    }

    /// `Object3D.updateMatrixWorld()` on the camera's own node, then rebuilds
    /// [`matrix_world_inverse`](Self::matrix_world_inverse) from it.
    pub fn update_matrix_world(&mut self) {
        self.object.update_matrix_world(None);
        self.matrix_world_inverse = self.object.matrix_world;
        self.matrix_world_inverse.invert();
    }
}