Initial checkin of the new Mozart compositor.

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
+// 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 region 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.
+  Clip? content_clip;

[abarth, 2016/01/10 04:22:08]

Woah there.  This should just be a rectangular clip.  More complex clips (e.g.,
RRect) should go through the LayerNodeOp.  You're going to want to do all sorts
of transformations with rectangular clips that you can't do with the more
complex clips (e.g., push them down to the images to restrict the source_rects).

Also, RRect clips can't be done with proper antialiasing without an intermediate
layer anyway.

[jeffbrown, 2016/01/16 03:28:31]

I need to put some thought into whether nodes have strict visual containment
too.  For now, I'll just drop RRects entirely.

+
+  // 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.

[abarth, 2016/01/10 04:22:09]

Yeah.  :)

It should be enough to get going though.

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

[abarth, 2016/01/10 04:22:09]

Sometimes we call this the source_rect

[jeffbrown, 2016/01/16 03:28:31]

Right.  I adopted this convention to line up with |image_resource_id| below to
make it clearer that they go hand-in-hand.

+
+  // 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 {

[abarth, 2016/01/10 04:22:08]

Oh, interesting.  I thought this was going to be something different.  I thought
you were going to give me a way to cache pixels in the compositor by letting me
create a node that retained its intermediate state.  Then I could use that
object in layer scenes until it was freed.  Obviously that's something we can
add later.  ;)

[jeffbrown, 2016/01/16 03:28:31]

Technically you can get that behavior simply by embedding the same layer node
multiple times in different places (a big benefit of having a DAG).  But we
might want to do something different here in the long run.

+  // 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 clip region as a rectangle or rounded rectangle.
+union Clip {

[abarth, 2016/01/10 04:22:09]

I'd skip having this union and just have the clips separated.  RRect and Rect
clips are so different from each other.

[jeffbrown, 2016/01/16 03:28:31]

Done.

+  mojo.Rect rect;
+  mojo.RRect rrect;
+  // TODO(jeffbrown): paths and masks
+};
+
+// Specifies a color to draw.
+// TODO(jeffbrown): This is silly but unambiguous for prototyping.
+// Make it less silly.

[abarth, 2016/01/10 04:22:08]

I'd have used a single uint32 with a defined color channel order (RGBA_8888
probably).

[jeffbrown, 2016/01/16 03:28:31]

Yeah, I'll probably land there.  Will leave it for later.

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