Make the documentation more explicit an talkative

Change-Id: Ifa4b7c3c5f8ec384addbb80a9436d55b32d8bc51
Reviewed-by: Lars Knoll <lars.knoll@digia.com>
Reviewed-by: Samuel Rødal <samuel.rodal@digia.com>

diff --git a/src/gui/math3d/qmatrix4x4.cpp b/src/gui/math3d/qmatrix4x4.cpp
index d8c2116..e0f401b 100644 (file)
--- a/src/gui/math3d/qmatrix4x4.cpp
+++ b/src/gui/math3d/qmatrix4x4.cpp
@@ -1458,27 +1458,29 @@ void QMatrix4x4::frustum(float left, float right, float bottom, float top, float
 
 /*!
     Multiplies this matrix by another that applies a perspective
-    projection.  The field of view will be \a angle degrees within
-    a window with a given \a aspect ratio.  The projection will
-    have the specified \a nearPlane and \a farPlane clipping planes.
+    projection. The vertical field of view will be \a verticalAngle degrees
+    within a window with a given \a aspectRatio that determines the horizontal
+    field of view.
+    The projection will have the specified \a nearPlane and \a farPlane clipping
+    planes which are the distances from the viewer to the corresponding planes.
 
     \sa ortho(), frustum()
 */
-void QMatrix4x4::perspective(float angle, float aspect, float nearPlane, float farPlane)
+void QMatrix4x4::perspective(float verticalAngle, float aspectRatio, float nearPlane, float farPlane)
 {
     // Bail out if the projection volume is zero-sized.
-    if (nearPlane == farPlane || aspect == 0.0f)
+    if (nearPlane == farPlane || aspectRatio == 0.0f)
         return;
 
     // Construct the projection.
     QMatrix4x4 m(1);
-    float radians = (angle / 2.0f) * M_PI / 180.0f;
+    float radians = (verticalAngle / 2.0f) * M_PI / 180.0f;
     float sine = sinf(radians);
     if (sine == 0.0f)
         return;
     float cotan = cosf(radians) / sine;
     float clip = farPlane - nearPlane;
-    m.m[0][0] = cotan / aspect;
+    m.m[0][0] = cotan / aspectRatio;
     m.m[1][0] = 0.0f;
     m.m[2][0] = 0.0f;
     m.m[3][0] = 0.0f;

diff --git a/src/gui/math3d/qmatrix4x4.h b/src/gui/math3d/qmatrix4x4.h
index bbad04b..df98f02 100644 (file)
--- a/src/gui/math3d/qmatrix4x4.h
+++ b/src/gui/math3d/qmatrix4x4.h
@@ -146,7 +146,7 @@ public:
     void ortho(const QRectF& rect);
     void ortho(float left, float right, float bottom, float top, float nearPlane, float farPlane);
     void frustum(float left, float right, float bottom, float top, float nearPlane, float farPlane);
-    void perspective(float angle, float aspect, float nearPlane, float farPlane);
+    void perspective(float verticalAngle, float aspectRatio, float nearPlane, float farPlane);
 #ifndef QT_NO_VECTOR3D
     void lookAt(const QVector3D& eye, const QVector3D& center, const QVector3D& up);
 #endif