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

library fuchsia.ui.pointer;

using fuchsia.input.report as device;
using zx;

const uint32 MOUSE_MAX_EVENT = 128;

/// A method for a client to receive mouse pointer events.
///
/// The position of a pointer event is defined in the context of a viewport,
/// situated in the view. The dimensions of the view and viewport, and their
/// spatial relationship (defined with a transform matrix), are supplied
/// synchronously in a |ViewParameter| table. A view may retrieve a pointer's
/// position in its local coordinate system by applying the viewport-to-view
/// transform matrix.
///
/// The viewport is embedded in an independent and stable coordinate system,
/// suitable for interpreting pointer events in a scale-independent manner;
/// mouse movement will be observed at a constant scale, even under effects such
/// as magnification or panning. However, other effects, such as enlargening the
/// view's clip bounds, may trigger a change in the viewport extents.
protocol MouseSource {
    /// A method for a client to receive mouse pointer events.
    ///
    /// This call is formulated as a "hanging get" pattern: the client asks for
    /// a set of recent events, and receives them via the callback. This
    /// pull-based approach ensures that clients consume events at their own
    /// pace; events don't clog up the channel in an unbounded manner.
    ///
    /// Flow control. The caller is allowed at most one in-flight |Watch| call
    /// at a time; it is a logical error to have concurrent calls to |Watch|.
    /// Non-compliance results in channel closure.
    ///
    /// Client pacing. The server will dispatch events to the caller on a FIFO,
    /// lossless, best-effort basis, but the caller must allocate enough time to
    /// keep up with new events.
    ///
    /// Event times. The timestamps on each event in the event vector are *not*
    /// guaranteed monotonic; events from different devices may be injected into
    /// Scenic at different times. Generally, events from a single device are
    /// expected to have monotonically increasing timestamps.
    ///
    /// View parameters. Occasionally, changes in view or viewport require
    /// notifying the client. If a |MouseEvent| carries |ViewParameters|, these
    /// parameters apply to successive |MousePointerSample|s until the next
    /// |ViewParameters|.
    Watch() -> (vector<MouseEvent>:MOUSE_MAX_EVENT events);
};

/// The self-sufficient, self-consistent collection of pointer-related data,
/// sent from server to client.
table MouseEvent {
    /// The time this event was observed.
    /// Required.
    1: zx.time timestamp;

    /// The parameters of the associated view and viewport, sufficient to
    /// correctly interpret the position, orientation, magnitude, and
    /// inter-event distance of pointer events dispatched to a view.
    /// - It is issued on connection and on change.
    2: ViewParameters view_parameters;

    /// A description of the mouse device, sufficient to correctly interpret
    /// the capabilities and usage intent of the device.
    /// - It is issued once per device.
    3: MouseDeviceInfo device_info;

    /// A description of each sampled data point in a mouse event stream.
    ///
    /// Issuance policy. There are two dispatch modes, "hover" and "latched".
    /// Hover mode is default, and the stream is dispatched in fragments to the
    /// visible client that each mouse event hovers above. Latched mode directs
    /// the stream to a single client (regardless of view boundary) until
    /// unlatched. Latched mode is typically toggled when the user presses the
    /// primary mouse button, but is ultimately a product-specific policy.
    4: MousePointerSample pointer_sample;

    /// The signal for view entry/exit in hover mode.
    /// - It is issued on hover entry into a view, and hover exit from a view.
    5: MouseEventStreamInfo stream_info;

    /// An identifier to correlate this event's send/receive occurrence across
    /// component boundaries or abstraction layers.
    6: uint64 trace_flow_id;
};

/// Information about a device that issues a mouse event stream.
table MouseDeviceInfo {
    /// An identifier for the mouse device that issues a mouse event stream.
    /// Required.
    1: uint32 id;

    /// Range of vertical scroll values issued by the device.
    2: device.Axis scroll_v_range;

    /// Range of horizontal scroll values issued by the device.
    3: device.Axis scroll_h_range;

    /// Button identifiers issued by the device.
    4: vector<uint8>:device.MOUSE_MAX_NUM_BUTTONS buttons;
};

/// A description of each sampled data point in a mouse event stream.
table MousePointerSample {
    /// An identifier for the mouse device that issues a mouse event stream.
    /// Required.
    1: uint32 device_id;

    /// The state of this event in the mouse event stream's state machine.
    /// Required.
    2: EventPhase phase;

    /// The position of this event, in the viewport's coordinate system.
    /// Required.
    3: Point2 position_in_viewport;

    /// Relative vertical scrolling displacement.
    4: int64 scroll_v;

    /// Relative horizontal scrolling displacement.
    5: int64 scroll_h;

    /// Identifiers of currently pressed buttons.
    6: vector<uint8>:device.MOUSE_MAX_NUM_BUTTONS pressed_buttons;
};

/// The status of a mouse event stream, sent from server to client.
///
/// Invariant: a client's mouse events are bracketed by
/// [`MouseViewStatus.ENTERED`] and [`MouseViewStatus.EXITED`].
///
/// This information is provided separately from the EventPhase state machine,
/// because it is a property of the event stream interacting with the scene,
/// instead of a property of the mouse device.
struct MouseEventStreamInfo {
    /// An identifier for the mouse device that issues a mouse event stream.
    uint32 device_id;

    /// The mouse event stream's enter/exit status, sent from server to client.
    MouseViewStatus status;
};

/// A description of mouse event stream's relationship to this view.
enum MouseViewStatus {
    /// The stream is directed towards this view.
    ENTERED = 1;

    /// The stream is directed away from this view.
    EXITED = 2;
};