Stub documentation for transformation interpolation and animation.

doc/animation.dox

@@ -0,0 +1,48 @@
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018
+              Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+namespace Magnum {
+
+/** @page animation Keyframe-based animation
+@brief Layered framework for authoring, loading, optimizing and playing back animations
+
+@tableofcontents
+@m_footernavigation
+
+Sorry, this page is yet to be written. Please see the @ref Animation namespace,
+especially documentation of the lowest-level @ref Animation::interpolate()
+function, the higher-level @ref Animation::Track class and the top-level
+@ref Animation::Player API. The @ref transformations-interpolation
+documentation lists all available builtin interpolation methods.
+
+@experimental
+
+@todoc bottom-up description (interpolating values, keyframes, storing, at(), player, callbacks)
+@todoc perf optimizations (shortest path, preprocessing..., extrapolation, ...), batchplayer
+@todoc mention animation import
+
+*/
+
+}

doc/features.dox

@@ -35,6 +35,7 @@ necessary to read through everything, pick only what you need.
 -   @subpage types --- @copybrief types
 -   @subpage matrix-vector --- @copybrief matrix-vector
 -   @subpage transformations --- @copybrief transformations
+-   @subpage animation --- @copybrief animation
 -   @subpage plugins --- @copybrief plugins
 -   @subpage opengl-wrapping --- @copybrief opengl-wrapping
 -   @subpage shaders --- @copybrief shaders

doc/namespaces.dox

@@ -186,8 +186,8 @@ See @ref building and @ref cmake for more information.
 @brief Keyframe-based animation
 
 This library is built as part of Magnum by default. To use it, you need to
-find `Magnum` package and link to `Magnum::Magnum` target. See @ref building
-and @ref cmake for more information.
+find `Magnum` package and link to `Magnum::Magnum` target. See @ref building,
+@ref cmake and @ref animation for more information.
 @experimental
 */
 

doc/transformations.dox

@@ -243,8 +243,45 @@ and translation matrices using @ref DualComplex::fromMatrix() and
 
 @section transformations-interpolation Transformation interpolation
 
-@todoc Write this when interpolation is done also for (dual) complex numbers and
-    dual quaternions
+Magnum provides various tools for interpolation, from basic constant/linear
+interpolation of scalars and vectors to spline-based interpolation of
+quaternions or dual quaternions. The table below is a complete list of all
+builtin interpolation methods:
+
+@m_class{m-fullwidth}
+
+Interpolation       | Value type        | Result type   | Interpolator
+------------------- | ----------------- | ------------- | ------------
+Constant            | any `V`           | `V`           | @ref Math::select()
+Constant | @ref Math::CubicHermite "Math::CubicHermite<T>" | `T` | @ref Math::select(const CubicHermite<T>&, const CubicHermite<T>&, U) "Math::select()"
+Linear  | @cpp bool @ce <b></b> | @cpp bool @ce <b></b> | @ref Math::select()
+Linear  | @ref Math::BoolVector | @ref Math::BoolVector | @ref Math::select()
+Linear              | any scalar `V`    | `V`           | @ref Math::lerp()
+Linear              | any vector `V`    | `V`           | @ref Math::lerp()
+Linear              | @ref Math::Complex | @ref Math::Complex | @ref Math::lerp(const Complex<T>&, const Complex<T>&, T) "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()"
+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()"
+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()"
+Spline | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::splerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T) "Math::splerp()"
+
+The @ref Math::CubicHermite class is a generic implementation of cubic Hermite
+splines to which other curve types such as Bézier are convertible. See its
+documentation for more information.
+
+@attention Direct interpolation of transformation matrices or Euler angles is
+    not supported due to their well known performance / correctness issues and
+    limitations such as gimbal lock --- you have to convert them to one of the
+    supported representations such as @ref Complex numbers or @ref Quaternion
+    and interpolate these instead.
+
+Interpolation is most commonly used in animations --- see @ref animation for
+more information.
 
 @section transformations-normalization Normalizing transformations
 

src/Magnum/Animation/Interpolation.h

@@ -120,8 +120,7 @@ Interpolation       | Value type        | Result type   | Interpolator
 @ref Interpolation::Spline "Spline" | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::splerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T) "Math::splerp()"
 
 @see @ref interpolate(), @ref interpolateStrict(),
-    @ref Animation-Track-interpolators "Track types and interpolators",
-    @ref Trade::animationInterpolatorFor()
+    @ref transformations-interpolation, @ref Trade::animationInterpolatorFor()
 @experimental
 */
 template<class V, class R = ResultOf<V>> auto interpolatorFor(Interpolation interpolation) -> R(*)(const V&, const V&, Float);

src/Magnum/Animation/Track.h

@@ -55,37 +55,18 @@ interpolator function and extrapolation behavior.
 
 @section Animation-Track-interpolators Types and interpolators
 
-The track supports arbitrary types for keys, values and interpolators. These
-are common combinations:
-
-@m_class{m-fullwidth}
-
-Interpolation       | Value type        | Result type   | Interpolator
-------------------- | ----------------- | ------------- | ------------
-Constant            | any `V`           | `V`           | @ref Math::select()
-Constant | @ref Math::CubicHermite "Math::CubicHermite<T>" | `T` | @ref Math::select(const CubicHermite<T>&, const CubicHermite<T>&, U) "Math::select()"
-Linear  | @cpp bool @ce <b></b> | @cpp bool @ce <b></b> | @ref Math::select()
-Linear  | @ref Math::BoolVector | @ref Math::BoolVector | @ref Math::select()
-Linear              | any scalar `V`    | `V`           | @ref Math::lerp()
-Linear              | any vector `V`    | `V`           | @ref Math::lerp()
-Linear              | @ref Math::Complex | @ref Math::Complex | @ref Math::lerp(const Complex<T>&, const Complex<T>&, T) "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()"
-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()"
-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()"
-Spline | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::splerp(const CubicHermiteQuaternion<T>&, const CubicHermiteQuaternion<T>&, T) "Math::splerp()"
-
-It's also possible to supply a generic interpolation behavior by passing the
-@ref Interpolation enum to the constructor. In case the interpolator function
-is not passed in as well, it's autodetected using @ref interpolatorFor(). See
-its documentation for more information. The @ref Interpolation enum is then
-stored in @ref interpolation() and acts as a hint for desired interpolation
-behavior for users who might want to use their own interpolator.
+The track supports arbitrary types for keys, values and interpolators. See
+@ref transformations-interpolation for an overview of builtin interpolation
+functions.
+
+Besides directly specifying an interpolator function as shown in the above
+snippet, it's also possible to supply a generic interpolation behavior by
+passing the @ref Interpolation enum to the constructor. In case the
+interpolator function is not passed in as well, it's autodetected using
+@ref interpolatorFor(). See its documentation for more information. The
+@ref Interpolation enum is then stored in @ref interpolation() and acts as a
+hint for desired interpolation behavior for users who might want to use their
+own interpolator.
 
 @section Animation-Track-performance Performance tuning