blob: ec1c093a3a82760a97c085062328bfe5a2e0be1e [file] [log] [blame]
// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
/// A TimelineFunction represents a relationship between a subject timeline and a
/// reference timeline with a linear relation.
/// For example, consider a common use case in which reference time is the
/// monotonic clock of a system and subject time is intended presentation time
/// for some media such as a video.
/// `reference_time` is the value of the monotonic clock at the beginning of
/// playback. `subject_time` is 0 assuming playback starts at the beginning of
/// the media. We then choose a `reference_delta` and `subject_delta` so that
/// `subject_delta` / `reference_delta` represents the desired playback rate,
/// e.g. 0/1 for paused and 1/1 for normal playback.
/// ## Formulas
/// With a function we can determine the subject timeline value `s` in terms of
/// reference timeline value `r` with this formula (where `reference_delta` > 0):
/// s = (r - reference_time) * (subject_delta / reference_delta) + subject_time
/// And similarly we can find the reference timeline value `r` in terms of
/// subject timeline value `s` with this formula (where `subject_delta` > 0):
/// r = (s - subject_time) * (reference_delta / subject_delta) + referenc_time
/// ## Choosing time values
/// Time values can be arbitrary and our linear relation will of course be the
/// same, but we can use them to represent the bounds of pieces in a piecewise
/// linear relation.
/// For example, if a user performs skip-chapter, we might want to describe
/// this with a TimelineFunction whose `subject_time` is the time to skip to,
/// `reference_time` is now plus some epsilon, and delta ratio is 1/1 for normal
/// playback rate.
struct TimelineFunction {
/// A value from the subject timeline that correlates to reference_time.
int64 subject_time = 0;
/// A value from the reference timeline that correlates to subject_time.
int64 reference_time = 0;
/// The change in the subject timeline corresponding to reference_delta.
uint32 subject_delta = 0;
/// The change in the reference timeline corresponding to subject_delta.
/// Cannot be zero.
uint32 reference_delta = 1;