// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
/// These augmentation protocols represent powerful introspection capabilities
/// into the view hierarchy, and must be individually routed to specific target
/// components. Most clients should not have access to these protocols. Some
/// commonalities:
/// - Theory of operation. These augmentation protocols accept a standard
///   protocol endpoint and return an augmented protocol endpoint. In case of
///   error, the original endpoint is returned.
/// - View hierarchy scope. The reach of the augmented protocols are inherently
///   bound to the original protocols they augment. That is, if the original
///   protocol has power over only one view, the augmented protocol gives access
///   to only that view.
/// - Security warning. These protocols enable a form of clickjacking! While the
///   view hierarchy prevents clickjacking of arbitrary views, care must be
///   taken to route these augmentation protocols to the intended view's
///   component.
/// - Security guarantees. These protocols offer Confidentiality, Integrity, and
///   Availability of the augmented data to authorized components. That is,
///   non-authorized components cannot snoop on this data, modify its contents,
///   or prevent its dispatch to authorized components.
/// - Append semantics. Each augmentation provides augmentation-specific data to
///   the protocol's regular event, but otherwise is not intended to modify the
///   original protocol's basic functionality.
/// - Synchronicity. The augmentation-specific data is synchronous with the
///   original protocol's data.
/// - API evolution. Server-side can introduce new methods to these protocols,
///   and new fields to these tables, without breaking existing clients of the
///   original or augmented protocol.
/// - API evolution. When clients require substantially different augmentation,
///   new augmentation protocols representing those capabilities can (and
///   should) be introduced.
@available(added=7)
library fuchsia.ui.pointer.augment;

using fuchsia.ui.pointer as pointer;
using zx;

/// Abnormal conditions for augmentation protocols.
type ErrorReason = strict enum {
    /// The augmentation attempt was denied.
    DENIED = 1;
};

// LOCAL HIT AUGMENTATION

// Abnormal return for local hit.
type ErrorForLocalHit = resource struct {
    /// Abnormal reason for return.
    error_reason ErrorReason;

    /// Original protocol endpoint for client use.
    original client_end:pointer.TouchSource;
};

/// A method for a client to upgrade its touch event protocol to additionally
/// receive local-hit data for touch events.
@discoverable
closed protocol LocalHit {
    /// An exchange from an `original` touch protocol endpoint to an `augmented`
    /// touch protocol endpoint. If successful, `error` is empty, `original` is
    /// consumed, and `augmented` is returned for the client's use. Otherwise,
    /// the `error` carries back `original` for the client's use, and
    /// `augmented` is null.
    strict Upgrade(resource struct {
        original client_end:pointer.TouchSource;
    }) -> (resource struct {
        augmented client_end:<TouchSourceWithLocalHit, optional>;
        error box<ErrorForLocalHit>;
    });
};

/// Like [`fuchsia.ui.pointer.TouchSource`], but with additional information
/// about the local-hit position of touch events, and otherwise identical in
/// operation. See [`fuchsia.ui.pointer.TouchSource`] for regular usage
/// information.
closed protocol TouchSourceWithLocalHit {
    /// Identical usage to [`fuchsia.ui.pointer.TouchSource.Watch`], but with
    /// augmented data.
    strict Watch(struct {
        responses vector<pointer.TouchResponse>:pointer.TOUCH_MAX_EVENT;
    }) -> (struct {
        events vector<TouchEventWithLocalHit>:pointer.TOUCH_MAX_EVENT;
    });
    /// Identical usage to [`fuchsia.ui.pointer.TouchSource.UpdateResponse`].
    strict UpdateResponse(struct {
        interaction pointer.TouchInteractionId;
        response pointer.TouchResponse;
    }) -> ();
};

/// A floating point two-dimensional point.
/// - The values are placed in (x, y) order.
alias Point2 = array<float32, 2>;

/// An augmentation of [`fuchsia.ui.pointer.TouchEvent`] to provide local-hit
/// data for a touch event.
///
/// For a given touch event `e`, consider the ordered list of intersections with
/// graphical content: its "hits" from top to bottom. The "local hit" of `e` is
/// the location of `e` in the coordinate system of the view in which `e` has
/// the top-most intersection.
type TouchEventWithLocalHit = struct {
    /// Identical usage to [`fuchsia.ui.pointer.TouchEvent`].
    touch_event pointer.TouchEvent;

    /// Augmented data for `touch_event` that describes the top-most client
    /// KOID that it hits.
    local_viewref_koid zx.Koid;

    /// Augmented data for `touch_event` that describes its local coordinates in
    /// the coordinate space for `local_viewref_koid`.
    local_point Point2;
};