QMatrix4x4: deprecate operator*(QMatrix4x4, QVector3D/QPoint(F))

The operation does not make sense at the "fundamental" level
for these classes (algebraic, in this case), so it shouldn't exist.

It's also a semantic trap:
* it interprets a _vector_ as a _point_ instead (the vector gets
  1-extended in 4D)
* after the multiplication, it gets perspective divided.

These semantics do not belong to operator*.

operator*(QVector3D/QPoint(F), QMatrix) will be tackled in a next commit;
we don't have a straightforward replacement for it.

Drive-by, document that map() interprets vectors as points.

[ChangeLog][QtGui][QMatrix4x4] operator* between a QMatrix4x4 and a
QVector3D, QPoint, or QPointF has been deprecated in favor of map()
and mapVector().

Pick-to: 6.1
Task-number: QTBUG-89708
Change-Id: Iad78d6eb68cc8cdc3ac16b1635c4d3b522c95213
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

1 files changed, 22 insertions, 3 deletions

diff --git a/src/gui/math3d/qmatrix4x4.cpp b/src/gui/math3d/qmatrix4x4.cpp
index 34f8a7d892..591809df31 100644
--- a/src/gui/math3d/qmatrix4x4.cpp
+++ b/src/gui/math3d/qmatrix4x4.cpp
@@ -635,16 +635,23 @@ QMatrix4x4& QMatrix4x4::operator/=(float divisor)
     with the matrix applied post-vector.
 */
 
+#if QT_DEPRECATED_SINCE(6, 1)
+
 /*!
     \fn QVector3D operator*(const QMatrix4x4& matrix, const QVector3D& vector)
     \relates QMatrix4x4
 
+    \obsolete Use QMatrix4x4::map() or QMatrix4x4::mapVector() instead.
+
     Returns the result of transforming \a vector according to \a matrix,
-    with the matrix applied pre-vector.
+    with the matrix applied pre-vector. The vector is transformed as a
+    projective point.
 */
 
 #endif
 
+#endif
+
 #ifndef QT_NO_VECTOR4D
 
 /*!
@@ -681,10 +688,14 @@ QMatrix4x4& QMatrix4x4::operator/=(float divisor)
     with the matrix applied post-point.
 */
 
+#if QT_DEPRECATED_SINCE(6, 1)
+
 /*!
     \fn QPoint operator*(const QMatrix4x4& matrix, const QPoint& point)
     \relates QMatrix4x4
 
+    \obsolete Use QMatrix4x4::map() instead.
+
     Returns the result of transforming \a point according to \a matrix,
     with the matrix applied pre-point.
 */
@@ -693,10 +704,14 @@ QMatrix4x4& QMatrix4x4::operator/=(float divisor)
     \fn QPointF operator*(const QMatrix4x4& matrix, const QPointF& point)
     \relates QMatrix4x4
 
+    \obsolete Use QMatrix4x4::map() instead.
+
     Returns the result of transforming \a point according to \a matrix,
     with the matrix applied pre-point.
 */
 
+#endif
+
 /*!
     \fn QMatrix4x4 operator-(const QMatrix4x4& matrix)
     \overload
@@ -1701,6 +1716,7 @@ QTransform QMatrix4x4::toTransform(float distanceToPlane) const
     \fn QPoint QMatrix4x4::map(const QPoint& point) const
 
     Maps \a point by multiplying this matrix by \a point.
+    The matrix is applied pre-point.
 
     \sa mapRect()
 */
@@ -1708,7 +1724,8 @@ QTransform QMatrix4x4::toTransform(float distanceToPlane) const
 /*!
     \fn QPointF QMatrix4x4::map(const QPointF& point) const
 
-    Maps \a point by multiplying this matrix by \a point.
+    Maps \a point by post-multiplying this matrix by \a point.
+    The matrix is applied pre-point.
 
     \sa mapRect()
 */
@@ -1719,6 +1736,7 @@ 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.
 
     \sa mapRect(), mapVector()
 */
@@ -1728,7 +1746,7 @@ QTransform QMatrix4x4::toTransform(float distanceToPlane) const
 
     Maps \a vector by multiplying the top 3x3 portion of this matrix
     by \a vector.  The translation and projection components of
-    this matrix are ignored.
+    this matrix are ignored. The matrix is applied pre-vector.
 
     \sa map()
 */
@@ -1741,6 +1759,7 @@ QTransform QMatrix4x4::toTransform(float distanceToPlane) const
     \fn QVector4D QMatrix4x4::map(const QVector4D& point) const;
 
     Maps \a point by multiplying this matrix by \a point.
+    The matrix is applied pre-point.
 
     \sa mapRect()
 */