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