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

/// A hardcoded number of max contacts per report. This should be increased in the future if
/// we see devices with more than the max amount.
const TOUCH_MAX_CONTACTS uint32 = 10;
const TOUCH_MAX_NUM_BUTTONS uint32 = 10;

/// The device type from which the touch originated.
type TouchType = flexible enum : uint32 {
    /// A touch screen has direct finger input associated with a display.
    TOUCHSCREEN = 1;
    /// A touch pad is a pointer device that tracks finger positions.
    TOUCHPAD = 2;
};

/// `ContactInputDescriptor` describes the fields associated with a touch on a touch device.
type ContactInputDescriptor = table {
    /// Describes the reporting of the x-axis.
    1: position_x Axis;

    /// Describes the reporting of the y-axis.
    2: position_y Axis;

    /// Pressure of the contact.
    3: pressure Axis;

    /// Width of the area of contact.
    4: contact_width Axis;

    /// Height of the area of contact.
    5: contact_height Axis;
};

/// Describes the format of the input report that will be sent from the keyboard
/// to the device.
type TouchInputDescriptor = table {
    /// The contact descriptors associated with this touch descriptor.
    1: contacts vector<ContactInputDescriptor>:TOUCH_MAX_CONTACTS;

    /// The max number of contacts that this touch device can report at once.
    2: max_contacts uint32;

    /// The type of touch device being used.
    3: touch_type TouchType;

    /// Identifiers for the physical buttons on a touch device.
    4: buttons vector<uint8>:TOUCH_MAX_NUM_BUTTONS;
};

/// Input mode indicating which top-level collection should be used for input reporting.
/// These values must correspond to the input modes defined in 16.7 of the HID Usage Tables
/// for Universal Serial Bus (USB) Spec (https://usb.org/sites/default/files/hut1_22.pdf).
type TouchConfigurationInputMode = flexible enum : uint32 {
    /// Use the Mouse Collection for reporting data.
    MOUSE_COLLECTION = 0;
    /// Use the Windows Precision Touchpad Collection for reporting data. Defined by Windows
    /// Precision Touchpad Required HID Top-Level Collections: https://docs.microsoft.com/
    /// en-us/windows-hardware/design/component-guidelines/windows-precision-touchpad-required
    /// -hid-top-level-collections).
    WINDOWS_PRECISION_TOUCHPAD_COLLECTION = 3;
};

/// Describes the format of the touchpad configuration's feature report. Feature reports
/// can be requested from the touchpad, or sent to the touchpad.
type TouchFeatureDescriptor = table {
    /// Indicates whether or not touch feature descriptor supports different input modes.
    1: supports_input_mode bool;

    /// Indicates whether or not touch feature descriptor supports selective reporting.
    2: supports_selective_reporting bool;
};

/// The capabilities of a touch device.
type TouchDescriptor = table {
    1: input TouchInputDescriptor;

    2: feature TouchFeatureDescriptor;
};

/// `ContactInputReport` describes one touch on a touch device.
type ContactInputReport = table {
    /// Identifier for this contact.
    1: contact_id uint32;

    /// A contact's position on the x axis.
    2: position_x int64;

    /// A contact's position on the y axis.
    3: position_y int64;

    /// Pressure of the contact.
    4: pressure int64;

    /// Width of the bounding box around the touch contact. Combined with
    /// `contact_height`, this describes the area of the touch contact.
    /// `contact_width` and `contact_height` should both have units of distance,
    /// and they should be in the same units as `position_x` and `position_y`.
    5: contact_width int64;

    /// Height of the bounding box around the touch contact. Combined with
    /// `contact_width`, this describes the area of the touch contact.
    /// `contact_width` and `contact_height` should both have units of distance,
    /// and they should be in the same units as `position_x` and `position_y`.
    6: contact_height int64;

    /// Also known as touch valid. Indicates the device’s confidence that the touch
    /// contact was an intended, valid contact. The device should report 0 if the
    /// contact is not a valid touch. The device should report 1 if the contact is
    /// intended and valid (e.g. a pointing touch)
    @available(added=9)
    7: confidence bool;
};

/// `TouchInputReport` describes the current contacts recorded by the touchscreen.
type TouchInputReport = table {
    /// The contacts currently being reported by the device.
    1: contacts vector<ContactInputReport>:TOUCH_MAX_CONTACTS;

    /// Identifiers for currently pressed buttons.
    2: pressed_buttons vector<uint8>:TOUCH_MAX_NUM_BUTTONS;
};

/// Selective Reporting Feature Report indicating which types of input are reported.
type SelectiveReportingFeatureReport = table {
    /// If this is true, the device will report surface contacts.
    1: surface_switch bool;

    /// If this is true, the device will report button state.
    2: button_switch bool;
};

/// A TouchFeatureReport describes the features of a given touch device. If a
/// FeatureReport is sent to the Input Device it sets the configuration of the device.
/// If a FeatureReport is requested from the Input Device it shows the device's
/// current configuration.
type TouchFeatureReport = table {
    /// The input mode currently reporting.
    1: input_mode TouchConfigurationInputMode;

    /// The current report types being reported.
    2: selective_reporting SelectiveReportingFeatureReport;
};