Google is committed to advancing racial equity for Black communities. See how.

Clock Transformations


Clock objects 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. Each segment of this function is a one dimensional 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 Roff (64 bits)
  • The offset on the clock timeline Coff (64 bits)
  • The ratio of the reference to clock rate (Rrate/Crate) (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 - Roff) * Crate) / Rrate) + Coff

Given a clock time c, the inverse of the C may be used to compute the corresponding time on the reference timeline r.

C-1(c) = r = (((c - Coff) * Rrate) / Crate) + Roff

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.