// 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
type Range = struct {
    min int32;
    max int32;
};

type RangeF = struct {
    min float32;
    max float32;
};

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

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

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

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

// Keyboards

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

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

// Mouse

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

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

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

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

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

    // buttons currently down
    pressed_buttons uint32;
};

// Stylus

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

    // Range for the pressure of the tip
    pressure box<Axis>;

    @allow_deprecated_struct_defaults
    is_invertible bool = false;

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

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

    // Pressure applied on the stylus tip
    pressure uint32;

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

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

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

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

// Touchscreen

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

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

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

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

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

// Motion Sensors

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

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

type SensorLocation = flexible enum {
    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.
type SensorDescriptor = struct {
    type SensorType;
    loc SensorLocation;

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

    // 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.
    phys_min int32;
    phys_max int32;
};

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

/// `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.
type MediaButtonsReport = struct {
    volume_up bool;
    volume_down bool;
    mic_mute bool;
    reset bool;
    pause bool;
    camera_disable bool;
};

// Device and Report

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

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

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

    keyboard box<KeyboardReport>;
    media_buttons box<MediaButtonsReport>;
    mouse box<MouseReport>;
    stylus box<StylusReport>;
    touchscreen box<TouchscreenReport>;
    sensor SensorReport:optional;

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