docs/concepts/kernel/clock_transformations.md

# 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.