From 2a9f4a1fed4a70fce486a0cc2d6ee42346a35ab3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Sat, 25 May 2019 03:18:38 +0200
Subject: [PATCH] Math: hint that lerpInverted() can be used for rane mapping.

---
 doc/snippets/MagnumMath.cpp | 12 ++++++++++++
 src/Magnum/Math/Functions.h | 10 +++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/doc/snippets/MagnumMath.cpp b/doc/snippets/MagnumMath.cpp
index 41ccf9c5a..4c31392fc 100644
--- a/doc/snippets/MagnumMath.cpp
+++ b/doc/snippets/MagnumMath.cpp
@@ -912,6 +912,18 @@ Math::min(Math::max(value, min), max)
 ;
 }
 
+{
+Float a{};
+/* [lerpInverted-map] */
+Deg b = Math::lerp(5.0_degf, 15.0_degf,
+    Math::lerpInverted(-1.0f, 1.0f, a));
+Deg bClamped = Math::lerp(5.0_degf, 15.0_degf, Math::clamp(
+    Math::lerpInverted(-1.0f, 1.0f, a), 0.0f, 1.0f));
+/* [lerpInverted-map] */
+static_cast<void>(b);
+static_cast<void>(bClamped);
+}
+
 {
 /* [Half-usage] */
 using namespace Math::Literals;
diff --git a/src/Magnum/Math/Functions.h b/src/Magnum/Math/Functions.h
index 69f65268c..8bc286dbb 100644
--- a/src/Magnum/Math/Functions.h
+++ b/src/Magnum/Math/Functions.h
@@ -437,7 +437,15 @@ template<std::size_t size> inline BoolVector<size> lerp(const BoolVector<size>&
 Returns interpolation phase *t*: @f[
     t = \frac{\boldsymbol{v_{LERP}} - \boldsymbol{v_A}}{\boldsymbol{v_B} - \boldsymbol{v_A}}
 @f]
-@see @ref lerp(), @ref select()
+
+Useful in combination with @ref lerp() for mapping values from one range to
+another --- for example, the following snippet maps `a` from a range
+@f$ [ -1; +1 ] @f$ to a range @f$ [ 5\degree; 15\degree ] @f$; the second
+expression combines that with @ref clamp() to ensure the value is in bounds:
+
+@snippet MagnumMath.cpp lerpInverted-map
+
+@see @ref select()
 */
 template<class T> inline UnderlyingTypeOf<typename std::enable_if<IsScalar<T>::value, T>::type> lerpInverted(T a, T b, T lerp) {
     return (lerp - a)/(b - a);