MdePkg/Include/Protocol/AbsolutePointer.h

   1 /** @file
   2   The file provides services that allow information about an
   3   absolute pointer device to be retrieved.
   4
   5   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8   @par Revision Reference:
   9   This Protocol was introduced in UEFI Specification 2.3.
  10
  11 **/
  12
  13 #ifndef __ABSOLUTE_POINTER_H__
  14 #define __ABSOLUTE_POINTER_H__
  15
  16 #define EFI_ABSOLUTE_POINTER_PROTOCOL_GUID \
  17   { 0x8D59D32B, 0xC655, 0x4AE9, { 0x9B, 0x15, 0xF2, 0x59, 0x04, 0x99, 0x2A, 0x43 } }
  18
  19 typedef struct _EFI_ABSOLUTE_POINTER_PROTOCOL EFI_ABSOLUTE_POINTER_PROTOCOL;
  20
  21 // *******************************************************
  22 // EFI_ABSOLUTE_POINTER_MODE
  23 // *******************************************************
  24
  25 /**
  26   The following data values in the EFI_ABSOLUTE_POINTER_MODE
  27   interface are read-only and are changed by using the appropriate
  28   interface functions.
  29 **/
  30 typedef struct {
  31   UINT64    AbsoluteMinX; ///< The Absolute Minimum of the device on the x-axis
  32   UINT64    AbsoluteMinY; ///< The Absolute Minimum of the device on the y axis.
  33   UINT64    AbsoluteMinZ; ///< The Absolute Minimum of the device on the z-axis
  34   UINT64    AbsoluteMaxX; ///< The Absolute Maximum of the device on the x-axis. If 0, and the
  35                           ///< AbsoluteMinX is 0, then the pointer device does not support a xaxis
  36   UINT64    AbsoluteMaxY; ///< The Absolute Maximum of the device on the y -axis. If 0, and the
  37                           ///< AbsoluteMinX is 0, then the pointer device does not support a yaxis.
  38   UINT64    AbsoluteMaxZ; ///< The Absolute Maximum of the device on the z-axis. If 0 , and the
  39                           ///< AbsoluteMinX is 0, then the pointer device does not support a zaxis
  40   UINT32    Attributes;   ///< The following bits are set as needed (or'd together) to indicate the
  41                           ///< capabilities of the device supported. The remaining bits are undefined
  42                           ///< and should be 0
  43 } EFI_ABSOLUTE_POINTER_MODE;
  44
  45 ///
  46 /// If set, indicates this device supports an alternate button input.
  47 ///
  48 #define EFI_ABSP_SupportsAltActive  0x00000001
  49
  50 ///
  51 /// If set, indicates this device returns pressure data in parameter CurrentZ.
  52 ///
  53 #define EFI_ABSP_SupportsPressureAsZ  0x00000002
  54
  55 /**
  56   This function resets the pointer device hardware. As part of
  57   initialization process, the firmware/device will make a quick
  58   but reasonable attempt to verify that the device is
  59   functioning. If the ExtendedVerification flag is TRUE the
  60   firmware may take an extended amount of time to verify the
  61   device is operating on reset. Otherwise the reset operation is
  62   to occur as quickly as possible. The hardware verification
  63   process is not defined by this specification and is left up to
  64   the platform firmware or driver to implement.
  65
  66   @param This                 A pointer to the EFI_ABSOLUTE_POINTER_PROTOCOL
  67                               instance.
  68
  69   @param ExtendedVerification Indicates that the driver may
  70                               perform a more exhaustive
  71                               verification operation of the
  72                               device during reset.
  73
  74   @retval EFI_SUCCESS       The device was reset.
  75
  76   @retval EFI_DEVICE_ERROR  The device is not functioning
  77                             correctly and could not be reset.
  78
  79 **/
  80 typedef
  81 EFI_STATUS
  82 (EFIAPI *EFI_ABSOLUTE_POINTER_RESET)(
  83   IN EFI_ABSOLUTE_POINTER_PROTOCOL *This,
  84   IN BOOLEAN                       ExtendedVerification
  85   );
  86
  87 ///
  88 /// This bit is set if the touch sensor is active.
  89 ///
  90 #define EFI_ABSP_TouchActive  0x00000001
  91
  92 ///
  93 /// This bit is set if the alt sensor, such as pen-side button, is active
  94 ///
  95 #define EFI_ABS_AltActive  0x00000002
  96
  97 /**
  98   Definition of EFI_ABSOLUTE_POINTER_STATE.
  99 **/
 100 typedef struct {
 101   ///
 102   /// The unsigned position of the activation on the x axis. If the AboluteMinX
 103   /// and the AboluteMaxX fields of the EFI_ABSOLUTE_POINTER_MODE structure are
 104   /// both 0, then this pointer device does not support an x-axis, and this field
 105   /// must be ignored.
 106   ///
 107   UINT64    CurrentX;
 108
 109   ///
 110   /// The unsigned position of the activation on the y axis. If the AboluteMinY
 111   /// and the AboluteMaxY fields of the EFI_ABSOLUTE_POINTER_MODE structure are
 112   /// both 0, then this pointer device does not support an y-axis, and this field
 113   /// must be ignored.
 114   ///
 115   UINT64    CurrentY;
 116
 117   ///
 118   /// The unsigned position of the activation on the z axis, or the pressure
 119   /// measurement. If the AboluteMinZ and the AboluteMaxZ fields of the
 120   /// EFI_ABSOLUTE_POINTER_MODE structure are both 0, then this pointer device
 121   /// does not support an z-axis, and this field must be ignored.
 122   ///
 123   UINT64    CurrentZ;
 124
 125   ///
 126   /// Bits are set to 1 in this structure item to indicate that device buttons are
 127   /// active.
 128   ///
 129   UINT32    ActiveButtons;
 130 } EFI_ABSOLUTE_POINTER_STATE;
 131
 132 /**
 133   The GetState() function retrieves the current state of a pointer
 134   device. This includes information on the active state associated
 135   with the pointer device and the current position of the axes
 136   associated with the pointer device. If the state of the pointer
 137   device has not changed since the last call to GetState(), then
 138   EFI_NOT_READY is returned. If the state of the pointer device
 139   has changed since the last call to GetState(), then the state
 140   information is placed in State, and EFI_SUCCESS is returned. If
 141   a device error occurs while attempting to retrieve the state
 142   information, then EFI_DEVICE_ERROR is returned.
 143
 144
 145   @param This   A pointer to the EFI_ABSOLUTE_POINTER_PROTOCOL
 146                 instance.
 147
 148   @param State  A pointer to the state information on the
 149                 pointer device.
 150
 151   @retval EFI_SUCCESS       The state of the pointer device was
 152                             returned in State.
 153
 154   @retval EFI_NOT_READY     The state of the pointer device has not
 155                             changed since the last call to GetState().
 156
 157   @retval EFI_DEVICE_ERROR  A device error occurred while
 158                             attempting to retrieve the pointer
 159                             device's current state.
 160
 161 **/
 162 typedef
 163 EFI_STATUS
 164 (EFIAPI *EFI_ABSOLUTE_POINTER_GET_STATE)(
 165   IN      EFI_ABSOLUTE_POINTER_PROTOCOL  *This,
 166   OUT  EFI_ABSOLUTE_POINTER_STATE        *State
 167   );
 168
 169 ///
 170 /// The EFI_ABSOLUTE_POINTER_PROTOCOL provides a set of services
 171 /// for a pointer device that can be used as an input device from an
 172 /// application written to this specification. The services include
 173 /// the ability to: reset the pointer device, retrieve the state of
 174 /// the pointer device, and retrieve the capabilities of the pointer
 175 /// device. The service also provides certain data items describing the device.
 176 ///
 177 struct _EFI_ABSOLUTE_POINTER_PROTOCOL {
 178   EFI_ABSOLUTE_POINTER_RESET        Reset;
 179   EFI_ABSOLUTE_POINTER_GET_STATE    GetState;
 180   ///
 181   /// Event to use with WaitForEvent() to wait for input from the pointer device.
 182   ///
 183   EFI_EVENT                         WaitForInput;
 184   ///
 185   /// Pointer to EFI_ABSOLUTE_POINTER_MODE data.
 186   ///
 187   EFI_ABSOLUTE_POINTER_MODE         *Mode;
 188 };
 189
 190 extern EFI_GUID  gEfiAbsolutePointerProtocolGuid;
 191
 192 #endif