Animatron/player — pull request #71 by shamansir (2013-03-01 18:42:57+00:00)
Title: Absolute and relative time modifiers

:sweat_smile:

The very great Pull Request that fixes (should fix) all the previous problems with integrating relative modifiers by making absolute ones to be default and adding relative ones as the separate feature. Also, there are a lot of internal fixes in there.

**Modifiers with seconds-based values** ( _absolute time_ modifiers )

* Type 1: _Usual ones_: `b().modify(function(t, duration, ...) { ... })` — modifiers, which are called while element is alive for every of its update-request (request for new frame, spawned by browser), receiving the time of this request; they receive `t` in seconds, which is relative to the owning element's band (lifetime), and `duration` is the duration (in seconds, for sure) of that band; it is also acceptable to say that they have their band equal to the lifetime of their owning element, so there is no need in specifying it;
* Type 2: _Band-restricted_: `b().modify([a, b], function(t, duration, ...) { ... })` — they have their own sub-band (lifetime) inside of the owning element's band and they are just called during that sub-band (if sub-band is wider than element's band, it is temporary reduced to match it, same way it works with element's children bands); `a` and `b` are specified in seconds relatively to element's band, however `t` value (in seconds) they receive is relative to the modifier sub-band, and `duration` is the duration (in seconds) of that sub-band.
* Type 3: _Time-restricted_ or _Trigger-like_: `b().modify(ct, function(t, duration, ...) { ... })` — they are guaranteed* to be called at specified time of element's life or a bit later (if they occasionally missed that time, say, due to low FPS), and receive actial time of the call as `t`; `ct` is specified in seconds relatively to owning element's band and `t` value (actual time of the call), in seconds, is relative to the very same band, and `duration` is the duration of that band, in seconds again.

**Modifiers with relative values** ( _relative time_ modifiers )

* Type 1: _Usual ones_: `b().rmodify(function(t, duration, ...) { ... })` — modifiers, which are called while element is alive for every of its update-request (request for new frame, spawned by browser), receiving the time of this request; they receive `t` in range of `[0..1]`, relatively to the owning element's band (lifetime), and `duration` is the duration (in seconds, for sure) of that band; it is also acceptable to say that they have their band equal to the lifetime of their owning element, so there is no need in specifying it;
* Type 2: _Band-restricted_: `b().rmodify([a, b], function(t, duration, ...) { ... })` — they have their own sub-band (lifetime) inside of the owning element's band and they are just called during that sub-band (if sub-band is wider than element's band, it is temporary reduced to match it, same way it works with element's children bands); `a` and `b` are specified in range of `[0..1]` relatively to element's band, however `t` value (in range of `[0..1]`) they receive is relative to the modifier sub-band, and `duration` is the duration (in seconds) of that sub-band, so you always may get time in seconds relatively to modifier's band with `t * duration`.
* Type 3: _Time-restricted_ or _Trigger-like_: `b().rmodify(ct, function(t, duration, ...) { ... })` — they are guaranteed* to be called at the specified time of element's life or a bit later (if they occasionally missed that time, say, due to low FPS), and receive actual time of the call as `t`; `ct` is specified in `[0..1]` range relatively to owning element's band and `t` value, in range of `[0..1]`, is relative to the very same band, and `duration` is the duration of that band, in seconds.

* actually _not so_, in the current version

Notes:

- relative time modifiers give you the ability to specify fractions of bands (for band- and time-restricted ones), where, say, `0` will mean start of that band, `1/2` will mean half of that band and `1` will mean the end of that band; just if you haven't noticed
- in case of `t` values you receive within `[0..1]` ranges, please do not expect to always get the exact `0` or `1` value in modifier, since it may never happen due to FPS.
- time values are often the subject to fail in floating point operations, since then they are actually returned mathematically rounded to some internal precision (currently `10^-9`), so please take it in consideration if you plan to make models of Higgs Boson using the player API.