// Copyright 2017 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.input;

// Descriptors are used to describe the capabilities of an input device.
//
// Devices can have multiple descriptors of multiple kinds, for example:
// `KeyboardDescriptor`, `MouseDescriptor`, `StylusDescriptor`,
// `TouchscreenDescriptor` and `SensorDescriptor`
//
// An input device will generate `InputReport` corresponding to the
// capabilities of that device listed in its descriptor.
// For instance a input device with a `KeyboardDescriptor` will generate
// `KeyboardReport` when a key is pressed on the keyboard.

// Describe a `Range` of values
struct Range {
    int32 min;
    int32 max;
};

struct RangeF {
    float32 min;
    float32 max;
};

enum AxisScale {
    LINEAR = 0;
    LOGARITHMIC = 1;
};

// An `Axis` is defined as a `range` and `resolution`.
struct Axis {
    Range range;
    int32 resolution = 1;
    AxisScale scale = AxisScale.LINEAR;
};

struct AxisF {
    RangeF range;
    float32 resolution = 1.0;
    AxisScale scale = AxisScale.LINEAR;
};

// `MediaButtonsDescriptor` describes the media buttons.
struct MediaButtonsDescriptor {
    // A bitmask that represents the list of media buttons available.
    // The mask bit values are located in usages.fidl.
    uint32 buttons;
};

// Keyboards

// `KeyboardDescriptor` describes the capabilities of a keyboard.
struct KeyboardDescriptor {
    // The list of HID keyboard usages that this keyboard can generate.
    vector<uint32> keys;
};

// `KeyboardReport` lists the keys currently pressed down.
struct KeyboardReport {
    // `pressed_keys` is the list of HID usage that are currently pressed down on
    // the keyboard.
    vector<uint32> pressed_keys;
};

// Mouse

// `MouseDescriptor` describes the capabilities of a mouse.
struct MouseDescriptor {
    // The range of relative X and Y movement which can be described by a mouse
    // report.
    Axis rel_x;
    Axis rel_y;

    // The range of relative vertical and horizontal scroll which can be
    // described by a mouse report.
    Axis? vscroll;
    Axis? hscroll;

    // The list of HID mouse usages that this mouse can generate.
    uint32 buttons;
};

// `MouseReport` gives the relative mouvement of the mouse and currently
// pressed buttons.
struct MouseReport {
    // Relative X and Y positional displacement.
    int32 rel_x;
    int32 rel_y;

    // Relative horizontal and vertical scrolling displacement.
    int32 rel_hscroll;
    int32 rel_vscroll;

    // buttons currently down
    uint32 pressed_buttons;
};

// Stylus

// `Stylus` describes the capabilities of a stylus.
struct StylusDescriptor {
    // Ranges for the `x` and `y` axis of the stylus.
    Axis x;
    Axis y;

    // Range for the pressure of the tip
    Axis? pressure;

    bool is_invertible = false;

    // The list of HID button usages that this stylus can generate.
    uint32 buttons;
};

// `StylusReport` describes the current state of the stylus.
struct StylusReport {
    // Current position of the stylus within the range described in
    // `StylusDescriptor`
    int32 x;
    int32 y;

    // Pressure applied on the stylus tip
    uint32 pressure;

    // Whether the stylus has made contact with the surface.
    bool is_in_contact;

    // Whether the stylus is within range. If `is_in_contact` is false, then the stylus
    // is hovering.
    bool in_range;

    // Whether the stylus is thought to be inverted.
    bool is_inverted;

    // List of buttons currently pressed down.
    uint32 pressed_buttons;
};

// Touchscreen

// `TouchscreenDescriptor` describes the capabilities of a touchscreen.
struct TouchscreenDescriptor {
    // Ranges of the `x` and `y` axis.
    Axis x;
    Axis y;
    uint32 max_finger_id;
};

// `Touch` describes one touch on a touchscreen, which should correspond to
// one finger.
struct Touch {
    // Identifier for a finger that is down.
    // Note: `finger_id` might not be sequential and will range from 0 to
    // `max_finger_id`
    uint32 finger_id;

    // Location within the axis defined in `TouchscreenDescriptor`
    int32 x;
    int32 y;

    // Area pressed.
    uint32 width;
    uint32 height;
};

// `TouchscreenReport` describes the current touches recorded by the touchscreen
// and holds a `Touch` per finger down.
struct TouchscreenReport {
    vector<Touch> touches;
};

// Motion Sensors

// Descriptive categories for sensor devices.
// We assume that each (SensorType,SensorLocation) pair is unique to the system.

enum SensorType {
    ACCELEROMETER = 0;
    GYROSCOPE = 1;
    MAGNETOMETER = 2;
    LIGHTMETER = 3;
};

enum SensorLocation {
    UNKNOWN = 0;
    BASE = 1;
    LID = 2;
};

// `SensorDescriptor` describes the capabilities of a sensor device.  It does
// not capture properties that can be changed after initialization, such as the
// current sampling frequency.
struct SensorDescriptor {
    SensorType type;
    SensorLocation loc;

    // Min and max sampling frequencies for a sensor.
    uint32 min_sampling_freq;
    uint32 max_sampling_freq;
    // Max number of sensor events that could be in hardware FIFO.
    uint32 fifo_max_event_count;

    // Physical range of a specific sensor.
    // Accelerometer ranges are given in Gs.
    // Gyroscope ranges are given in deg/s.
    // Magnetometer ranges are given in multiples of 1/16 uT.
    // Light meter ranges can be given in Lux or units not specified.
    int32 phys_min;
    int32 phys_max;
};

// `SensorReport` describes the sensor event delivered from the event stream.
union SensorReport {
    1: array<int16>:3 vector;
    2: uint16 scalar;
};

/// `MediaButtonsReport` describes the media buttons event delivered from the event stream.
/// Each bool in the report represents a single button where true means the button
/// is being pressed. A single report should be sent on every state change.
struct MediaButtonsReport {
    bool volume_up;
    bool volume_down;
    bool mic_mute;
    bool reset;
    bool pause;
};

// Device and Report

struct DeviceInfo {
    uint32 vendor_id;
    uint32 product_id;
    uint32 version;
    string name;
};

// `DeviceDescriptor` describes one input device.
struct DeviceDescriptor {
    DeviceInfo? device_info;
    KeyboardDescriptor? keyboard;
    MediaButtonsDescriptor? media_buttons;
    MouseDescriptor? mouse;
    StylusDescriptor? stylus;
    TouchscreenDescriptor? touchscreen;
    SensorDescriptor? sensor;
};

// `InputReport` is an input `report` triggered by an input device.
struct InputReport {
    // `event_time` is in nanoseconds when the event was recorded.
    uint64 event_time;

    KeyboardReport? keyboard;
    MediaButtonsReport? media_buttons;
    MouseReport? mouse;
    StylusReport? stylus;
    TouchscreenReport? touchscreen;
    SensorReport? sensor;

    uint64 trace_id = 0; // Unique ID to connect trace async begin/end events.
};