Initial checkin of the new Mozart compositor.

mojo/services/gfx/composition/interfaces/scenes.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;
+
+import "mojo/services/gfx/composition/interfaces/nodes.mojom";
+import "mojo/services/gfx/composition/interfaces/resources.mojom";
+import "mojo/services/gfx/composition/interfaces/scene_token.mojom";
+import "mojo/services/gfx/composition/interfaces/scheduling.mojom";
+
+// The node id which represents the root of a scene.
+//
+// Every scene should have a root node which uses this id unless the scene
+// has no content at all.
+const uint32 kSceneRootNodeId = 0;
+
+// The scene version used as a placeholder when the version doesn't matter.
+//
+// This version code can be used by a consumer of a scene to express that
+// it would like to consume the latest version of the scene.
+//
+// This version code can also be used by a scene itself if it has not
+// received any other specific indications as to the version it should
+// report when publishing its content.
+const uint32 kSceneVersionNone = 0;
+
+// A scene component maintains a description of some graphical content which
+// an application would like to render.  This description consists of
+// resources and nodes.
+//
+// Use |Compositor.RegisterScene()| to register a scene.  The application
+// uses the |Scene| interface to manage the scene's content and implements
+// the |SceneListener| interface to handle events.
+//
+// CONTENT
+//
+// Resources are references to foreign objects which are being imported into
+// the scene graph, such as images and other scenes.  Each resource must be
+// given a locally unique identifier when it is bound to the scene.
+//
+// Nodes express the geometry and content of the scene, such as images and
+// references to embedded scenes.  Nodes are arranged to form a directed
+// acyclic graph of drawing commands.
+//
+// The root node of the scene has the special id of |kSceneRootNodeId|.
+//
+// ATOMICITY
+//
+// To ensure atomicity of updates, the evolution of a scene occurs in two
+// phases: update and publish.  Incremental changes to the scene made during
+// the update phase are not observed until published.
+//
+// - Update phase: To construct the next state of a scene, the scene owner
+//   issues any number of scene update requests to add, update, or remove
+//   resources and nodes.
+//
+// - Publish phase: When the next state of a scene is fully constructed, the
+//   scene owner issues a request to publish its changes to the scene and
+//   assigns it a version identifier.  The version identifer may be used
+//   in scene references to coordinate updates across multiple scenes which
+//   must be synchronized.
+//
+// Once the scene has been published, the scene owner may begin to construct
+// the next state without disrupting the state just published.
+//
+// SYNCHRONIZATION
+//
+// To ensure synchronization of updates across scenes, some additional work
+// is needed.
+//
+// For example, consider the case of a scene X which embeds two other scenes
+// A and B.  If X changes size, it may need to resize A and B as well to
+// fit properly within its layout.
+//
+// To do so, X sends the owners of A and B each a message indicating the
+// new size it desires along with new scene version identifiers V(A) and
+// V(B) which the owners of A and B must use when they publish the new scene
+// state which incorporates the requested size change.
+//
+// Meanwhile, X produces a new scene of its own taking into account its
+// new size.  As part of constructing this new scene, it binds to the V(A)
+// and V(B) versions of A and B to express its dependence on A and B
+// having been updated to the new size.
+//
+// Propagating version information top-down through the scene graph in
+// this manner allows for state changes to be synchronized in a purely
+// feed-forward manner.
+//
+// CONCURRENCY
+//
+// In the above synchronization example, version numbers were used to
+// couple the state of one scene with others that it depends on.
+// What should happen if these dependencies are not satisfied promptly?
+//
+// Suppose X and A quickly produce new scenes with the new size but
+// B is taking longer than anticipated to do so.  We have a few choices:
+//
+// - Stall: The compositor could continue to show the old state of X, A, and B
+//   until such time as all three have published their new versions.
+//
+// - Recover: The compositor could realize that X and A are already up to date
+//   but B is lagging and choose to apply a transformation to B's old content
+//   cover for the lag, such as by scaling, clipping, masking, or discarding
+//   B's old content.
+//
+// - Speculate: The compositor could allow X to provide alternate descriptions
+//   of the scene in the case where A or B are not keeping up so that it
+//   can more finely control the recovery policy.
+//
+// To maximize concurrency, we adopt the latter approach.
+interface Scene {
+  // Sets the listener for receiving events from the scene.
+  //
+  // If |listener| is null, then the previously set listener is removed.
+  SetListener(SceneListener? listener);
+
+  // Applies a batch of incremental updates to the contents of the scene.
+  //
+  // Incremental changes can be split across any number of updates but it is
+  // more efficient to process them in batches.  Updates have no visible
+  // effect until the scene owner calls |Publish()| to publish them.
+  //
+  // Updates are buffered and applied when |Publish()| is called.  This means
+  // it is safe to issue an update which adds a node that refers to a resource
+  // which is not added until a subsequent update as long as the scene is
+  // not published in between those updates.
+  Update(SceneUpdate update);
+
+  // Publishes the scene and tags it with the specified version.
+  //
+  // All pending incremental updates are applied atomically when the scene
+  // is published and the new state is labeled with the version indicated
+  // in the associated metadata.
+  //
+  // The |metadata| describes how the published scene should be presented.
+  // If null, this method behaves as if a |SceneMetadata| object initialized
+  // with default values had been supplied.
+  //
+  // Publishing a scene graph applies all pending updates.  It is an error
+  // to publish updates which cause the scene state to become inconsistent,
+  // such as by having nodes which refer to non-existent resources; the
+  // connection will be closed.
+  Publish(SceneMetadata? metadata);
+
+  // Gets a scheduler for scheduling upcoming scene operations.
+  GetScheduler(SceneScheduler& scheduler);
+};
+
+// An interface applications may implement to receive events from a scene.
+interface SceneListener {
+  // Called when a resource has become unavailable.
+  //
+  // Any nodes which are using the resource will be considered blocked
+  // until the resource is replaced or the nodes using it are removed.
+  OnResourceUnavailable(uint32 resource_id) => ();
+};
+
+// A batch of incremental changes to be applied to a scene.
+struct SceneUpdate {
+  // If true, clears all resources before processing the update.
+  bool clear_resources = false;
+
+  // If true, clears all nodes before processing the update.
+  bool clear_nodes = false;
+
+  // Resources to be added, updated, or removed, indexed by resource id.
+  // The value replaces the definition of the resource with the given id.
+  // If the value is null, then the resource is removed from the scene.
+  map<uint32, Resource?>? resources;
+
+  // Nodes to be added, updated, or removed, indexed by node id.
+  // The value replaces the definition of the node with the given id.
+  // If the value is null, then the node is removed from the scene.
+  //
+  // The root node must have an id of 0.
+  map<uint32, Node?>? nodes;
+};
+
+// Describes how a published scene should be presented.
+struct SceneMetadata {
+  // The scene's new version number.
+  //
+  // Version numbers are usually associated with requests to change the
+  // state of the scene.  For example, the embedder of this scene may send
+  // it a request to resize its content or change its color and provide a
+  // new version number that this scene should apply when it publishes the
+  // first update which addresses this request.
+  //
+  // In general, the version number will be provided to the owner of the
+  // scene by some other party which is in change of synchronizing updates
+  // across multiple scenes including this one.  The other party will
+  // frequently be the owner of some other scene which embeds this one.
+  //
+  // In certain cases there might not be a version number provided for
+  // synchronization.  When this happens, set |version| to |kSceneVersionNone|.
+  //
+  // Note that version numbers are unordered; there is no need to increment
+  // them monotonically.  Values may also be reused at will.
+  uint32 version = 0; // kSceneVersionNone
+
+  // A timestamp indicating approximately when the published contents of the
+  // scene are to be shown on the display output assuming everything is
+  // fully rendered and submitted by the appropriate deadline.
+  //
+  // Expressed in microseconds in the |MojoTimeTicks| timebase.
+  //
+  // A value of 0 means "as soon as possible".
+  //
+  // See also: |FrameInfo.presentation_time|.
+  int64 presentation_time = 0;
+};