| # Clock Transformations | |
| ## Overview | |
| [Clock objects](/docs/reference/kernel_objects/clock.md) represent functions which map all of the | |
| points on a reference clock timeline to all of the points on the clock object's | |
| timeline. Over all time, this function is represented as a | |
| [piecewise linear function](https://en.wikipedia.org/wiki/Piecewise_linear_function). | |
| Each segment of this function is a one dimensional | |
| [affine transformation](https://en.wikipedia.org/wiki/Affine_transformation) | |
| which relates the reference timeline to the clock's timeline. | |
| Clock objects store only the most recent segment of the transformation at any | |
| given time, not the entire history. | |
| ## Definition of the Affine Transformation | |
| A segment of the piecewise linear function is stored using four numbers. | |
| + The offset on the reference timeline _R<sub>off_</sub> (64 bits) | |
| + The offset on the clock timeline _C<sub>off_</sub> (64 bits) | |
| + The ratio of the reference to clock rate (_R<sub>rate_</sub>/_C<sub>rate_</sub>) (32/32 bits) | |
| Given a reference time _r_, the function to apply the most recent segment of the | |
| transformation, _C(r)_ is given as | |
| _C(r) = (((r - R<sub>off</sub>) * C<sub>rate</sub>) / R<sub>rate</sub>) + C<sub>off</sub>_ | |
| Given a clock time _c_, the inverse of the _C_ may be used to compute the | |
| corresponding time on the reference timeline _r_. | |
| _C<sup>-1</sup>(c) = r = (((c - C<sub>off</sub>) * R<sub>rate</sub>) / C<sub>rate</sub>) + R<sub>off</sub>_ | |
| Care should be taken to avoid overflow when scaling the offset values. It is | |
| recommended to store the intermediate result of multiplication in 96 bits before | |
| dividing back down to something which will fit in 64 bits. |