wacom/wactablet.h

   1 /*****************************************************************************
   2 ** wactablet.h
   3 **
   4 ** Copyright (C) 2002 - 2004 - John E. Joganic
   5 ** Copyright (C) 2003 - 2008 - Ping Cheng
   6 **
   7 ** This program is free software; you can redistribute it and/or
   8 ** modify it under the terms of the GNU General Public License
   9 ** as published by the Free Software Foundation; either version 2
  10 ** of the License, or (at your option) any later version.
  11 **
  12 ** This program is distributed in the hope that it will be useful,
  13 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 ** GNU General Public License for more details.
  16 **
  17 ** You should have received a copy of the GNU General Public License
  18 ** along with this program; if not, write to the Free Software
  19 ** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  20 **
  21 ****************************************************************************/
  22
  23 #ifndef __LINUXWACOM_WACTABLET_H
  24 #define __LINUXWACOM_WACTABLET_H
  25
  26 #include <stdarg.h>
  27 #include <sys/time.h>
  28
  29 #define WACOMVENDOR_UNKNOWN     0x0000
  30 #define WACOMVENDOR_WACOM       0x056A
  31 #define WACOMVENDOR_TPC         0xFFFFFF01
  32
  33 #define WACOMCLASS_SERIAL       0x0001
  34 #define WACOMCLASS_USB          0x0002
  35
  36 #define WACOMDEVICE_UNKNOWN     0x0000
  37 #define WACOMDEVICE_ARTPAD      0x0001
  38 #define WACOMDEVICE_ARTPADII    0x0002
  39 #define WACOMDEVICE_DIGITIZER   0x0003
  40 #define WACOMDEVICE_DIGITIZERII 0x0004
  41 #define WACOMDEVICE_PENPARTNER  0x0005
  42 #define WACOMDEVICE_GRAPHIRE    0x0006
  43 #define WACOMDEVICE_GRAPHIRE2   0x0007
  44 #define WACOMDEVICE_GRAPHIRE3   0x0008
  45 #define WACOMDEVICE_GRAPHIRE4   0x0009
  46 #define WACOMDEVICE_INTUOS      0x000A
  47 #define WACOMDEVICE_INTUOS2     0x000B
  48 #define WACOMDEVICE_CINTIQ      0x000C
  49 #define WACOMDEVICE_PTU         0x000D
  50 #define WACOMDEVICE_VOLITO      0x000E
  51 #define WACOMDEVICE_VOLITO2     0x000F
  52 #define WACOMDEVICE_TPC         0x0010
  53 #define WACOMDEVICE_INTUOS3     0x0011
  54 #define WACOMDEVICE_CINTIQV5    0x0012
  55 #define WACOMDEVICE_MO          0x0013
  56
  57 typedef struct _WACOMMODEL WACOMMODEL;
  58 struct _WACOMMODEL
  59 {
  60         unsigned int uClass;
  61         unsigned int uVendor;
  62         unsigned int uDevice;
  63         unsigned int uSubType;
  64 };
  65
  66 #define WACOMTOOLTYPE_NONE      0x00
  67 #define WACOMTOOLTYPE_PEN       0x01
  68 #define WACOMTOOLTYPE_PENCIL    0x02
  69 #define WACOMTOOLTYPE_BRUSH     0x03
  70 #define WACOMTOOLTYPE_ERASER    0x04
  71 #define WACOMTOOLTYPE_AIRBRUSH  0x05
  72 #define WACOMTOOLTYPE_MOUSE     0x06
  73 #define WACOMTOOLTYPE_LENS      0x07
  74 #define WACOMTOOLTYPE_PAD       0x08
  75 #define WACOMTOOLTYPE_TOUCH     0x09
  76 #define WACOMTOOLTYPE_MAX       0x0A
  77
  78 #define WACOMBUTTON_LEFT        0
  79 #define WACOMBUTTON_MIDDLE      1
  80 #define WACOMBUTTON_RIGHT       2
  81 #define WACOMBUTTON_EXTRA       3
  82 #define WACOMBUTTON_SIDE        4
  83 #define WACOMBUTTON_TOUCH       5
  84 #define WACOMBUTTON_STYLUS      6
  85 #define WACOMBUTTON_STYLUS2     7
  86 #define WACOMBUTTON_BT0         8
  87 #define WACOMBUTTON_BT1         9
  88 #define WACOMBUTTON_BT2         10
  89 #define WACOMBUTTON_BT3         11
  90 #define WACOMBUTTON_BT4         12
  91 #define WACOMBUTTON_BT5         13
  92 #define WACOMBUTTON_BT6         14
  93 #define WACOMBUTTON_BT7         15
  94 #define WACOMBUTTON_BT8         16
  95 #define WACOMBUTTON_BT9         17
  96 #define WACOMBUTTON_BT10        18
  97 #define WACOMBUTTON_BT11        19
  98 #define WACOMBUTTON_BT12        20
  99 #define WACOMBUTTON_BT13        21
 100 #define WACOMBUTTON_BT14        22
 101 #define WACOMBUTTON_BT15        23
 102 #define WACOMBUTTON_BT16        24
 103 #define WACOMBUTTON_BT17        25
 104 #define WACOMBUTTON_BT18        26
 105 #define WACOMBUTTON_BT19        27
 106 #define WACOMBUTTON_BT20        28
 107 #define WACOMBUTTON_BT21        29
 108 #define WACOMBUTTON_BT22        30
 109 #define WACOMBUTTON_BT23        31
 110 #define WACOMBUTTON_MAX         32
 111
 112 #define WACOMFIELD_TOOLTYPE     0
 113 #define WACOMFIELD_SERIAL       1
 114 #define WACOMFIELD_PROXIMITY    2
 115 #define WACOMFIELD_BUTTONS      3
 116 #define WACOMFIELD_POSITION_X   4
 117 #define WACOMFIELD_POSITION_Y   5
 118 #define WACOMFIELD_ROTATION_Z   6
 119 #define WACOMFIELD_DISTANCE     7
 120 #define WACOMFIELD_PRESSURE     8
 121 #define WACOMFIELD_TILT_X       9
 122 #define WACOMFIELD_TILT_Y       10
 123 #define WACOMFIELD_ABSWHEEL     11
 124 #define WACOMFIELD_RELWHEEL     12
 125 #define WACOMFIELD_THROTTLE     13
 126 #define WACOMFIELD_MAX          14
 127
 128 typedef struct
 129 {
 130         int nValue;
 131         int nMin;
 132         int nMax;
 133         int nReserved;
 134 } WACOMVALUE;
 135
 136 typedef struct
 137 {
 138         unsigned int uValueCnt;     /* This MUST be set to WACOMFIELD_MAX. */
 139         unsigned int uValid;        /* Bit mask of WACOMFIELD_xxx bits. */
 140         WACOMVALUE values[WACOMFIELD_MAX];
 141 } WACOMSTATE;
 142
 143 #define WACOMSTATE_INIT { WACOMFIELD_MAX }
 144
 145 typedef struct
 146 {
 147         const char* pszName;
 148         const char* pszDesc;
 149         unsigned int uDeviceClass;
 150 } WACOMCLASSREC;
 151
 152 typedef struct
 153 {
 154         const char* pszName;
 155         const char* pszDesc;
 156         const char* pszVendorName;
 157         const char* pszVendorDesc;
 158         const char* pszClass;
 159         WACOMMODEL model;
 160 } WACOMDEVICEREC;
 161
 162 typedef enum
 163 {
 164         WACOMLOGLEVEL_NONE,
 165         WACOMLOGLEVEL_CRITICAL,
 166         WACOMLOGLEVEL_ERROR,
 167         WACOMLOGLEVEL_WARN,
 168         WACOMLOGLEVEL_INFO,
 169         WACOMLOGLEVEL_DEBUG,
 170         WACOMLOGLEVEL_TRACE,
 171         WACOMLOGLEVEL_MAX
 172 } WACOMLOGLEVEL;
 173
 174 typedef void (*WACOMLOGFUNC)(struct timeval tv, WACOMLOGLEVEL level,
 175         const char* pszLog);
 176
 177 /*****************************************************************************
 178 ** Public structures
 179 *****************************************************************************/
 180
 181 typedef struct { int __unused; } *WACOMENGINE;
 182 typedef struct { int __unused; } *WACOMTABLET;
 183
 184 /*****************************************************************************
 185 ** Public API
 186 *****************************************************************************/
 187
 188         WACOMENGINE WacomInitEngine(void);
 189         /* Initialize the tablet engine */
 190
 191         void WacomTermEngine(WACOMENGINE hEngine);
 192         /* Shutdown the tablet engine */
 193
 194         void WacomSetLogFunc(WACOMENGINE hEngine, WACOMLOGFUNC pfnLog);
 195         void WacomSetLogLevel(WACOMENGINE hEngine, WACOMLOGLEVEL level);
 196         void WacomLogV(WACOMENGINE hEngine, WACOMLOGLEVEL level,
 197                         const char* pszFmt, va_list args);
 198         void WacomLog(WACOMENGINE hEngine, WACOMLOGLEVEL level,
 199                         const char* pszFmt, ...);
 200         /* Logging functions. Default log function does nothing. */
 201
 202         int WacomGetSupportedClassList(WACOMCLASSREC** ppList, int* pnSize);
 203         /* Returns 0 on success.  Pointer to class record list is returned to
 204          * ppList, and size of list to pnSize.  Use WacomFreeList to release. */
 205
 206         int WacomGetSupportedDeviceList(unsigned int uDeviceClass,
 207                         WACOMDEVICEREC** ppList, int* pnSize);
 208         /* Returns 0 on success.  If device class is specified, only devices
 209          * of the request type are returned.  A value of 0 will return all
 210          * devices for all classes.  Pointer to device record list is returned to
 211          * ppList, and size of list to pnSize.  Use WacomFreeList to release. */
 212
 213         void WacomFreeList(void* pvList);
 214         /* Releases list memory. */
 215
 216         int WacomCopyState(WACOMSTATE* pDest, WACOMSTATE* pSrc);
 217         /* Returns 0 on success.  Copies tablet state structures.
 218          * Source and destination structures must be properly initialized,
 219          * particularly the uValueCnt field must be set WACOMFIELD_MAX.
 220          * Returns 0 on success. */
 221
 222         unsigned int WacomGetClassFromName(const char* pszName);
 223         /* Returns the device class for a given name. Returns 0, if unknown. */
 224
 225         unsigned int WacomGetDeviceFromName(const char* pszName,
 226                         unsigned int uDeviceClass);
 227         /* Returns the device type for a given device name.  If the
 228          * device class is specified, only that class will be searched.
 229          * Returns 0, if unknown. */
 230
 231         WACOMTABLET WacomOpenTablet(WACOMENGINE hEngine,
 232                 const char* pszDevice, WACOMMODEL* pModel);
 233         /* Returns tablet handle on success, NULL otherwise.
 234          * pszDevice is pathname to device.  Model may be NULL; if any model
 235          * parameters are 0, detection is automatic. */
 236
 237         void WacomCloseTablet(WACOMTABLET hTablet);
 238         /* Releases all resource associated with tablet and closes device. */
 239
 240         WACOMMODEL WacomGetModel(WACOMTABLET hTablet);
 241         /* Returns model (vendor, class, and device) of specified tablet. */
 242
 243         const char* WacomGetVendorName(WACOMTABLET hTablet);
 244         /* Returns vendor name as human-readable string.  String is valid as
 245          * long as tablet handle is valid and does not need to be freed. */
 246
 247         const char* WacomGetClassName(WACOMTABLET hTablet);
 248         /* Returns class name as human-readable string.  String is valid as
 249          * long as tablet handle is valid and does not need to be freed. */
 250
 251         const char* WacomGetDeviceName(WACOMTABLET hTablet);
 252         /* Returns device name as human-readable string.  String is valid as
 253          * long as tablet handle is valid and does not need to be freed. */
 254
 255         const char* WacomGetSubTypeName(WACOMTABLET hTablet);
 256         /* Returns subtype name as human-readable string.  This is typically
 257          * the model number (eg. ABC-1234).  String is valid as long as tablet
 258          * handle is valid and does not need to be freed. */
 259
 260         const char* WacomGetModelName(WACOMTABLET hTablet);
 261         /* Returns model name as human-readable string.  This is typically
 262          * the full model name (eg. FooCo FooModel 9x12).  String is valid as
 263          * long as tablet handle is valid and does not need to be freed. */
 264
 265         int WacomGetROMVersion(WACOMTABLET hTablet, int* pnMajor, int* pnMinor,
 266                         int* pnRelease);
 267         /* Returns 0 on success.  ROM version of the tablet firmware is returned
 268          * in major, minor, and release values.  If the caller needs to
 269          * distinguish between ROM versions to work around a bug, please consider
 270          * submitting a patch to this library.  All tablets should appear
 271          * equivalent through this interface. This call is provided for
 272          * information purposes. */
 273
 274         int WacomGetCapabilities(WACOMTABLET hTablet);
 275         /* Returns bitmask of valid fields.  Use (1 << WACOMFIELD_xxx) to
 276          * translate field identifiers to bit positions.  This API will only
 277          * support 32 capabilities. */
 278
 279         int WacomGetState(WACOMTABLET hTablet, WACOMSTATE* pState);
 280         /* Returns 0 on success.  Tablet state is copied to specified structure.
 281          * Data is only a snapshot of the device and may not accurately reflect
 282          * the position of any specific tool. This is particularly true of
 283          * multi-tool mode tablets.  NOTE: pState must point to an initialized
 284          * structure; the uValueCnt field must be correctly set to
 285          * WACOMFIELD_MAX. */
 286
 287         int WacomGetFileDescriptor(WACOMTABLET hTablet);
 288         /* Returns the file descriptor of the tablet or -1 on error. */
 289
 290         int WacomReadRaw(WACOMTABLET hTablet, unsigned char* puchData,
 291                         unsigned int uSize);
 292         /* Returns number of bytes read, typically a single packet.  Call will
 293          * block.  uSize should be the maximum size of the given data buffer. */
 294
 295         int WacomParseData(WACOMTABLET hTablet, const unsigned char* puchData,
 296                         unsigned int uLength, WACOMSTATE* pState);
 297         /* Updates the tablet state from a given packet.  If pState is specified,
 298          * the tablet state is copied to the given structure.  This structure
 299          * must be correctly initialized; the uValueCnt member must be set to
 300          * WACOMFIELD_MAX. Returns 0 on success. */
 301
 302 /*****************************************************************************
 303 ** Private structures
 304 *****************************************************************************/
 305
 306 typedef struct _WACOMTABLET_PRIV WACOMTABLET_PRIV;
 307
 308 struct _WACOMTABLET_PRIV
 309 {
 310         void (*Close)(WACOMTABLET_PRIV* pTablet);
 311         WACOMMODEL (*GetModel)(WACOMTABLET_PRIV* pTablet);
 312         const char* (*GetVendorName)(WACOMTABLET_PRIV* pTablet);
 313         const char* (*GetClassName)(WACOMTABLET_PRIV* pTablet);
 314         const char* (*GetDeviceName)(WACOMTABLET_PRIV* pTablet);
 315         const char* (*GetSubTypeName)(WACOMTABLET_PRIV* pTablet);
 316         const char* (*GetModelName)(WACOMTABLET_PRIV* pTablet);
 317         int (*GetROMVer)(WACOMTABLET_PRIV* pTablet, int* pnMajor, int* pnMinor,
 318                 int* pnRelease);
 319         int (*GetCaps)(WACOMTABLET_PRIV* pTablet);
 320         int (*GetState)(WACOMTABLET_PRIV* pTablet, WACOMSTATE* pState);
 321         int (*GetFD)(WACOMTABLET_PRIV* pTablet);
 322         int (*ReadRaw)(WACOMTABLET_PRIV* pTablet, unsigned char* puchData,
 323                         unsigned int uSize);
 324         int (*ParseData)(WACOMTABLET_PRIV* pTablet, const unsigned char* puchData,
 325                         unsigned int uLength, WACOMSTATE* pState);
 326 };
 327
 328 #endif /* __LINUXWACOM_WACTABLET_H */