Source code
Revision control
Copy as Markdown
// 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
// Qt-Security score:significant reason:default
#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
//
// QQuaternion::Axis
//
/*!
\since 6.11
\class QQuaternion::Axis
\ingroup painting-3D
\inmodule QtGui
A struct representing a 3D axis used to define \l{QQuaternion}{quaternions},
through \l{QQuaternion::Axes}{three (orthonormal) axes}.
The struct itself does not constrain the values of its \l{x}, \l{y} and \l{z}
members, though QQuaternion functions using this type may. In particular, Axis
objects need not be normalized.
This type is very similar to QVector3D, to and from which it can be readily
converted, but has a narrower focus. You may call it a "strong typedef" for
QVector3D.
\sa QQuaternion::Axes
*/
/*!
\fn QQuaternion::Axis QQuaternion::Axis::fromVector3D(QVector3D v)
Constructs an Axis from \a v, as if by
\code
return Axis{v.x(), v.y(), v.z()}}
\endcode
*/
/*!
\fn QVector3D QQuaternion::Axis::toVector3D() const
Returns this Axis as a QVector3D, as if by
\code
Axis a = *this;
return QVector3D{a.x, a.y, a.z}
\endcode
*/
/*!
\since 6.11
\fn bool QQuaternion::Axis::qFuzzyIsNull(QQuaternion::Axis axis)
Returns \c true if \a axis is degenerate, that is, equal to \c{(0, 0, 0)},
allowing for a small fuzziness factor for floating-point comparisons; \c false
otherwise.
*/
/*!
\variable QQuaternion::Axis::x
Contains the x-component of the 3D axis.
*/
/*!
\variable QQuaternion::Axis::y
Contains the y-component of the 3D axis.
*/
/*!
\variable QQuaternion::Axis::z
Contains the z-component of the 3D axis.
*/
//
// QQuaternion
//
/*!
\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:
// 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
EulerAngles\<T\> is a struct template where \a T specifies the floating-point
type used for the angle values (typically \c float).
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:
// "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:
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:
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:
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]);
}
/*!
\since 6.11
\class QQuaternion::Axes
\ingroup painting-3D
\inmodule QtGui
A struct containing the three orthonormal \l{QQuaternion::Axis}{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 6.11
Constructs the quaternion using axes contained in \a axes.
\note The axes are assumed to be orthonormal.
\sa toAxes(), fromRotationMatrix()
*/
QQuaternion QQuaternion::fromAxes(Axes axes) // clazy:exclude=function-args-by-ref
{
QMatrix3x3 rot3x3(Qt::Uninitialized);
rot3x3(0, 0) = axes.x.x;
rot3x3(1, 0) = axes.x.y;
rot3x3(2, 0) = axes.x.z;
rot3x3(0, 1) = axes.y.x;
rot3x3(1, 1) = axes.y.y;
rot3x3(2, 1) = axes.y.z;
rot3x3(0, 2) = axes.z.x;
rot3x3(1, 2) = axes.z.y;
rot3x3(2, 2) = axes.z.z;
return QQuaternion::fromRotationMatrix(rot3x3);
}
/*!
\fn QQuaternion QQuaternion::fromAxes(const QVector3D &xAxis, const QVector3D &yAxis, const QVector3D &zAxis)
\since 5.5
\overload
*/
#ifndef QT_NO_VECTOR3D
/*!
\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 fastSlerp(), 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.0000001f) {
float angle = std::acos(dot);
// Compute 1 - dot^2 as (1 - dot) * (1 + dot) to reduce
// cancellation when dot is close to 1.0.
const float sinOfAngleSquared = (1.0f - dot) * (1.0f + dot);
// Since q2 was flipped when needed above, dot is non-negative here.
// Thus angle = acos(dot) is in [0, pi / 2], where sin(angle) is
// non-negative and equals sqrt(1 - dot^2).
const float sinOfAngle = std::sqrt(sinOfAngleSquared);
if (sinOfAngle > 0.0000001f) {
factor1 = std::sin((1.0f - t) * angle) / sinOfAngle;
factor2 = std::sin(t * angle) / sinOfAngle;
}
}
// Construct the result quaternion.
return q1 * factor1 + q2b * factor2;
}
// fastSlerp() passes the post-flip dot product, so x is in [0, 1]. This is
// the polynomial part of the fast acos approximation, i.e. acos(x) / sqrt(1 - x).
static constexpr float qt_quaternionFastAcosScale(float x) noexcept
{
Q_PRESUME(x >= 0.0f);
Q_PRESUME(x <= 1.0f);
// Handbook of Mathematical Functions
// M. Abramowitz and I.A. Stegun, Ed.
float result = -0.0187293f;
result = result * x + 0.0742610f;
result = result * x - 0.2121144f;
result = result * x + 1.5707288f;
return result;
}
// fastSlerp() approximates sin(x) on [0, pi / 2] as x * Q(x^2). Return
// Q(x^2), with Q(0) fixed to 1 so that sin(0) and sin'(0) are exact. The
// coefficients were generated with Sollya 8.0, which reports a maximum
// absolute approximation error below 8.3e-9 for x * Q(x^2).
static constexpr float qt_quaternionFastSinScale(float xSquared) noexcept
{
Q_PRESUME(xSquared >= 0.0f);
float result = 0x1.5e6d1ep-19f;
result = result * xSquared - 0x1.9f7d66p-13f;
result = result * xSquared + 0x1.110f24p-7f;
result = result * xSquared - 0x1.55554ep-3f;
return 1.0f + xSquared * result;
}
/*!
\since 6.13
Interpolates along the shortest spherical path between the
rotational positions \a q1 and \a q2. \a q1 and \a q2 are
expected to be normalized. The value \a t should be between 0 and 1,
indicating the spherical distance to travel between \a q1 and \a q2.
This function uses approximations for the trigonometric functions, so it
can be more than 3x faster than slerp(). The result is suitable for graphics
and animation code where small angular errors are acceptable.
Prefer slerp() when maximum precision is required.
For very small angles, this function uses normalized linear interpolation.
For normalized input quaternions, this applies to rotation differences below
about 3.6 degrees.
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 slerp(), nlerp()
*/
QQuaternion QQuaternion::fastSlerp
(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;
}
float factor1 = 1.0f - t;
float factor2 = t;
if (dot > 0.9995f && dot <= 1.0f)
return (q1 * factor1 + q2b * factor2).normalized();
const float oneMinusDot = 1.0f - dot;
if (oneMinusDot > 0.0000001f) {
const float acosScale = qt_quaternionFastAcosScale(dot);
const float angleSquared = oneMinusDot * acosScale * acosScale;
// Since fastAcos(dot) is sqrt(1 - dot) * acosScale and fastSin(x) is
// x * Q(x^2), the division by sin(acos(dot)) cancels sqrt(1 - dot).
const float commonFactor = acosScale / std::sqrt(1.0f + dot);
factor1 *= commonFactor * qt_quaternionFastSinScale(factor1 * factor1 * angleSquared);
factor2 *= commonFactor * qt_quaternionFastSinScale(factor2 * factor2 * angleSquared);
}
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(), fastSlerp()
*/
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)
return q2;
// Determine the angle between the two quaternions.
QQuaternion q2b(q2);
float dot = QQuaternion::dotProduct(q1, q2);
if (dot < 0.0f)
q2b = -q2b;
// Perform the linear interpolation.
return (q1 * (1.0f - t) + q2b * t).normalized();
}
/*!
Returns the quaternion as a QVariant.
*/
QQuaternion::operator QVariant() const
{
return QVariant::fromValue(*this);
}
#ifndef QT_NO_DEBUG_STREAM
QDebug operator<<(QDebug dbg, const QQuaternion &q)
{
QDebugStateSaver saver(dbg);
dbg.nospace() << "QQuaternion(scalar:" << q.scalar()
<< ", vector:(" << q.x() << ", "
<< q.y() << ", " << q.z() << "))";
return dbg;
}
#endif
#ifndef QT_NO_DATASTREAM
/*!
\fn QDataStream &operator<<(QDataStream &stream, const QQuaternion &quaternion)
\relates QQuaternion
Writes the given \a quaternion to the given \a stream and returns a
reference to the stream.
\sa {Serializing Qt Data Types}
*/
QDataStream &operator<<(QDataStream &stream, const QQuaternion &quaternion)
{
stream << quaternion.scalar() << quaternion.x()
<< quaternion.y() << quaternion.z();
return stream;
}
/*!
\fn QDataStream &operator>>(QDataStream &stream, QQuaternion &quaternion)
\relates QQuaternion
Reads a quaternion from the given \a stream into the given \a quaternion
and returns a reference to the stream.
\sa {Serializing Qt Data Types}
*/
QDataStream &operator>>(QDataStream &stream, QQuaternion &quaternion)
{
float scalar, x, y, z;
stream >> scalar;
stream >> x;
stream >> y;
stream >> z;
quaternion.setScalar(scalar);
quaternion.setX(x);
quaternion.setY(y);
quaternion.setZ(z);
return stream;
}
#endif // QT_NO_DATASTREAM
#endif
QT_END_NAMESPACE