Drop-In Easing Module for U++ Animate() (Edit-file path)

[Trilec]

Below is the same proposal with the correct file paths and a couple of wording tweaks so nobody has to hunt for headers again.

---

Industrial Bézier Curve Engine for U++ Animation

U++ 2025.1 shipped the first Animate() helper, but it only slides a widget’s rectangle with a fixed linear timer.
This patch adds a tiny cubic-Bézier API plus a generic AnimateProperty() template so any property—position, size, colour, opacity, angle—can move with ease-in, ease-out, or a designer-supplied curve. Four doubles describe the spline; classic helpers like EaseInQuad are just wrappers. Everything is header-only, constexpr, and costs four multiplies per frame.
Cubic-Bézier timing is standard in CSS, Qt, WPF, and Flutter, evaluated with the de Casteljau algorithm.

---

1 · Minimal source changes

File	Change
Core/Util.h	Add overload: template<class T> constexpr T Lerp(const T&, const T&, double, Upp::Easing::Fn) noexcept → returns Lerp(a,b,fn(t)).
CtrlLib/CtrlUtil.h	• Extend existing builder with .Easing(Fn). • Add template <class T> void AnimateProperty(...) (timer loop + new Lerp).
CtrlLib/Easing.h (new)	Header below — Bézier factory, presets, de Casteljau, using Fn.

No .cpp files are needed; everything is inline.

---

2 · Easing.h (drop-in)

// CtrlLib/Easing.h — single-header Bézier helper (≈50 LOC)
#pragma once
#include <Core/Core.h>

namespace Upp::Easing {

using Fn = double(*)(double) noexcept;   // maps 0-1 → 0-1, must be monotone

// de Casteljau for cubic Bézier (P0=(0,0), P3=(1,1))
constexpr double DeCasteljau(double x1,double y1,double x2,double y2,double t) noexcept
{
    double u = 1.0 - t;
    double a = 3.0 * u * u * t;
    double b = 3.0 * u * t * t;
    return (a * y1) + (b * y2) + (t * t * t);   // x term cancels (P0.x=0, P3.x=1)
}

// Factory
constexpr Fn Bezier(double x1,double y1,double x2,double y2) noexcept
{
    return [=](double t) noexcept -> double { return DeCasteljau(x1,y1,x2,y2,t); };
}

// Presets (CSS / easings.net)
constexpr Fn EaseLinear     = Bezier(0.0  ,0.0  ,1.0 ,1.0 );
constexpr Fn EaseInQuad     = Bezier(0.55 ,0.085,0.68,0.53);
constexpr Fn EaseOutQuad    = Bezier(0.25 ,0.46 ,0.45,0.94);
constexpr Fn EaseInOutQuad  = Bezier(0.455,0.03 ,0.515,0.955);
constexpr Fn EaseOutBounce  = Bezier(0.68 ,-0.55,0.265,1.55); // single-segment bounce
} // namespace Upp::Easing

The curve must start (0,0) and end (1,1)—same rule as Qt QEasingCurve::BezierSpline and WPF KeySpline.

---

3 · Usage examples

using namespace Upp;
using namespace Easing;

// 1. Slide a panel with ease-in-out
Animate(panel)
    .Time(400)
    .Easing(EaseInOutQuad)
    .Pos(Rect(40,40,200,100))
    .Run();

// 2. Fade dialog opacity
AnimateProperty<double>(1.0, 0.0,
    [&](double a){ dlg.SetOpacity(a); }, 250, EaseLinear);

// 3. Pulse button colour with custom curve (CSS “ease-out-expo”)
auto expo = Bezier(0.19,1.0,0.22,1.0);
AnimateProperty<Color>(Red(), Blue(),
    [&](Color c){ btn.SetInk(c); }, 500, expo);

// 4. Rotate a knob 0°→360° with ease-out
AnimateProperty<double>(0.0, 360.0,
    [&](double d){ knob.SetAngle(d); }, 600, EaseOutQuad);

// 5. Hover bounce pop
b.WhenMouseEnter = [=]{
    Animate(b).Time(350).Easing(EaseOutBounce)
              .Pos(Rect(b.Left()-4, b.Top()-4,
                        b.GetWidth()+8, b.GetHeight()+8))
              .Run();
};
b.WhenMouseLeave = [=]{
    Animate(b).Time(200).Easing(EaseInQuad)
              .Pos(b.GetRect()).Run();
};

Everything compiles after the three tiny edits above.

---

4 · Why this matters

• Industry-standard cubic-Bézier (CSS, Qt, WPF, Flutter).
• Tiny & fast — 4 multiplies + 3 adds per frame.
• Header-only — no ABI churn, minimal footprint.
• Drop-in compatible — linear timing remains default (0,0,1,1).
• Scalable — future spring or LUT curves can reuse the same Fn typedef.

Copy Easing.h, add the two small patches, rebuild TheIDE, and your widgets will glide like any modern toolkit.

[mirek-fidler]

Related?

#267

[Trilec]

Absolutely—same foundation, but the concept is broader:

Existing PR: adds Lerp(a,b,t, Fn)—you hand-write a lambda for each easing (e.g. a piece-wise “BounceOut”).

My patch: offers a parametric easing engine—four control-points in Easing::Bezier(x1,y1,x2,y2) generate an infinite family of curves; presets like EaseInQuad are just wrappers. No duplicate math, one constexpr helper.

Then .Easing(fn) + AnimateProperty() wire those Bézier lambdas into Animate().
So it extends, not overlaps, and gives designers more flexibility with less code.

[ismail-yilmaz]

Yes, Lerp is essentially the same in concept, but in my proposal, the easing function is left to the client code. This arguably (though not necessarily) has the advantage of reducing maintenance overhead for U++.

I also prefer the use of static assertions for invalid function signatures, as it definitely helps make template errors more readable/bearable.

That said, this implementation is more comprehensive and robust, and would be a great addition. I'm just not entirely sure the namespace is necessary. Does it really add any value in this context?

[Trilec]

I'm not usually a fan of name spaces but in this circumstance .
*Enhances clarity and supports future extensibility for the easing module,
*The usual prevention of conflicts,
*Minimal overhead.

Otherwise we could use prefixed names. ie EasingBezier, but still feels like a small namespace is just that much cleaner.

[Trilec]

Quick check-in on the Bézier easing patch:

I’m ready to finish my new upp_stateMachine demo and some nice upp_animationManager concepts, but it depends on the Bézier-based AnimateProperty helper.

If core devs are happy with the idea, let me know what’s still needed (tests? doc stubs?) and I’ll prep the PR against 2025.1 right away.

Thanks!

[klugier]

I think, we should move forward with this. However, we need to do it very careful, it is a big change. So, I have a questions:

• Right now Animate is a set of overloaded functions, but in your proposition, it is a class. How do you plan to solve it? Please, keep in mind backwards compatibility. Probably in this case, we will need to add Easing as a function parameter rather than introducing Builder. Also, Builder is not popular design pattern in U++.
• AnimateProperty, shouldn't we have more specialized functions like Animate::Fade, Animate::Rotate and Animate::Pulse? The main reason for that is avoid using template specailization in client code and make it as simple as possible. Of course, you can have something similar to AnimateProperty, but it should be used in the end

We can think about new animation API, but we will need to depricate the old one and then remove it after several releases. Since c++14 there is this excellent [[deprecated]] attribute.

In context of approving the patch for changes like this, you will need to prepare:

• T++ docs, please do not use Doxygen comments, we are in U++ :)
• reference/example - put example or reference for your changes, so other users can learn about it
• auotests - testing code - optional, but recommended
• Adding new chapter to GUI tutorial about animations - optional, but recommended, can be deliver in separate PR

[Trilec]

Great, thanks for the feedback. I'm certainly open to changes and being careful about how we approach things.

Here is my revised implementation (incorporating the feedback, thanks for that).

---

Proposed Implementation

This plan is designed to be minimally invasive.

A. New File: CtrlLib/Easing.h

This is a new file. The code below represents its entire content.

// CtrlLib/Easing.h — single-header Bézier helper
#pragma once

#include <Core/Core.h>
#include <functional>
#include <cmath>

NAMESPACE_UPP

namespace Easing {

// The core contract: a callable object mapping time progress (0-1) to eased progress (0-1).
using Fn = std::function<double(double)>;

namespace Detail {
    // Helper to get the X-coordinate for a given curve parameter 't'
    constexpr double BezierX(double x1, double x2, double t) noexcept {
        double u = 1.0 - t;
        return (3.0 * u * u * t * x1) + (3.0 * u * t * t * x2) + (t * t * t);
    }
}

// Correct de Casteljau implementation that solves for the curve parameter 't'
// that corresponds to a given time 'x' using binary search.
inline double DeCasteljau(double x1, double y1, double x2, double y2, double x) noexcept
{
    if (x <= 0.0) return 0.0;
    if (x >= 1.0) return 1.0;

    double t_min = 0.0, t_max = 1.0;
    double t = x; // Start with a good guess

    // Iteratively find the 't' that produces the desired 'x'
    for (int i = 0; i < 8; ++i) {
        double current_x = Detail::BezierX(x1, x2, t);
        if (std::abs(x - current_x) < 1e-6) break;
        if (current_x < x) t_min = t;
        else t_max = t;
        t = (t_max + t_min) / 2.0;
    }

    // Now use the correct 't' to find the Y value (the eased progress)
    double u = 1.0 - t;
    return (3.0 * u * u * t * y1) + (3.0 * u * t * t * y2) + (t * t * t);
}

// Factory to create a custom Bézier easing function.
inline Fn Bezier(double x1, double y1, double x2, double y2) noexcept
{
    return [=](double t) noexcept -> double { return DeCasteljau(x1, y1, x2, y2, t); };
}

// Common presets, matching CSS standards for ease of use.
static Fn EaseLinear     = Bezier(0.0,   0.0,   1.0,   1.0);
static Fn EaseInQuad     = Bezier(0.55,  0.085, 0.68,  0.53);
static Fn EaseOutQuad    = Bezier(0.25,  0.46,  0.45,  0.94);
static Fn EaseInOutQuad  = Bezier(0.455, 0.03,  0.515, 0.955);
static Fn EaseOutBounce  = Bezier(0.68, -0.55,  0.265, 1.55);

} // namespace Easing

END_UPP_NAMESPACE

B. Additions to CtrlLib/CtrlUtil.h

The following declarations should be added to the existing CtrlLib/CtrlUtil.h file.

#include "Easing.h"

// The new Animate overload for Rects
void Animate(Ctrl& q, Rect target, int ms, const Easing::Fn& easing);

// The existing Animate remains for perfect backwards compatibility
inline void Animate(Ctrl& q, Rect target, int ms) { Animate(q, target, ms, Easing::EaseLinear); }

// New specialized, simple property animators
void AnimateFade(Ctrl& q, double target_opacity, int ms, const Easing::Fn& easing = Easing::EaseLinear);
void AnimateColor(Gate<void(Color)> setter, Color from, Color to, int ms, const Easing::Fn& easing = Easing::EaseLinear);

C. Additions to CtrlLib/CtrlUtil.cpp

The following implementations should be added to the existing CtrlLib/CtrlUtil.cpp file.

#include "CtrlLib.h"
#include <algorithm>

NAMESPACE_UPP

namespace Detail {
    // The robust, recursive-safe, correctly-timed animation engine
    template <typename T>
    void AnimateProperty(Gate<void(T)> setter, T from, T to, int ms, const Easing::Fn& easing)
    {
        int start_time = msecs();
        
        std::function<void()> update;
        update = [=, &update]() mutable {
            int elapsed = msecs() - start_time;
            double t = std::min(1.0, ms > 0 ? (double)elapsed / ms : 1.0);
            
            // Apply easing to time 't' before passing to Lerp
            setter(Lerp(from, to, easing(t)));
            
            if (t < 1.0) {
                SetTimeCallback(0, update);
            }
        };
        update();
    }
}

void Animate(Ctrl& q, Rect target, int ms, const Easing::Fn& easing) {
    Detail::AnimateProperty<Rect>([&](Rect r) { q.SetRect(r); }, q.GetRect(), target, ms, easing);
}

void AnimateFade(Ctrl& q, double target_opacity, int ms, const Easing::Fn& easing) {
    Detail::AnimateProperty<double>([&](double o) { q.SetOpacity(o); }, q.GetOpacity(), target_opacity, ms, easing);
}

void AnimateColor(Gate<void(Color)> setter, Color from, Color to, int ms, const Easing::Fn& easing) {
    Detail::AnimateProperty<Color>(setter, from, to, ms, easing);
}

END_UPP_NAMESPACE

[Trilec]

Just checking in — since the full code is already in the discussion above and incorporates the feedback, do you want me to submit a formal PR as well, or are we happy to proceed from here?

Happy to create the PR if that’s the preferred next step.

Cheers,
Trilec

[Trilec]

Animation lib update

Hey all — just a quick update after a few weeks on this. The little easing header I dropped earlier has grown into a proper animation lib.

What’s working now
• Core ops: play, cancel, stop, delay, looping/yoyo, pause/resume.
• Easing: both presets and custom Beziers.
• Safe: reentrancy is handled, memory cleans up properly (no leaks or dangling refs).
• Stress tests: concurrent bursts, pause/resume loops, cancel/restart abuse… holding up well so far.
• API surface is still U++-native and clean (AnimateProperty, AnimateFade, AnimateColor, Easing::Bezier, etc.).

What’s different from the old stuff
• The older Animate() helpers were very narrow (mostly fade/move/color with ad-hoc state handling). Those are now effectively deprecated.
• Instead of tacking features on, this lib provides a single consistent core with specialized helpers layered on top (so Fade/Rotate/Pulse become thin wrappers, not special cases).
• Much better resource management — animations finish or cancel deterministically, without dangling timers or half-cleaned state.
• Designed with UI integration in mind rather than bolted on.

Next steps
• I’m finishing the last of the stress tests + examples.
• Would be great to hear thoughts on UI integration (buttons, sliders, menus) before I go hacking it in and get scolded later 😅.

— overall this feels like the right replacement path for the old helpers: lighter, cleaner, but with far more reach. Close to PR-ready now.

[Trilec]

finished the stress tests.
Starting probe against CtrlLib/Animation
L1: Made TopWindow
PASS L1
L2: Pumped events
PASS L2
L3: Construct+scope-exit ok
PASS L3
L4: Play+Cancel done
PASS L4
L5: ticks=48
PASS L5
L6: natural finish
PASS L6
L7: double cancel ok
PASS L7
L8: KillAllFor issued
PASS L8
L9: ticks a1=65 a2=65
PASS L9
L11: burst at i=0
L11: burst at i=40
L11: burst at i=80
L11: burst at i=120
L11: burst at i=160
L11: stress done
PASS L11
L12: pause/resume done
PASS L12
L13: stop->finish only
PASS L13
L14: cancel->cancel only
PASS L14
L15: delay respected
PASS L15
L16: loop+yoyo
PASS L16
L17: easing completes
PASS L17
L19: progress final=1.000
PASS L19
L20: reentrant finish
PASS L20
L21: exception caught (no crash)
PASS L21
L22: finalize while running
PASS L22
L10: owner gone, ticks(before close)=0
PASS L10
L18: FPS clamp
PASS L18
DONE — passed 22, failed 0
<--- Finished in (0:03.23), exitcode: 0 --->

[Trilec]

woow. Finished the GUI test suit.

Man this has been a lot of work...
Hopefully publish up to Github this weekend.