diff --git a/doc/snippets/MagnumMath.cpp b/doc/snippets/MagnumMath.cpp index 7de1317bc..fdfb1ff6c 100644 --- a/doc/snippets/MagnumMath.cpp +++ b/doc/snippets/MagnumMath.cpp @@ -1105,6 +1105,15 @@ Quaternion a = static_cast(a); } +{ +/* [Quaternion-axis-nan] */ +Quaternion a = DOXYGEN_ELLIPSIS({}); +Rad angle = a.angle(); +Vector3 axis = angle == 0.0_radf ? Vector3::xAxis() : a.axis(); +/* [Quaternion-axis-nan] */ +static_cast(axis); +} + { /* [unpack-template-explicit] */ // Literal type is (signed) char, but we assumed unsigned char, a != 1.0f diff --git a/src/Magnum/Math/Quaternion.h b/src/Magnum/Math/Quaternion.h index 042bae3f6..ae90afea1 100644 --- a/src/Magnum/Math/Quaternion.h +++ b/src/Magnum/Math/Quaternion.h @@ -435,12 +435,20 @@ template class Quaternion { /** * @brief Rotation axis of a unit quaternion * - * Expects that the quaternion is normalized. Returns either unit-length - * vector for valid rotation quaternion or NaN vector for - * default-constructed quaternion. @f[ + * Expects that the quaternion is normalized. @f[ * \boldsymbol a = \frac{\boldsymbol q_V}{\sqrt{1 - q_S^2}} * @f] - * @see @ref isNormalized(), @ref angle(), @ref rotation() + * + * If the @ref angle() is zero, the returned axis is a NaN vector, + * indicating that the axis is arbitrary. In other words, rotating + * by a zero angle around any axis will always give back a + * @f$ [\boldsymbol 0, 1] @f$ quaternion. To always get a unit vector + * back, you do the following, replace it with an X axis for a zero + * angle: + * + * @snippet MagnumMath.cpp Quaternion-axis-nan + * + * @see @ref isNormalized(), @ref rotation() */ Vector3 axis() const;