Mozart: Add hit testing interfaces.

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;
@@ skipping 37 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.
 //
+// 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
 // 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.
@@ skipping 53 matching lines @@
   // 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 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
   // 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;
 };
@@ skipping 92 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.
 };