Wacom Feel™ Multi-Touch API

API Version

Update date (author)

Reasons for update

2.0

5/7/2012 (RCC)

Corrected lParam usage.

3.0

5/22/2012 (DT, RCC)

Added FrameNumber support; reference to FAQ

4.0

04/21/2014 (RCC, MH,KL)

Added descriptions of Windows-only HWND-tracking and Mac-only WindowID-tracking methods; and new pass-through processing mode

 

Contents

Overview   2

Windows Usage  2

Mac Usage  2

Supported Tablets  3

Function Details  3

Initialization function  3

Quit function  3

Attached Device Array function  3

Device Capabilities function  3

Device Callback functions  3

Data read functions  3

Sample Code  4

Data Structures and Enumerations  5

WacomMTError 5

WacomMTDeviceType  5

WacomMTCapabilityFlags  5

WacomMTCapability  6

WacomMTFingerState  7

WacomMTFinger 8

WacomMTFingerCollection  8

WacomMTBlobType  9

WacomMTBlobPoint 9

WacomMTBlob  9

WacomMTBlobAggregate  10

WacomMTRawData  10

WacomMTHitRect 11

WacomMTProcessingMode  11

Functions  13

WacomMTInitialize  13

WacomMTQuit 13

WacomMTGetAttachedDeviceIDs  13

WacomMTGetDeviceCapabilities  13

WacomMTRegisterAttachCallback  13

WacomMTRegisterDetachCallback  14

WacomMTRegisterFingerReadCallback  14

WacomMTUnRegisterFingerReadCallback  14

WacomMTRegisterBlobReadCallback  15

WacomMTRegisterRawReadCallback  15

WacomMTRegisterFingerReadHWND (This is a Windows only call) 16

WacomMTUnRegisterFingerReadHWND (This is a Windows only call) 16

WacomMTRegisterBlobReadHWND (This is a Windows only call) 16

WacomMTUnRegisterBlobReadHWND (This is a Windows only call) 17

WacomMTRegisterRawReadHWND (This is a Windows only call) – THIS FUNCTION IS DEPRECATED – Use WacomMTRegisterRawReadCallback() instead  17

WacomMTRegisterFingerReadID (This is a Mac only call) 17

WacomMTUnRegisterFingerReadID (This is a Mac only call) 18

WacomMTRegisterBlobReadID (This is a Mac only call) 18

WacomMTUnRegisterBlobReadID (This is a Mac only call) 19

WacomMTMoveRegisteredFingerReadCallback  19

WacomMTMoveRegisteredBlobReadCallback  19

 

Overview

This document describes the Wacom Feel™ Multi-Touch application programmers interface.  This API allows an application to get low level touch data from a Wacom multi-touch device.  While the APIs dynamic load library is included with the Wacom tablet driver not all devices support multi-touch.  The low level data provided by the API is finger point data, blob region data and/or raw sensor data.  Some devices may not support all data types.  See Wacom Feel™ Multi-Touch API FAQ for details on supported tablets.

Windows Usage

To use the API, an application needs only to include a few files from the Feel™ Multi-Touch SDK.  There is a header file that defines all the data structures and data types (WacomMultiTouchTypes.h), a header file the defines and entry points of the API (WacomMultiTouch.h); and an implementation file that sets  up the dynamic loading of the library(WacomMultiTouch.cpp).  The dynamic library (WacomMT.dll) is included with the driver and should not be included in the application.

 

The basic use model for processing touch point data is as follows:

1.       Initialization the API DLL.  If the dll does not load, either the Wacom driver is not installed or the current Wacom Driver does not support the Feel™ Multi-Touch API.

2.       Establish a device attach callback.  This will immediately be a called for each multi-touch device on the system.  This will also be called if the user attached a new multi-touch device to the system.  This callback includes a capabilities structure for each device.  Using this data the application can see what types of data are supported and the data ranges.

3.       Establish a device detach callback.  This will be called when a device is detached from the system.  Use this callback to close any open data callbacks the application has created.

4.       Assuming a device is attached that supports touch point data, the application would establish a touch point data callback.  This can be done using the direct callback methods or the window message loop callback method.  This callback is triggered whenever a finger is detected on the device.  Finger data includes position and state information.  The application will either quickly process the data or buffer the data to a worker thread for further processing.

5.       When the application is done processing touch data it should close all the callbacks and call the quit function.

 

This API can be used alongside the Wintab pen interface API.  The touch API does not process or inform about the pen proximity.  If the application needs to process both pen and touch data than the application should monitor both APIs.

 

Mac Usage

 

To use the API, an application needs only to include a few files from the Feel™ Multi-Touch SDK.  There is a header file that defines all the data structures and data types (WacomMultiTouchTypes.h), a header file the defines and entry points of the API (WacomMultiTouch.h.  The dynamic library(WacomMultitouch.framework) is included with the driver and should be included in the application.

 

The basic use model for processing touch point data is as follows:

1.       Establish a device attach callback.  This will immediately be a called for each multi-touch device on the system.  This will also be called if the user attached a new multi-touch device to the system.  This callback includes a capabilities structure for each device.  Using this data the application can see what types of data are supported and the data ranges.

2.       Establish a device detach callback.  This will be called when a device is detached from the system.  Use this callback to close any open data callbacks the application has created.

3.       Assuming a device is attached that supports touch point data, the application would establish a touch point data callback.  This callback is triggered whenever a finger is detected on the device.  Finger data includes position and state information.  The application will either quickly process the data or buffer the data to a worker thread for further processing.

4.       When the application is done processing touch data it should close all the callbacks and call the quit function.

 

The touch API does not process or inform about the pen proximity.  If the application needs to process both pen and touch data than the application should monitor both APIs.

 

Supported Tablets

See the Wacom Feel™ Multi-Touch API FAQ for a list of supported tablets.  Note that you should never use product names or model numbers as conditions in your multi-touch applications.  Rather, you should always program to tablet touch properties as described in this document.

Function Details

This section will provide detailed information about each of the API functions.

Initialization function

Some of  this function is implemented in the sample code.  First the function attempts to load the Wacom Feel™ Multi-Touch library.  If this succeeds then the entry point for all the other API function are loaded.  The function then calls the library with the version of the API requested by the application.  If the library supports this version it will report success.  If any part of this function fails the function returns the error code and the library will not work.

Quit function

If the library was loaded then it is called to release any open resources.  Then all of the API functions are reset back to their default error handles.  Finally the library is unloaded.

Attached Device Array function

This function will return an array of attached devices.  This function takes in an array of integers.  To use this function the application should call it with no buffer and no size.  This will return the number of devices attached.  The application will then create a buffer and recall the function.  It should be noted that the number of devices could change between these two calls.  The function will then again return the number of devices attached and provide as many of the device ids as the buffer will hold.  These device ids will then be used to get the device capabilities.  It is recommended that the application use the attach callback function.

Device Capabilities function

The capabilities function is used to get the device capabilities for a given device id.  If the application used the above function to get the ids then it will call this function with each of the ids to get a capabilities structure.  These capabilities structure are cached by the application so it will know the scaling of the data provided by that device.  An application can call this function when processing the data but this will cause a lot of unneeded processing.

Device Callback functions

The attach callback function is the best choice for for receiving notification of change in device information.  Not only does this function provide a capabilities structure for all the currently attached devices it will also monitor the system and inform the application when a new device is added.  Along with the detach callback this is the recommended method to keep track of the multi-touch devices.

The detach callback function will monitor and inform the application when a device is detached.  While strictly speaking an application could ignore a detach, it is recommended that the application close any open callbacks.  This will allow the application to respond to the attach function more quickly.

Data read functions

There are three different types of data that may be provided by any given device.  They are finger, blob and raw.

  1. The finger data is the most common any the most useful.  All multi-touch devices at least support finger data.  This data will track a touch point for each finger placed on the device.  While that finger is down it will be assigned an id.  The id represents a point of contact and not a specific finger.  For example if the user places their index finger on the device it may be assigned id 1.  They then place their middle finger down it is assigned 2.  The ring finger follows assigning it 3.  The user then lefts the middle finger finishing the lifetime of the contact labeled 2.  If the finger is returned to the device it may be given the id 2 because it is not currently being used as a contact but it could also be given the id 4.  If both the middle and ring finger are removed and the ring finger returned to the device the id will not be 3 as before but should be 2 or maybe 5.
  2. If the device supports blob data it will be indicated in the capabilities structure. Blob data represents an outline of the object or objects on the surface of the device.  There are two types of blobs; the primary blob and a void blob.  A blob is made from one primary and zero or more voids.  The best way to think of a void is to imagine a doughnut.  The outline of the outside of the doughnut is the primary blob and the hole is the void blob.  Blobs are used when you want to perform and action on an irregular shape like a mask or smudge.
  3. If the device supports raw data it will be indicated in the capabilities structure.  Raw data consists of the raw values from each point on the device.

 

There are two primary ways that an application can be notified of touch data availability: by callback, on both Windows and Mac systems; or by window handle (Windows only) or window ID (Mac only).

 

The data callback function sets up a callback for a specific device.  The callback is defined by the device for which it is created and the hit rectangle provided for that callback.  This means that an application can create regions on a device.  Most of the time an application will not need to segment the device, that is why the default (NULL) region is the entire touch device.  The units for the hit rectangle vary depending on the device.  For an opaque device like an Intuos or Bamboo tablet, the units are normalized.  I.e., the origin of the device is 0,0 and the width is 1 and the height is 1.  For an integrated device like a TabletPC, the hit rectangle is in pixels.   The device location in the virtual monitor world is known by the driver.  These values will change when the monitor location or size is changed.  The application should monitor the system device change message.

 

For Windows, the API has extra data collection functions.  These functions take in a HWND and instead of activating a callback the data is sent to the application on the message thread of the provided window.  The provided window is also used to create the hit rectangle for integrated devices.  Special care should be used with these functions as improper data handling will interfere with regular message handling.

 

For Mac, the API also has extra data collection functions. These functions take in a windowID and instead of activating a callback the data is sent to the application on the event thread of the provided window.  The provided windowID is also used to create the hit rectangle for integrated devices.  Special care should be used with these functions as improper data handling will interfere with regular message handling.

 

When the data function is created the application indicates what it is planning to do with the data by specifying what processing mode should be used (see WacomMTProcessingMode).  There are three processing modes that an application can use:

 

1.       If the application is registered as an observer (see WMTProcessingModeObserver in WacomMTProcessingMode), the data is sent both to the application and the system.  This means that if the application performs actions based on the data the driver/OS does not know and will also act upon the data.  The callbacks can also be created in consumer mode.  An observer will get all data not captured by a consumer even when the application is in the background. 

2.       If an application is registered as a consumer (see WMTProcessingModeNone in WacomMTProcessingMode), the data is only sent to that application and any observers whose hitrect intersects with the consumer.  The first consumer for that data is the only one to receive the data.  The OS does not get the data.  Simply put, for a consumer to get data, the application must be the front most application. (has keyboard focus). 

3.       Finally, if an application has registered a hitrect in passthrough mode (see WMTProcessingModePassThrough in WacomMTProcessingMode), all data going to that hitrect is passed through to the OS.  This is useful for carving out a section of your multi-touch application that can still respond to user touch input for program control (such as button presses, or an application tool palette).  Note that passthrough mode can co-exist with either the consumer or observer modes described above.  Touch data going to a passthrough hitrect region will – in addition to being processed by  the OS – be processed by an observer, but not processed by a consumer.  Thus if your application is primarily a consumer, and you register a small dialog as a passthrough hitrect, you can interact with and move that dialog around without sending data to the consumer below.

 

If an observer needs to stop getting data it should unregister its callback functions or unregister its window handle (Windows only) or windowID (Mac only)

Sample Code

There are both Windows and Mac-based sample code applications included with the SDK (at http://us.wacom.com/en/developerrelations/feel-multi-touch).  These applications show how to get finger point data from a device and paint these fingers on the client area. The examples also show how to setup a device for receiving touch callbacks or track a client through its Windows handle (Windows-only) or WindowID (Mac-only).  Included in the sample code is a demonstration of querying for the list of attached touch tablet devices and the touch properties of each tablet. Please see the sample code comments for detailed information on API usage.

Data Structures and Enumerations

WacomMTError

Error conditions used as a return value for all functions.

 

typedef enum _WacomMTError

{

WMTErrorSuccess                                               = 0

WMTErrorDriverNotFound                               = 1

WMTErrorBadVersion                                       = 2

WMTErrorAPIOutdated                                     = 3

WMTErrorInvalidParam                                    = 4

WMTErrorQuit                                                     = 5

WMTErrorBufferTooSmall                               = 6

} WacomMTError

 

WMTErrorSuccess:

Returned when a call is successful.

WMTErrorDriverNotFound:

Returned when the API does not find an installed and running driver.

WMTErrorBadVersion:

Returned when the version of the driver is not compatible with the API.  This will happen when an application requests newer API data structures that are not supported by the driver.

WMTErrorAPIOutdated:

Returned when an application requests API data structures that are no longer supported by the driver.

WMTErrorInvalidParam:

Returned when one or more parameters are invalid.

WMTErrorQuit:

Returned by wait functions when the API quit call is made or if the API has not been successfully initialized.

WMTErrorBufferTooSmall

Returned if the supplied buffer is to small

WacomMTDeviceType

Type of sensor device.  Used in the capabilities data structure.

 

typedef enum _WacomMTDeviceType

{

WMTDeviceTypeOpaque                                  = 0

WMTDeviceTypeIntegrated                             = 1

} WacomMTDeviceType

 

WMTDeviceTypeOpaque:

The touch sensor is not integrated with a display.  Opaque track pad like devices return this value.

WMTDeviceTypeIntegrated:

The touch sensor is integrated with a display.  On screen touch devices, such as TabletPCs return this value.

WacomMTCapabilityFlags

Used in the capabilities structure to indicate the type of data supported by the device.

 

typedef enum _WacomMTCapabilityFlags

{

WMTCapabilityFlagsRawAvailable                                = (1 <<  0)

WMTCapabilityFlagsBlobAvailable               = (1 <<  1)

WMTCapabilityFlagsSensitivityAvailable     = (1 <<  2)

WMTCapabilityFlagsReserved                         = (1 << 31)

} WacomMTCapabilityFlags

 

WMTCapabilityFlagsRawAvailable:

If this flag is set, the device supports raw data and raw data can be read.

WMTCapabilityFlagsBlobAvailable:

If this flag is set, the device supports blob data and blob data can be read.

WMTCapabilityFlagsSensitivityAvailable:

If this flag is set, sensitivity data will be available in the finger data.  Sensitivity data is a value between 0 and 0xFFFF.  If this flag is not set, sensitivity data will be set to zero in each up packet and max for the down/hold packets.  See the WacomMTFinger data structure for a definition of sensitivity.

WacomMTCapability

This structure contains the physical and logical capabilities of a multi-touch device.

 

typedef struct WacomMTCapability

{

int                                                            Version

int                                                             DeviceID

WacomMTDeviceType                      Type

float                                                        LogicalOriginX

float                                                        LogicalOriginY

float                                                        LogicalWidth

float                                                        LogicalHeight

float                                                        PhysicalSizeX

float                                                        PhysicalSizeY

int                                                             ReportedSizeX

int                                                             ReportedSizeY

int                                                             ScanSizeX

int                                                             ScanSizeY

int                                                             FingerMax

int                                                            BlobMax

int                                                            BlobPointsMax

WacomMTCapabilityFlags               CapabilityFlags

} WacomMTCapability

 

Version:

The version of this data structure.

DeviceID:

A value that identifies a touch device.  This is a unique number that may vary from machine to machine and session to session, but will be the same during any given session.  This value is used with all other calls to identify the device.

Type:

A value that indicates the device type.  An opaque device does not have a fixed relationship with the screen.  An integrated device is has a one to one relationship to a single monitor.

LogicalOriginX:

Minimum horizontal value of the device reported after interpolation.  For an opaque device this value will be zero.  For integrated devices this value is the (upper) left point in pixels of the mapped monitor in relation to the entire desktop.  This may map to an adjacent monitor if the touch device is larger than the integrated display.

LogicalOriginY:

Minimum vertical value of the device reported after interpolation.  For an opaque device this value will be zero.  For integrated devices this value is the upper (left) point in pixels of the mapped monitor in relation to the entire desktop.  This may map to an adjacent monitor if the touch device is larger than the integrated display.

LogicalWidth:

Width of the device reported after interpolation.  For an opaque device this value is 1 and is unit neutral.  For integrated devices this value is the number of pixels the device covers.  This may map to an adjacent display if the touch device is larger than the integrated display.

LogicalHeight:

Height of the device reported after interpolation.  For an opaque device this value is 1 and is unit neutral.  For integrated devices this value is the number of pixels the device covers.  This may map to an adjacent display if the touch device is larger than the integrated display.

PhysicalSizeX:

Width of the sensing area of the device in mm.  Used with other size factors to convert the device data from one coordinate system to another.

PhysicalSizeY:

Height of the sensing area of the device in mm.  Used with other size factors to convert the device data from one coordinate system to another.

ReportedSizeX:

Width of the device in native counts.  Used with other size factors to determine the maximum resolution of the data.  The horizontal resolution is calculated by dividing this value by PhysicalSizeX.

ReportedSizeY:

Height of the device in native counts.  Used with other size factors to determine the maximum resolution of the data.  The vertical resolution is calculated by dividing this value by PhysicalSizeY.

ScanSizeX:

Width of the device in scan coils.  This is only provided for devices that support raw data.  This value is used to calculate the size of the raw data buffer.  (ScanSizeX * ScanSizeY)  If the device does not support raw data this value should be ignored.

ScanSizeY:

Height of the device in scan coils.  This is only provided for devices that support raw data.  This value is used to calculate the size of the raw data buffer.  (ScanSizeX * ScanSizeY)  If the device does not support raw data this value should be ignored.

FingerMax:

Maximum number of fingers that are supported.  This is the number of fingers this device can report as down at any given time.  The can be used to help calculate the maximum size of the finger collection structure.  This is not the maximum value for FingerID.

BlobMax:

Maximum number of blobs in a blob aggregate.  A blob is a series of points that define its outline.  A blob can be a primary blob or a void blob.  Each void blob has one and only one parent while a primary blob can have zero or more child blobs which define void areas within the parent blob.  For example, a doughnut shape is a blob aggregate with the outer ring being the parent blob and the inner ring being a child blob.

BlobPointsMax:

Maximum number of blob points that make up a blob.  These blob values (BlobMax and BlobPointsMax) can be used to calculate the maximum size of a blob aggregate.  (BlobMax * BlobPointsMax)

CapabilityFlags:

A value to indicate the presence of specific data elements.  See the WacomMTCapabilityFlags enumeration definition.

WacomMTFingerState

Used in the finger structure to indicate the state of the finger.

 

typedef enum _WacomMTFingerState

{

WMTFingerStateNone                                        = 0

WMTFingerStateDown                                       = 1

WMTFingerStateHold                                        = 2

WMTFingerStateUp                                            = 3

} WacomMTFingerState

 

WMTFingerStateNone:

A finger buffer may contain room for more than one contact.  Any extra unused contact is set to "None".  Once a contact has passed through the "Up" state it has the TouchState set to "None" to indicate that no further processing is needed.  Any other data included with this state is not valid.

WMTFingerStateDown:

Indicates initial finger contact.  First touch packet for a particular contact.

WMTFingerStateHold:

Subsequent packets during the finger contact.

WMTFingerStateUp:

Last touch packet for a particular finger contact.  Reported when the finger is lifted.  This will be reported at the last known valid position.

WacomMTFinger

This structure contains the data for individual touch contacts.

 

typedef struct WacomMTFinger

{

int                                                             FingerID

float                                                        X

float                                                        Y

float                                                        Width

float                                                        Height

unsigned short                                      Sensitivity

float                                                        Orientation

bool                                                        Confidence

WacomMTFingerState                       TouchState

} WacomMTFinger

 

FingerID:

Unique identifier of the contact.  This value starts with 1 for the first contact and increments for each subsequent contact.  This value resets to 1 when all contacts are lifted up.  This is to be used to track contacts from frame to frame.  This does not represent a unique value for a specific finger but is unique for the contact and represents the same contact point for the duration of the contact.

X:

Scaled X of the contact area in logical units.

Y:

Scaled Y of the contact area in logical units.

Width:

Width of the contact area in logical units.

Height:

Height of the contact area in logical units.

Sensitivity:

Strength of the contact.  This is not pressure.  This is a device/user specific indication of the strength of the contact point.  Only valid in relation to other fingers within the same frame/gesture.

Orientation:

The orientation of the contact point in degrees.

Confidence:

If true the driver believes this is a valid touch from a finger.  If false the driver thinks this may be an accidental touch, forearm or palm.

TouchState:

The state of this finger contact.  See the WacomMTFingerState enumeration definition.

WacomMTFingerCollection

This structure allows for a list of fingers.

 

typedef struct WacomMTFingerCollection

{

int                                            Version

int                                            DeviceID

int                                            FrameNumber

int                                            FingerCount

WacomMTFinger                                *FingerData

} WacomMTFingerCollection

 

Version:

The version of this data structure.

DeviceID:

A value that identifies a touch device.  This is a unique number that may vary from machine to machine and session to session, but will be the same during any given session.

FingerCount:

The number of elements in the finger data array.  This value will vary from frame to frame but will never be greater than the FingerMax value for the specific device.

FingerData:

Pointer to an array of fingers.  The size of the FingerData block is FingerCount * sizeof(WacomMTFinger).

WacomMTBlobType

Used by the blob structure to identify the blog type.

 

typedef enum _WacomMTBlobType

{

WMTBlobTypePrimary                                     = 0

WMTBlobTypeVoid                                           = 1

} WacomMTBlobType

 

WMTBlobTypePrimary:

This is an outline of an outer primary blob.

WMTBlobTypeVoid:

This is an outline of an inner blob that is contained within an outer primary blob.  Void blobs are regions of no touch within primary blobs.  A primary blob may contain one or more void blobs.  Void blobs do not contain other blobs.  A unique primary blob can be within another blobs void but the void does not reference that blob.

WacomMTBlobPoint

This structure contains information about a specific point of blob data.

 

typedef struct WacomMTBlobPoint

{

float                                        X

float                                        Y

unsigned short                      Sensitivity

} WacomMTBlobPoint

 

X:

Scaled X value of a blob point in logical units.

Y:

Scaled Y value of a blob point in logical units.

Sensitivity:

Strength of the signal at this blob point.  This is not pressure.  This is a device/user specific indication of the strength of the contact point.  Only valid in relation to other blobs within the same frame.

WacomMTBlob

This structure contains the contact data for an irregular region.

 

typedef struct WacomMTBlob

{

int                                                            BlobID

float                                                        X

float                                                        Y

bool                                                        Confidence

WacomMTBlobType                         BlobType

int                                                            ParentID

int                                                            PointCount

WacomMTBlobPoint                         *BlobPoints

} WacomMTBlob

 

BlobID:

This is a value that uniquely identifies this blob.  This value persists from frame to frame.

X:

Scaled X center of gravity of the blob area in logical units.

Y:

Scaled Y center of gravity of the blob area in logical units.

Confidence:

If true the driver believes this is a valid touch.  If false the driver thinks this may be an accidental touch, forearm or palm.

BlobType:

The blob type this structure represents.  See the WacomMTBlobType enumeration definition.

ParentID:

This identifies the parent blob.  Valid only if the BlobType is "Void".

PointCount:

The number of elements in the blob points array.  This is the number of points that make up the outline of the blob.

BlobPoints:

Pointer to an array of blob points.  The size of the BlobPoints block is PointCount * sizeof(WacomMTBlobPoint).  The blob points form a closed area.

WacomMTBlobAggregate

This structure allows for a list of blobs.

 

typedef struct WacomMTBlobAggregate

{

int                                                            Version

int                                                            DeviceID

int                                                            FrameNumber

int                                                            BlobCount

WacomMTBlob                                   *BlobArray

} WacomMTBlobAggregate

 

Version:

The version of this data structure.

DeviceID:

A value that identifies a touch device.  This is a unique number that may vary from machine to machine and session to session, but will be the same during any given session.

BlobCount:

Number of elements in the blob data array.

BlobArray:

An array of blobs.  The size of the BlobArray block is BlobCount * sizeof(WacomMTBlob).

WacomMTRawData

This structure represents the strength values for the surface of the device.

 

typedef struct WacomMTRawData

{

int                                            Version

int                                            DeviceID

int                                            FrameNumber

int                                            ElementCount

unsigned short                      *Sensitivity

} WacomMTRawData

 

Version:

The version of this data structure.

DeviceID:

A value that identifies a touch device.  This is a unique number that may vary from machine to machine but will be the same during any given session.

ElementCount:

Number of elements in the sensitivity array.  This value should be ScanSizeY * ScanSizeX.

Sensitivity:

Pointer to an array sensitivity values.  The size of the Sensitivity block is ElementCount * sizeof(unsigned short).  The location of each point is calculated as (Y * ScanSizeX) + X.

WacomMTHitRect

This structure represents a hit test rectangle.   For opaque tablets (such as Intuos), the hitrect coordinates are normalized to a value between 0.0 and 1.0.  For display tablets (such as Cintiq), the hitrect coordinates are desktop pixel values.

 

typedef struct WacomMTHitRect

{

float                        originX

float                        originY

float                        width

float                        height

} WacomMTHitRect

 

originX:

The horizontal value of the origin point of the rectangle.

originY:

The vertical value of the origin point of the rectangle.

width:

The horizontal width of the rectangle.

height:

The vertical height of the rectangle.

WacomMTProcessingMode

Used by the callback functions.  Provides instructions for how to process the data.  If no flags are set the data is sent to the callback and not processed by the system.

 

typedef enum _WacomMTProcessingMode

{

WMTProcessingModeNone                               = 0

WMTProcessingModeObserver                        = (1 << 0)

WMTProcessingModePassThrough                 = (1 << 1)

WMTProcessingModeReserved                        = (1 << 31)

} WacomMTProcessingMode

 

WMTProcessingModeNone:

The data is sent to the callback and no other processing is done.

WMTProcessingModeObserver:

The data is posted in parallel to the OS for processing.

WMTProcessingModePassthrough:

The data is posted in parallel to the OS and WMT observers.

 

Functions

Unless otherwise specified, the functions are specified and used in the same way for both Windows and Mac systems.

WacomMTInitialize

WacomMTError WacomMTInitialize( int libraryAPIVersion );

This function attempts to connect the application to the driver and must be called successfully before any other Wacom Multi-Touch function is called.

Parameters:

libraryAPIVersion:

This is the version of the API that the application is using.  This value will be used by the API to construct the expected data structures for the application.  Please use the provided predefined value WACOM_MULTI_TOUCH_API_VERSION.

Return Value:

See the WacomMTError enumeration definition.

WacomMTQuit

void WacomMTQuit();

This function closes the connection to the driver service.  This should be called when the application is closing or no longer needs touch data.  After calling WacomMTQuit, WacomMTInitialize would need to be called again to resume touch interaction.

WacomMTGetAttachedDeviceIDs

int WacomMTGetAttachedDeviceIDs( int *deviceArray, size_t bufferSize );

This function returns the number of multi-touch sensors attached to the system.

Parameters:

deviceArray:

A user allocated buffer used to return the deviceIDs of the currently attached devices.  This call will provide as many devices as will fit into the provided buffer.  This can be NULL.

bufferSize:

The size of the buffer provided.  Should be zero if no buffer provided.

Return Value:

The return value is the number of sensors attached to the system.

WacomMTGetDeviceCapabilities

WacomMTError WacomMTGetDeviceCapabilities( int deviceID, WacomMTCapability *capabilityBuffer );

This function fills in a caller allocated WacomMTCapability structure with the capability information for the requested device identifier.

Parameters:

deviceID:

The ID of the device.  These IDs can be from the GetAttachedDeviceIDs array, the finger packet deviceID member, the blob packet deviceID member or the raw packet deviceID member.

capabilityBuffer:

This is the caller allocated structure that is filled in with device capability data upon success.  This structure will be defined by the API version provided at initialization.

Return Value:

See the WacomMTError enumeration definition.

WacomMTRegisterAttachCallback

WacomMTError WacomMTRegisterAttachCallback( WMT_ATTACH_CALLBACK attachCallback, void *userData );

This function allows you to register a callback function that you would like called when a new touch device is attached.  When registered the API will issue a callback for each device currently attached.  Only one attach callback can be registered for each process.  To cancel the attach callback, a process can call this function with NULL.

Parameters:

The function definition is: void ( *WMT_ATTACH_CALLBACK )( WacomMTCapability deviceInformation, void *userData );

This function will be called with the WacomMTCapability structure for the device attached and the userData provided when the call was registered.

Return Value:

See the WacomMTError enumeration definition.

WacomMTRegisterDetachCallback

WacomMTError WacomMTRegisterDetachCallback( WMT_DETACH_CALLBACK detachCallback, void *userData );

This function allows you to register a callback function that you would like called when a touch device is detached. Only one detach callback can be registered for each process.  To cancel the detach callback, a process can call this function with NULL.

Parameters:

The function definition is: void ( *WMT_DETACH_CALLBACK )( int deviceId, void *userData );

The function will be called with the deviceID of the sensor that has been detached and the userData provided when the call was registered.

Return Value:

See the WacomMTError enumeration definition.

WacomMTRegisterFingerReadCallback

WacomMTError WacomMTRegisterFingerReadCallback( int deviceID, WacomMTHitRect *hitRect, WacomMTProcessingMode mode, WMT_FINGER_CALLBACK fingerCallback, void *userData );

This function allows you to register a callback function that you would like called when a finger touch packet is ready and within the requested device's hit rectangle.  A process can create as many callbacks as needed but only one callback per device hit rectangle.  If you wish to cancel a callback, call this function or WacomMTUnRegisterFingerReadCallback() on an existing device hit rectangle with NULL for the function.  The callbacks are processed in the order in which they are created.

Parameters:

deviceID:

The deviceID of the device.

hitRect:

A rectangle used to hit test the data.  If a finger begins contact with in the hit rectangle the callback will be called.  The callback will continue to be called for that finger until that contact is removed from the device.  If a contact begins outside the hit rectangle, the callback will not be called for that finger. A NULL rectangle will assume the entire device surface.  The hit rectangle is defined in the logical units of the device.  See WacomMTCapability structure for a definition of logical units.

mode:

Specifies what the API does with the data during the callback.

fingerCallback:

The function definition is:  int ( *WMT_FINGER_CALLBACK )( WacomMTFingerCollection *fingerPacket, void *userData );

The function will be called with the fingerPacket structure filled in and the userData provided when the call was registered.  The fingerPacket is only valid while the callback is being processed.  This memory is release/reused upon return from the callback.  The return value is reserved and should be zero.

userData:

A parameter provided by the caller and echoed back in the callback function.

Return Value:

See the WacomMTError enumeration definition.

 

WacomMTUnRegisterFingerReadCallback

WacomMTError WacomMTUnRegisterFingerReadCallback( int deviceID, WacomMTHitRect *hitRect, WacomMTProcessingMode mode, void *userData );

This function allows you to cancel a callback.

Parameters:

deviceID:

The deviceID of the device.

hitRect:

A rectangle that was registered for callbacks.  A NULL rectangle will assume the entire device surface.  The hit rectangle is defined in the logical units of the device.  See WacomMTCapability structure for a definition of logical units.

mode:

Specifies what the API does with the data during the callback.

userData:

A parameter provided by the caller and echoed back in the callback function.

Return Value:

      If a matching hitrect/mode is not found, then this function will return an error.  See the WacomMTError enumeration definition.

 

WacomMTRegisterBlobReadCallback

WacomMTError WacomMTRegisterBlobReadCallback( int deviceID, WacomMTHitRect *hitRect, WacomMTProcessingMode mode, WMT_BLOB_CALLBACK blobCallback, void *userData );

This function allows you to register a callback function that you would like called when blob data is ready and within the requested device's hit rectangle.  A process can create as many callbacks as needed but only one callback per device hit rectangle.  If you wish to cancel a callback, call this function on an existing device hit rectangle with NULL for the function.  The callbacks are processed in the order in which they are created.

Parameters:

deviceID:

The deviceID of the device.

hitRect:

A rectangle used to hit test the data.  If any part of the blob contact is within the hit rectangle the callback will be called.  A NULL rectangle will assume the entire device surface.  The hit rectangle is defined in the logical units of the device.  See WacomMTCapability structure for a definition of logical units.

mode:

Specifies what the API does with the data during the callback.

blobCallback:

The function definition is: int ( *WMT_BLOB_CALLBACK )( WacomMTBlobAggregate *blobPacket, void *userData );

The function will be called with the blobPacket structure filled in and the userData provided when the call was registered.  The blobPacket is only valid while the callback is being processed.  This memory is release/reused upon return from the callback.  The return value is reserved and should be zero.

userData:

A parameter provided by the caller and echoed back in the callback function.

Return Value:

See the WacomMTError enumeration definition.

WacomMTRegisterRawReadCallback

WacomMTError WacomMTRegisterRawReadCallback( int deviceID, WacomMTProcessingMode mode, WMT_RAW_CALLBACK rawCallback, void *userData );

This function allows you to register a callback function that you would like called when raw data is ready for the specified device.  Only one callback can be registered per device.  If you wish to cancel the device callback call this function with NULL for the callback.  The callbacks are processed in the order in which they are created.

Parameters:

deviceID:

The deviceID of the device.

mode:

Specifies what the API does with the data during the callback.

rawCallback:

The function definition is: int ( *WMT_RAW_CALLBACK )( WacomMTRawData *rawPacket, void *userData );

The function will be called with the rawPacket structure filled in and the userData provided when the call was registered.  The rawPacket is only valid while the callback is being processed.  This memory is release/reused upon return from the callback.  The return value is reserved and should be zero.

userData:

A parameter provided by the caller and echoed back in the callback function.

Return Value:

See the WacomMTError enumeration definition.

WacomMTRegisterFingerReadHWND (This is a Windows only call)

WacomMTError WacomMTRegisterFingerReadHWND( int deviceID, WacomMTProcessingMode mode, HWND hWnd, int bufferDepth );

This function allows you to register a window handle to receive finger data.  When a packet of finger data for the given device is ready a WM_FINGERDATA message will be sent to the window handle.  The lParam parameter will be a pointer to a WacomMTFingerCollection structure that contains the finger data.  The bufferDepth parameter determines the number of callback buffers created.  The buffers are used in a ring format.  Only one finger data message is allowed for each device per window handle.  The window handle is also used to produce a hit rectangle.  The hit rectangle is calculated when this function is called.  If the window is moved or resized this function should be called again.  If the bufferDepth is changed, all existing buffers will be invalid.  To cancel the device callback, this function can either be called with a bufferDepth of zero, or the function WacomMTUnRegisterFingerReadHWND can be used.

Parameters:

deviceID:

The deviceID of the device.

mode:

Specifies what the API does with the data during the callback.

hWnd:

This is the window handle that will receive the WM_FINGERDATA message.

bufferDepth:

This is the number of WacomMTFingerCollection data structures that will be allocated for the message callbacks.

Return Value:

See the WacomMTError enumeration definition.

 

WacomMTUnRegisterFingerReadHWND (This is a Windows only call)

WacomMTError WacomMTUnRegisterFingerReadHWND(HWND hWnd);

This function allows you to unregister a Window handle from receiving touch finger data updates.  The function will return an error for an invalid Window handle.

Parameters:

hWnd:

This is a window handle that was registered to receive the WM_FINGERDATA message.

Return Value:

See the WacomMTError enumeration definition.

WacomMTRegisterBlobReadHWND (This is a Windows only call)

WacomMTError WacomMTRegisterBlobReadHWND( int deviceID, WacomMTProcessingMode mode, HWND hWnd, int bufferDepth );

This function allows you to register a window handle to receive blob data.  When a blob packet for the given device is ready a WM_BLOBDATA message will be sent to the window handle.  The lParam parameter will be a pointer to a WacomMTBlobAggregate structure that contains the blob data.  The bufferDepth parameter determines the number of callback buffers created.  The buffers are used in a ring format.  Only one blob data callback is allowed for each device per window handle.  The window handle is also used to produce a hit rectangle.  The hit rectangle is calculated when this function is called.  If the window is moved or resized this function should be called again.  If the bufferDepth is changed, all existing buffers will be invalid.  To cancel the device callback, this function can be called with a bufferDepth of zero, or the function WacomMTUnRegisterBlobReadHWND can be used.

Parameters:

deviceID:

The deviceID of the device.

mode:

Specifies what the API does with the data during the callback.

hWnd:

This is the window handle that will receive the WM_BLOBDATA message.

bufferDepth:

This is the number of WacomMTBlobAggregate data structures that will be allocated for the message callbacks.

Return Value:

See the WacomMTError enumeration definition.

 

WacomMTUnRegisterBlobReadHWND (This is a Windows only call)

WacomMTError WacomMTUnRegisterBlobReadHWND(HWND hWnd);

This function allows you to unregister a Window handle from receiving touch blob data updates.  The function will return an error for an invalid Window handle.

Parameters:

hWnd:

This is a window handle that was registered to receive the WM_FINGERDATA message.

Return Value:

See the WacomMTError enumeration definition.

 

WacomMTRegisterRawReadHWND (This is a Windows only call) – THIS FUNCTION IS DEPRECATED – Use WacomMTRegisterRawReadCallback() instead

WacomMTError WacomMTRegisterRawReadHWND( int deviceID, WacomMTProcessingMode mode, HWND hWnd, int bufferDepth );

This function allows you to register a window handle to receive raw data.  When a data frame for the given device is ready a WM_RAWDATA message will be sent to the window handle.  The lParam parameter will be a pointer to a WacomMTRawData structure.  The bufferDepth parameter determines the number of callback buffers created.  The buffers are used in a ring format.  Only one raw data callback is allowed for each device per window handle.  If the bufferDepth is changed, all existing buffers will be invalid.  To cancel the device callback this function should be called with the bufferDepth equal to zero.

Parameters:

deviceID:

The deviceID of the device.

mode:

Specifies what the API does with the data during the callback.

hWnd:

This is the window handle that will receive the WM_RAWDATA message.

bufferDepth:

This is the number if RawData data structures that will be allocated for the message callbacks.

Return Value:

See the WacomMTError enumeration definition.

 

WacomMTRegisterFingerReadID (This is a Mac only call)

WacomMTError WacomMTRegisterFingerReadID( int deviceID, WacomMTProcessingMode mode, id windowID, int bufferDepth );

This function allows you to register a Mac window to receive finger data.  When a packet of finger data for the given device is ready a callback will be made to the specified windowID. The bufferDepth parameter determines the number of callback buffers created.  The buffers are used in a ring format.  Only one finger data registration is allowed for each device per windowID.  The windowID is also used to produce a hit rectangle.  The hit rectangle is calculated when this function is called and the window is tracked as it is moved and resized. If this function is called again with changed bufferDepth, all existing buffers will be invalid.  To cancel the device callback this function can be called with a bufferDepth of zero, or the function WacomMTUnRegisterFingerReadID can be used.

Parameters:

deviceID:

The deviceID of the device.

mode:

Specifies what the API does with the data during the callback.

windowID:

This is the window that will receive the callbacks.

bufferDepth:

This is the number of WacomMTFingerCollection data structures that will be allocated for the message callbacks.

Return Value:

See the WacomMTError enumeration definition.

 

The protocol signature that is required to be supported is below.

 

Protocol Name: WacomMTWindowFingerRegistration

Required Method: -(void) FingerDataAvailable:(WacomMTFingerCollection *)packet data:(void *)userData;

   packet: the data that contains the finger data.

   userData: unused.

 

 

WacomMTUnRegisterFingerReadID (This is a Mac only call)

WacomMTError WacomMTRegisterFingerReadID(id windowID);

This function allows you to unregister a Mac view or Window ID from receiving touch finger data updates.  The function will return an error for an invalid window.

Parameters:

windowID:

This is a Mac window that was registered to receive callbacks

Return Value:

See the WacomMTError enumeration definition.

 

WacomMTRegisterBlobReadID (This is a Mac only call)

WacomMTError WacomMTRegisterFingerReadID( int deviceID, WacomMTProcessingMode mode, id windowID, int bufferDepth );

This function allows you to register a Mac windowID to receive blob data.  When a packet of blob data for the given device is ready a callback will be made to the specified windowID delegate.  The bufferDepth parameter determines the number of callback buffers created.  The buffers are used in a ring format.  Only one blob data registration is allowed for each device per windowID. The windowID is also used to produce a hit rectangle.  The hit rectangle is calculated when this function is called and the window is tracked as it is moved and resized. If this function is called again with changed bufferDepth, all existing buffers will be invalid.  To cancel the device callback this function should be called with the bufferDepth of zero.

Parameters:

deviceID:

The deviceID of the device.

mode:

Specifies what the API does with the data during the callback.

windowID:

This is the window that will receive the callbacks

bufferDepth:

This is the number of WacomMTFingerCollection data structures that will be allocated for the message callbacks.

Return Value:

See the WacomMTError enumeration definition.

 

The protocol signature that is required to be supported is below.

 

Protocol Name: WacomMTWindowBlobRegistration

Required Method: -(void) BlobDataAvailable:(WacomMTBlobAggregate *)packet data:(void *)userData;

Parameters:

   packet: the data that contains the Blob data.

   userData: unused.

 

 

WacomMTUnRegisterBlobReadID (This is a Mac only call)

WacomMTError WacomMTRegisterBlobReadID(id windowID);

This function allows you to unregister a Mac view or windowID from receiving touch blob data updates.  The function will return an error for an invalid windowID.

Parameters:

windowID:

This is a Mac window that was registered to receive callbacks.

Return Value:

See the WacomMTError enumeration definition.

 

WacomMTMoveRegisteredFingerReadCallback

WacomMTError WacomMTMoveRegisteredFingerReadCallback( int deviceID, WacomMTHitRect *oldHitRect, WacomMTProcessingMode mode, WacomMTHitRect *newHitRect, void *userData);

      This function allows you to register a new finger hitrect without having to first explicitly unregister an old hitrect.

Parameters:

deviceID:

The deviceID of the device.

oldHitRect:

A rectangle that was registered for callbacks.  A NULL rectangle will assume the entire device surface.  The hit rectangle is defined in the logical units of the device.  See WacomMTCapability structure for a definition of logical units.

mode:

Specifies what the API does with the data during the callback.

newHitRect:

A new rectangle to be registered for callbacks.  A NULL rectangle will assume the entire device surface.  The hit rectangle is defined in the logical units of the device.  See WacomMTCapability structure for a definition of logical units.

userData:

A parameter provided by the caller and echoed back in the callback function.

Return Value:

      If oldHitRect/mode is not found or if the newHitRect/mode has already been registered, then this function will return an error.  See the WacomMTError enumeration definition.

 

 

WacomMTMoveRegisteredBlobReadCallback

WacomMTError WacomMTMoveRegisteredBlobReadCallback( int deviceID, WacomMTHitRect *oldHitRect, WacomMTProcessingMode mode, WacomMTHitRect *newHitRect, void *userData);

      This function allows you to register a new blob hitrect without having to first explicitly unregister an old hitrect.

Parameters:

deviceID:

The deviceID of the device.

oldHitRect:

A rectangle that was registered for callbacks.  A NULL rectangle will assume the entire device surface.  The hit rectangle is defined in the logical units of the device.  See WacomMTCapability structure for a definition of logical units.

mode:

Specifies what the API does with the data during the callback.

newHitRect:

A new rectangle to be registered for callbacks.  A NULL rectangle will assume the entire device surface.  The hit rectangle is defined in the logical units of the device.  See WacomMTCapability structure for a definition of logical units.

userData:

A parameter provided by the caller and echoed back in the callback function.

Return Value:

      If oldHitRect/mode is not found or if the newHitRect/mode has already been registered, then this function will return an error.  See the WacomMTError enumeration definition.