Improve doc to avoid row vs col major confusion.

There has been a few reports of user confusion from the fact that the
constData and data functions return results in column-major format.
There is nothing in the doc anywhere that states this, and nothing
states that the class is especially for OpenGL which would give a clue
at least.

Change-Id: I3a9afde0fbeb8b9d2bcba6a387620b60a56774b9
Reviewed-on: http://codereview.qt.nokia.com/2066
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Julian de Bhal <julian.debhal@nokia.com>

1 files changed, 16 insertions, 0 deletions

diff --git a/src/gui/math3d/qmatrix4x4.cpp b/src/gui/math3d/qmatrix4x4.cpp
index 837bd519b8..cef92af66b 100644
--- a/src/gui/math3d/qmatrix4x4.cpp
+++ b/src/gui/math3d/qmatrix4x4.cpp
@@ -55,6 +55,20 @@ QT_BEGIN_NAMESPACE
     \since 4.6
     \ingroup painting-3D
 
+    The QMatrix4x4 class in general is treated as a row-major matrix, in that the
+    constructors and operator() functions take data in row-major format, as is
+    familiar in C-style usage.
+
+    Internally the data is stored as column-major format, so as to be optimal for
+    passing to OpenGL functions, which expect column-major data.
+
+    When using these functions be aware that they return data in \bold{column-major}
+    format:
+    \list
+    \o data()
+    \o constData()
+    \endlist
+
     \sa QVector3D, QGenericMatrix
 */
 
@@ -1725,6 +1739,7 @@ QRectF QMatrix4x4::mapRect(const QRectF& rect) const
     \fn const qreal *QMatrix4x4::data() const
 
     Returns a constant pointer to the raw data of this matrix.
+    This raw data is stored in column-major format.
 
     \sa constData()
 */
@@ -1733,6 +1748,7 @@ QRectF QMatrix4x4::mapRect(const QRectF& rect) const
     \fn const qreal *QMatrix4x4::constData() const
 
     Returns a constant pointer to the raw data of this matrix.
+    This raw data is stored in column-major format.
 
     \sa data()
 */