tween
scene/tween.h, moves a float over a duration through a curve
moves a float from where it is to where you want it, over a duration, through a curve, and fires once when it lands. every slide and fade and smooth value is made of this
why it is shaped this way lives in the scene system,
under tween, P1.22. this page is the contract only
#include "scene/tween.h"the shape of it
one tweens_t holds every live tween and one tick steps the lot, so there is no timer per tween and no
timer in here at all. whoever drives frames owns a manager, ticks it with its own clock, and every tween
in that window shares it
gui::tweens_t tweens;
// a real host hangs SetTimer and KillTimer off the pair, a check installs nothing
tweens.set_ticker([&] { start_timer(); }, [&] { stop_timer(); });
// somewhere in a frame
tweens.tick(now_ms);types
| type | what it is |
|---|---|
tween_id_t | uint64_t, what start hands back, 0 means nothing was started |
ease_t | linear, in, out, in_out, all four monotonic so nothing overshoots |
ease_fn_t | float(float), a curve of your own, a spring or a bounce goes here |
done_fn_t | void(), fired once when a tween lands |
ticker_fn_t | void(), the arm and park pair, see set_ticker |
an id and never a pointer. a tween frees itself the instant it lands, so a pointer to one is a dangling read waiting to happen. a stale id is simply not found, and every call taking one is a no-op on it, so holding an id past the end of its animation is safe rather than fatal
tween_spec_t
what one tween is made of. a new field here never moves an existing call site, which is the same
bargain paint_ctx_t makes
| field | default | means |
|---|---|---|
float* target | nullptr | the value we move, BORROWED, see ownership below |
float to | 0.0f | where it ends up, it starts wherever it already is |
int32_t dur | 150 | how long in ms, clamped to 1 or more so t cannot divide by zero |
ease_t curve | out | which named curve, ignored when custom is set |
ease_fn_t custom | empty | a curve of your own, wins over curve |
done_fn_t on_done | empty | fired once when it lands, never fired when it is cancelled |
control_t* repaint | nullptr | who to ask for a repaint after each write, BORROWED, optional |
starting one
tween_id_t start(tween_spec_t _spec);
tween_id_t to(float* _target, float _to, int32_t _dur, ease_t _curve = ease_t::out);
tween_id_t drive(control_t& _ctrl, float* _target, float _to, int32_t _dur, ease_t _curve = ease_t::out, done_fn_t _on_done = {});startis the full one. a nulltargetreturns 0 and does nothingtois the common case, a value and a target and a duration, no repaint and no callbackdriveis the control facing one, it repaints the control after each write
retargeting the same value CANCELS the old tween, and it is cancel and not finish, so the old on_done
never fires. two tweens writing one float would fight over it every tick and the value would visibly jitter
drive SNAPS instead of animating when the control has no route to a host. a control built and set up
before its tree ever reached a window should just BE in its resting state, not animate itself in. it
still fires on_done and still invalidates, it just does it now
a return of 0 means nothing is running, either the target was null or it snapped. that is not an error
stepping it
void tick(int64_t _now_ms);the clock arrives as a PARAMETER and is never read in here. you hand it the clock you already have, and every tween advances off the DELTA between two ticks, which is what makes a check deterministic instead of a sleep with a tolerance on it
- the first tick is a zero. without that, a manager built at 0 and first ticked with a real clock hands every tween the whole uptime of the machine and lands the lot on frame one
- the delta is clamped at 250ms. a stall, a breakpoint or a big load stretches the animation rather than teleporting every tween to its end
on_donecallbacks fire AFTER the list is settled, so a handler is free to start the next leg, cancel its siblings, or ask the manager anything
stopping things
| call | lands the value ? | fires on_done ? |
|---|---|---|
cancel(id) | no, leaves it where it sits | no |
finish(id) | yes, jumps to the end | yes |
kill(const float*) | no | no |
cancel_for(const control_t*) | no | no |
cancel_all() | no | no |
finish_all() | yes | yes |
killcancels whatever is moving a value, so a caller can write it by hand without a fightcancel_forcancels every tween repainting a control, what a control calls on its way out- a stale id is a no-op and never an error
asking it things
std::size_t live() const; // how many are running
int64_t now() const; // the last clock we were ticked with
bool running() const; // is the ticker armed
bool enabled() const;
bool idle() const; // nothing running
bool has(tween_id_t) const;
bool has_target(const float*) const;running() is the parking criterion in one call. the ticker arms on the empty to non-empty edge and
parks itself when the last tween lands, so an idle widget never sits on a live timer. every path that
empties the list parks for free and none of them can forget
wiring
void set_ticker(ticker_fn_t _arm, ticker_fn_t _park);
void set_enabled(bool _on);set the ticker BEFORE the first tween or the arm for one already running is missed
set_enabled(false) FINISHES every live tween rather than cancelling it, so nothing is left stuck
half faded, and it parks on the way through. turning it back on needs no work. that is the reduced motion
switch, and landing values instantly is a product decision as much as a code one
reaching a manager from the tree
control_t carries two slots for this, both ROOT ONLY and both walked up to, the same way invalidate
finds its own
void set_tweens(tweens_t* _mgr); // on the root, BORROWED
tweens_t* tweens() const; // walks to the root, null when nobody wired one
bool has_tweens() const;
void set_leaving(leaving_fn_t _fn); // on the root, fired from EVERY controls dtor
bool has_leaving() const;root.set_tweens(&tweens);
root.set_leaving([&](const gui::control_t* _c) { tweens.cancel_for(_c); });a manager set on a CHILD is never read, and that fails quiet, same as every other slot in control_t
ownership, and what this does NOT do
a tween does not keep anything alive. it holds a raw float* and a borrowed control_t*, so whatever
owns those has to outlive the tween or kill it on the way out. same bargain as the borrowed theme pointer
and the overlay slot
with set_leaving wired, a control dying takes its own tweens with it and you do not have to remember.
one gap, a control that is REMOVED from its tree and then dropped reports nothing, bc remove_child
detaches it first and it has no root left to reach. that one is still your cancel_for, and the reason it is
a trade rather than a miss is in the folder README
out of scope and deliberately absent, keyframes and sequencing. one tween has one from, one to and one
curve, and anything richer is built by chaining on_done
free functions
float eased(ease_t _curve, float _t);runs a t through one of the named curves, both ends clamped. free rather than a method so a paint
easing something by hand does not have to find a manager first