mojo/services/media/common/interfaces/timelines.mojom

// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[DartPackage="mojo_services"]
module mojo;

// TODO(dalesat): Move out of media to somewhere more generic.

// Used as a placefolder for unspecified time values.
const int64 kUnspecifiedTime = 0x7fffffffffffffff;

// Represents the relationship between and subject timeline and a reference
// timeline.
//
// To translate a reference timeline value r to the subject timeline, apply
// the following formula:
//
//   (r - reference_time) * subject_delta / reference_delta + subject_time
//
// To translate a subject timeline value s to the reference timeline, apply
// this formula provided subject_delta isn't zero:
//
//   (s - subject_time) * reference_delta / subject_delta + reference_time
//
struct TimelineTransform {
  // A value from the reference timeline that correlates to subject_time.
  // When TimelineTransform is used in TimelineConsumer.SetTimelineTransform,
  // reference_time is also the effective time at which the transform should
  // be applied. In that case, it may be kUnspecifiedTime, to indicate that the
  // transform should be applied as soon as possible.
  int64 reference_time = 0;

  // A value from the subject timeline that correlates to reference_time. When
  // TimelineTransform is used in TimelineConsumer.SetTimelineTransform,
  // subject_time may be kUnspecifiedTime to indicate that the transition
  // should be first-order continuous. That is, kUnspecifiedTime indicates that
  // the consumer should use the previous timeline transform to calculate the
  // correct subject_time from the reference_time (if specified) or the
  // reference time chosen by the timeline consumer if reference_time is not
  // specified.
  int64 subject_time = 0;

  // The change in the reference timeline corresponding to subject_delta.
  // Cannot be zero.
  uint32 reference_delta = 1;

  // The change in the subject timeline corresponding to reference_delta.
  uint32 subject_delta = 0;
};

// A push-mode consumer of timeline updates.
interface TimelineConsumer {
  // Sets a timeline transform. Note that in this usage, the reference_time and
  // subject_time fields of TimelineTransform have semantics beyond being a
  // correlated pair of time values, and either or both may be unspecified
  // (kUnspecifiedTime).
  //
  // The reference_time is the effective time (in the reference timeline) at
  // which the new transform is to be applied. If not specified, the transition
  // is to occur as soon as possible, and the consumer must choose the earliest
  // reference time at which the transition can reliably occur.
  //
  // The subject_time is the new subject time that will correlate to the
  // specified or consumer-chosen reference time. If not specified, the
  // consumer uses the previous timeline transform to calculate a subject time
  // that will achieve a first-order continuous transition. If specified, the
  // timeline will effectively jump to that value at the chosen reference time,
  // a transition that's unlikely to be first-order continuous.
  //
  // The callback is called at the effective time or when a pending operation is
  // cancelled due to a subsequent call, in which case the 'completed' value is
  // false.
  SetTimelineTransform(TimelineTransform timeline_transform) =>
      (bool completed);
};