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