Initial checkin of the new Mozart compositor.

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

Index: mojo/services/gfx/composition/interfaces/nodes.mojom
diff --git a/mojo/services/gfx/composition/interfaces/nodes.mojom b/mojo/services/gfx/composition/interfaces/nodes.mojom
new file mode 100644
index 0000000000000000000000000000000000000000..dc773d798ec7c997e3abba0eca5c2a4dbf6cfe8b
--- /dev/null
+++ b/mojo/services/gfx/composition/interfaces/nodes.mojom
@@ -0,0 +1,217 @@
+// 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
+// root, the compositor applies the transformation, clip, recursively
+// processes the node's children according to the node's combinator rule,
+// then applies the node's own operation.
+//
+// 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.
+//
+// When a node cannot be drawn due to an unsatisfied dependency, it is
+// said to be "blocked".  Blocked nodes prevent rendering of the entire
+// subgraph below them.
+//
+// NODE COMBINATORS
+//
+// Node combinator rules describe what should happen when a node which is
+// otherwise unblocked has one or more blocked children.
+//
+// With the |MERGE| combinator, the children of a node are all drawn in
+// sequence if none of them are blocked, otherwise the node itself is
+// blocked.  This is the default.
+//
+// With the |PRUNE| combinator, the children of a node are all drawn in
+// sequence while skipping over any of them which are blocked.  Blocked
+// 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.
+//
+// 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
+//    occur, such as when embedding scenes produced by other applications.
+//    Provide alternate content where possible.
+//
+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.
+    FALLBACK,
+  };
+
+  // The forward transformation from the node's content space to its
+  // containing node's content space.  If null, an identity transformation
+  // is assumed.
+  //
+  // For example, if you want to translate the content of the node so that
+  // it is drawn at X = 100 relative to its containing node's origin, simply
+  // set a transformation matrix with the X translation component equal to 100.
+  // Take care not to specify the inverse transform by mistake.
+  mojo.Transform? content_transform;
+
+  // The clip rectangle to apply to this node's content and to its children
+  // in content space in addition to any clipping performed by the container.
+  // If null, the node does not apply any clipping of its own.
+  mojo.Rect? content_clip;
+
+  // The hit test id to report if anything within the node is hit.
+  // 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.
+  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;
+  ImageNodeOp image;
+  SceneNodeOp scene;
+  LayerNodeOp layer;
+  // TODO(jeffbrown): Color filters.
+};
+
+// Fills a rectangle with a solid color.
+struct RectNodeOp {
+  // The rectangle to fill in content space.
+  mojo.Rect content_rect;
+
+  // The rectangle's color.
+  Color color;
+};
+
+// Draws an image at the specified location.
+//
+// The node containing this operation will be blocked if the image resource
+// is not ready for use at draw time.
+struct ImageNodeOp {
+  // The rectangle in which to draw the image in content space.
+  mojo.Rect content_rect;
+
+  // The portion of the image to draw.
+  // If null, draws the entire image.
+  mojo.Rect? image_rect;
+
+  // The resource id of a valid |MailboxTextureResource| to draw.
+  // It is an error to specify a resource id that does not refer to an image
+  // resource; the compositor will close the connection when the scene
+  // is published.
+  uint32 image_resource_id;
+
+  // The blending parameters.  If null, uses the default values specified
+  // in the |Blend| structure declaration.
+  Blend? blend;
+};
+
+// Draws a scene.
+//
+// A scene operation embeds another scene at this point in the scene graph.
+// It has essentially the same effect as drawing the root node of the
+// referenced scene and drawing it as if it were a child of this node.
+//
+// The node containing this operation will be blocked if the specified
+// 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.
+  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.
+//
+// Conceptually, this operation has the effect of drawing the children of
+// the node to a temporary buffer of the specified size which is then
+// composited in place like an image.  This is useful for ensuring
+// correct blending of layered content.
+struct LayerNodeOp {
+  // The size of the layer to create.
+  mojo.Size layer_size;
+
+  // The blending parameters.  If null, uses the default values specified
+  // in the |Blend| structure declaration.
+  Blend? blend;
+};
+
+// Specifies a color to draw.
+// TODO(jeffbrown): This is silly but unambiguous for prototyping.
+// Make it less silly.
+struct Color {
+  uint8 red;
+  uint8 green;
+  uint8 blue;
+  uint8 alpha;
+};
+
+// 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.
+};