Mozart: Add hit testing interfaces.

mojo/services/gfx/composition/interfaces/hit_tests.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.
 
 [DartPackage="mojo_services"]
 module mojo.gfx.composition;
 
 import "mojo/services/geometry/interfaces/geometry.mojom";
 import "mojo/services/gfx/composition/interfaces/scene_token.mojom";
 
-// Indicates that hit testing is not needed for a given node.
-const uint32 kHitIdNone = 0;
+// Determines how a node behaves during hit testing.
+//
+// See |Node| for more details of the hit testing traversal process.
+struct HitTestBehavior {
+  // The visibility specifies how a node itself is hit and its effect on
+  // the hit testing traversal.
+  enum Visibility {
+    // The node can be hit and prevents other targets visually behind the
+    // node from being hit.  This is the default.
+    //
+    // Opaque targets are useful for UI elements like buttons which cover and
+    // block interaction with content visually behind them.
+    OPAQUE,
 
-// Provides information about the point of intersection of a hit test with
-// a node in a scene graph.
-struct Hit {
-  // The scene token of the scene which was hit.
+    // The node can be hit and allows other targets visually behind the node
+    // to also be hit.
+    //
+    // Translucent targets are useful for UI elements like dimissed drawers
+    // which may not obscure content visually behind them but which do need
+    // to intercept gestures in that area (perhaps to reveal themselves).
+    TRANSLUCENT,
+
+    // The node cannot be hit.
+    //
+    // Invisible targets are useful for explicitly suppressing hit testing
+    // for a node and its children when combined with the |prune| flag.
+    INVISIBLE,
+  };
+
+  // Specifies the visibility of the node for hit testing purposes.
+  // The default is opaque.
+  Visibility visibility = Visibility.OPAQUE;
+
+  // When set to true, prevents a node's children from being hit tested.
+  bool prune = false;
+
+  // The rectangle within the node's content space to test for hits.
+  // If null, the node's entire clip region is tested for hits.
+  //
+  // TODO(jeffbrown): Support more complex hit test regions and masks.
+  mojo.Rect? hit_rect;
+};
+
+// The result of a hit test operation.
+//
+// Hit test results form a tree which describes which nodes were hit within
+// the scene graph.  It is essentially a subtree of the scene graph which
+// only includes nodes which were hit by the hit test.  Structural information
+// about the scene graph is retained but only limited information about the
+// nodes themselves is included.
+//
+// To walk the hits in dispatch order, perform a post-order traversal of the
+// hit tree, processing children before their parents.
+struct HitTestResult {
+  // If a hit occurred, contains information about hits which occurred within
+  // the root scene of the scene graph.
+  SceneHit? scene_hit;
+};
+
+// Describes a collection of hits within a scene in the scene graph.
+struct SceneHit {
+  // The scene token of the scene which contains the hit.
   SceneToken scene_token;
 
-  // The version of the scene which was consulted as part of evaluating the
-  // hit test.
+  // The version of the scene which was consulted at the time the hit test
+  // was performed.
   uint32 scene_version;
 
+  // The nodes which were hit, in order of traversal.
+  // This list always contains at least one node.
+  array<NodeHit> node_hits;
+};
+
+// Describes the point of intersection of a hit test with a particular
+// node within a scene.
+struct NodeHit {
   // The node id of the node which was hit.
   uint32 node_id;
 
-  // The hit test id of the node which was hit.
-  uint32 hit_id;
+  // True if the node was visible to hit testing and would like to receive
+  // events related to the hit.  False if the node is only being included
+  // for structural reasons because of a scene which it references which
+  // was hit.
+  bool visible;
 
   // The coordinates of the hit within the node's content space.
   mojo.Point intersection;
-};
 
-// The result of a hit test operation.
-struct HitTestResult {
-  // A sorted list of hits in dispatch order from the top-most hit node
-  // to the nodes underneath it and containing it, or an empty array if none.
-  // Omits nodes for which the hit_id was |kHitIdNone|.
-  array<Hit> hits;
+  // If the node had a |SceneNodeOp| and a hit occurred within the scene
+  // which it referenced, contains information about the hits which occurred
+  // within that scene.
+  SceneHit? scene_hit;
 };

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

I was expecting NodeHit to have an array<NodeHit>, but I guess you just flatten
those up into SceneHit...  Maybe change the docs for HitTestResult to reflect
this?  It current says this is a subtree, but it's got a different tree
structure.

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

Good point.  I'm not reflecting the entire node structure here because I don't
think we need it, but I should make that clearer.

I'm also not fond of the naming convention.  |NodeHit| is kind of weird when
it's possible for the node to be invisible and only be carrying scene
information.  Open to suggestions.

I think I'm going to try to get rid of the usage of |visible| here.

 
 // A hit testing service for scene graphs.
 interface HitTester {
   // Performs a hit test on the specified point.
   //
   // TODO(jeffbrown): Specify a timestamp to allow for hit-tests of geometry
   // as it appeared in the recent past.
   HitTest(mojo.Point point) => (HitTestResult result);
 };