diff --git a/doc/animation.dox b/doc/animation.dox new file mode 100644 index 000000000..e8562c635 --- /dev/null +++ b/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š + + 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 + +*/ + +} diff --git a/doc/features.dox b/doc/features.dox index 6832b64e2..22177f8df 100644 --- a/doc/features.dox +++ b/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 diff --git a/doc/namespaces.dox b/doc/namespaces.dox index 0787f4ca6..9445476d1 100644 --- a/doc/namespaces.dox +++ b/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 */ diff --git a/doc/transformations.dox b/doc/transformations.dox index 6bbb253b2..ebf276b2d 100644 --- a/doc/transformations.dox +++ b/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` | @ref Math::select(const CubicHermite&, const CubicHermite&, U) "Math::select()" +Linear | @cpp bool @ce | @cpp bool @ce | @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&, const Complex&, T) "Math::lerp()" +Linear | @ref Math::Quaternion | @ref Math::Quaternion | @ref Math::lerp(const Quaternion&, const Quaternion&, T) "Math::lerp()", \n @ref Math::lerpShortestPath(const Quaternion&, const Quaternion&, T) "Math::lerpShortestPath()" +Linear | @ref Math::CubicHermite "Math::CubicHermite" | `T` | @ref Math::lerp(const CubicHermite&, const CubicHermite&, U) "Math::lerp()" +Linear | @ref Math::CubicHermiteComplex | @ref Math::Complex | @ref Math::lerp(const CubicHermiteComplex&, const CubicHermiteComplex&, T) "Math::lerp()" +Linear | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::lerp(const CubicHermiteQuaternion&, const CubicHermiteQuaternion&, T) "Math::lerp()" +Spherical linear | @ref Math::Complex | @ref Math::Complex | @ref Math::slerp(const Complex&, const Complex&, T) "Math::slerp()" +Spherical linear | @ref Math::Quaternion | @ref Math::Quaternion | @ref Math::slerp(const Quaternion&, const Quaternion&, T) "Math::slerp()", \n @ref Math::slerpShortestPath(const Quaternion&, const Quaternion&, T) "Math::slerpShortestPath()" +Screw linear | @ref Math::DualQuaternion | @ref Math::DualQuaternion | @ref Math::sclerp(const DualQuaternion&, const DualQuaternion&, T) "Math::sclerp()", \n @ref Math::sclerpShortestPath(const DualQuaternion&, const DualQuaternion&, T) "Math::sclerpShortestPath()" +Spline | @ref Math::CubicHermite "Math::CubicHermite" | `T` | @ref Math::splerp(const CubicHermite&, const CubicHermite&, U) "Math::splerp()" +Spline | @ref Math::CubicHermiteComplex | @ref Math::Complex | @ref Math::splerp(const CubicHermiteComplex&, const CubicHermiteComplex&, T) "Math::splerp()" +Spline | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::splerp(const CubicHermiteQuaternion&, const CubicHermiteQuaternion&, 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 diff --git a/src/Magnum/Animation/Interpolation.h b/src/Magnum/Animation/Interpolation.h index 3261bf3bf..d93195717 100644 --- a/src/Magnum/Animation/Interpolation.h +++ b/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&, const CubicHermiteQuaternion&, 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> auto interpolatorFor(Interpolation interpolation) -> R(*)(const V&, const V&, Float); diff --git a/src/Magnum/Animation/Track.h b/src/Magnum/Animation/Track.h index 3d0866dea..c5dc55308 100644 --- a/src/Magnum/Animation/Track.h +++ b/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` | @ref Math::select(const CubicHermite&, const CubicHermite&, U) "Math::select()" -Linear | @cpp bool @ce | @cpp bool @ce | @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&, const Complex&, T) "Math::lerp()" -Linear | @ref Math::Quaternion | @ref Math::Quaternion | @ref Math::lerp(const Quaternion&, const Quaternion&, T) "Math::lerp()", \n @ref Math::lerpShortestPath(const Quaternion&, const Quaternion&, T) "Math::lerpShortestPath()" -Linear | @ref Math::CubicHermite "Math::CubicHermite" | `T` | @ref Math::lerp(const CubicHermite&, const CubicHermite&, U) "Math::lerp()" -Linear | @ref Math::CubicHermiteComplex | @ref Math::Complex | @ref Math::lerp(const CubicHermiteComplex&, const CubicHermiteComplex&, T) "Math::lerp()" -Linear | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::lerp(const CubicHermiteQuaternion&, const CubicHermiteQuaternion&, T) "Math::lerp()" -Spherical linear | @ref Math::Complex | @ref Math::Complex | @ref Math::slerp(const Complex&, const Complex&, T) "Math::slerp()" -Spherical linear | @ref Math::Quaternion | @ref Math::Quaternion | @ref Math::slerp(const Quaternion&, const Quaternion&, T) "Math::slerp()", \n @ref Math::slerpShortestPath(const Quaternion&, const Quaternion&, T) "Math::slerpShortestPath()" -Screw linear | @ref Math::DualQuaternion | @ref Math::DualQuaternion | @ref Math::sclerp(const DualQuaternion&, const DualQuaternion&, T) "Math::sclerp()", \n @ref Math::sclerpShortestPath(const DualQuaternion&, const DualQuaternion&, T) "Math::sclerpShortestPath()" -Spline | @ref Math::CubicHermite "Math::CubicHermite" | `T` | @ref Math::splerp(const CubicHermite&, const CubicHermite&, U) "Math::splerp()" -Spline | @ref Math::CubicHermiteComplex | @ref Math::Complex | @ref Math::splerp(const CubicHermiteComplex&, const CubicHermiteComplex&, T) "Math::splerp()" -Spline | @ref Math::CubicHermiteQuaternion | @ref Math::Quaternion | @ref Math::splerp(const CubicHermiteQuaternion&, const CubicHermiteQuaternion&, 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