From 7f4448962126b90bf8dc733847bf00baeb89ade9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Fri, 21 Aug 2015 09:43:53 +0200
Subject: [PATCH] SceneGraph: document projectionSize() usage.

I got like five e-mails about this already, putting that in the docs so I
don't have to invent that every time again.

This is very specific to many transformation/projection properties
(origin, Y up, 2D/3D and whatnot) and thus I'm not adding any convenience
function to calculate that.
---
 src/Magnum/SceneGraph/Camera.h | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/Magnum/SceneGraph/Camera.h b/src/Magnum/SceneGraph/Camera.h
index 14b1289d1..0569e3eac 100644
--- a/src/Magnum/SceneGraph/Camera.h
+++ b/src/Magnum/SceneGraph/Camera.h
@@ -197,6 +197,22 @@ template<UnsignedInt dimensions, class T> class Camera: public AbstractFeature<d
          * @brief 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
+         * @ref Platform::Sdl2Application::MouseEvent "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:
+         * @code
+         * Vector2 position = (Vector2{event.position()}/defaultFramebuffer.viewport().size() - Vector2{0.5f})*Vector2::yScale(-1.0f)*camera.projectionSize();
+         * @endcode
+         * This is position relative to camera transformation, getting absolute
+         * transformation in 2D scene can be done for example using
+         * @ref SceneGraph::Object::absoluteTransformation():
+         * @code
+         * Vector2 absolutePosition = cameraObject->absoluteTransformation().transformPoint(position);
+         * @endcode
+         *
          * @see @ref projectionMatrix()
          */
         Math::Vector2<T> projectionSize() const {