Fix up some QMatrix4x4 docs

The deprecation note for one of the operator* is wrong: Using
mapVector() is never the right choice given the deprecated operator*
itself is implemented by calling map(). It could be that in some cases
the results are identical so one can get away with migrating to
mapVector(), but this is incorrect in other cases and causes
regressions all over the place. Thus we should only recommend using
map() instead, never mapVector(). As shown by recent experiences, the
current docs are insufficient/wrong and caused a number of regressions
in the Qt code base as well.

Also enhance some related docs. It could be that the wording is not
always academically correct, however having some additional notes in
there help make it obvious to the reader (or at least raise some
alarms) that there are important differences between map and
mapVector.

Also improve the note for the other deprecated operator*. There is
only one way to convert to a vec4, given the existing implementation
of the operator, and that is by using 1 for w. Make this clear to the
reader.

Pick-to: 6.3 6.2
Change-Id: I1d8dbca44fdc103ab62d49bfc1d4ce37a9bc130b
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

2 files changed, 10 insertions, 6 deletions

diff --git a/src/gui/math3d/qmatrix4x4.cpp b/src/gui/math3d/qmatrix4x4.cpp
index 0e40966bef..f59f45ba5b 100644
--- a/src/gui/math3d/qmatrix4x4.cpp
+++ b/src/gui/math3d/qmatrix4x4.cpp
@@ -633,7 +633,7 @@ QMatrix4x4& QMatrix4x4::operator/=(float divisor)
     \fn QVector3D operator*(const QVector3D& vector, const QMatrix4x4& matrix)
     \relates QMatrix4x4
 
-    \deprecated [6.1] Convert the QVector3D to a QVector4D first, then multiply.
+    \deprecated [6.1] Convert the QVector3D to a QVector4D with 1.0 as the w coordinate, then multiply.
 
     Returns the result of transforming \a vector according to \a matrix,
     with the matrix applied post-vector. The vector is transformed as a point.
@@ -643,7 +643,7 @@ QMatrix4x4& QMatrix4x4::operator/=(float divisor)
     \fn QVector3D operator*(const QMatrix4x4& matrix, const QVector3D& vector)
     \relates QMatrix4x4
 
-    \deprecated [6.1] Use QMatrix4x4::map() or QMatrix4x4::mapVector() instead.
+    \deprecated [6.1] Use QMatrix4x4::map() instead.
 
     Returns the result of transforming \a vector according to \a matrix,
     with the matrix applied pre-vector. The vector is transformed as a
@@ -1737,8 +1737,12 @@ QTransform QMatrix4x4::toTransform(float distanceToPlane) const
 /*!
     \fn QVector3D QMatrix4x4::map(const QVector3D& point) const
 
-    Maps \a point by multiplying this matrix by \a point.
-    The matrix is applied pre-point.
+    Maps \a point by multiplying this matrix by \a point extended to a 4D
+    vector by assuming 1.0 for the w coordinate. The matrix is applied
+    pre-point.
+
+    \note This function is not the same as mapVector(). For points, always use
+    map(). mapVector() is suitable for vectors (directions) only.
 
     \sa mapRect(), mapVector()
 */
diff --git a/src/gui/math3d/qmatrix4x4.h b/src/gui/math3d/qmatrix4x4.h
index ecfddc4148..4b9c903957 100644
--- a/src/gui/math3d/qmatrix4x4.h
+++ b/src/gui/math3d/qmatrix4x4.h
@@ -726,7 +726,7 @@ inline QMatrix4x4 operator*(const QMatrix4x4& m1, const QMatrix4x4& m2)
 
 #if QT_DEPRECATED_SINCE(6, 1)
 
-QT_DEPRECATED_VERSION_X_6_1("Extend the QVector3D to a QVector4D before multiplying")
+QT_DEPRECATED_VERSION_X_6_1("Extend the QVector3D to a QVector4D with 1.0 as the w coordinate before multiplying")
 inline QVector3D operator*(const QVector3D& vector, const QMatrix4x4& matrix)
 {
     float x, y, z, w;
@@ -752,7 +752,7 @@ inline QVector3D operator*(const QVector3D& vector, const QMatrix4x4& matrix)
         return QVector3D(x / w, y / w, z / w);
 }
 
-QT_DEPRECATED_VERSION_X_6_1("Use matrix.map(vector) or matrix.mapVector(vector) instead")
+QT_DEPRECATED_VERSION_X_6_1("Use matrix.map(vector) instead")
 inline QVector3D operator*(const QMatrix4x4& matrix, const QVector3D& vector)
 {
     return matrix.map(vector);