From 4b7dab10e1f775df7a1d499afbd297320da89a8b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Tue, 4 Sep 2018 17:23:44 +0200
Subject: [PATCH] Math: improve docs of Matrix4::perspectiveProjection().

---
 src/Magnum/Math/Matrix4.h | 35 +++++++++++++++++++++++------------
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/src/Magnum/Math/Matrix4.h b/src/Magnum/Math/Matrix4.h
index f1b30eaa4..454f9da4f 100644
--- a/src/Magnum/Math/Matrix4.h
+++ b/src/Magnum/Math/Matrix4.h
@@ -266,7 +266,7 @@ template<class T> class Matrix4: public Matrix4x4<T> {
          *      \boldsymbol{A} = \begin{pmatrix}
          *          \frac{2}{s_x} & 0 & 0 & 0 \\
          *          0 & \frac{2}{s_y} & 0 & 0 \\
-         *          0 & 0 & \frac{2}{n - f} & \frac{2n}{n - f} - 1 \\
+         *          0 & 0 & \frac{2}{n - f} & \frac{n + f}{n - f} \\
          *          0 & 0 & 0 & 1
          *      \end{pmatrix}
          * @f]
@@ -298,7 +298,8 @@ template<class T> class Matrix4: public Matrix4x4<T> {
          *          0 & 0 & -1 & 0
          *      \end{pmatrix}
          * @f]
-         * @see @ref orthographicProjection(), @ref Matrix3::projection(),
+         * @see @ref perspectiveProjection(Rad<T> fov, T, T, T),
+         *      @ref orthographicProjection(), @ref Matrix3::projection(),
          *      @ref Constants::inf()
          * @m_keywords{gluPerspective()}
          */
@@ -306,15 +307,15 @@ template<class T> class Matrix4: public Matrix4x4<T> {
 
         /**
          * @brief 3D perspective projection matrix
-         * @param fov           Field of view angle (horizontal)
-         * @param aspectRatio   Aspect ratio
-         * @param near          Near clipping plane
-         * @param far           Far clipping plane
+         * @param fov           Horizontal field of view angle @f$ \theta @f$
+         * @param aspectRatio   Horizontal:vertical aspect ratio @f$ a @f$
+         * @param near          Near clipping plane @f$ n @f$
+         * @param far           Far clipping plane @f$ f @f$
          *
          * If @p far is finite, the result is: @f[
          *      \boldsymbol{A} = \begin{pmatrix}
-         *          \frac{1}{\tan{\frac{\theta}{2}}} & 0 & 0 & 0 \\
-         *          0 & \frac{a}{\tan{\frac{\theta}{2}}} & 0 & 0 \\
+         *          \frac{1}{\tan \left(\frac{\theta}{2} \right)} & 0 & 0 & 0 \\
+         *          0 & \frac{a}{\tan \left(\frac{\theta}{2} \right)} & 0 & 0 \\
          *          0 & 0 & \frac{n + f}{n - f} & \frac{2nf}{n - f} \\
          *          0 & 0 & -1 & 0
          *      \end{pmatrix}
@@ -322,19 +323,29 @@ template<class T> class Matrix4: public Matrix4x4<T> {
          *
          * For infinite @p far, the result is: @f[
          *      \boldsymbol{A} = \begin{pmatrix}
-         *          \frac{1}{\tan{\frac{\theta}{2}}} & 0 & 0 & 0 \\
-         *          0 & \frac{a}{\tan{\frac{\theta}{2}}} & 0 & 0 \\
+         *          \frac{1}{\tan \left( \frac{\theta}{2} \right) } & 0 & 0 & 0 \\
+         *          0 & \frac{a}{\tan \left( \frac{\theta}{2} \right) } & 0 & 0 \\
          *          0 & 0 & -1 & -2n \\
          *          0 & 0 & -1 & 0
          *      \end{pmatrix}
          * @f]
+         *
+         * This function is equivalent to calling
+         * @ref perspectiveProjection(const Vector2<T>&, T, T) with the
+         * @p size parameter calculated as @f[
+         *      \boldsymbol{s} = 2 n \tan \left(\tfrac{\theta}{2} \right)
+         *      \begin{pmatrix}
+         *          1 \\
+         *          \frac{1}{a}
+         *      \end{pmatrix}
+         * @f]
+         *
          * @see @ref orthographicProjection(), @ref Matrix3::projection(),
          *      @ref Constants::inf()
          * @m_keywords{gluPerspective()}
          */
         static Matrix4<T> perspectiveProjection(Rad<T> fov, T aspectRatio, T near, T far) {
-            const T xyScale = 2*std::tan(T(fov)/2)*near;
-            return perspectiveProjection(Vector2<T>(xyScale, xyScale/aspectRatio), near, far);
+            return perspectiveProjection(T(2)*near*std::tan(T(fov)*T(0.5))*Vector2<T>::yScale(T(1)/aspectRatio), near, far);
         }
 
         /**