// Copyright (C) 2020 The Qt Company Ltd.

// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only

#include "qquaternion.h"

#include <QtCore/qdatastream.h>

#include <QtCore/qmath.h>

#include <QtCore/qvariant.h>

#include <QtCore/qdebug.h>

#include <cmath>

QT_BEGIN_NAMESPACE

#ifndef QT_NO_QUATERNION

/*!

    \class QQuaternion

    \brief The QQuaternion class represents a quaternion consisting of a vector and scalar.

    \since 4.6

    \ingroup painting-3D

    \inmodule QtGui

    Quaternions are used to represent rotations in 3D space, and

    consist of a 3D rotation axis specified by the x, y, and z

    coordinates, and a scalar representing the rotation angle.

*/

/*!

    \fn QQuaternion::QQuaternion() noexcept

    Constructs an identity quaternion (1, 0, 0, 0), i.e. with the vector (0, 0, 0)

    and scalar 1.

*/

/*!

    \fn QQuaternion::QQuaternion(Qt::Initialization) noexcept

    \since 5.5

    \internal

    Constructs a quaternion without initializing the contents.

*/

/*!

    \fn QQuaternion::QQuaternion(float scalar, float xpos, float ypos, float zpos) noexcept

    Constructs a quaternion with the vector (\a xpos, \a ypos, \a zpos)

    and \a scalar.

*/

#ifndef QT_NO_VECTOR3D

/*!

    \fn QQuaternion::QQuaternion(float scalar, const QVector3D &vector) noexcept

    Constructs a quaternion vector from the specified \a vector and

    \a scalar.

    \sa vector(), scalar()

*/

/*!

    \fn QVector3D QQuaternion::vector() const noexcept

    Returns the vector component of this quaternion.

    \sa setVector(), scalar()

*/

/*!

    \fn void QQuaternion::setVector(const QVector3D &vector) noexcept

    Sets the vector component of this quaternion to \a vector.

    \sa vector(), setScalar()

*/

#endif

/*!

    \fn void QQuaternion::setVector(float x, float y, float z) noexcept

    Sets the vector component of this quaternion to (\a x, \a y, \a z).

    \sa vector(), setScalar()

*/

#ifndef QT_NO_VECTOR4D

/*!

    \fn QQuaternion::QQuaternion(const QVector4D &vector) noexcept

    Constructs a quaternion from the components of \a vector.

*/

/*!

    \fn QVector4D QQuaternion::toVector4D() const noexcept

    Returns this quaternion as a 4D vector.

*/

#endif

/*!

    \fn bool QQuaternion::isNull() const noexcept

    Returns \c true if the x, y, z, and scalar components of this

    quaternion are set to 0.0; otherwise returns \c false.

*/

/*!

    \fn bool QQuaternion::isIdentity() const noexcept

    Returns \c true if the x, y, and z components of this

    quaternion are set to 0.0, and the scalar component is set

    to 1.0; otherwise returns \c false.

*/

/*!

    \fn float QQuaternion::x() const noexcept

    Returns the x coordinate of this quaternion's vector.

    \sa setX(), y(), z(), scalar()

*/

/*!

    \fn float QQuaternion::y() const noexcept

    Returns the y coordinate of this quaternion's vector.

    \sa setY(), x(), z(), scalar()

*/

/*!

    \fn float QQuaternion::z() const noexcept

    Returns the z coordinate of this quaternion's vector.

    \sa setZ(), x(), y(), scalar()

*/

/*!

    \fn float QQuaternion::scalar() const noexcept

    Returns the scalar component of this quaternion.

    \sa setScalar(), x(), y(), z()

*/

/*!

    \fn void QQuaternion::setX(float x) noexcept

    Sets the x coordinate of this quaternion's vector to the given

    \a x coordinate.

    \sa x(), setY(), setZ(), setScalar()

*/

/*!

    \fn void QQuaternion::setY(float y) noexcept

    Sets the y coordinate of this quaternion's vector to the given

    \a y coordinate.

    \sa y(), setX(), setZ(), setScalar()

*/

/*!

    \fn void QQuaternion::setZ(float z) noexcept

    Sets the z coordinate of this quaternion's vector to the given

    \a z coordinate.

    \sa z(), setX(), setY(), setScalar()

*/

/*!

    \fn void QQuaternion::setScalar(float scalar) noexcept

    Sets the scalar component of this quaternion to \a scalar.

    \sa scalar(), setX(), setY(), setZ()

*/

/*!

    \fn float QQuaternion::dotProduct(const QQuaternion &q1, const QQuaternion &q2) noexcept

    \since 5.5

    Returns the dot product of \a q1 and \a q2.

    \sa length()

*/

/*!

    Returns the length of the quaternion.  This is also called the "norm".

    \sa lengthSquared(), normalized(), dotProduct()

*/

float QQuaternion::length() const

{

    return qHypot(xp, yp, zp, wp);

}

/*!

    Returns the squared length of the quaternion.

    \note Though cheap to compute, this is susceptible to overflow and underflow

    that length() avoids in many cases.

    \sa length(), dotProduct()

*/

float QQuaternion::lengthSquared() const

{

    return xp * xp + yp * yp + zp * zp + wp * wp;

}

/*!

    Returns the normalized unit form of this quaternion.

    If this quaternion is null, then a null quaternion is returned.

    If the length of the quaternion is very close to 1, then the quaternion

    will be returned as-is.  Otherwise the normalized form of the

    quaternion of length 1 will be returned.

    \sa normalize(), length(), dotProduct()

*/

QQuaternion QQuaternion::normalized() const

{

    const float scale = length();

    if (qFuzzyIsNull(scale))

        return QQuaternion(0.0f, 0.0f, 0.0f, 0.0f);

    return *this / scale;

}

/*!

    Normalizes the current quaternion in place.  Nothing happens if this

    is a null quaternion or the length of the quaternion is very close to 1.

    \sa length(), normalized()

*/

void QQuaternion::normalize()

{

    const float len = length();

    if (qFuzzyIsNull(len))

        return;

    xp /= len;

    yp /= len;

    zp /= len;

    wp /= len;

}

/*!

    \fn QQuaternion QQuaternion::inverted() const noexcept

    \since 5.5

    Returns the inverse of this quaternion.

    If this quaternion is null, then a null quaternion is returned.

    \sa isNull(), length()

*/

/*!

    \fn QQuaternion QQuaternion::conjugated() const noexcept

    \since 5.5

    Returns the conjugate of this quaternion, which is

    (-x, -y, -z, scalar).

*/

/*!

    Rotates \a vector with this quaternion to produce a new vector

    in 3D space.  The following code:

    \snippet code/src_gui_math3d_qquaternion.cpp 0

    is equivalent to the following:

    \snippet code/src_gui_math3d_qquaternion.cpp 1

*/

QVector3D QQuaternion::rotatedVector(const QVector3D &vector) const

{

    return (*this * QQuaternion(0, vector) * conjugated()).vector();

}

/*!

    \fn QQuaternion &QQuaternion::operator+=(const QQuaternion &quaternion) noexcept

    Adds the given \a quaternion to this quaternion and returns a reference to

    this quaternion.

    \sa operator-=()

*/

/*!

    \fn QQuaternion &QQuaternion::operator-=(const QQuaternion &quaternion) noexcept

    Subtracts the given \a quaternion from this quaternion and returns a

    reference to this quaternion.

    \sa operator+=()

*/

/*!

    \fn QQuaternion &QQuaternion::operator*=(float factor) noexcept

    Multiplies this quaternion's components by the given \a factor, and

    returns a reference to this quaternion.

    \sa operator/=()

*/

/*!

    \fn QQuaternion &QQuaternion::operator*=(const QQuaternion &quaternion) noexcept

    Multiplies this quaternion by \a quaternion and returns a reference

    to this quaternion.

*/

/*!

    \fn QQuaternion &QQuaternion::operator/=(float divisor)

    Divides this quaternion's components by the given \a divisor, and

    returns a reference to this quaternion.

    \sa operator*=()

*/

#ifndef QT_NO_VECTOR3D

/*!

    \fn void QQuaternion::getAxisAndAngle(QVector3D *axis, float *angle) const noexcept

    \since 5.5

    \overload

    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()

*/

/*!

    Creates a normalized quaternion that corresponds to rotating through

    \a angle degrees about the specified 3D \a axis.

    \sa getAxisAndAngle()

*/

QQuaternion QQuaternion::fromAxisAndAngle(const QVector3D &axis, float angle)

{

    // Algorithm from:

    // http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q56

    // We normalize the result just in case the values are close

    // to zero, as suggested in the above FAQ.

    float a = qDegreesToRadians(angle / 2.0f);

    float s = std::sin(a);

    float c = std::cos(a);

    QVector3D ax = axis.normalized();

    return QQuaternion(c, ax.x() * s, ax.y() * s, ax.z() * s).normalized();

}

#endif

/*!

    \since 5.5

    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

{

    Q_ASSERT(x && y && z && angle);

    // The quaternion representing the rotation is

    //   q = cos(A/2)+sin(A/2)*(x*i+y*j+z*k)

    const float length = qHypot(xp, yp, zp);

    if (!qFuzzyIsNull(length)) {

        if (qFuzzyCompare(length, 1.0f)) {

            *x = xp;

            *y = yp;

            *z = zp;

        } else {

            *x = xp / length;

            *y = yp / length;

            *z = zp / length;

        }

        *angle = qRadiansToDegrees(2.0f * std::atan2(length, wp));

    } else {

        // angle is 0 (mod 2*pi), so any axis will fit

        *x = *y = *z = *angle = 0.0f;

    }

}

/*!

    Creates a normalized quaternion that corresponds to rotating through

    \a angle degrees about the 3D axis (\a x, \a y, \a z).

    \sa getAxisAndAngle()

*/

QQuaternion QQuaternion::fromAxisAndAngle

        (float x, float y, float z, float angle)

{

    float length = qHypot(x, y, z);

    if (!qFuzzyIsNull(length) && !qFuzzyCompare(length, 1.0f)) {

        x /= length;

        y /= length;

        z /= length;

    }

    float a = qDegreesToRadians(angle / 2.0f);

    float s = std::sin(a);

    float c = std::cos(a);

    return QQuaternion(c, x * s, y * s, z * s).normalized();

}

#ifndef QT_NO_VECTOR3D

/*!

    \fn QVector3D QQuaternion::toEulerAngles() const

    \since 5.5

    Calculates roll, pitch, and yaw Euler angles (in degrees)

    that correspond to this quaternion.

    \sa fromEulerAngles()

*/

/*!

    \fn QQuaternion QQuaternion::fromEulerAngles(const QVector3D &angles)

    \since 5.5

    \overload

    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()

*/

#endif // QT_NO_VECTOR3D

/*!

    \fn void QQuaternion::getEulerAngles(float *pitch, float *yaw, float *roll) const

    \since 5.5

    \obsolete

    Use eulerAngles() instead.

    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 eulerAngles(), fromEulerAngles()

*/

/*!

    \since 6.11

    \class QQuaternion::EulerAngles

    \ingroup painting-3D

    \inmodule QtGui

    A struct containing three fields \l{pitch}, \l{yaw}, and \l{roll},

    representing the three Euler angles that define a

    \l{QQuaternion}{quaternion}.

    Consult the documentation of functions taking or returning an EulerAngles

    object for the order in which the rotations are applied.

    \sa QQuaternion::eulerAngles(), QQuaternion::fromEulerAngles(QQuaternion::EulerAngles<float>)

*/

/*!

    \variable QQuaternion::EulerAngles::pitch

    The pitch represents the rotation around the x-axis.

*/

/*!

    \variable QQuaternion::EulerAngles::yaw

    The yaw represents the rotation around the y-axis.

*/

/*!

    \variable QQuaternion::EulerAngles::roll

    The roll represents the rotation around the z-axis.

*/

/*!

    \since 6.11

    Returns the Euler angles (in degrees) that correspond to this quaternion.

    \sa fromEulerAngles()

*/

auto QQuaternion::eulerAngles() const -> EulerAngles<float>

{

    EulerAngles<float> result;

    // to avoid churn

    auto pitch = &result.pitch;

    auto yaw = &result.yaw;

    auto roll = &result.roll;

    // Algorithm adapted from:

    // https://ingmec.ual.es/~jlblanco/papers/jlblanco2010geometry3D_techrep.pdf

    // "A tutorial on SE(3) transformation parameterizations and on-manifold optimization".

    // We can only detect Gimbal lock when we normalize, which we can't do when

    // length is nearly zero. Do so before multiplying coordinates, to avoid

    // underflow.

    const float len = length();

    const bool rescale = !qFuzzyIsNull(len);

    const float xps = rescale ? xp / len : xp;

    const float yps = rescale ? yp / len : yp;

    const float zps = rescale ? zp / len : zp;

    const float wps = rescale ? wp / len : wp;

    const float xx = xps * xps;

    const float xy = xps * yps;

    const float xz = xps * zps;

    const float xw = xps * wps;

    const float yy = yps * yps;

    const float yz = yps * zps;

    const float yw = yps * wps;

    const float zz = zps * zps;

    const float zw = zps * wps;

    // For the common case, we have a hidden division by cos(pitch) to calculate

    // yaw and roll: atan2(a / cos(pitch), b / cos(pitch)) = atan2(a, b). This equation

    // wouldn't work if cos(pitch) is close to zero (i.e. abs(sin(pitch)) =~ 1.0).

    // This threshold is copied from qFuzzyIsNull() to avoid the hidden division by zero.

    constexpr float epsilon = 0.00001f;

    const float sinp = -2.0f * (yz - xw);

    if (std::abs(sinp) < 1.0f - epsilon) {

        *pitch = std::asin(sinp);

        *yaw = std::atan2(2.0f * (xz + yw), 1.0f - 2.0f * (xx + yy));

        *roll = std::atan2(2.0f * (xy + zw), 1.0f - 2.0f * (xx + zz));

    } else {

        // Gimbal lock case, which doesn't have a unique solution. We just use

        // XY rotation.

        *pitch = std::copysign(static_cast<float>(M_PI_2), sinp);

        *yaw = 2.0f * std::atan2(yps, wps);

        *roll = 0.0f;

    }

    *pitch = qRadiansToDegrees(*pitch);

    *yaw = qRadiansToDegrees(*yaw);

    *roll = qRadiansToDegrees(*roll);

    return result;

}

/*!

    \since 5.5

    Creates a quaternion that corresponds to a rotation of

    \a roll degrees around the z axis, \a pitch degrees around the x axis,

    and \a yaw degrees around the y axis (in that order).

    \sa eulerAngles(), toEulerAngles(), fromEulerAngles(QQuaternion::EulerAngles<float>)

*/

QQuaternion QQuaternion::fromEulerAngles(float pitch, float yaw, float roll)

{

    // Algorithm from:

    // http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q60

    pitch = qDegreesToRadians(pitch);

    yaw = qDegreesToRadians(yaw);

    roll = qDegreesToRadians(roll);

    pitch *= 0.5f;

    yaw *= 0.5f;

    roll *= 0.5f;

    const float c1 = std::cos(yaw);

    const float s1 = std::sin(yaw);

    const float c2 = std::cos(roll);

    const float s2 = std::sin(roll);

    const float c3 = std::cos(pitch);

    const float s3 = std::sin(pitch);

    const float c1c2 = c1 * c2;

    const float s1s2 = s1 * s2;

    const float w = c1c2 * c3 + s1s2 * s3;

    const float x = c1c2 * s3 + s1s2 * c3;

    const float y = s1 * c2 * c3 - c1 * s2 * s3;

    const float z = c1 * s2 * c3 - s1 * c2 * s3;

    return QQuaternion(w, x, y, z);

}

/*!

    \fn QQuaternion QQuaternion::fromEulerAngles(EulerAngles<float> angles)

    \since 6.11

    \overload

    Equivalent to

    \code

    fromEulerAngles(angles.pitch, angles.yaw, angles.roll);

    \endcode

    \sa eulerAngles(), toEulerAngles(), fromEulerAngles()

*/

/*!

    \since 5.5

    Creates a rotation matrix that corresponds to this quaternion.

    \note If this quaternion is not normalized,

    the resulting rotation matrix will contain scaling information.

    \sa fromRotationMatrix(), toAxes()

*/

QMatrix3x3 QQuaternion::toRotationMatrix() const

{

    // Algorithm from:

    // http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q54

    QMatrix3x3 rot3x3(Qt::Uninitialized);

    const float f2x = xp + xp;

    const float f2y = yp + yp;

    const float f2z = zp + zp;

    const float f2xw = f2x * wp;

    const float f2yw = f2y * wp;

    const float f2zw = f2z * wp;

    const float f2xx = f2x * xp;

    const float f2xy = f2x * yp;

    const float f2xz = f2x * zp;

    const float f2yy = f2y * yp;

    const float f2yz = f2y * zp;

    const float f2zz = f2z * zp;

    rot3x3(0, 0) = 1.0f - (f2yy + f2zz);

    rot3x3(0, 1) =         f2xy - f2zw;

    rot3x3(0, 2) =         f2xz + f2yw;

    rot3x3(1, 0) =         f2xy + f2zw;

    rot3x3(1, 1) = 1.0f - (f2xx + f2zz);

    rot3x3(1, 2) =         f2yz - f2xw;

    rot3x3(2, 0) =         f2xz - f2yw;

    rot3x3(2, 1) =         f2yz + f2xw;

    rot3x3(2, 2) = 1.0f - (f2xx + f2yy);

    return rot3x3;

}

/*!

    \since 5.5

    Creates a quaternion that corresponds to the rotation matrix \a rot3x3.

    \note If the given rotation matrix is not normalized,

    the resulting quaternion will contain scaling information.

    \sa toRotationMatrix(), fromAxes()

*/

QQuaternion QQuaternion::fromRotationMatrix(const QMatrix3x3 &rot3x3)

{

    // Algorithm from:

    // http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q55

    float scalar;

    float axis[3];

    const float trace = rot3x3(0, 0) + rot3x3(1, 1) + rot3x3(2, 2);

    if (trace > 0.00000001f) {

        const float s = 2.0f * std::sqrt(trace + 1.0f);

        scalar = 0.25f * s;

        axis[0] = (rot3x3(2, 1) - rot3x3(1, 2)) / s;

        axis[1] = (rot3x3(0, 2) - rot3x3(2, 0)) / s;

        axis[2] = (rot3x3(1, 0) - rot3x3(0, 1)) / s;

    } else {

        constexpr int s_next[3] = { 1, 2, 0 };

        int i = 0;

        if (rot3x3(1, 1) > rot3x3(0, 0))

            i = 1;

        if (rot3x3(2, 2) > rot3x3(i, i))

            i = 2;

        int j = s_next[i];

        int k = s_next[j];

        const float s = 2.0f * std::sqrt(rot3x3(i, i) - rot3x3(j, j) - rot3x3(k, k) + 1.0f);

        axis[i] = 0.25f * s;

        scalar = (rot3x3(k, j) - rot3x3(j, k)) / s;

        axis[j] = (rot3x3(j, i) + rot3x3(i, j)) / s;

        axis[k] = (rot3x3(k, i) + rot3x3(i, k)) / s;

    }

    return QQuaternion(scalar, axis[0], axis[1], axis[2]);

}

#ifndef QT_NO_VECTOR3D

/*!

    \since 6.11

    \class QQuaternion::Axes

    \ingroup painting-3D

    \inmodule QtGui

    A struct containing the three orthonormal axes that define a

    \l{QQuaternion}{quaternion}.

    \sa QQuaternion::toAxes(), QQuaternion::fromAxes(QQuaternion::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.

*/

/*!

    \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());

    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

    Constructs the quaternion using 3 axes (\a xAxis, \a yAxis, \a zAxis).

    \note The axes are assumed to be orthonormal.

    \sa toAxes(), fromRotationMatrix()

*/

QQuaternion QQuaternion::fromAxes(const QVector3D &xAxis, const QVector3D &yAxis, const QVector3D &zAxis)

{

    QMatrix3x3 rot3x3(Qt::Uninitialized);

    rot3x3(0, 0) = xAxis.x();

    rot3x3(1, 0) = xAxis.y();

    rot3x3(2, 0) = xAxis.z();

    rot3x3(0, 1) = yAxis.x();

    rot3x3(1, 1) = yAxis.y();

    rot3x3(2, 1) = yAxis.z();

    rot3x3(0, 2) = zAxis.x();

    rot3x3(1, 2) = zAxis.y();

    rot3x3(2, 2) = zAxis.z();

    return QQuaternion::fromRotationMatrix(rot3x3);

}

/*!

    \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

    and upward direction \a up.

    If the upward direction was not specified or the forward and upward

    vectors are collinear, a new orthonormal upward direction will be generated.

    \sa fromAxes(), rotationTo()

*/

QQuaternion QQuaternion::fromDirection(const QVector3D &direction, const QVector3D &up)

{

    if (qFuzzyIsNull(direction.x()) && qFuzzyIsNull(direction.y()) && qFuzzyIsNull(direction.z()))

        return QQuaternion();

    const QVector3D zAxis(direction.normalized());

    QVector3D xAxis(QVector3D::crossProduct(up, zAxis));

    if (qFuzzyIsNull(xAxis.lengthSquared())) {

        // collinear or invalid up vector; derive shortest arc to new direction

        return QQuaternion::rotationTo(QVector3D(0.0f, 0.0f, 1.0f), zAxis);

    }

    xAxis.normalize();

    const QVector3D yAxis(QVector3D::crossProduct(zAxis, xAxis));

    return QQuaternion::fromAxes(xAxis, yAxis, zAxis);

}

/*!

    \since 5.5

    Returns the shortest arc quaternion to rotate from the direction described by the vector \a from

    to the direction described by the vector \a to.

    \sa fromDirection()

*/

QQuaternion QQuaternion::rotationTo(const QVector3D &from, const QVector3D &to)

{

    // Based on Stan Melax's article in Game Programming Gems

    const QVector3D v0(from.normalized());

    const QVector3D v1(to.normalized());

    float d = QVector3D::dotProduct(v0, v1) + 1.0f;

    // if dest vector is close to the inverse of source vector, ANY axis of rotation is valid

    if (qFuzzyIsNull(d)) {

        QVector3D axis = QVector3D::crossProduct(QVector3D(1.0f, 0.0f, 0.0f), v0);

        if (qFuzzyIsNull(axis.lengthSquared()))

            axis = QVector3D::crossProduct(QVector3D(0.0f, 1.0f, 0.0f), v0);

        axis.normalize();

        // same as QQuaternion::fromAxisAndAngle(axis, 180.0f)

        return QQuaternion(0.0f, axis.x(), axis.y(), axis.z());

    }

    d = std::sqrt(2.0f * d);

    const QVector3D axis(QVector3D::crossProduct(v0, v1) / d);

    return QQuaternion(d * 0.5f, axis).normalized();

}

#endif // QT_NO_VECTOR3D

/*!

    \fn bool QQuaternion::operator==(const QQuaternion &q1, const QQuaternion &q2) noexcept

    Returns \c true if \a q1 is equal to \a q2; otherwise returns \c false.

    This operator uses an exact floating-point comparison.

*/

/*!

    \fn bool QQuaternion::operator!=(const QQuaternion &q1, const QQuaternion &q2) noexcept

    Returns \c true if \a q1 is not equal to \a q2; otherwise returns \c false.

    This operator uses an exact floating-point comparison.

*/

/*!

    \fn const QQuaternion operator+(const QQuaternion &q1, const QQuaternion &q2) noexcept

    \relates QQuaternion

    Returns a QQuaternion object that is the sum of the given quaternions,

    \a q1 and \a q2; each component is added separately.

    \sa QQuaternion::operator+=()

*/

/*!

    \fn const QQuaternion operator-(const QQuaternion &q1, const QQuaternion &q2) noexcept

    \relates QQuaternion

    Returns a QQuaternion object that is formed by subtracting

    \a q2 from \a q1; each component is subtracted separately.

    \sa QQuaternion::operator-=()

*/

/*!

    \fn const QQuaternion operator*(float factor, const QQuaternion &quaternion) noexcept

    \relates QQuaternion

    Returns a copy of the given \a quaternion,  multiplied by the

    given \a factor.

    \sa QQuaternion::operator*=()

*/

/*!

    \fn const QQuaternion operator*(const QQuaternion &quaternion, float factor) noexcept

    \relates QQuaternion

    Returns a copy of the given \a quaternion,  multiplied by the

    given \a factor.

    \sa QQuaternion::operator*=()

*/

/*!

    \fn const QQuaternion operator*(const QQuaternion &q1, const QQuaternion &q2) noexcept

    \relates QQuaternion

    Multiplies \a q1 and \a q2 using quaternion multiplication.

    The result corresponds to applying both of the rotations specified

    by \a q1 and \a q2.

    \sa QQuaternion::operator*=()

*/

/*!

    \fn const QQuaternion operator-(const QQuaternion &quaternion) noexcept

    \relates QQuaternion

    \overload

    Returns a QQuaternion object that is formed by changing the sign of

    all three components of the given \a quaternion.

    Equivalent to \c {QQuaternion(0,0,0,0) - quaternion}.

*/

/*!

    \fn const QQuaternion operator/(const QQuaternion &quaternion, float divisor)

    \relates QQuaternion

    Returns the QQuaternion object formed by dividing all components of

    the given \a quaternion by the given \a divisor.

    \sa QQuaternion::operator/=()

*/

#ifndef QT_NO_VECTOR3D

/*!

    \fn QVector3D operator*(const QQuaternion &quaternion, const QVector3D &vec) noexcept

    \since 5.5

    \relates QQuaternion

    Rotates a vector \a vec with a quaternion \a quaternion to produce a new vector in 3D space.

*/

#endif

/*!

    \fn bool qFuzzyCompare(const QQuaternion &q1, const QQuaternion &q2) noexcept

    \relates QQuaternion

    Returns \c true if \a q1 and \a q2 are equal, allowing for a small

    fuzziness factor for floating-point comparisons; false otherwise.

*/

/*!

    Interpolates along the shortest spherical path between the

    rotational positions \a q1 and \a q2.  The value \a t should

    be between 0 and 1, indicating the spherical distance to travel

    between \a q1 and \a q2.

    If \a t is less than or equal to 0, then \a q1 will be returned.

    If \a t is greater than or equal to 1, then \a q2 will be returned.

    \sa nlerp()

*/

QQuaternion QQuaternion::slerp

    (const QQuaternion &q1, const QQuaternion &q2, float t)

{

    // Handle the easy cases first.

    if (t <= 0.0f)

        return q1;

    else if (t >= 1.0f)

        return q2;

    // Determine the angle between the two quaternions.

    QQuaternion q2b(q2);

    float dot = QQuaternion::dotProduct(q1, q2);

    if (dot < 0.0f) {

        q2b = -q2b;

        dot = -dot;

    }

    // Get the scale factors.  If they are too small,

    // then revert to simple linear interpolation.

    float factor1 = 1.0f - t;

    float factor2 = t;

    if ((1.0f - dot) > 0.0000001) {

        float angle = std::acos(dot);

        float sinOfAngle = std::sin(angle);

        if (sinOfAngle > 0.0000001) {

            factor1 = std::sin((1.0f - t) * angle) / sinOfAngle;

            factor2 = std::sin(t * angle) / sinOfAngle;

        }

    }

    // Construct the result quaternion.

    return q1 * factor1 + q2b * factor2;

}

/*!

    Interpolates along the shortest linear path between the rotational

    positions \a q1 and \a q2.  The value \a t should be between 0 and 1,

    indicating the distance to travel between \a q1 and \a q2.

    The result will be normalized().

    If \a t is less than or equal to 0, then \a q1 will be returned.

    If \a t is greater than or equal to 1, then \a q2 will be returned.

    The nlerp() function is typically faster than slerp() and will

    give approximate results to spherical interpolation that are

    good enough for some applications.

    \sa slerp()

*/

QQuaternion QQuaternion::nlerp

    (const QQuaternion &q1, const QQuaternion &q2, float t)

{

    // Handle the easy cases first.

    if (t <= 0.0f)

        return q1;

    else if (t >= 1.0f)