Mozart: Improve internal scene graph representation.

mojo/services/gfx/composition/interfaces/nodes.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.
 
 // Primitives express the geometry of the scene, such as quads and references
 // to embedded scenes.  Primitives are arranged hierarchically as nodes,
 // each with an associated transformation matrix.
 
 [DartPackage="mojo_services"]
 module mojo.gfx.composition;
 
 import "mojo/services/geometry/interfaces/geometry.mojom";
 import "mojo/services/gfx/composition/interfaces/hit_tests.mojom";
 
 // 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 node graph is processed in pre-order traversal.  Starting from the
+// RENDERING
+//
+// The node graph is renderer in pre-order traversal.  Starting from the
 // root, the compositor applies the transformation, clip, applies the
 // node's operation (if any), then recursively processes the node's children
 // according to the node's combinator rule.
 //
 // BLOCKED NODES
 //
 // Due to the asynchronous nature of the system, it may happen that some
 // nodes cannot be processed immediately at drawing time because they require
 // access to certain resources which are not available, such as a specific
 // version of a scene which has yet to be produced by some other application.
@@ skipping 16 matching lines @@
 // children will not appear in the output.
 //
 // With the |FALLBACK| combinator, the first unblocked child of a node is
 // drawn and the remaining nodes are ignored.  If the node has children
 // and all of them are blocked then the node itself is blocked.
 //
 // Combinators make it possible to express complex rules such as substituting
 // missing content for an earlier version of that content or for a placeholder
 // if not available.
 //
+// INSTANCING
+//
+// The compositor allows nodes to be referenced and reused multiple times
+// within a scene (this is known as instancing).  Instancing makes it easier
+// to take advantage of combinators for interleaving placeholder content
+// when certain nodes are blocked from rendering (see above).  It also allows
+// common elements to be reused if desired.
+//
+// Likewise, the compositor allows scenes to be multiply referenced so that
+// the same content can be presented simultaneously in several places.
+//
+// CYCLES
+//
+// The compositor forbids cycles among nodes within scenes and will
+// reject scene updates which introduce node cycles by closing the client's
+// connection.
+//
+// Likewise, the compositor forbids cycles across scenes and will respond
+// to them by considering any scene within a cycle to be blocked from
+// rendering.
+//
+// For example, if there are scenes A, B, and C linked such that rendering
+// would traverse a path A -> B -> C -> B, the compositor will consider both
+// scenes B and C to be blocked and will apply A's combinator rules as required
+// to resolve the problem at the point where it would have entered the cycle.
+// This may cause A itself to be blocked if there are no applicable |PRUNE|
+// or |FALLBACK| predicated alternatives.
+//
+// This policy protects clients from cross-scene cycles which may have been
+// introduced downstream in the graph without their knowledge or which may
+// occur transiently, so long as they are not within the cycle themselves.
+// It also ensures that cycles are resolved deterministically regardless of
+// where they are encountered during traversal; all scenes within the cycle
+// are suppressed.
+//
 // TIPS
 //
 // 1. Reuse nodes when possible to reduce the size of the graph.  Consider
 //    using LayerNodeOps to flatten common elements to a texture which can
 //    be redrawn efficiently in many places.
 //
-// 2. Insert PRUNE or FALLBACK nodes in places where blocking is likely to
+// 2. Insert |PRUNE| or |FALLBACK| nodes in places where blocking is likely to
 //    occur, such as when embedding scenes produced by other applications.
-//    Provide alternate content where possible.
+//    Provide alternate content where possible to avoid stalling the
+//    rendering pipeline at these points.
 //
 struct Node {
   // The combinator specifies how child nodes are processed.
   enum Combinator {
     // All children are drawn in sequence, blocking if any are blocked.
     MERGE,
     // All children are drawn in sequence, skipping any that are blocked.
     PRUNE,
     // The first unblocked node is drawn, blocking if there are children
     // and all of them are blocked.
@@ skipping 19 matching lines @@
   // Use |kHitIdNone| if the node should not be hit tested.
   //
   // TODO(jeffbrown): This scheme is probably too naive.
   uint32 hit_id = kHitIdNone;
 
   // The Combinator to apply when processing the children of this node.
   Combinator combinator = Combinator.MERGE;
 
   // The ids of the children of this node.
   // It is an error to specify a node id that does not refer to a valid
-  // node; the compositor will close the connection when the scene
-  // is published.
-  // If a cycle is introduced then the node will be considered to be blocked
-  // at the point where recursion occurs.  A subsequent rearrangement of
-  // scenes which removes the cycle will unblock the node.
+  // node or which creates a cycle in the graph; the compositor will close
+  // the connection when the scene is published.
   array<uint32>? child_node_ids;
 
   // The drawing operation to apply when processing this node.
   // If null, no drawing operation occurs at this node.
   NodeOp? op;
 };
 
 // A drawing operation to apply when processing the node.
 union NodeOp {
   RectNodeOp rect;
@@ skipping 45 matching lines @@
 // version of the scene is not ready for use at draw time or if it too
 // is blocked.
 //
 // It is often useful to wrap this node with a |LayerNodeOp| when blending
 // the scene with other content.
 struct SceneNodeOp {
   // The resource id of a valid |SceneResource| to link into the scene.
   // It is an error to specify a resource id that does not refer to a scene
   // resource; the compositor will close the connection when the scene
   // is published.
-  // If a cycle is introduced then the node will be considered to be blocked
-  // at the point where recursion occurs.  A subsequent rearrangement of
-  // scenes which removes the cycle will unblock the node.
+  // If a cycle is introduced then the scene will be substituted with
+  // placeholder content by the compositor.
   uint32 scene_resource_id;
 
   // The version of the scene that we would like to reference.
   // Use |kSceneVersionNone| to request the most recently published
   // version of the scene if synchronization is unimportant.
   uint32 scene_version = 0; // kSceneVersionNone
 };
 
 // Draws a layer.
 //
@@ skipping 21 matching lines @@
 };
 
 // Specifies how blending should take place.
 struct Blend {
   // The opacity for composition in a range from 0 (fully transparent)
   // to 255 (fully opaque).
   uint8 alpha = 255;
 
   // TODO(jeffbrown): Blend modes and texture filtering.
 };