MdePkg/Include/Protocol/AbsolutePointer.h

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