// 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.gfx.composition;

// Provides support for scheduling drawing and composition operations
// for a particular scene.
//
// Instances of this interface must be obtained from a |Scene|.  This interface
// is modeled separately so as to allow applications to use different threads
// for scheduling work as opposed to publishing scene updates.
interface SceneScheduler {
  // Asks the compositor to invoke the callback when it is a good time to
  // draw the next frame.
  //
  // The rate at which the callback is invoked may depend on how the scene
  // has been embedded.  The scene will only receive frame callbacks while
  // it is attached to a scene graph which the compositor has been asked
  // to renderer since timing information ultimately derives from the
  // renderer.  If the same scene is being rendered to multiple destinations
  // with different timing requirements, the compositor will perform rate
  // adaptation as required behind the scenes.
  //
  // The returned |frame_info| provides information about the frame to
  // be drawn.
  //
  // TODO(jeffbrown): Consider whether we should have the callback be invoked
  // immediately rather than on schedule, letting the client set its own
  // timers.  Advantage may be a reduction in latency due to the elimination
  // of an IPC on a timing critical path.  Disadvantage may be an increase
  // in the number of context switches and some extra client side bookkeeping.
  // Note that although clients could predict future frame times based on the
  // reported information, it's still better for them to schedule each frame
  // individually so they stay in sync with one another and quickly catch
  // up to any changes in timing.  This also gives the compositor more
  // opportunity to plan for the upcoming frame, perhaps even boost clocks
  // in anticipation.
  ScheduleFrame() => (FrameInfo frame_info);
};

// Provides timestamp information about a frame which has been scheduled
// to be drawn.
struct FrameInfo {
  // A timestamp indicating when the work of updating the frame was scheduled
  // to begin which may be used to coordinate animations that require a
  // monotonic timing reference for synchronization, even across scenes.
  //
  // This value monotonically increases with each frame, never repeats, and
  // is guaranteed to represent a time in the past.  It will always be less
  // than or equal to the value returned by |MojoGetTimeTicksNow()| when the
  // frame info is received as part of a |ScheduleFrame()| callback.
  //
  // Expressed in microseconds in the |MojoTimeTicks| timebase.
  // TODO(jeffbrown): Time ticks may need finer resolution guarantees.
  int64 frame_time;

  // The anticipated time interval between the currently scheduled frame
  // and the next one.
  //
  // The interval is approximate and may change at any time.  There is no
  // guarantee that the next frame will occur precisely on the specified
  // interval.
  //
  // Expressed in microseconds.
  uint64 frame_interval;

  // A timestamp indicating when scene updates must be published and ready
  // to be composited in order for the changes to be reflected in this frame.
  //
  // This value is guaranteed to be no less than |frame_time| but it is
  // not necessarily monotonic; it may briefly go backwards if the frame
  // interval or pipeline depth changes between frames.
  //
  // Expressed in microseconds in the |MojoTimeTicks| timebase.
  int64 frame_deadline;

  // A timestamp indicating approximately when the contents of the frame
  // will be shown on the display output assuming everything is fully rendered
  // and submitted by the indicated |frame_deadline|.
  //
  // This value is guaranteed to be no less than |frame_deadline| but it is
  // not necessarily monotonic; it may briefly go backwards if the frame
  // interval or pipeline depth changes between frames.
  //
  // Expressed in microseconds in the |MojoTimeTicks| timebase.
  int64 presentation_time;
};