2 files changed, 113 insertions, 24 deletions
diff --git a/src/gui/math3d/qquaternion.cpp b/src/gui/math3d/qquaternion.cpp
index edbe507e93d..99061fb7163 100644
--- a/src/gui/math3d/qquaternion.cpp
+++ b/src/gui/math3d/qquaternion.cpp
@@ -336,6 +336,9 @@ QVector3D QQuaternion::rotatedVector(const QVector3D &vector) const
     Extracts a 3D axis \a axis and a rotating angle \a angle (in degrees)
     that corresponds to this quaternion.
 
+    Both \a axis and \a angle must be valid, non-\nullptr pointers,
+    otherwise the behavior is undefined.
+
     \sa fromAxisAndAngle()
 */
 
@@ -366,6 +369,9 @@ QQuaternion QQuaternion::fromAxisAndAngle(const QVector3D &axis, float angle)
     Extracts a 3D axis (\a x, \a y, \a z) and a rotating angle \a angle (in degrees)
     that corresponds to this quaternion.
 
+    All of \a x, \a y, \a z, and \a angle must be valid, non-\nullptr pointers,
+    otherwise the behavior is undefined.
+
     \sa fromAxisAndAngle()
 */
 void QQuaternion::getAxisAndAngle(float *x, float *y, float *z, float *angle) const
@@ -421,19 +427,20 @@ QQuaternion QQuaternion::fromAxisAndAngle
     \since 5.5
 
     Calculates roll, pitch, and yaw Euler angles (in degrees)
-    that corresponds to this quaternion.
+    that correspond to this quaternion.
 
     \sa fromEulerAngles()
 */
 
 /*!
-    \fn QQuaternion QQuaternion::fromEulerAngles(const QVector3D &eulerAngles)
+    \fn QQuaternion QQuaternion::fromEulerAngles(const QVector3D &angles)
     \since 5.5
     \overload
 
-    Creates a quaternion that corresponds to a rotation of \a eulerAngles:
-    eulerAngles.z() degrees around the z axis, eulerAngles.x() degrees around the x axis,
-    and eulerAngles.y() degrees around the y axis (in that order).
+    Creates a quaternion that corresponds to a rotation of \a angles:
+    angles.\l{QVector3D::}{z()} degrees around the z axis,
+    angles.\l{QVector3D::}{x()} degrees around the x axis, and
+    angles.\l{QVector3D::}{y()} degrees around the y axis (in that order).
 
     \sa toEulerAngles()
 */
@@ -446,6 +453,9 @@ QQuaternion QQuaternion::fromAxisAndAngle
     Calculates \a roll, \a pitch, and \a yaw Euler angles (in degrees)
     that corresponds to this quaternion.
 
+    All of \a pitch, \a yaw, and \a roll must be valid, non-\nullptr pointers,
+    otherwise the behavior is undefined.
+
     \sa fromEulerAngles()
 */
 void QQuaternion::getEulerAngles(float *pitch, float *yaw, float *roll) const
@@ -547,7 +557,7 @@ QQuaternion QQuaternion::fromEulerAngles(float pitch, float yaw, float roll)
     \note If this quaternion is not normalized,
     the resulting rotation matrix will contain scaling information.
 
-    \sa fromRotationMatrix(), getAxes()
+    \sa fromRotationMatrix(), toAxes()
 */
 QMatrix3x3 QQuaternion::toRotationMatrix() const
 {
@@ -585,9 +595,9 @@ QMatrix3x3 QQuaternion::toRotationMatrix() const
 /*!
     \since 5.5
 
-    Creates a quaternion that corresponds to a rotation matrix \a rot3x3.
+    Creates a quaternion that corresponds to the rotation matrix \a rot3x3.
 
-    \note If a given rotation matrix is not normalized,
+    \note If the given rotation matrix is not normalized,
     the resulting quaternion will contain scaling information.
 
     \sa toRotationMatrix(), fromAxes()
@@ -630,23 +640,71 @@ QQuaternion QQuaternion::fromRotationMatrix(const QMatrix3x3 &rot3x3)
 #ifndef QT_NO_VECTOR3D
 
 /*!
-    \since 5.5
+    \since 6.11
+    \class QQuaternion::Axes
+    \ingroup painting-3D
+    \inmodule QtGui
 
-    Returns the 3 orthonormal axes (\a xAxis, \a yAxis, \a zAxis) defining the quaternion.
+    A struct containing the three orthonormal axes that define a
+    \l{QQuaternion}{quaternion}.
 
-    \sa fromAxes(), toRotationMatrix()
+
+    \sa QQuaternion::toAxes(), QQuaternion::fromAxes(Axes)
+*/
+
+/*!
+    \variable QQuaternion::Axes::x
+
+    The x orthonormal axis that, together with \l{y} and \l{z}, defines a
+    quaternion.
+*/
+
+/*!
+    \variable QQuaternion::Axes::y
+
+    The y orthonormal axis that, together with \l{x} and \l{z}, defines a
+    quaternion.
+*/
+
+/*!
+    \variable QQuaternion::Axes::z
+
+    The z orthonormal axis that, together with \l{x} and \l{y}, defines a
+    quaternion.
 */
-void QQuaternion::getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis) const
-{
-    Q_ASSERT(xAxis && yAxis && zAxis);
 
+/*!
+    \since 6.11
+
+    Returns the three orthonormal axes that define this quaternion.
+
+    \sa QQuaternion::Axes, fromAxes(QQuaternion::Axes), toRotationMatrix()
+*/
+auto QQuaternion::toAxes() const -> Axes
+{
     const QMatrix3x3 rot3x3(toRotationMatrix());
 
-    *xAxis = QVector3D(rot3x3(0, 0), rot3x3(1, 0), rot3x3(2, 0));
-    *yAxis = QVector3D(rot3x3(0, 1), rot3x3(1, 1), rot3x3(2, 1));
-    *zAxis = QVector3D(rot3x3(0, 2), rot3x3(1, 2), rot3x3(2, 2));
+    return { {rot3x3(0, 0), rot3x3(1, 0), rot3x3(2, 0)},
+             {rot3x3(0, 1), rot3x3(1, 1), rot3x3(2, 1)},
+             {rot3x3(0, 2), rot3x3(1, 2), rot3x3(2, 2)} };
 }
 
+
+/*!
+    \fn void QQuaternion::getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis) const
+    \since 5.5
+
+    \obsolete
+    Use toAxes() instead.
+
+    Returns the 3 orthonormal axes (\a xAxis, \a yAxis, \a zAxis) defining the quaternion.
+
+    All of \a xAxis, \a yAxis, and \a zAxis must be valid, non-\nullptr pointers,
+    otherwise the behavior is undefined.
+
+    \sa fromAxes(), toRotationMatrix()
+*/
+
 /*!
     \since 5.5
 
@@ -654,7 +712,7 @@ void QQuaternion::getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis)
 
     \note The axes are assumed to be orthonormal.
 
-    \sa getAxes(), fromRotationMatrix()
+    \sa toAxes(), fromRotationMatrix()
 */
 QQuaternion QQuaternion::fromAxes(const QVector3D &xAxis, const QVector3D &yAxis, const QVector3D &zAxis)
 {
@@ -673,6 +731,17 @@ QQuaternion QQuaternion::fromAxes(const QVector3D &xAxis, const QVector3D &yAxis
 }
 
 /*!
+    \since 6.11
+    \overload
+
+    \sa toAxes(), fromRotationMatrix()
+*/
+QQuaternion QQuaternion::fromAxes(Axes axes) // clazy:exclude=function-args-by-ref
+{
+    return fromAxes(axes.x, axes.y, axes.z);
+}
+
+/*!
     \since 5.5
 
     Constructs the quaternion using specified forward direction \a direction
diff --git a/src/gui/math3d/qquaternion.h b/src/gui/math3d/qquaternion.h
index 7fb153063c5..ffc95a852ce 100644
--- a/src/gui/math3d/qquaternion.h
+++ b/src/gui/math3d/qquaternion.h
@@ -109,7 +109,7 @@ QT_WARNING_POP
 
 #ifndef QT_NO_VECTOR3D
     inline QVector3D toEulerAngles() const;
-    static inline QQuaternion fromEulerAngles(const QVector3D &eulerAngles);
+    static inline QQuaternion fromEulerAngles(const QVector3D &angles);
 #endif
     QT7_ONLY(Q_GUI_EXPORT) void getEulerAngles(float *pitch, float *yaw, float *roll) const;
     QT7_ONLY(Q_GUI_EXPORT) static QQuaternion fromEulerAngles(float pitch, float yaw, float roll);
@@ -118,7 +118,14 @@ QT_WARNING_POP
     QT7_ONLY(Q_GUI_EXPORT) static QQuaternion fromRotationMatrix(const QMatrix3x3 &rot3x3);
 
 #ifndef QT_NO_VECTOR3D
-    QT7_ONLY(Q_GUI_EXPORT) void getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis) const;
+    struct Axes
+    {
+        QVector3D x, y, z;
+    };
+    QT7_ONLY(Q_GUI_EXPORT) Axes toAxes() const;
+    QT7_ONLY(Q_GUI_EXPORT) static QQuaternion fromAxes(Axes axes); // clazy:exclude=function-args-by-ref
+    QT_GUI_INLINE_SINCE(6, 11)
+    void getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis) const;
     QT7_ONLY(Q_GUI_EXPORT) static QQuaternion fromAxes(const QVector3D &xAxis,
                                                        const QVector3D &yAxis,
                                                        const QVector3D &zAxis);
@@ -311,24 +318,37 @@ inline QVector3D operator*(const QQuaternion &quaternion, const QVector3D &vec)
     return quaternion.rotatedVector(vec);
 }
 
-inline void QQuaternion::getAxisAndAngle(QVector3D *axis, float *angle) const
+void QQuaternion::getAxisAndAngle(QVector3D *axis, float *angle) const
 {
     float aX, aY, aZ;
     getAxisAndAngle(&aX, &aY, &aZ, angle);
     *axis = QVector3D(aX, aY, aZ);
 }
 
-inline QVector3D QQuaternion::toEulerAngles() const
+QVector3D QQuaternion::toEulerAngles() const
 {
     float pitch, yaw, roll;
     getEulerAngles(&pitch, &yaw, &roll);
     return QVector3D(pitch, yaw, roll);
 }
 
-inline QQuaternion QQuaternion::fromEulerAngles(const QVector3D &eulerAngles)
+QQuaternion QQuaternion::fromEulerAngles(const QVector3D &angles)
+{
+    return QQuaternion::fromEulerAngles(angles.x(), angles.y(), angles.z());
+}
+
+#if QT_GUI_INLINE_IMPL_SINCE(6, 11)
+void QQuaternion::getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis) const
 {
-    return QQuaternion::fromEulerAngles(eulerAngles.x(), eulerAngles.y(), eulerAngles.z());
+    Q_PRE(xAxis);
+    Q_PRE(yAxis);
+    Q_PRE(zAxis);
+    const Axes axes = toAxes();
+    *xAxis = axes.x;
+    *yAxis = axes.y;
+    *zAxis = axes.z;
 }
+#endif // QT_GUI_INLINE_IMPL_SINCE(6, 11)
 
 #endif // QT_NO_VECTOR3D