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