// 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. For example, [`MouseEventWithGlobalMouse`]
///   can be extended without consequences for
///   [`fuchsia.ui.pointer.MouseEvent`].
/// - API evolution. When clients require substantially different augmentation,
///   new augmentation protocols representing those capabilities can (and
///   should) be introduced. For example, if one client of [`GlobalMouse`]
///   requires additional fields that are really about view-local hit data, it
///   would be reasonable to mint a new augmentation.
@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;
};

// GLOBAL MOUSE AUGMENTATION

/// Abnormal return for global mouse.
type ErrorForGlobalMouse = resource struct {
    /// Abnormal reason for return.
    error_reason ErrorReason;

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

/// A method for a client to receive view-global visibility for mouse behavior.
/// - The augmented data are scoped to the view of the client.
protocol GlobalMouse {
    /// An exchange from an `original` mouse protocol endpoint to an `augmented`
    /// mouse 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.
    Upgrade(resource struct {
        original client_end:pointer.MouseSource;
    }) -> (resource struct {
        augmented client_end:<MouseSourceWithGlobalMouse, optional>;
        error box<ErrorForGlobalMouse>;
    });
};

/// Like [`fuchsia.ui.pointer.MouseSource`], but with additional information
/// about the global position of mouse events, and otherwise identical in
/// operation. See [`fuchsia.ui.pointer.MouseSource`] for regular usage
/// information.
protocol MouseSourceWithGlobalMouse {
    /// Identical usage to [`fuchsia.ui.pointer.MouseSource.Watch`], but with
    /// augmented data.
    Watch() -> (struct {
        events vector<MouseEventWithGlobalMouse>:pointer.MOUSE_MAX_EVENT;
    });
};

/// An augmentation of [`fuchsia.ui.pointer.MouseEvent`] to provide global
/// visibility for mouse behavior in the injection subtree.
/// - The augmented data is scoped to the view of the client, meaning no events
///   will be delivered when the mouse pointer is outside the view (even when
///   the stream is latched to this view).
/// - Augmented data is only produced for events injected either into or above
///   the view in the scene graph.
///   -  This means that local events ~= global events when the view is the
///      root of the injection subtree.
///   -  Otherwise the client will see all events up to root of the injection
///      subtree.
type MouseEventWithGlobalMouse = table {
    /// Identical usage to [`fuchsia.ui.pointer.MouseEvent`]. In particular, if
    /// the client's view is obscured, `mouse_event` will be empty.
    1: mouse_event pointer.MouseEvent;

    /// Augmented data that describes the position of a `mouse_event` within the
    /// client's view, regardless of obscuring or latching.
    2: global_position pointer.MousePointerSample;

    /// Augmented data that describes when the mouse stream enters or exits
    /// the client's view.
    3: global_stream_info pointer.MouseEventStreamInfo;
};

// 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
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.
    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.
protocol TouchSourceWithLocalHit {
    /// Identical usage to [`fuchsia.ui.pointer.TouchSource.Watch`], but with
    /// augmented data.
    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`].
    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;
};