- Qt 6.9
- Qt GUI
- C++ Classes
- QQuaternion
- Qt 6.9.3 Reference Documentation

# QQuaternion Class

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

Header: | `#include <QQuaternion>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Gui)` `target_link_libraries(mytarget PRIVATE Qt6::Gui)`
qmake: | `QT += gui`

- List of all members, including inherited members
- QQuaternion is part of Rendering in 3D.

## Public Functions

| QQuaternion()
| QQuaternion(const QVector4D &vector)
| QQuaternion(float scalar, const QVector3D &vector)
| QQuaternion(float scalar, float xpos, float ypos, float zpos)
QQuaternion | conjugated() const
void | getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis) const
void | getAxisAndAngle(float *x, float *y, float *z, float *angle) const
void | getAxisAndAngle(QVector3D *axis, float *angle) const
void | getEulerAngles(float *pitch, float *yaw, float *roll) const
QQuaternion | inverted() const
bool | isIdentity() const
bool | isNull() const
float | length() const
float | lengthSquared() const
void | normalize()
QQuaternion | normalized() const
QVector3D | rotatedVector(const QVector3D &vector) const
float | scalar() const
void | setScalar(float scalar)
void | setVector(const QVector3D &vector)
void | setVector(float x, float y, float z)
void | setX(float x)
void | setY(float y)
void | setZ(float z)
QVector3D | toEulerAngles() const
QMatrix3x3 | toRotationMatrix() const
QVector4D | toVector4D() const
QVector3D | vector() const
float | x() const
float | y() const
float | z() const
QVariant | operator QVariant() const
QQuaternion & | operator*=(const QQuaternion &quaternion)
QQuaternion & | operator*=(float factor)
QQuaternion & | operator+=(const QQuaternion &quaternion)
QQuaternion & | operator-=(const QQuaternion &quaternion)
QQuaternion & | operator/=(float divisor)

## Static Public Members

float | dotProduct(const QQuaternion &q1, const QQuaternion &q2)
QQuaternion | fromAxes(const QVector3D &xAxis, const QVector3D &yAxis, const QVector3D &zAxis)
QQuaternion | fromAxisAndAngle(const QVector3D &axis, float angle)
QQuaternion | fromAxisAndAngle(float x, float y, float z, float angle)
QQuaternion | fromDirection(const QVector3D &direction, const QVector3D &up)
QQuaternion | fromEulerAngles(float pitch, float yaw, float roll)
QQuaternion | fromEulerAngles(const QVector3D &angles)
QQuaternion | fromRotationMatrix(const QMatrix3x3 &rot3x3)
QQuaternion | nlerp(const QQuaternion &q1, const QQuaternion &q2, float t)
QQuaternion | rotationTo(const QVector3D &from, const QVector3D &to)
QQuaternion | slerp(const QQuaternion &q1, const QQuaternion &q2, float t)

## Related Non-Members

bool | qFuzzyCompare(const QQuaternion &q1, const QQuaternion &q2)
bool | operator!=(const QQuaternion &q1, const QQuaternion &q2)
QQuaternion | operator*(const QQuaternion &q1, const QQuaternion &q2)
QVector3D | operator*(const QQuaternion &quaternion, const QVector3D &vec)
QQuaternion | operator*(const QQuaternion &quaternion, float factor)
QQuaternion | operator*(float factor, const QQuaternion &quaternion)
QQuaternion | operator+(const QQuaternion &q1, const QQuaternion &q2)
QQuaternion | operator-(const QQuaternion &quaternion)
QQuaternion | operator-(const QQuaternion &q1, const QQuaternion &q2)
QQuaternion | operator/(const QQuaternion &quaternion, float divisor)
QDataStream & | operator<<(QDataStream &stream, const QQuaternion &quaternion)
bool | operator==(const QQuaternion &q1, const QQuaternion &q2)
QDataStream & | operator>>(QDataStream &stream, QQuaternion &quaternion)

## Detailed Description

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.

## Member Function Documentation

### `[constexpr noexcept]` QQuaternion::QQuaternion()

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

### `[explicit constexpr noexcept]` QQuaternion::QQuaternion(const QVector4D &vector)

Constructs a quaternion from the components of vector.

### `[constexpr noexcept]` QQuaternion::QQuaternion(float scalar, const QVector3D &vector)

Constructs a quaternion vector from the specified vector and scalar.

See also vector() and scalar().

### `[constexpr noexcept]` QQuaternion::QQuaternion(float scalar, float xpos, float ypos, float zpos)

Constructs a quaternion with the vector (xpos, ypos, zpos) and scalar.

### `[constexpr noexcept]` QQuaternion QQuaternion::conjugated() const

Returns the conjugate of this quaternion, which is (-x, -y, -z, scalar).

### `[static constexpr noexcept]` float QQuaternion::dotProduct(const QQuaternion &q1, const QQuaternion &q2)

Returns the dot product of q1 and q2.

See also length().

### `[static]` QQuaternion QQuaternion::fromAxes(const QVector3D &xAxis, const QVector3D &yAxis, const QVector3D &zAxis)

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

Note: The axes are assumed to be orthonormal.

See also getAxes() and fromRotationMatrix().

### `[static]` QQuaternion QQuaternion::fromAxisAndAngle(const QVector3D &axis, float angle)

Creates a normalized quaternion that corresponds to rotating through angle degrees about the specified 3D axis.

See also getAxisAndAngle().

### `[static]` QQuaternion QQuaternion::fromAxisAndAngle(float x, float y, float z, float angle)

Creates a normalized quaternion that corresponds to rotating through angle degrees about the 3D axis (x, y, z).

See also getAxisAndAngle().

### `[static]` QQuaternion QQuaternion::fromDirection(const QVector3D &direction, const QVector3D &up)

Constructs the quaternion using specified forward direction direction and upward direction up. If the upward direction was not specified or the forward and upward vectors are collinear, a new orthonormal upward direction will be generated.

See also fromAxes() and rotationTo().

### `[static]` QQuaternion QQuaternion::fromEulerAngles(float pitch, float yaw, float roll)

Creates a quaternion that corresponds to a rotation of roll degrees around the z axis, pitch degrees around the x axis, and yaw degrees around the y axis (in that order).

See also getEulerAngles().

### `[static]` QQuaternion QQuaternion::fromEulerAngles(const QVector3D &angles)

Creates a quaternion that corresponds to a rotation of angles: angles.z() degrees around the z axis, angles.x() degrees around the x axis, and angles.y() degrees around the y axis (in that order).

This is an overloaded function.

See also toEulerAngles().

### `[static]` QQuaternion QQuaternion::fromRotationMatrix(const QMatrix3x3 &rot3x3)

Creates a quaternion that corresponds to the rotation matrix rot3x3.

Note: If the given rotation matrix is not normalized, the resulting quaternion will contain scaling information.

See also toRotationMatrix() and fromAxes().

### void QQuaternion::getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis) const

Returns the 3 orthonormal axes (xAxis, yAxis, zAxis) defining the quaternion.

All of xAxis, yAxis, and zAxis must be valid, non-`nullptr` pointers, otherwise the behavior is undefined.

See also fromAxes() and toRotationMatrix().

### void QQuaternion::getAxisAndAngle(float *x, float *y, float *z, float *angle) const

Extracts a 3D axis (x, y, z) and a rotating angle angle (in degrees) that corresponds to this quaternion.

All of x, y, z, and angle must be valid, non-`nullptr` pointers, otherwise the behavior is undefined.

See also fromAxisAndAngle().

### void QQuaternion::getAxisAndAngle(QVector3D *axis, float *angle) const

Extracts a 3D axis axis and a rotating angle angle (in degrees) that corresponds to this quaternion.

Both axis and angle must be valid, non-`nullptr` pointers, otherwise the behavior is undefined.

This is an overloaded function.

See also fromAxisAndAngle().

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

Calculates roll, pitch, and yaw Euler angles (in degrees) that corresponds to this quaternion.

All of pitch, yaw, and roll must be valid, non-`nullptr` pointers, otherwise the behavior is undefined.

See also fromEulerAngles().

### `[constexpr noexcept]` QQuaternion QQuaternion::inverted() const

Returns the inverse of this quaternion. If this quaternion is null, then a null quaternion is returned.

See also isNull() and length().

### `[constexpr noexcept]` bool QQuaternion::isIdentity() const

Returns `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 `false`.

### `[constexpr noexcept]` bool QQuaternion::isNull() const

Returns `true` if the x, y, z, and scalar components of this quaternion are set to 0.0; otherwise returns `false`.

### float QQuaternion::length() const

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

See also lengthSquared(), normalized(), and dotProduct().

### float QQuaternion::lengthSquared() const

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.

See also length() and dotProduct().

### `[static]` QQuaternion QQuaternion::nlerp(const QQuaternion &q1, const QQuaternion &q2, float t)

Interpolates along the shortest linear path between the rotational positions q1 and q2. The value t should be between 0 and 1, indicating the distance to travel between q1 and q2. The result will be normalized().

If t is less than or equal to 0, then q1 will be returned. If t is greater than or equal to 1, then 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.

See also slerp().

### void QQuaternion::normalize()

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.

See also length() and normalized().

### QQuaternion QQuaternion::normalized() const

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.

See also normalize(), length(), and dotProduct().

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

Rotates vector with this quaternion to produce a new vector in 3D space. The following code:

     QVector3D result = q.rotatedVector(vector);

is equivalent to the following:

     QVector3D result = (q * QQuaternion(0, vector) * q.conjugated()).vector();

### `[static]` QQuaternion QQuaternion::rotationTo(const QVector3D &from, const QVector3D &to)

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

See also fromDirection().

### `[constexpr noexcept]` float QQuaternion::scalar() const

Returns the scalar component of this quaternion.

See also setScalar(), x(), y(), and z().

### `[constexpr noexcept]` void QQuaternion::setScalar(float scalar)

Sets the scalar component of this quaternion to scalar.

See also scalar(), setX(), setY(), and setZ().

### `[constexpr noexcept]` void QQuaternion::setVector(const QVector3D &vector)

Sets the vector component of this quaternion to vector.

See also vector() and setScalar().

### `[constexpr noexcept]` void QQuaternion::setVector(float x, float y, float z)

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

See also vector() and setScalar().

### `[constexpr noexcept]` void QQuaternion::setX(float x)

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

See also x(), setY(), setZ(), and setScalar().

### `[constexpr noexcept]` void QQuaternion::setY(float y)

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

See also y(), setX(), setZ(), and setScalar().

### `[constexpr noexcept]` void QQuaternion::setZ(float z)

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

See also z(), setX(), setY(), and setScalar().

### `[static]` QQuaternion QQuaternion::slerp(const QQuaternion &q1, const QQuaternion &q2, float t)

Interpolates along the shortest spherical path between the rotational positions q1 and q2. The value t should be between 0 and 1, indicating the spherical distance to travel between q1 and q2.

If t is less than or equal to 0, then q1 will be returned. If t is greater than or equal to 1, then q2 will be returned.

See also nlerp().

### QVector3D QQuaternion::toEulerAngles() const

Calculates roll, pitch, and yaw Euler angles (in degrees) that correspond to this quaternion.

See also fromEulerAngles().

### QMatrix3x3 QQuaternion::toRotationMatrix() const

Creates a rotation matrix that corresponds to this quaternion.

Note: If this quaternion is not normalized, the resulting rotation matrix will contain scaling information.

See also fromRotationMatrix() and getAxes().

### `[constexpr noexcept]` QVector4D QQuaternion::toVector4D() const

Returns this quaternion as a 4D vector.

### `[constexpr noexcept]` QVector3D QQuaternion::vector() const

Returns the vector component of this quaternion.

See also setVector() and scalar().

### `[constexpr noexcept]` float QQuaternion::x() const

Returns the x coordinate of this quaternion's vector.

See also setX(), y(), z(), and scalar().

### `[constexpr noexcept]` float QQuaternion::y() const

Returns the y coordinate of this quaternion's vector.

See also setY(), x(), z(), and scalar().

### `[constexpr noexcept]` float QQuaternion::z() const

Returns the z coordinate of this quaternion's vector.

See also setZ(), x(), y(), and scalar().

### QVariant QQuaternion::operator QVariant() const

Returns the quaternion as a QVariant.

### `[constexpr noexcept]` QQuaternion &QQuaternion::operator*=(const QQuaternion &quaternion)

Multiplies this quaternion by quaternion and returns a reference to this quaternion.

### `[constexpr noexcept]` QQuaternion &QQuaternion::operator*=(float factor)

Multiplies this quaternion's components by the given factor, and returns a reference to this quaternion.

See also operator/=().

### `[constexpr noexcept]` QQuaternion &QQuaternion::operator+=(const QQuaternion &quaternion)

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

See also operator-=().

### `[constexpr noexcept]` QQuaternion &QQuaternion::operator-=(const QQuaternion &quaternion)

Subtracts the given quaternion from this quaternion and returns a reference to this quaternion.

See also operator+=().

### `[constexpr]` QQuaternion &QQuaternion::operator/=(float divisor)

Divides this quaternion's components by the given divisor, and returns a reference to this quaternion.

See also operator*=().

## Related Non-Members

### `[constexpr noexcept]` bool qFuzzyCompare(const QQuaternion &q1, const QQuaternion &q2)

Returns `true` if q1 and q2 are equal, allowing for a small fuzziness factor for floating-point comparisons; false otherwise.

### `[constexpr noexcept]` bool operator!=(const QQuaternion &q1, const QQuaternion &q2)

Returns `true` if q1 is not equal to q2; otherwise returns `false`. This operator uses an exact floating-point comparison.

### `[constexpr noexcept]` QQuaternion operator*(const QQuaternion &q1, const QQuaternion &q2)

Multiplies q1 and q2 using quaternion multiplication. The result corresponds to applying both of the rotations specified by q1 and q2.

See also QQuaternion::operator*=().

### QVector3D operator*(const QQuaternion &quaternion, const QVector3D &vec)

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

### `[constexpr noexcept]` QQuaternion operator*(const QQuaternion &quaternion, float factor)

Returns a copy of the given quaternion, multiplied by the given factor.

See also QQuaternion::operator*=().

### `[constexpr noexcept]` QQuaternion operator*(float factor, const QQuaternion &quaternion)

Returns a copy of the given quaternion, multiplied by the given factor.

See also QQuaternion::operator*=().

### `[constexpr noexcept]` QQuaternion operator+(const QQuaternion &q1, const QQuaternion &q2)

Returns a QQuaternion object that is the sum of the given quaternions, q1 and q2; each component is added separately.

See also QQuaternion::operator+=().

### `[constexpr noexcept]` QQuaternion operator-(const QQuaternion &quaternion)

Returns a QQuaternion object that is formed by changing the sign of all three components of the given quaternion.

Equivalent to `QQuaternion(0,0,0,0) - quaternion`.

This is an overloaded function.

### `[constexpr noexcept]` QQuaternion operator-(const QQuaternion &q1, const QQuaternion &q2)

Returns a QQuaternion object that is formed by subtracting q2 from q1; each component is subtracted separately.

See also QQuaternion::operator-=().

### `[constexpr]` QQuaternion operator/(const QQuaternion &quaternion, float divisor)

Returns the QQuaternion object formed by dividing all components of the given quaternion by the given divisor.

See also QQuaternion::operator/=().

### QDataStream &operator<<(QDataStream &stream, const QQuaternion &quaternion)

Writes the given quaternion to the given stream and returns a reference to the stream.

See also Serializing Qt Data Types.

### `[constexpr noexcept]` bool operator==(const QQuaternion &q1, const QQuaternion &q2)

Returns `true` if q1 is equal to q2; otherwise returns `false`. This operator uses an exact floating-point comparison.

### QDataStream &operator>>(QDataStream &stream, QQuaternion &quaternion)

Reads a quaternion from the given stream into the given quaternion and returns a reference to the stream.

See also Serializing Qt Data Types.