// Copyright 2015 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.media;

// TimelineQuad
// TODO(dalesat): Rename reference -> presentation.
// TODO(dalesat): Rename target -> reference.
//
// A structure which holds the four numbers needed to define a linear
// relationship between the points in two different timelines.  The relationship
// is expressed using 4 integers in order to facilitate compositions of multiple
// transformations (A->B can be composed with B->C to produce the transformation
// from A->C), and to minimize rounding and scaling errors when mapping points
// between timelines which do not have an integer scaling relationship between
// each other.
//
// These values are used to define the following functions which map from
// points from the reference timeline to the target timeline, and back again.
//
// Let r be a point in the reference timeline.
// Let t be a point in the target timeline timeline.
// Let ref and tgt be abbreviations for reference and target in equations below.
//
// Given that r and t represent the same instant in time (in a single frame of
// reference)
//
// t = f(r) = (((r - ref_offset) * tgt_delta) / ref_delta) + tgt_offset
// r = F(t) = (((t - tgt_offset) * ref_delta) / tgt_delta) + ref_offset
//
// See also...
// mojo/services/media/common/linear_transform.h
//
struct TimelineQuad {
  int64  reference_offset = 0;
  int64  target_offset    = 0;
  int32  reference_delta  = 0;
  uint32 target_delta     = 1;
};

// TimelineTransform
// TODO(dalesat): Rename reference -> presentation.
// TODO(dalesat): Rename target -> reference.
//
// A structure which holds both a timeline quad, and a pair of identifiers which
// define the specific timelines which are the reference and target timelines.
struct TimelineTransform {
  // TODO: These constants should probably defined by a central time management
  // service, not here.
  const uint32 kLocalTimeID = 0xFFFFFFFF;
  const uint32 kContextual  = 0xFFFFFFFE;

  TimelineQuad quad;
  uint32 reference_timeline_id = kContextual;
  uint32 target_timeline_id    = kLocalTimeID;
};

// RateControl
//
// An interface typically exposed by media renderers which allow producers of
// media to specify how the presentation time stamps of the media queued to the
// renderer relate to real time.  Users may initialize the transformation with a
// specific Quad, change the rate immediately in a first order contiguous
// fashion, or schedule ranges in the rate at points in time on either the
// reference or target timelines.
interface RateControl {
  // Get the current quad which describes the transformation between the
  // reference and target timelines.
  GetCurrentTransform() => (TimelineTransform trans);

  // Immediately, explicitly set the quad which describes the mapping from
  // reference to target timeline.  It is understood that this can cause
  // discontinuities and should only be used in situations which are already
  // fundamentally discontinuous (startup/seeking, for example)
  SetCurrentQuad(TimelineQuad quad);

  // Configure the target timeline ID.  Note, the reference timeline ID will
  // always be contextual.
  SetTargetTimelineID(uint32 id);

  // Immediately change the rate of the existing transformation in a fashion
  // which is first order continuous with the current transformation.
  SetRate(int32 reference_delta, uint32 target_delta);

  // Schedule a first order continuous rate change at the specified reference
  // time.
  SetRateAtReferenceTime(int32 reference_delta,
                         uint32 target_delta,
                         int64 reference_time);

  // Schedule a first order continuous rate change at the specified target time.
  SetRateAtTargetTime(int32 reference_delta,
                      uint32 target_delta,
                      int64 target_time);

  // Cancel any pending rate changes
  CancelPendingChanges();
};