camera.h

Go to the documentation of this file.

#pragma once
 
#include <liboscar/graphics/camera_clipping_planes.h>
#include <liboscar/graphics/camera_projection.h>
#include <liboscar/maths/angle.h>
#include <liboscar/maths/matrix4x4.h>
#include <liboscar/maths/quaternion.h>
#include <liboscar/maths/ray.h>
#include <liboscar/maths/vector.h>
#include <liboscar/utilities/copy_on_upd_shared_value.h>
 
#include <optional>
 
namespace osc { class Rect; }
 
namespace osc
{
    class Camera {
    public:
        Camera();
 
        // resets the camera to default parameters
        void reset();
 
        // get/set the kind of projection that the camera should use when projecting view space
        // vertices into clip space (ignored if `set_projection_matrix_override` is used)
        CameraProjection projection() const;
        void set_projection(CameraProjection);
 
        // get/set the height of the orthographic projection plane that the camera will use
        //
        // undefined behavior if `projection() != CameraProjection::Orthographic`, or the
        // projection matrix has been overridden with `set_projection_matrix_override`, the
        // width of the orthographic plane is calculated from the aspect ratio of the render
        // target at runtime.
        float orthographic_size() const;
        void set_orthographic_size(float);
 
        // get/set the vertical field-of-view angle of the viewer's projection camera
        //
        // undefined behavior if `projection() != CameraProjection::Perspective` or the projection matrix
        // has been overridden with `set_projection_matrix_override`.
        Radians vertical_field_of_view() const;
        void set_vertical_field_of_view(Radians);
 
        // returns the horizontal field-of-view angle of the viewer's projection camera, assuming
        // it's rendering to a render target with the given `aspect_ratio`.
        //
        // undefined behavior if `projection() != CameraProjection::Perspective` or the projection matrix
        // has been overridden with `set_projection_matrix_override`.
        Radians horizontal_field_of_view(float aspect_ratio) const;
 
        // get/set the distance, in world space units, between both the camera and the nearest
        // clipping plane, and the camera and the farthest clipping plane
        CameraClippingPlanes clipping_planes() const;
        void set_clipping_planes(CameraClippingPlanes);
 
        // get/set the distance, in world space units, between the camera and the nearest
        // clipping plane
        float near_clipping_plane() const;
        void set_near_clipping_plane(float);
 
        // get/set the distance, in world space units, between the camera and the farthest
        // clipping plane
        float far_clipping_plane() const;
        void set_far_clipping_plane(float);
 
        // get/set the world space position of this `Camera`
        Vector3 position() const;
        void set_position(const Vector3&);
 
        // get/set the world space orientation of this `Camera` (normalized by
        // the implementation).
        Quaternion rotation() const;
        void set_rotation(const Quaternion&);
 
        // get/set the direction in which this `Camera` is pointing (normalized by
        // the implementation).
        Vector3 direction() const;
        void set_direction(const Vector3&);
 
        // Returns the forward-facing unit vector of this `Camera` in world space.
        Vector3 forward() const;
 
        // Sets the forward vector of this camera to `direction`.
        //
        // The implementation always internally normalizes `direction` and may
        // store it differently. Therefore, it is not guaranteed that `forward()`
        // returns `direction`.
        void set_forward(const Vector3& direction);
 
        // get/set the upwards direction of this camera (normalized by the implementation).
        Vector3 up() const;
        void set_up(const Vector3&);
 
        // returns the principal ray of this camera in world space
        //
        // the principal ray originates at the camera's `position()` and travels
        // straight down its optical axis (i.e. `direction()`).
        Ray principal_ray() const;
 
        // returns the matrix that this camera uses to transform world space points into
        // view space
        //
        // world space and view space operate with the same units-of-measure, handedness, etc.
        // but view space places the camera at `(0, 0, 0)`
        Matrix4x4 view_matrix() const;
 
        // returns the equivalent of `inverse(view_matrix())`, i.e. a matrix that transforms
        // view space points into world space points.
        Matrix4x4 inverse_view_matrix() const;
 
        // get/set matrices that override the default view matrix that this `Camera` uses
        //
        // by default, `Camera` computes its view matrix from its position and rotation, but
        // it's sometimes necessary/handy to override this default behavior.
        std::optional<Matrix4x4> view_matrix_override() const;
        void set_view_matrix_override(std::optional<Matrix4x4>);
 
        // returns the matrix that this camera uses to transform view space points into
        // clip space.
        //
        // clip space is defined such that there exists a unit cube in it that eventually
        // projects onto screen space in the following way:
        //
        // - transformed points (affine, homogeneous) are divided by their `w` component (perspective
        //   divide) to yield their normalized device coordinates (NDC).
        // - Anything outside of [{-1,-1,-1},{+1,+1,+1}] in NDC is discarded (clipping)
        // - NDC `( 0,  0,  0)` maps to the midpoint of screen space (i.e. 0.5 * {w, h})
        // - NDC `(-1, -1, -1)` maps to the bottom-left of screen space (z = -1 means 'closest')
        // - NDC `(+1, +1, +1)` maps to the top-right of screen space (z = +1 means 'farthest')
        // - Therefore, NDC is left-handed
        //
        // The XY component of fragments that land within clip space are transformed into screen
        // space and drawn to the output pixel rectangle (assuming they also pass the scissor test).
        // The Z component of things that land within the NDC cube are written to the depth buffer
        // if the `Material` that's being drawn enables this behavior (and there's a depth buffer
        // attached to the render target).
        Matrix4x4 projection_matrix(float aspect_ratio) const;
        std::optional<Matrix4x4> projection_matrix_override() const;
        void set_projection_matrix_override(std::optional<Matrix4x4>);
 
        // returns the equivalent of `projection_matrix(aspect_ratio) * view_matrix()`
        Matrix4x4 view_projection_matrix(float aspect_ratio) const;
 
        // returns the equivalent of `inverse(view_projection_matrix(aspect_ratio))`
        Matrix4x4 inverse_view_projection_matrix(float aspect_ratio) const;
 
        // Returns a point in ui space where this `Camera` would project
        // `world_position` (in world space) into `ui_rect` (in ui space).
        //
        // If the projection results in a negative `w` term (e.g. the point lies
        // beind the camera) then the returned point will contain NaNs.
        Vector2 world_to_ui(const Vector3& world_position, const Rect& ui_rect) const;
 
        // Returns a `Ray` in world space that represents where `ui_position` (in
        // ui space, Z unknown) would shoot along the view space's Z axis, assuming
        // `ui_rect` represents the ui space viewport that this camera projects to.
        Ray ui_to_world(const Vector2& ui_position, const Rect& ui_rect) const;
 
        // Returns the view volume's vertical extent in world units at a given depth
        // from the camera origin.
        float view_volume_height_at_depth(float depth) const;
    private:
        friend bool operator==(const Camera&, const Camera&);
        class Impl;
        CopyOnUpdSharedValue<Impl> impl_;
    };
 
    bool operator==(const Camera&, const Camera&);
}