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