Mozart: Add hit testing interfaces.

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
index 602ec44b591c4917e8811dc1028f7dde88034d59..31420a95de880572314e52aef62ac5c230e100a6 100644
--- a/mojo/services/gfx/composition/interfaces/nodes.mojom
+++ b/mojo/services/gfx/composition/interfaces/nodes.mojom
@@ -55,6 +55,46 @@ import "mojo/services/gfx/composition/interfaces/hit_tests.mojom";
 // missing content for an earlier version of that content or for a placeholder
 // if not available.
 //
+// HIT TESTING
+//
+// Hit testing is the process of determining which nodes within a scene graph
+// should be responsible for handling events which occur within their visual
+// space on the screen.
+//
+// For example, when the user touches objects on a touch screen, the input
+// system asks the compositor to performs a hit test at the contact point to
+// find the nodes which represent the objects the user wants to interact with.
+// The result of the hit test is a list of nodes, in dispatch order, which
+// have asked to participate in handling events related to the contact point.
+//
+// Nodes may be opaque, translucent, or invisible to the hit testing
+// process depending on whether they prevent or allow targets visually
+// behind them from being hit and whether they can actually be hit,
+// as specified by |HitTestBehavior.visibility|.
+//
+// Nodes are added to the hit test result whenever one of their opaque children
+// is hit.  This is useful for scrolling containers which may need to intercept
+// certain gestures within the space of their children and therefore need to
+// be added to the hit test result themselves.
+//
+// Nodes can also request to prune hit testing for their children, which
+// prevents their children from being hit.
+//
+// Hit testing proceeds recursively in post-order traversal (the reverse of
+// the drawing order).  Intuitively, this means that the most specific
+// (deepest) nodes of the tree are tested before their ancestors.
+//
+// Starting from the root, the compositor transforms the point of interest
+// into the node's coordinate system, rejects the node if the point is
+// outside of the node's clip region, otherwise recursively tests the
+// node's children (those which were selected by the combinator rule)
+// until the first opaque target hit is found, then evaluates the node's
+// |HitTestBehavior| to determine whether the node was hit.  Nodes are
+// accumulated into a hit test result in the order in which they were
+// determined to have been hit.
+//
+// See |HitTestBehavior| for more details.
+//
 // INSTANCING
 //
 // The compositor allows nodes to be referenced and reused multiple times
@@ -128,15 +168,13 @@ struct Node {
   // 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;

[abarth, 2016/03/01 17:33:43]

It looks like you've removed the concept of a hit_id and just used the node_id
instead.  It's slightly more flexible if you like the client assign IDs for hit
testing separately from how they assign IDs for the nodes.  Of course, they're
free to use the node ID for the hit ID, but some clients might want to use
separate systems to assign the IDs.  Specifically, in Flutter, the compositor
might be in charge of assigning node IDs but the framework might want to assign
hit IDs.

[jeffbrown, 2016/03/02 00:51:52]

*nod*  I got rid of this as part of an exercise to see if we could get away with
something more minimal.  I think I'm going to leave this out for the moment
since clients can perform their own mapping without extra assistance from the
compositor anyhow.  But if it's too painful I might put it back in or add
something else.

-
   // The Combinator to apply when processing the children of this node.
   Combinator combinator = Combinator.MERGE;
 
+  // The hit testing behavior of the node.
+  // If null, the node is considered invisible for hit testing.
+  HitTestBehavior? hit_test_behavior;
+
   // 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 or which creates a cycle in the graph; the compositor will close