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, 15 insertions, 0 deletions

diff --git a/src/gui/math3d/qmatrix4x4.h b/src/gui/math3d/qmatrix4x4.h
index 4433f47af4..05e882d7c4 100644
--- a/src/gui/math3d/qmatrix4x4.h
+++ b/src/gui/math3d/qmatrix4x4.h
@@ -107,7 +107,9 @@ public:
     friend QMatrix4x4 operator-(const QMatrix4x4& m1, const QMatrix4x4& m2);
     friend QMatrix4x4 operator*(const QMatrix4x4& m1, const QMatrix4x4& m2);
 #ifndef QT_NO_VECTOR3D
+#if QT_DEPRECATED_SINCE(6, 1)
     friend QVector3D operator*(const QMatrix4x4& matrix, const QVector3D& vector);
+#endif
     friend QVector3D operator*(const QVector3D& vector, const QMatrix4x4& matrix);
 #endif
 #ifndef QT_NO_VECTOR4D
@@ -117,8 +119,10 @@ public:
     friend QPoint operator*(const QPoint& point, const QMatrix4x4& matrix);
     friend QPointF operator*(const QPointF& point, const QMatrix4x4& matrix);
     friend QMatrix4x4 operator-(const QMatrix4x4& matrix);
+#if QT_DEPRECATED_SINCE(6, 1)
     friend QPoint operator*(const QMatrix4x4& matrix, const QPoint& point);
     friend QPointF operator*(const QMatrix4x4& matrix, const QPointF& point);
+#endif
     friend QMatrix4x4 operator*(float factor, const QMatrix4x4& matrix);
     friend QMatrix4x4 operator*(const QMatrix4x4& matrix, float factor);
     friend Q_GUI_EXPORT QMatrix4x4 operator/(const QMatrix4x4& matrix, float divisor);
@@ -741,6 +745,9 @@ inline QVector3D operator*(const QVector3D& vector, const QMatrix4x4& matrix)
         return QVector3D(x / w, y / w, z / w);
 }
 
+#if QT_DEPRECATED_SINCE(6, 1)
+
+QT_DEPRECATED_VERSION_X_6_1("Use matrix.map(vector) or matrix.mapVector(vector) instead")
 inline QVector3D operator*(const QMatrix4x4& matrix, const QVector3D& vector)
 {
     return matrix.map(vector);
@@ -748,6 +755,8 @@ inline QVector3D operator*(const QMatrix4x4& matrix, const QVector3D& vector)
 
 #endif
 
+#endif
+
 #ifndef QT_NO_VECTOR4D
 
 inline QVector4D operator*(const QVector4D& vector, const QMatrix4x4& matrix)
@@ -839,16 +848,22 @@ inline QPointF operator*(const QPointF& point, const QMatrix4x4& matrix)
     }
 }
 
+#if QT_DEPRECATED_SINCE(6, 1)
+
+QT_DEPRECATED_VERSION_X_6_1("Use matrix.map(point) instead")
 inline QPoint operator*(const QMatrix4x4& matrix, const QPoint& point)
 {
     return matrix.map(point);
 }
 
+QT_DEPRECATED_VERSION_X_6_1("Use matrix.map(point) instead")
 inline QPointF operator*(const QMatrix4x4& matrix, const QPointF& point)
 {
     return matrix.map(point);
 }
 
+#endif
+
 inline QMatrix4x4 operator-(const QMatrix4x4& matrix)
 {
     QMatrix4x4 m(Qt::Uninitialized);