// 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.
//
// Instances of this interface must be obtained from a |Scene| or |Renderer|.
interface FrameScheduler {
  // 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 render 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 couple the
  // scene scheduling to one of the renderers.
  //
  // The returned |frame_info| provides information about the frame to
  // be drawn.  This information should be passed to a
  // |mojo::gfx::composition::FrameTracker| to apply compensation for
  // skipped frames before using it.
  //
  // 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.
//
// As there may be latency in receiving an updated |FrameInfo| from the
// system, the consumer of this structure should apply compensation for
// skipped frames.
//
// See |mojo::gfx::composition::FrameTracker|.
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.
  //
  // It essentially represents the time when the work of producing a new
  // frame began.
  //
  // This value monotonically increases with each frame, never repeats, and
  // is guaranteed to represent a time in the recent 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 although that is what is expected to happen in steady state.
  //
  // 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 monotonically increases with each frame, never repeats, and
  // is guaranteed to be no less than |frame_deadline|.
  //
  // Expressed in microseconds in the |MojoTimeTicks| timebase.
  int64 presentation_time;
};