Math: added missing CubicHermite [s]lerp[ShortestPath]() overloads.

mosra · Sep 6, 2018 · 523c167 · 523c167
1 parent dfcd33f
commit 523c167
Show file tree

Hide file tree

Showing 4 changed files with 276 additions and 9 deletions.
diff --git a/doc/transformations.dox b/doc/transformations.dox
@@ -263,9 +263,11 @@ Linear              | @ref Math::Complex | @ref Math::Complex | @ref Math::lerp(
 Linear              | @ref Math::Quaternion | @ref Math::Quaternion | @ref Math::lerp(const Quaternion<T>&, const Quaternion<T>&, T) "Math::lerp()", \n @ref Math::lerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T) "Math::lerpShortestPath()"
 Linear | @ref Math::CubicHermite "Math::CubicHermite<T>" | `T` | @ref Math::lerp(const CubicHermite<T>&, const CubicHermite<T>&, U) "Math::lerp()"
 Linear | @ref Math::CubicHermiteComplex | @ref Math::Complex | @ref Math::lerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T) "Math::lerp()"
-Linear | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::lerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T) "Math::lerp()"
+Linear | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::lerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T) "Math::lerp()", \n @ref Math::lerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T) "Math::lerpShortestPath()"
 Spherical linear    | @ref Math::Complex | @ref Math::Complex | @ref Math::slerp(const Complex<T>&, const Complex<T>&, T) "Math::slerp()"
 Spherical linear    | @ref Math::Quaternion | @ref Math::Quaternion | @ref Math::slerp(const Quaternion<T>&, const Quaternion<T>&, T) "Math::slerp()", \n @ref Math::slerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T) "Math::slerpShortestPath()"
+Spherical linear    | @ref Math::CubicHermiteComplex | @ref Math::Complex | @ref Math::slerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T) "Math::slerp()"
+Spherical linear    | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::slerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T) "Math::slerp()", \n @ref Math::slerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T) "Math::slerpShortestPath()"
 Screw linear        | @ref Math::DualQuaternion | @ref Math::DualQuaternion | @ref Math::sclerp(const DualQuaternion<T>&, const DualQuaternion<T>&, T) "Math::sclerp()", \n @ref Math::sclerpShortestPath(const DualQuaternion<T>&, const DualQuaternion<T>&, T) "Math::sclerpShortestPath()"
 Spline | @ref Math::CubicHermite "Math::CubicHermite<T>" | `T` | @ref Math::splerp(const CubicHermite<T>&, const CubicHermite<T>&, U) "Math::splerp()"
 Spline | @ref Math::CubicHermiteComplex | @ref Math::Complex | @ref Math::splerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T) "Math::splerp()"

diff --git a/src/Magnum/Math/CubicHermite.h b/src/Magnum/Math/CubicHermite.h
@@ -316,6 +316,10 @@ Equivalent to calling @ref lerp(const T&, const T&, U) on
 @ref CubicHermite::point() extracted from both @p a and @p b.
 @see @ref lerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T),
     @ref lerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
+    @ref lerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
+    @ref slerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T),
+    @ref slerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
+    @ref slerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
     @ref select(const CubicHermite<T>&, const CubicHermite<T>&, U),
     @ref splerp(const CubicHermite<T>&, const CubicHermite<T>&, U),
     @ref splerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T),
@@ -337,6 +341,7 @@ normalized complex number in both @p a and @p b.
 @see @ref Complex::isNormalized(),
     @ref lerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
     @ref select(const CubicHermite<T>&, const CubicHermite<T>&, U),
+    @ref slerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T),
     @ref splerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T)
 */
 template<class T> Complex<T> lerp(const CubicHermiteComplex<T>& a, const CubicHermiteComplex<T>& b, T t) {
@@ -352,14 +357,86 @@ on @ref CubicHermite::point() extracted from @p a and @p b. Compared to
 normalization step after. Expects that @ref CubicHermite::point() is a
 normalized quaternion in both @p a and @p b.
 @see @ref Quaternion::isNormalized(),
+    @ref lerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
     @ref lerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T),
     @ref select(const CubicHermite<T>&, const CubicHermite<T>&, U),
+    @ref slerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
     @ref splerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
 */
 template<class T> Quaternion<T> lerp(const CubicHermiteQuaternion<T>& a, const CubicHermiteQuaternion<T>& b, T t) {
     return lerp(a.point(), b.point(), t);
 }
 
+/** @relatesalso CubicHermite
+@brief Linear shortest-path interpolation of two cubic Hermite quaternions
+
+Equivalent to calling @ref lerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T)
+on @ref CubicHermite::point() extracted from @p a and @p b. Expects that
+@ref CubicHermite::point() is a normalized quaternion in both @p a and @p b.
+
+Note that rotations interpolated with this function may go along a completely
+different path compared to @ref splerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T).
+Use @ref lerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
+for behavior that is consistent with spline interpolation.
+@see @ref Quaternion::isNormalized(),
+    @ref slerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
+*/
+template<class T> Quaternion<T> lerpShortestPath(const CubicHermiteQuaternion<T>& a, const CubicHermiteQuaternion<T>& b, T t) {
+    return lerpShortestPath(a.point(), b.point(), t);
+}
+
+/** @relatesalso CubicHermite
+@brief Spherical linear interpolation of two cubic Hermite complex numbers
+
+Equivalent to calling @ref slerp(const Complex<T>&, const Complex<T>&, T) on
+@ref CubicHermite::point() extracted from @p a and @p b. Expects that
+@ref CubicHermite::point() is a normalized complex number in both @p a and @p b.
+@see @ref Complex::isNormalized(),
+    @ref slerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
+    @ref select(const CubicHermite<T>&, const CubicHermite<T>&, U),
+    @ref lerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T),
+    @ref splerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T)
+ */
+template<class T> inline Complex<T> slerp(const CubicHermiteComplex<T>& a, const CubicHermiteComplex<T>& b, T t) {
+    return slerp(a.point(), b.point(), t);
+}
+
+/** @relatesalso CubicHermite
+@brief Spherical linear interpolation of two cubic Hermite quaternions
+
+Equivalent to calling @ref slerp(const Quaternion<T>&, const Quaternion<T>&, T)
+on @ref CubicHermite::point() extracted from @p a and @p b. Expects that
+@ref CubicHermite::point() is a normalized complex number in both @p a and @p b.
+@see @ref Quaternion::isNormalized(),
+    @ref slerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
+    @ref slerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T),
+    @ref select(const CubicHermite<T>&, const CubicHermite<T>&, U),
+    @ref lerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
+    @ref splerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
+ */
+template<class T> inline Quaternion<T> slerp(const CubicHermiteQuaternion<T>& a, const CubicHermiteQuaternion<T>& b, T t) {
+    return slerp(a.point(), b.point(), t);
+}
+
+/** @relatesalso CubicHermite
+@brief Spherical linear shortest-path interpolation of two cubic Hermite quaternions
+
+Equivalent to calling @ref slerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T)
+on @ref CubicHermite::point() extracted from @p a and @p b. Expects that
+@ref CubicHermite::point() is a normalized quaternion in both @p a and @p b.
+
+Note that rotations interpolated with this function may go along a completely
+different path compared to @ref splerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T).
+Use @ref slerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
+for spherical linear interpolation with behavior that is consistent with spline
+interpolation.
+@see @ref Quaternion::isNormalized(),
+    @ref lerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
+*/
+template<class T> Quaternion<T> slerpShortestPath(const CubicHermiteQuaternion<T>& a, const CubicHermiteQuaternion<T>& b, T t) {
+    return slerpShortestPath(a.point(), b.point(), t);
+}
+
 /** @relatesalso CubicHermite
 @brief Spline interpolation of two cubic Hermite points
 @param a     First spline point
@@ -402,7 +479,8 @@ Expects that @ref CubicHermite::point() is a normalized complex number in both
 @see @ref Complex::isNormalized(),
     @ref splerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
     @ref select(const CubicHermite<T>&, const CubicHermite<T>&, U),
-    @ref lerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T)
+    @ref lerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T),
+    @ref slerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T)
 */
 template<class T> Complex<T> splerp(const CubicHermiteComplex<T>& a, const CubicHermiteComplex<T>& b, T t) {
     CORRADE_ASSERT(a.point().isNormalized() && b.point().isNormalized(),
@@ -431,7 +509,8 @@ and @p b.
 @see @ref Quaternion::isNormalized(),
     @ref splerp(const CubicHermiteComplex<T>&, const CubicHermiteComplex<T>&, T),
     @ref select(const CubicHermite<T>&, const CubicHermite<T>&, U),
-    @ref lerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
+    @ref lerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
+    @ref slerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
 */
 template<class T> Quaternion<T> splerp(const CubicHermiteQuaternion<T>& a, const CubicHermiteQuaternion<T>& b, T t) {
     CORRADE_ASSERT(a.point().isNormalized() && b.point().isNormalized(),

diff --git a/src/Magnum/Math/Quaternion.h b/src/Magnum/Math/Quaternion.h
@@ -89,7 +89,8 @@ Expects that both quaternions are normalized. @f[
 @f]
 
 Note that this function does not check for shortest path interpolation, see
-@ref lerpShortestPath() for an alternative.
+@ref lerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T) for an
+alternative.
 @see @ref Quaternion::isNormalized(),
     @ref slerp(const Quaternion<T>&, const Quaternion<T>&, T), @ref sclerp(),
     @ref lerp(const T&, const T&, U),
@@ -122,7 +123,9 @@ both quaternions are normalized. @f[
         q_{LERP} & = & \cfrac{(1 - t) q'_A + t q_B}{|(1 - t) q'_A + t q_B|}
     \end{array}
 @f]
-@see @ref Quaternion::isNormalized(), @ref slerpShortestPath(),
+@see @ref Quaternion::isNormalized(),
+    @ref slerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T),
+    @ref lerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
     @ref sclerpShortestPath()
 */
 template<class T> inline Quaternion<T> lerpShortestPath(const Quaternion<T>& normalizedA, const Quaternion<T>& normalizedB, T t) {
@@ -153,9 +156,11 @@ otherwise, the interpolation is performed as: @f[
 @f]
 
 Note that this function does not check for shortest path interpolation, see
-@ref slerpShortestPath() for an alternative.
+@ref slerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T) for an
+alternative.
 @see @ref Quaternion::isNormalized(), @ref lerp(const Quaternion<T>&, const Quaternion<T>&, T),
-    @ref slerp(const Complex<T>&, const Complex<T>&, T), @ref sclerp()
+    @ref slerp(const Complex<T>&, const Complex<T>&, T), @ref sclerp(),
+    @ref slerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T)
 */
 template<class T> inline Quaternion<T> slerp(const Quaternion<T>& normalizedA, const Quaternion<T>& normalizedB, T t) {
     CORRADE_ASSERT(normalizedA.isNormalized() && normalizedB.isNormalized(),
@@ -198,8 +203,10 @@ otherwise, the interpolation is performed as: @f[
         q_{SLERP} & = & \cfrac{\sin((1 - t) \theta) q'_A + \sin(t \theta) q_B}{\sin(\theta)}
     \end{array}
 @f]
-@see @ref Quaternion::isNormalized(), @ref lerpShortestPath(),
-        @ref sclerpShortestPath()
+@see @ref Quaternion::isNormalized(),
+    @ref lerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T),
+    @ref slerpShortestPath(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T),
+    @ref sclerpShortestPath()
 */
 template<class T> inline Quaternion<T> slerpShortestPath(const Quaternion<T>& normalizedA, const Quaternion<T>& normalizedB, T t) {
     CORRADE_ASSERT(normalizedA.isNormalized() && normalizedB.isNormalized(),