template<UnsignedInt dimensions, class T>
Magnum::SceneGraph::Camera class

Camera.

See Drawable documentation for more information. The camera by default displays OpenGL unit cube [(-1, -1, -1); (1, 1, 1)] and doesn't do any aspect ratio correction.

Common setup example for 2D scenes:

SceneGraph::Camera2D camera{cameraObject};
camera.setProjectionMatrix(Matrix3::projection({4.0f/3.0f, 1.0f}))
      .setAspectRatioPolicy(SceneGraph::AspectRatioPolicy::Extend);

Common setup example for 3D scenes:

SceneGraph::Camera3D camera{cameraObject};
camera.setProjectionMatrix(Matrix4::perspectiveProjection(35.0_degf, 1.0f, 0.001f, 100.0f))
      .setAspectRatioPolicy(SceneGraph::AspectRatioPolicy::Extend);

Explicit template specializations

The following specializations are explicitly compiled into SceneGraph library. For other specializations (e.g. using Double type) you have to use Camera.hpp implementation file to avoid linker errors. See also Template headers and implementation files for more information.

Base classes

template<UnsignedInt dimensions, class T>
class AbstractFeature
Base for object features.

Constructors, destructors, conversion operators

Camera(AbstractObject<dimensions, T>& object) explicit
Constructor.

Public functions

auto aspectRatioPolicy() const -> AspectRatioPolicy
Aspect ratio policy.
auto setAspectRatioPolicy(AspectRatioPolicy policy) -> Camera<dimensions, T>&
Set aspect ratio policy.
auto cameraMatrix() -> MatrixTypeFor<dimensions, T>
Camera matrix.
auto projectionMatrix() const -> MatrixTypeFor<dimensions, T>
Projection matrix.
auto setProjectionMatrix(const MatrixTypeFor<dimensions, T>& matrix) -> Camera<dimensions, T>&
Set projection matrix.
auto projectionSize() const -> Math::Vector2<T>
Size of (near) XY plane in current projection.
auto viewport() const -> Vector2i
Viewport size.
void setViewport(const Vector2i& size)
Set viewport size.
auto drawableTransformations(DrawableGroup<dimensions, T>& group) -> std::vector<std::pair<std::reference_wrapper<Drawable<dimensions, T>>, MatrixTypeFor<dimensions, T>>>
Drawable transformations.
void draw(DrawableGroup<dimensions, T>& group)
Draw.
void draw(const std::vector<std::pair<std::reference_wrapper<Drawable<dimensions, T>>, MatrixTypeFor<dimensions, T>>>& drawableTransformations)
Draw given drawables with transformations.

Private functions

void cleanInverted(const MatrixTypeFor<dimensions, T>& invertedAbsoluteTransformationMatrix) override virtual

Function documentation

template<UnsignedInt dimensions, class T>
Magnum::SceneGraph::Camera<dimensions, T>::Camera(AbstractObject<dimensions, T>& object) explicit

Constructor.

Parameters
object Object holding the camera

Sets orthographic projection to the default OpenGL cube (range $ [-1; 1] $ in all directions).

template<UnsignedInt dimensions, class T>
Camera<dimensions, T>& Magnum::SceneGraph::Camera<dimensions, T>::setAspectRatioPolicy(AspectRatioPolicy policy)

Set aspect ratio policy.

Returns Reference to self (for method chaining)

template<UnsignedInt dimensions, class T>
MatrixTypeFor<dimensions, T> Magnum::SceneGraph::Camera<dimensions, T>::cameraMatrix()

Camera matrix.

Camera matrix describes world position relative to the camera and is applied after object transformation matrix and before projection matrix.

template<UnsignedInt dimensions, class T>
MatrixTypeFor<dimensions, T> Magnum::SceneGraph::Camera<dimensions, T>::projectionMatrix() const

Projection matrix.

Projection matrix handles e.g. perspective distortion and is applied as last, after cameraMatrix() and object transformation matrix.

template<UnsignedInt dimensions, class T>
Camera<dimensions, T>& Magnum::SceneGraph::Camera<dimensions, T>::setProjectionMatrix(const MatrixTypeFor<dimensions, T>& matrix)

Set projection matrix.

Returns Reference to self (for method chaining)

template<UnsignedInt dimensions, class T>
Math::Vector2<T> Magnum::SceneGraph::Camera<dimensions, T>::projectionSize() const

Size of (near) XY plane in current projection.

Returns size of near XY plane computed from projection matrix.

Conversion from integer window-space coordinates with origin in top left corner and Y down (e.g. from Platform::*Application::MouseEvent) to floating-point coordinates on near XY plane with origin at camera position and Y up can be done using the following snippet:

Vector2 position = (Vector2{event.position()}/Vector2{GL::defaultFramebuffer.viewport().size()}
    - Vector2{0.5f})*Vector2::yScale(-1.0f)*camera.projectionSize();

This is position relative to camera transformation, getting absolute transformation in 2D scene can be done for example using SceneGraph::Object::absoluteTransformation():

Vector2 absolutePosition = cameraObject->absoluteTransformation().transformPoint(position);

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::Camera<dimensions, T>::setViewport(const Vector2i& size)

Set viewport size.

Stores viewport size internally and recalculates projection matrix according to aspect ratio policy.

template<UnsignedInt dimensions, class T>
std::vector<std::pair<std::reference_wrapper<Drawable<dimensions, T>>, MatrixTypeFor<dimensions, T>>> Magnum::SceneGraph::Camera<dimensions, T>::drawableTransformations(DrawableGroup<dimensions, T>& group)

Drawable transformations.

Returns calculated transformations for given group of drawables. Useful in combination with draw(const std::vector<std::pair<std::reference_wrapper<Drawable<dimensions, T>>, MatrixTypeFor<dimensions, T>>>&) to provide custom draw order. See Custom draw order for more information.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::Camera<dimensions, T>::draw(DrawableGroup<dimensions, T>& group)

Draw.

Draws given group of drawables.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::Camera<dimensions, T>::draw(const std::vector<std::pair<std::reference_wrapper<Drawable<dimensions, T>>, MatrixTypeFor<dimensions, T>>>& drawableTransformations)

Draw given drawables with transformations.

Useful in combination with drawableTransformations() for drawing in a custom order. See Custom draw order for more information.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::Camera<dimensions, T>::cleanInverted(const MatrixTypeFor<dimensions, T>& invertedAbsoluteTransformationMatrix) override virtual private

Recalculates camera matrix