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
Attached Device Array function
Data Structures and Enumerations
WacomMTRegisterFingerReadCallback
WacomMTUnRegisterFingerReadCallback
WacomMTRegisterBlobReadCallback
WacomMTRegisterRawReadCallback
WacomMTRegisterFingerReadHWND (This is a Windows only call)
WacomMTUnRegisterFingerReadHWND (This is a Windows only
call)
WacomMTRegisterBlobReadHWND (This is
a Windows only call)
WacomMTUnRegisterBlobReadHWND (This is a Windows only call)
WacomMTRegisterFingerReadID (This is a Mac only call)
WacomMTUnRegisterFingerReadID (This is a Mac only call)
WacomMTRegisterBlobReadID (This is a Mac only call)
WacomMTUnRegisterBlobReadID (This is a Mac only call)
WacomMTMoveRegisteredFingerReadCallback
WacomMTMoveRegisteredBlobReadCallback
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.
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.
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.
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.
This
section will provide detailed information about each of the API functions.
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.
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.
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.
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.
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.
There
are three different types of data that may be provided by any given
device. They are finger, blob and raw.
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)
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.
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
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.
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.
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.
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.
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.
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).
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.
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.
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.
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).
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.
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.
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.
Unless otherwise specified, the functions are specified and
used in the same way for both Windows and Mac systems.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.