// 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";

// 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,

    // 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 or reference scenes 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.RectF? hit_rect;
};

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

// The result of a hit test operation.
//
// Hit test results form a hit tree with information about the nodes which
// were hit and the scenes which contain them.  The structure of the hit
// tree reflects the path that the scene graph was traversed during the
// hit test.
//
// To walk the hit nodes in dispatch order, perform a post-order traversal
// of the hit tree starting at |root| and processing children before their
// parents.
struct HitTestResult {
  // A tree of hits beginning at the root scene, or null if nothing was hit.
  SceneHit? root;
};

// An element in a hit tree.
// This either contains a reference to another scene which contains hits or
// to a specific node within the containing scene which was hit.
union Hit {
  SceneHit scene;
  NodeHit node;
};

// Describes a collection of hits within a scene.
struct SceneHit {
  // The scene token of the scene which contains hits.
  SceneToken scene_token;

  // The version of the scene which was consulted at the time the hit test
  // was performed.
  uint32 scene_version;

  // The array of hits within this scene, in dispatch order.
  // This list always contains at least one entry.
  array<Hit> hits;
};

// Describes the intersection of a hit test with a node.
struct NodeHit {
  // The node id of the node which was hit.
  uint32 node_id;

  // The transformation from the global coordinate system of the scene graph
  // to the local coordinate system of the node's content space at the time
  // the hit test was performed.
  //
  // To obtain the point of intersection of the hit test within the node's
  // content space, multiply this transformation matrix by the hit test point.
  mojo.Transform transform;
};