1. フィンガーデータは最も一般的で、最も有用です。すべてのマルチタッチデバイスは、少なくともフィンガーデータをサポートしています。このデータは、デバイス上に置かれた各指のタッチポイントを追跡します。その指が置かれている間はIDが割り当てられます。このIDは特定の指ではなく、接触点を表わします。 たとえば、ユーザが人差し指をデバイスに置くとID 1が割り当てられるとします。次に中指を置くと2が割り当てられます。続けて薬指を置くと3が割り当てられます。次いでユーザが中指を上げてラベル2の接触期間を終了します。その指をデバイスにもう一度戻すと、接触として現在使用されていないという理由でID 2が割り当てられる可能性はありますが、ID 4が割り当てられることもあります。中指と薬指の両方を離してから薬指をデバイスに戻すと、IDは前と同じ3ではなく2になるはずですが、5になる可能性もあります。




2. デバイスがBLOBデータをサポートする場合は、そのことがケイパビリティー構造体に示されます。 BLOBデータは、デバイスの表面のオブジェクトの輪郭を表わします。 BLOBには、基本BLOBとボイドBLOBの2種類があります。BLOBは、1つの基本BLOBと、ゼロ個以上のボイドBLOBで構成されます。ボイドについてはドーナツを思い浮かべると分かりやすいです。ドーナツの外側の輪郭が基本BLOBで、穴がボイドBLOBです。BLOBは、マスクやスマッジなどの不規則な形に対してアクションを実行する場合に使用されます。




3. デバイスがRAWデータをサポートする場合は、そのことがケイパビリティー構造体に示されます。 RAWデータは、デバイス上の各点の未処理の値です。

typedef enum _WacomMTError
{
  WMTErrorSuccess			= 0
  WMTErrorDriverNotFound		= 1
  WMTErrorBadVersion			= 2
  WMTErrorAPIOutdated			= 3
  WMTErrorInvalidParam			= 4
  WMTErrorQuit				= 5
  WMTErrorBufferTooSmall		= 6
} WacomMTError

WMTErrorSuccess：

呼び出しが成功した場合に返されます。

WMTErrorDriverNotFound:

インストール済みで実行中のドライバがAPIで検出されない場合に返されます。

WMTErrorBadVersion:

ドライバのバージョンがAPIと互換性がない場合に返されます。これは、アプリケーションがドライバでサポートされていない新しいAPIデータ構造体を要求する場合に発生します。

WMTErrorAPIOutdated:

アプリケーションが、ドライバでサポートされなくなったAPIデータ構造体を要求する場合に返されます。

WMTErrorInvalidParam:

1つ以上のパラメータが無効の場合に返されます。

WMTErrorQuit:

API終了呼び出しが行われる場合、またはAPIが正常に初期化されなかった場合に、待機関数によって返されます。

WMTErrorBufferTooSmall

提供されたバッファーが小さすぎる場合に返されます。

typedef enum _WacomMTDeviceType
{
  WMTDeviceTypeOpaque			= 0
  WMTDeviceTypeIntegrated		= 1
} WacomMTDeviceType

WMTDeviceTypeOpaque:

タッチセンサーはディスプレイに組み込まれません。液晶表示のないトラックパッドのようなデバイスが、この値を返します。

WMTDeviceTypeIntegrated:

タッチセンサーがディスプレイに組み込まれます。タブレットPCなどのオンスクリーンタッチデバイスが、この値を返します。

typedef enum _WacomMTCapabilityFlags
{
  WMTCapabilityFlagsRawAvailable		= (1 <<  0)
  WMTCapabilityFlagsBlobAvailable		= (1 <<  1)
  WMTCapabilityFlagsSensitivityAvailable	= (1 <<  2)
  WMTCapabilityFlagsReserved		= (1 << 31)
} WacomMTCapabilityFlags

WMTCapabilityFlagsRawAvailable:

このフラグが設定される場合、デバイスはRAWデータをサポートし、RAWデータの読み取りが可能になります。

WMTCapabilityFlagsBlobAvailable:

このフラグが設定される場合、デバイスはBLOBデータをサポートし、BLOBデータの読み取りが可能になります。

WMTCapabilityFlagsSensitivityAvailable:

このフラグが設定される場合、フィンガーデータで感度データが使用可能になります。感度データは、0から0xFFFFまでの値です。このフラグが設定されない場合、感度データは各アップパケットでゼロに設定され、ダウンパケット/ホールドパケットで最大に設定されます。感度の定義については、WacomMTFingerデータ構造体を参照してください。

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:

このデータ構造体のバージョン。

DeviceID:

タッチデバイスを識別する値。これはコンピュータごと、またセッションごとに異なる可能性がある固有の数値ですが、特定のセッション中は同じです。この値は、デバイスを識別するために、他のすべての呼出しで使用されます。

Type:

デバイスの種類を示す値。ペンタブレットには、画面との固定の関係はありません。液晶ペンタブレットは、単一ディスプレイと1対1の関係があります。

LogicalOriginX:

挿入後に報告されるデバイスの水平方向の最小値。ペンタブレットの場合、この値はゼロです。液晶ペンタブレットの場合、この値は、デスクトップ全体との関連でマップされたディスプレイの左（上）のポイント（ピクセル単位）です。タッチデバイスがディスプレイより大きい場合、これは隣接ディスプレイにマップされる場合があります。

LogicalOriginY:

挿入後に報告されるデバイスの垂直方向の最小値。ペンタブレットの場合、この値はゼロです。液晶ペンタブレットの場合、この値は、デスクトップ全体との関連でマップされたディスプレイの上（左）のポイント（ピクセル単位）です。タッチデバイスが統合ディスプレイより大きい場合、これは隣接ディスプレイにマップされる場合があります。

LogicalWidth:

挿入後に報告されるデバイスの幅。ペンタブレットの場合、この値は1で、単位は中立です。液晶ペンタブレットの場合、この値はデバイスがカバーするピクセルの数です。タッチデバイスがディスプレイより大きい場合、これは隣接ディスプレイにマップされる場合があります。

LogicalHeight:

挿入後に報告されるデバイスの高さ。ペンタブレットの場合、この値は1で、単位は中立です。液晶ペンタブレットの場合、この値はデバイスがカバーするピクセルの数です。タッチデバイスがディスプレイより大きい場合、これは隣接ディスプレイにマップされる場合があります。

PhysicalSizeX:

デバイスの検知領域の幅（mm単位）。ある座標系から別の座標系にデバイスデータを変換するために、他のサイズ因子と一緒に使用されます。

PhysicalSizeY:

デバイスの検知領域の高さ（mm単位）。ある座標系から別の座標系にデバイスデータを変換するために、他のサイズ因子と一緒に使用されます。

ReportedSizeX:

デバイスの幅（ネイティブカウント単位）。データの最大解像度を判別するために、他のサイズ因子と一緒に使用されます。水平方向の解像度は、この値をPhysicalSizeXで除算することによって計算されます。

ReportedSizeY:

デバイスの高さ（ネイティブカウント単位）。データの最大解像度を判別するために、他のサイズ因子と一緒に使用されます。垂直方向の解像度は、この値をPhysicalSizeYで除算することによって計算されます。

ScanSizeX:

デバイスの幅（スキャンコイル単位）。 これは未処理データをサポートするデバイスにのみ提供されます。 この値は、未処理データバッファーのサイズ（ScanSizeX * ScanSizeY）を計算するために使用されます。デバイスで未処理データがサポートされない場合は、この値を無視する必要があります。

ScanSizeY:

デバイスの高さ（スキャンコイル単位）。 これは未処理データをサポートするデバイスにのみ提供されます。 この値は、未処理データバッファーのサイズ（ScanSizeX * ScanSizeY）を計算するために使用されます。 デバイスで未処理データがサポートされない場合は、この値を無視する必要があります。

FingerMax:

サポートされる指の最大数。これは、このデバイスが任意の時点でダウンと報告できる指の数です。これは、指収集構造体の最大サイズの計算に役立てるために使用できます。これはFingerIDの最大値ではありません。

BlobMax:

BLOB集合内のBLOBの最大数。BLOBは、輪郭を定義する一連のポイントです。有効なBLOBは、基本BLOBまたはボイドBLOBです。 各ボイドBLOBには、親が1つだけあります。一方、基本BLOBには、親BLOB内のボイド領域を定義するゼロ個以上の子BLOBがあります。例えば、ドーナツの形は、外側の輪が親BLOBで、内側の輪が子BLOBであるBLOB集合です。

BlobPointsMax:

BLOBを構成するBLOBポイントの最大数。 これらのBLOBの値（BlobMaxとBlobPointsMax）を使用して、BLOB集合の最大サイズ（BlobMax * BlobPointsMax）を計算できます。

CapabilityFlags:

特定のデータ要素の存在を示すための値。WacomMTCapabilityFlags列挙型定義を参照してください。

typedef enum _WacomMTFingerState
{
  WMTFingerStateNone			= 0
  WMTFingerStateDown			= 1
  WMTFingerStateHold			= 2
  WMTFingerStateUp			= 3
} WacomMTFingerState

WMTFingerStateNone:

指バッファーには、複数の接触のスペースが含まれる可能性があります。使用されていない追加の接触は「None」に設定されます。接触が「アップ」状態を通過すると、TouchStateが「None」に設定され、これ以上の処理は不要であることが示されます。この状態で組み込まれているデータがあれば、そのデータは無効です。

WMTFingerStateDown:

最初の指の接触を示します。特定の接触用の最初のタッチパケット。

WMTFingerStateHold:

指が接触している間の後続のパケット。

WMTFingerStateUp:

特定の指の接触用の最後のタッチパケット。指を上げるときに報告されます。これは、認識された最後の有効な位置で報告されます。

typedef struct WacomMTFinger
{
  int				FingerID
  float				X
  float				Y
  float				Width
  float				Height
  unsigned short			Sensitivity
  float				Orientation
  bool				Confidence
  WacomMTFingerState		TouchState
} WacomMTFinger

FingerID:

接触の固有の識別子。この値は最初の接触の1で始まり、後続の接触ごとに増やされます。この値は、すべての接触がなくなると1にリセットされます。これは、フレームごとに接触を追跡するために使用されます。これは特定の指の固有の値を表わしているのではなく、接触ごとに固有であり、接触期間中は同じ接触点を表わします。

X:

論理単位内の接触領域のスケールされたX。

Y:

論理単位内の接触領域のスケールされたY。

Width:

論理単位内の接触領域の幅。

Height:

論理単位内の接触領域の高さ。

Sensitivity:

接触の強さ。これは圧力ではありません。これは接触点の強さをデバイス/ユーザごとに個別に表わしたものです。同じフレーム/ジェスチャー内の他の指との関係でのみ有効です。

Orientation:

接触点の方向（角度）。

Confidence:

trueの場合、これが指による有効なタッチであるとドライバは認識します。falseの場合、これは不測のタッチ（前腕または手のひら）である可能性があるとドライバは見なします。

TouchState:

この指の接触の状態。WacomMTFingerState列挙型定義を参照してください。

typedef struct WacomMTFingerCollection
{
  int			Version
  int			DeviceID
  int			FrameNumber
  int			FingerCount
  WacomMTFinger		*FingerData
} WacomMTFingerCollection

Version:

このデータ構造体のバージョン。

DeviceID:

タッチデバイスを識別する値。これはコンピュータごと、またセッションごとに異なる可能性がある固有の数値ですが、特定のセッション中は同じです。

FingerCount:

フィンガーデータ配列内のエレメントの数。この値はフレームごとに異なりますが、特定のデバイスのFingerMax値より大きくなることはありません。

FingerData:

複数の指で構成される配列へのポインタ。FingerDataブロックのサイズは、FingerCount * sizeof(WacomMTFinger)で計算されます。

typedef enum _WacomMTBlobType
{
  WMTBlobTypePrimary			= 0
  WMTBlobTypeVoid			= 1
} WacomMTBlobType

WMTBlobTypePrimary:

これは外側の基本BLOBの輪郭です。

WMTBlobTypeVoid:

外側の基本BLOB内に含まれている内側のBLOBの輪郭です。ボイド BLOBは、基本BLOB内のタッチされていない領域です。基本 BLOBには、1つ以上のボイドBLOBが含まれている場合があります。ボイド BLOBには、他のBLOBは含まれていません。固有の基本BLOBが別のBLOBのボイド内に存在することは可能ですが、ボイドはそのBLOBを参照しません。

typedef struct WacomMTBlobPoint
{
  float			X
  float			Y
  unsigned short		Sensitivity
} WacomMTBlobPoint

X:

論理単位内のBLOBポイントのスケールされたX値

Y:

論理単位内のBLOBポイントのスケールされたY値

Sensitivity:

この BLOBポイントでの信号の強さ。これは圧力ではありません。これは接触点の強さをデバイス/ユーザごとに個別に表わしたものです。同じフレーム内の他のBLOBとの関係でのみ有効です。

typedef struct WacomMTBlob
{
  int				BlobID
  float				X
  float				Y
  bool				Confidence
  WacomMTBlobType		BlobType
  int				ParentID
  int				PointCount
  WacomMTBlobPoint		*BlobPoints
} WacomMTBlob

BlobID:

これは、このBLOBを一意に識別する値です。この値はフレームごとに持続します。

X:

BLOB領域のスケールされたX重心（論理単位）。

Y:

BLOB領域のスケールされたＹ重心（論理単位）。

Confidence:

trueの場合、これは有効なタッチであるとドライバは認識します。falseの場合、これは不測のタッチ（前腕または手のひら）である可能性があるとドライバは見なします。

BlobType:

この構造体が表わすBLOBの種類。WacomMTBlobType列挙型定義を参照してください。

ParentID:

これは親BLOBを識別します。BlobTypeが「Void」の場合にのみ有効です。

PointCount:

BLOBポイント配列内のエレメントの数。これはBLOBの輪郭を構成するポイントの数です。

BlobPoints:

複数のBLOBポイントで構成される配列へのポインタ。BlobPointsブロックのサイズは、PointCount * sizeof(WacomMTBlobPoint)で計算されます。これらのBLOBポイントは、閉じられた領域を形成します。

typedef struct WacomMTBlobAggregate
{
  int				Version
  int				DeviceID
  int				FrameNumber
  int				BlobCount
  WacomMTBlob			*BlobArray
} WacomMTBlobAggregate

Version:

このデータ構造体のバージョン。

DeviceID:

タッチデバイスを識別する値。これはコンピュータごと、またセッションごとに異なる可能性がある固有の数値ですが、特定のセッション中は同じです。

BlobCount:

BLOBデータ配列内のエレメントの数。

BlobArray:

BLOBの配列。BlobArrayブロックのサイズは、BlobCount * sizeof(WacomMTBlob)で計算されます。

typedef struct WacomMTRawData
{
  int			Version
  int			DeviceID
  int			FrameNumber
  int			ElementCount
  unsigned short		*Sensitivity
} WacomMTRawData

Version:

このデータ構造体のバージョン。

DeviceID:

タッチデバイスを識別する値。これはコンピュータごとに異なる可能性がある固有の数値ですが、特定のセッション中は同じです。

ElementCount:

接触配列内のエレメントの数。この値は、ScanSizeY * ScanSizeXで計算されます。

Sensitivity:

配列感度値へのポインタ。感度ブロックのサイズは、ElementCount * sizeof(unsigned short)で計算されます。各ポイントの位置は、(Y * ScanSizeX) + Xで計算されます。

typedef struct WacomMTHitRect
{
  float		originX
  float		originY
  float		width
  float		height
} WacomMTHitRect

originX:

矩形の原点の水平方向の値。

originY:

矩形の原点の垂直方向の値。

width:

矩形の水平方向の幅。

height:

矩形の垂直方向の高さ。

typedef enum _WacomMTProcessingMode
{
  WMTProcessingModeNone		= 0
  WMTProcessingModeObserver		= (1 << 0)
  WMTProcessingModeReserved		= (1 << 31)
} WacomMTProcessingMode

WMTProcessingModeNone:

データがコールバックに送信され、これ以上の処理は行われません。

WMTProcessingModeObserver:

データが処理のためにOSに並行して送られます。

WacomMTError WacomMTInitialize( int libraryAPIVersion );

この関数は、アプリケーションとドライバの接続を試行します。この関数は、他のWacomマルチタッチ関数を呼び出す前に正常に呼び出す必要があります。

void WacomMTQuit();

この関数は、ドライバサービスとの接続を閉じます。これは、アプリケーションを閉じる場合や、タッチデータが不要になる場合に呼び出す必要があります。WacomMTQuitを呼び出した後は、タッチ対話を再開するためにWacomMTInitializeをもう一度呼び出す必要があります。

int WacomMTGetAttachedDeviceIDs( int *deviceArray, size_t bufferSize );

この関数は、システムに接続されているマルチタッチセンサーの数を返します。

WacomMTError WacomMTGetDeviceCapabilities( int deviceID, WacomMTCapability *capabilityBuffer );

この関数は、呼び出し側が割り振ったWacomMTCapability構造体に、要求されたデバイス識別子のケイパビリティー情報を入れます。

WacomMTError WacomMTRegisterAttachCallback( WMT_ATTACH_CALLBACK attachCallback, void *userData );

この関数は、新しいタッチデバイスの接続時に呼び出すコールバック関数を登録できます。登録すると、APIは、現在接続されているデバイスごとにコールバックを発行します。各プロセスに登録できるアタッチコールバックは1つのみです。アタッチコールバックをキャンセルするには、プロセスはNULLを使用して、この関数を呼び出すことができます。

WacomMTError WacomMTRegisterDetachCallback( WMT_DETACH_CALLBACK detachCallback, void *userData );

この関数は、タッチデバイスの切り離し時に呼び出すコールバック関数を登録できます。各プロセスに登録できるデタッチコールバックは1つのみです。デタッチコールバックをキャンセルするには、プロセスはNULLを使用して、この関数を呼び出すことができます。

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

この関数を使用すると、指タッチパケットの準備が整って要求されたデバイスのヒット矩形内にあるときに呼び出すコールバック関数を登録できます。プロセスは必要なだけのコールバックを作成できますが、デバイスヒット矩形ごとに作成できるコールバックは1つのみです。コールバックをキャンセルする場合は、この関数にNULLを指定して既存のデバイスヒット矩形に対して呼び出します。コールバックは、作成された順に処理されます。

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

この関数を使用すると、BLOBデータの準備が整って要求されたデバイスのヒット矩形内にあるときに呼び出すコールバック関数を登録できます。プロセスは必要なだけのコールバックを作成できますが、デバイスヒット矩形ごとに作成できるコールバックは1つのみです。コールバックをキャンセルする場合は、この関数にNULLを指定して既存のデバイスヒット矩形に対して呼び出します。コールバックは、作成された順に処理されます。

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

この関数は、指定されたデバイスでRAWデータの準備が整ったときに呼び出すコールバック関数を登録できます。デバイスごとに登録できるコールバックは1つのみです。デバイスコールバックをキャンセルする場合は、コールバックにNULLを指定して、この関数を呼び出します。コールバックは、作成された順に処理されます。

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

この関数を使用すると、フィンガーデータを受信するためのウィンドウハンドルを登録できます。指定されたデバイスのフィンガーデータのパケットの準備が整ったら、WM_FINGERDATAメッセージがウィンドウハンドルに送信されます。lParamパラメータは、フィンガーデータが入っているWacomMTFingerCollection構造体へのポインタになります。bufferDepthパラメータは、作成されるコールバックバッファーの数を決定します。バッファーはリング形式で使用されます。ウィンドウハンドルにつき、デバイスごとに使用できるフィンガーデータコールバックの数は1つのみです。ウィンドウハンドルは、ヒット矩形を作成するためにも使用されます。ヒット矩形は、この関数が呼び出されるときに計算されます。ウィンドウを移動するかサイズ変更すると、この関数をもう一度呼び出す必要があります。bufferDepthが変更されると、既存のすべてのバッファーが無効になります。デバイスコールバックをキャンセルするには、ゼロのbufferDepthを指定して、この関数を呼び出す必要があります

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

この関数を使用すると、BLOBデータを受信するためのウィンドウハンドルを登録できます。指定のデバイスのBLOBパケットの準備が整ったら、WM_BLOBDATAメッセージがウィンドウハンドルに送信されます。lParamパラメータは、BLOBデータが入っているWacomMTBlobAggregate構造体へのポインタになります。bufferDepthパラメータは、作成されるコールバックバッファーの数を決定します。バッファーはリング形式で使用されます。ウィンドウハンドルにつき、デバイスごとに使用できるBLOBデータコールバックの数は1つのみです。ウィンドウハンドルは、ヒット矩形を作成するためにも使用されます。ヒット矩形は、この関数が呼び出されるときに計算されます。ウィンドウを移動するかサイズ変更すると、この関数をもう一度呼び出す必要があります。bufferDepthが変更されると、既存のすべてのバッファーが無効になります。デバイスコールバックをキャンセルするには、ゼロのbufferDepthを指定して、この関数を呼び出す必要があります。
この関数はCintiq 24HD touchのみ対応しています。

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

この関数を使用すると、RAWデータを受信するためのウィンドウハンドルを登録できます。指定されたデバイスのデータフレームの準備が整ったら、WM_RAWDATAメッセージがウィンドウハンドルに送信されます。lParamパラメータは、WacomMTRawData構造体へのポインタになります。bufferDepthパラメータは、作成されるコールバックバッファーの数を決定します。バッファーはリング形式で使用されます。ウィンドウハンドルにつき、デバイスごとに使用できるRAWデータコールバックの数は1つのみです。bufferDepthが変更されると、既存のすべてのバッファーが無効になります。デバイスコールバックをキャンセルするには、ゼロのbufferDepthを指定して、この関数を呼び出す必要があります。
この関数はCintiq 24HD touchのみ対応しています。