Initial checkin of the new Mozart compositor.

mojo/services/gfx/composition/interfaces/scheduling.mojom

+// 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;
+};