Wacom feel™ Multi-Touch API
更新情報
APIバージョン | 更新日付(作成者) | 更新理由 |
2.0 | 2012/5/7(RCC) | lParamの使用法を訂正 |
3.0 | 2012/5/22(DT、RCC) | FrameNumberサポートの追加、FAQへの言及 |
INDEX
- 1 概要
- 2 サポートされるタブレット
- 3 関数の詳細
- 3.1 初期化関数
- 3.2 終了関数
- 3.3 接続デバイス配列関数
- 3.4 デバイスケイパビリティー関数
- 3.5 デバイスコールバック関数
- 3.6 日付読み取り関数
- 4 サンプルコード
- 5 データ構造体と列挙型
- 5.1 WacomMTError
- 5.2 WacomMTDeviceType
- 5.3 WacomMTCapabilityFlags
- 5.4 WacomMTCapability
- 5.5 WacomMTFingerState
- 5.6 WacomMTFinger
- 5.7 WacomMTFingerCollection
- 5.8 WacomMTBlobType
- 5.9 WacomMTBlobPoint
- 5.10 WacomMTBlob
- 5.11 WacomMTBlobAggregate
- 5.12 WacomMTRawData
- 5.13 WacomMTHitRect
- 5.14 WacomMTProcessingMode
- 6 関数
- 6.1 WacomMTInitialize
- 6.2 WacomMTQuit
- 6.3 WacomMTGetAttachedDeviceIDs
- 6.4 WacomMTGetDeviceCapabilities
- 6.5 WacomMTRegisterAttachCallback
- 6.6 WacomMTRegisterDetachCallback
- 6.7 WacomMTRegisterFingerReadCallback
- 6.8 WacomMTRegisterBlobReadCallback
- 6.9 WacomMTRegisterRawReadCallback
- 6.10 WacomMTRegisterFingerReadHWND(Windows専用の呼出し)
- 6.11 WacomMTRegisterBlobReadHWND(Windows専用の呼出し)
- 6.12 WacomMTRegisterRawReadHWND(Windows専用の呼出し)
詳細
1 概要
この資料では、Wacom feel™ Multi-Touchアプリケーションプログラミングインターフェースについて説明します。このAPIを使用することにより、アプリケーションはWacomマルチタッチデバイスの詳細なタッチデータを取得できます。APIのダイナミックロードライブラリがWacomタブレットドライバに組み込まれていますが、すべてのデバイスがマルチタッチをサポートしているわけではありません。APIによって提供される低レベルデータは、フィンガーポイントデータ、BLOB領域データ、およびRAWセンサーデータです。一部のデバイスでは、すべての種類のデータがサポートされているわけではありません。
いくつかのファイルをfeel Mutil-Touch SDKからアプリケーションに組み込むだけで、このAPIを使用できます。すべてのデータ構造体およびデータの種類を定義するヘッダーファイル(WacomMultiTouchTypes.h)、APIのエントリポイントを定義するヘッダーファイル(WacomMultiTouch.h)、およびライブラリの動的ロードを設定する実装ファイル(WacomMutiTouch.cpp)があります。ダイナミックライブラリ(WacomMT.dll)はドライバに組み込まれているため、アプリケーションには組み込まないでください。
- API DLLを初期化します。dllがロードされていない場合は、Wacomドライバがインストールされていないか、現在のWacomドライバがfeel Multi-Touch APIをサポートしていません。
- デバイスアタッチコールバックを確立します。これは、システム上のマルチタッチデバイスごとに即時に呼び出されます。ユーザが新しいマルチタッチデバイスをシステムにアタッチする場合にも呼び出されます。このコールバックには、各デバイスのケイパビリティー構造体も含まれています。このデータを使用することにより、アプリケーションはサポートされているデータ型とデータ範囲を確認できます。
- デバイスデタッチコールバックを確立します。これは、デバイスをシステムから切り離すときに呼び出されます。アプリケーションが作成したデータコールバックで開いているものがあれば、このコールバックを使用して閉じます。
- タッチポイントデータをサポートするデバイスがアタッチされたものと想定して、アプリケーションがタッチポイントデータコールバックを確立します。このコールバックは、デバイス上で指が検出されるたびにトリガーされます。フィンガーデータには、位置情報と状態情報が含まれています。アプリケーションは、すぐにデータを処理するか、後で処理するためにデータをワーカースレッドのバッファーに入れます。
- アプリケーションでタッチデータの処理が完了したら、アプリケーションはすべてのコールバックを閉じて、終了関数を呼び出す必要があります。
このAPIは、WintabペンインターフェースAPIと一緒に使用できます。タッチAPIは、ペンの近接性を処理したり通知したりすることはありません。アプリケーションがペンデータとタッチデータの両方を処理する必要がある場合、アプリケーションは両方のAPIをモニターする必要があります。
2 サポートされるタブレット
サポートされるタブレットのリストについては、FAQ – Wacom feel™ Multi-Touch API を参照してください。マルチタッチアプリケーションでは、製品名やモデル番号を条件として使用してはならいことに注意してください。この資料で説明されているとおり、常にタブレットのタッチプロパティにプログラムする必要があります。
3 関数の詳細
このセクションでは、各API関数の詳細について説明します。
3.1 初期化関数
この関数の一部がサンプルコードに実装されています。最初に、この関数はWacom feel Multi-Touchライブラリのロードを試行します。これが成功すると、他のすべてのAPI関数のエントリポイントがロードされます。次に、この関数は、アプリケーションによって要求されているAPIのバージョンを使用してライブラリを呼び出します。このバージョンがライブラリでサポートされている場合は、成功と報告されます。この関数のいずれかの部分で障害が発生すると、エラーコードが返され、ライブラリは機能しません。
3.2 終了関数
ライブラリがロードされていた場合、この関数は、開いているリソースを解放するために呼び出されます。次に、すべてのAPI関数が、デフォルトのエラーハンドラにリセットされます。最後に、ライブラリがアンロードされます。
3.3 接続デバイス配列関数
この関数は、接続されているデバイスの配列を返します。この関数は、整数の配列を取り込みます。この関数を使用するには、アプリケーションは、バッファーとサイズを指定しないで、この関数を呼び出す必要があります。この関数は、接続されているデイバスの数を返します。次に、アプリケーションがバッファーを作成してから、この関数を再呼び出しします。これら2回の呼出しで、デバイスの数が異なる場合があることに注意してください。次に、この関数は、接続されているデバイスの数をもう一度返し、バッファーに保持されるデバイスIDを提供します。次に、これらのデバイスIDを使用して、デバイスケイパビリティーが取得されます。アプリケーションでアタッチコールバック関数を使用することが推奨されています。
3.4 デバイスケイパビリティー関数
ケイパビリティー関数は、指定のデバイスIDのデバイスケイパビリティーを取得するために使用されます。アプリケーションが上記の関数を使用してIDを取得する場合は、各IDを指定してこの関数を呼び出し、ケイパビリティー構造体を取得します。これらのケイパビリティー構造体は、アプリケーションによってキャッシュに入れられ、そのデバイスで提供されるデータのスケーリングが認識されます。アプリケーションは、データ処理時にこの関数を呼び出すことができますが、これにより多くの不必要な処理が行われることになります。
3.5 デバイスコールバック関数
アタッチコールバック関数は、デバイス情報を収集するための最善の方法です。この関数は、現在接続されているすべてのデバイスのケイパビリティー構造体を提供するだけでなく、システムをモニターして新しいデバイスが追加されたときにアプリケーションへの通知も行います。これは、デタッチコールバックとともに、マルチタッチデバイスを追跡するための推奨される方法です。
デタッチコールバック関数は、デバイスの切り離しをモニターしてアプリケーションに通知します。厳密に言えばアプリケーションは切り離しを無視できますが、アプリケーションは開いているコールバックを閉じることが推奨されています。これにより、アプリケーションが接続関数により迅速に応答できるようになります。
3.6 日付読み取り関数
- フィンガーデータは最も一般的で、最も有用です。すべてのマルチタッチデバイスは、少なくともフィンガーデータをサポートしています。このデータは、デバイス上に置かれた各指のタッチポイントを追跡します。その指が置かれている間はIDが割り当てられます。このIDは特定の指ではなく、接触点を表わします。 たとえば、ユーザが人差し指をデバイスに置くとID 1が割り当てられるとします。次に中指を置くと2が割り当てられます。続けて薬指を置くと3が割り当てられます。次いでユーザが中指を上げてラベル2の接触期間を終了します。その指をデバイスにもう一度戻すと、接触として現在使用されていないという理由でID 2が割り当てられる可能性はありますが、ID 4が割り当てられることもあります。中指と薬指の両方を離してから薬指をデバイスに戻すと、IDは前と同じ3ではなく2になるはずですが、5になる可能性もあります。
- デバイスがBLOBデータをサポートする場合は、そのことがケイパビリティー構造体に示されます。 BLOBデータは、デバイスの表面のオブジェクトの輪郭を表わします。 BLOBには、基本BLOBとボイドBLOBの2種類があります。BLOBは、1つの基本BLOBと、ゼロ個以上のボイドBLOBで構成されます。ボイドについてはドーナツを思い浮かべると分かりやすいです。ドーナツの外側の輪郭が基本BLOBで、穴がボイドBLOBです。BLOBは、マスクやスマッジなどの不規則な形に対してアクションを実行する場合に使用されます。
- デバイスがRAWデータをサポートする場合は、そのことがケイパビリティー構造体に示されます。 RAWデータは、デバイス上の各点の未処理の値です。
データコールバック関数は、特定のデバイスのコールバックを設定します。コールバックは、コールバックの作成対象のデバイスと、そのコールバックに提供されるヒット矩形とによって定義されます。これは、アプリケーションがデバイス上に領域を作成できるという意味です。ほとんどの場合、アプリケーションがデバイスを分割する必要はないため、デフォルトの(NULL)領域はタッチデバイス全体になっています。ヒット矩形の単位は、デバイスによって異なります。Bambooなどのペンタブレットの場合、単位は中立です。デバイスの起点は0,0で、幅は1、高さは1です。タブレットPCなどの液晶ペンタブレットの場合、ヒット矩形はピクセル単位です。仮想ディスプレイでのデバイスの位置は、ドライバが認識しています。これらの値は、ディスプレイの位置またはサイズの変更時に変更されます。アプリケーションは、システムデバイスの変更メッセージをモニターする必要があります。
APIには、Windows用の追加のデータ収集関数があります。これらの関数はHWNDを取り込み、コールバックをアクティブにするのではなく、提供されるウィンドウのメッセージスレッドでデータがアプリケーションに送信されます。提供されるウィンドウは、液晶ペンタブレットのヒット矩形を作成するためにも使用されます。不適切なデータ処理は通常のメッセージ処理を妨げるため、これらの関数を使用する場合は特に注意が必要です。
データ関数が作成されると、アプリケーションはデータの扱い方を示します。アプリケーションがオブザーバの場合、データはアプリケーションとシステムの両方に送信されます。これは、アプリケーションがデータに基づいてアクションを実行する場合、ドライバ/OSはそのことを認識しないで、データを処理するということです。コールバックは、コンシューマモードでも作成できます。そのデータの最初のコンシューマが、データを受信する唯一のコンシューマです。OSはデータを取得しません。コンシューマがデータを取得するには、アプリケーションが最前面のアプリケーションになっている(キーボードフォーカスが置かれている)必要があります。オブザーバは、アプリケーションがバックグラウンドにあるとしても、コンシューマによって取り込まれなかったすべてのデータを取得します。オブザーバがデータの取得を停止する必要がある場合は、コールバック関数を閉じる必要があります。
4 サンプルコード
走り書きサンプルコードアプリケーションが、SDKに付属しています。このアプリケーションは、フィンガーポイントデータをデバイスから取得して、これらの指をクライアント領域に描画する方法を示しています。この例では、デバイスコールバックを設定する方法を示します。また、デバイス配列メソッドも示します。前述のとおり、この両方を同じアプリケーションで行う必要はありません。サンプルコードについての他の具体的な情報については、コード内のコメントを参照してください。。
5 データ構造体と列挙型
5.1 WacomMTError
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
- 提供されたバッファーが小さすぎる場合に返されます。
5.2 WacomMTDeviceType
typedef enum _WacomMTDeviceType { WMTDeviceTypeOpaque = 0 WMTDeviceTypeIntegrated = 1 } WacomMTDeviceType
- WMTDeviceTypeOpaque:
- タッチセンサーはディスプレイに組み込まれません。液晶表示のないトラックパッドのようなデバイスが、この値を返します。
- WMTDeviceTypeIntegrated:
- タッチセンサーがディスプレイに組み込まれます。タブレットPCなどのオンスクリーンタッチデバイスが、この値を返します。
5.3 WacomMTCapabilityFlags
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データ構造体を参照してください。
5.4 WacomMTCapability
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列挙型定義を参照してください。
5.5 WacomMTFingerState
typedef enum _WacomMTFingerState { WMTFingerStateNone = 0 WMTFingerStateDown = 1 WMTFingerStateHold = 2 WMTFingerStateUp = 3 } WacomMTFingerState
- WMTFingerStateNone:
- 指バッファーには、複数の接触のスペースが含まれる可能性があります。使用されていない追加の接触は「None」に設定されます。接触が「アップ」状態を通過すると、TouchStateが「None」に設定され、これ以上の処理は不要であることが示されます。この状態で組み込まれているデータがあれば、そのデータは無効です。
- WMTFingerStateDown:
- 最初の指の接触を示します。特定の接触用の最初のタッチパケット。
- WMTFingerStateHold:
- 指が接触している間の後続のパケット。
- WMTFingerStateUp:
- 特定の指の接触用の最後のタッチパケット。指を上げるときに報告されます。これは、認識された最後の有効な位置で報告されます。
5.6 WacomMTFinger
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列挙型定義を参照してください。
5.7 WacomMTFingerCollection
typedef struct WacomMTFingerCollection { int Version int DeviceID int FrameNumber int FingerCount WacomMTFinger *FingerData } WacomMTFingerCollection
- Version:
- このデータ構造体のバージョン。
- DeviceID:
- タッチデバイスを識別する値。これはコンピュータごと、またセッションごとに異なる可能性がある固有の数値ですが、特定のセッション中は同じです。
- FingerCount:
- フィンガーデータ配列内のエレメントの数。この値はフレームごとに異なりますが、特定のデバイスのFingerMax値より大きくなることはありません。
- FingerData:
- 複数の指で構成される配列へのポインタ。FingerDataブロックのサイズは、FingerCount * sizeof(WacomMTFinger)で計算されます。
5.8 WacomMTBlobType
typedef enum _WacomMTBlobType { WMTBlobTypePrimary = 0 WMTBlobTypeVoid = 1 } WacomMTBlobType
- WMTBlobTypePrimary:
- これは外側の基本BLOBの輪郭です。
- WMTBlobTypeVoid:
- 外側の基本BLOB内に含まれている内側のBLOBの輪郭です。ボイド BLOBは、基本BLOB内のタッチされていない領域です。基本 BLOBには、1つ以上のボイドBLOBが含まれている場合があります。ボイド BLOBには、他のBLOBは含まれていません。固有の基本BLOBが別のBLOBのボイド内に存在することは可能ですが、ボイドはそのBLOBを参照しません。
5.9 WacomMTBlobPoint
typedef struct WacomMTBlobPoint { float X float Y unsigned short Sensitivity } WacomMTBlobPoint
- X:
- 論理単位内のBLOBポイントのスケールされたX値
- Y:
- 論理単位内のBLOBポイントのスケールされたY値
- Sensitivity:
- この BLOBポイントでの信号の強さ。これは圧力ではありません。これは接触点の強さをデバイス/ユーザごとに個別に表わしたものです。同じフレーム内の他のBLOBとの関係でのみ有効です。
5.10 WacomMTBlob
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領域のスケールされたY重心(論理単位)。
- Confidence:
- trueの場合、これは有効なタッチであるとドライバは認識します。falseの場合、これは不測のタッチ(前腕または手のひら)である可能性があるとドライバは見なします。
- BlobType:
- この構造体が表わすBLOBの種類。WacomMTBlobType列挙型定義を参照してください。
- ParentID:
- これは親BLOBを識別します。BlobTypeが「Void」の場合にのみ有効です。
- PointCount:
- BLOBポイント配列内のエレメントの数。これはBLOBの輪郭を構成するポイントの数です。
- BlobPoints:
- 複数のBLOBポイントで構成される配列へのポインタ。BlobPointsブロックのサイズは、PointCount * sizeof(WacomMTBlobPoint)で計算されます。これらのBLOBポイントは、閉じられた領域を形成します。
5.11 WacomMTBlobAggregate
typedef struct WacomMTBlobAggregate { int Version int DeviceID int FrameNumber int BlobCount WacomMTBlob *BlobArray } WacomMTBlobAggregate
- Version:
- このデータ構造体のバージョン。
- DeviceID:
- タッチデバイスを識別する値。これはコンピュータごと、またセッションごとに異なる可能性がある固有の数値ですが、特定のセッション中は同じです。
- BlobCount:
- BLOBデータ配列内のエレメントの数。
- BlobArray:
- BLOBの配列。BlobArrayブロックのサイズは、BlobCount * sizeof(WacomMTBlob)で計算されます。
5.12 WacomMTRawData
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で計算されます。
5.13 WacomMTHitRect
typedef struct WacomMTHitRect { float originX float originY float width float height } WacomMTHitRect
- originX:
- 矩形の原点の水平方向の値。
- originY:
- 矩形の原点の垂直方向の値。
- width:
- 矩形の水平方向の幅。
- height:
- 矩形の垂直方向の高さ。
5.14 WacomMTProcessingMode
typedef enum _WacomMTProcessingMode { WMTProcessingModeNone = 0 WMTProcessingModeObserver = (1 << 0) WMTProcessingModeReserved = (1 << 31) } WacomMTProcessingMode
- WMTProcessingModeNone:
- データがコールバックに送信され、これ以上の処理は行われません。
- WMTProcessingModeObserver:
- データが処理のためにOSに並行して送られます。
6 関数
6.1 WacomMTInitialize
- WacomMTError WacomMTInitialize( int libraryAPIVersion );
- この関数は、アプリケーションとドライバの接続を試行します。この関数は、他のWacomマルチタッチ関数を呼び出す前に正常に呼び出す必要があります。
- パラメーター:
- libraryAPIVersion:
- これはアプリケーションが使用しているAPIのバージョンです。この値はAPIで使用され、アプリケーションの期待されるデータ構造体が構成されます。提供されている定義済みの値WACOM_MULTI_TOUCH_API_VERSIONを使用してください。
- 戻り値:
- WacomMTError列挙型定義を参照してください。
6.2 WacomMTQuit
- void WacomMTQuit();
- この関数は、ドライバサービスとの接続を閉じます。これは、アプリケーションを閉じる場合や、タッチデータが不要になる場合に呼び出す必要があります。WacomMTQuitを呼び出した後は、タッチ対話を再開するためにWacomMTInitializeをもう一度呼び出す必要があります。
6.3 WacomMTGetAttachedDeviceIDs
- int WacomMTGetAttachedDeviceIDs( int *deviceArray, size_t bufferSize );
- この関数は、システムに接続されているマルチタッチセンサーの数を返します。
- パラメータ:
- deviceArray:
- これはアプリケーションが使用しているAPIのバージョンです。この値はAPIで使用され、アプリケーションの期待されるデータ構造体が構成されます。提供されている定義済みの値WACOM_MULTI_TOUCH_API_VERSIONを使用してください。
bufferSize: - これはアプリケーションが使用しているAPIのバージョンです。この値はAPIで使用され、アプリケーションの期待されるデータ構造体が構成されます。提供されている定義済みの値WACOM_MULTI_TOUCH_API_VERSIONを使用してください。
- 戻り値:
- 戻り値は、システムに接続されているセンサーの数です。
6.4 WacomMTGetDeviceCapabilities
- WacomMTError WacomMTGetDeviceCapabilities( int deviceID, WacomMTCapability *capabilityBuffer );
- この関数は、呼び出し側が割り振ったWacomMTCapability構造体に、要求されたデバイス識別子のケイパビリティー情報を入れます。
- パラメータ:
- deviceID:
- デバイスのID。これらのIDの取得元として有効なのは、GetAttachedDeviceID配列、指パケットdeviceIDメンバー、BLOBパケットdeviceIDメンバー、またはRAWパケットdeviceIDメンバーです。
- capabilityBuffer:
- これは、成功時にデバイスケイパビリティーデータが入れられる、呼び出し側が割り振った構造体です。この構造体は、初期化時に提供されたAPIバージョンによって定義されます。
- 戻り値:
- WacomMTError列挙型定義を参照してください。
6.5 WacomMTRegisterAttachCallback
- WacomMTError WacomMTRegisterAttachCallback( WMT_ATTACH_CALLBACK attachCallback, void *userData );
- この関数は、新しいタッチデバイスの接続時に呼び出すコールバック関数を登録できます。登録すると、APIは、現在接続されているデバイスごとにコールバックを発行します。各プロセスに登録できるアタッチコールバックは1つのみです。アタッチコールバックをキャンセルするには、プロセスはNULLを使用して、この関数を呼び出すことができます。
- パラメータ:
- 関数定義は、次のとおりです。void ( *WMT_ATTACH_CALLBACK )( WacomMTCapability deviceInformation, void *userData );
この関数は、接続されているデバイスのWacomMTCapability構造体と、呼び出しの登録時に提供されたuserDataを使用して呼び出されます。
- 戻り値:
- WacomMTError列挙型定義を参照してください。
6.6 WacomMTRegisterDetachCallback
- WacomMTError WacomMTRegisterDetachCallback( WMT_DETACH_CALLBACK detachCallback, void *userData );
- この関数は、タッチデバイスの切り離し時に呼び出すコールバック関数を登録できます。各プロセスに登録できるデタッチコールバックは1つのみです。デタッチコールバックをキャンセルするには、プロセスはNULLを使用して、この関数を呼び出すことができます。
- パラメータ:
- 関数定義は、次のとおりです。void ( *WMT_DETACH_CALLBACK )( int deviceId, void *userData );
この関数は、切り離されているセンサーのdeviceIDと、呼び出しの登録時に提供されたuserDataを使用して呼び出されます。
- 戻り値:
- WacomMTError列挙型定義を参照してください。
6.7 WacomMTRegisterFingerReadCallback
- WacomMTError WacomMTRegisterFingerReadCallback( int deviceID, WacomMTHitRect *hitRect, WacomMTProcessingMode mode, WMT_FINGER_CALLBACK fingerCallback, void *userData );
- この関数を使用すると、指タッチパケットの準備が整って要求されたデバイスのヒット矩形内にあるときに呼び出すコールバック関数を登録できます。プロセスは必要なだけのコールバックを作成できますが、デバイスヒット矩形ごとに作成できるコールバックは1つのみです。コールバックをキャンセルする場合は、この関数にNULLを指定して既存のデバイスヒット矩形に対して呼び出します。コールバックは、作成された順に処理されます。
- パラメーター:
- deviceID:
- デバイスのdeviceID。
- hitRect:
- データをヒットテストするために使用される矩形。指がヒット矩形内に接触し始めると、コールバックが呼び出されます。コールバックは、デバイスとの接触がなくなるまで、その指に対して呼び出され続けます。接触がヒット矩形の外側で始まる場合、コールバックはその指に対しては呼び出されません。NULLの矩形は、デバイスの表面全体を想定します。ヒット矩形は、デバイスの論理単位内で定義されます。論理単位の定義については、WacomMTCapability構造体を参照してください。
- mode:
- コールバック中にAPIがデータに対して行うことを指定します。
- fingerCallback:
- 関数定義は、次のとおりです。int ( *WMT_FINGER_CALLBACK )( WacomMTFingerCollection *fingerPacket, void *userData );
この関数は、fingerPacket構造体が入力された状態で、呼び出しの登録時に提供されたuserDataを使用して呼び出されます。fingerPacketは、コールバックが処理されている間のみ有効です。このメモリーは、コールバックから戻ると、解放/再使用されます。戻り値は予約済みでゼロでなければなりません。 - userData:
- 呼び出し側によって提供されるパラメータで、コールバック関数にエコーバックされます。
- 戻り値:
- WacomMTError列挙型定義を参照してください。
6.8 WacomMTRegisterBlobReadCallback
- WacomMTError WacomMTRegisterBlobReadCallback( int deviceID, WacomMTHitRect *hitRect, WacomMTProcessingMode mode, WMT_BLOB_CALLBACK blobCallback, void *userData );
- この関数を使用すると、BLOBデータの準備が整って要求されたデバイスのヒット矩形内にあるときに呼び出すコールバック関数を登録できます。プロセスは必要なだけのコールバックを作成できますが、デバイスヒット矩形ごとに作成できるコールバックは1つのみです。コールバックをキャンセルする場合は、この関数にNULLを指定して既存のデバイスヒット矩形に対して呼び出します。コールバックは、作成された順に処理されます。
- パラメーター:
- deviceID:
- デバイスのdeviceID。
- hitRect:
- データをヒットテストするために使用される矩形。BLOB接触の一部がヒット矩形内にある場合は、コールバックが呼び出されます。NULLの矩形は、デバイスの表面全体を想定します。ヒット矩形は、デバイスの論理単位内で定義されます。論理単位の定義については、WacomMTCapability構造体を参照してください。
- mode:
- コールバック中にAPIがデータに対して行うことを指定します。
- blobCallback:
- 関数定義は、次のとおりです。int ( *WMT_BLOB_CALLBACK )( WacomMTBlobAggregate *blobPacket, void *userData );
この関数は、 blobPacket構造体が入力された状態で、呼び出しの登録時に提供されたuserDataを使用して呼び出されます。blobPacketは、コールバックが処理されている間のみ有効です。このメモリーは、コールバックから戻ると、解放/再使用されます。戻り値は予約済みでゼロでなければなりません。 - userData:
- 呼び出し側によって提供されるパラメータで、コールバック関数にエコーバックされます。
- Return Value:
- WacomMTError列挙型定義を参照してください。
6.9 WacomMTRegisterRawReadCallback
- WacomMTError WacomMTRegisterRawReadCallback( int deviceID, WacomMTProcessingMode mode, WMT_RAW_CALLBACK rawCallback, void *userData );”
- この関数は、指定されたデバイスでRAWデータの準備が整ったときに呼び出すコールバック関数を登録できます。デバイスごとに登録できるコールバックは1つのみです。デバイスコールバックをキャンセルする場合は、コールバックにNULLを指定して、この関数を呼び出します。コールバックは、作成された順に処理されます。
- パラメーター:
- deviceID:
- デバイスのdeviceID。
- mode:
- コールバック中にAPIがデータに対して行うことを指定します。
- rawCallback:
- 関数定義は、次のとおりです。int ( *WMT_RAW_CALLBACK )( WacomMTRawData *rawPacket, void *userData );
この関数は、rawPacket構造体が入力された状態で、呼び出しの登録時に提供されたuserDataを使用して呼び出されます。rawPacketは、コールバックが処理されている間のみ有効です。このメモリーは、コールバックから戻ると、解放/再使用されます。戻り値は予約済みでゼロでなければなりません。 - userData:
- 呼び出し側によって提供されるパラメータで、コールバック関数にエコーバックされます。
- 戻り値:
- WacomMTError列挙型定義を参照してください。
6.10 WacomMTRegisterFingerReadHWND(Windows専用の呼出し)
- WacomMTError WacomMTRegisterFingerReadHWND( int deviceID, WacomMTProcessingMode mode, HWND hWnd, int bufferDepth );
- この関数を使用すると、フィンガーデータを受信するためのウィンドウハンドルを登録できます。指定されたデバイスのフィンガーデータのパケットの準備が整ったら、WM_FINGERDATAメッセージがウィンドウハンドルに送信されます。lParamパラメータは、フィンガーデータが入っているWacomMTFingerCollection構造体へのポインタになります。bufferDepthパラメータは、作成されるコールバックバッファーの数を決定します。バッファーはリング形式で使用されます。ウィンドウハンドルにつき、デバイスごとに使用できるフィンガーデータコールバックの数は1つのみです。ウィンドウハンドルは、ヒット矩形を作成するためにも使用されます。ヒット矩形は、この関数が呼び出されるときに計算されます。ウィンドウを移動するかサイズ変更すると、この関数をもう一度呼び出す必要があります。bufferDepthが変更されると、既存のすべてのバッファーが無効になります。デバイスコールバックをキャンセルするには、ゼロのbufferDepthを指定して、この関数を呼び出す必要があります
deviceID:
デバイスのdeviceID。
mode:
コールバック中にAPIがデータに対して行うことを指定します。
hWnd:
これは、WM_FINGERDATAメッセージを受信するウィンドウハンドルです。
bufferDepth:
これは、メッセージコールバックに割り振られるWacomMTFingerCollectionデータ構造体の数です。
WacomMTError列挙型定義を参照してください。
6.11 WacomMTRegisterBlobReadHWND(Windows専用の呼出し)
- 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のみ対応しています。
- パラメーター:
- deviceID:
- デバイスのdeviceID。
- mode:
- コールバック中にAPIがデータに対して行うことを指定します。
- hWnd:
- これは、WM_BLOBDATAメッセージを受信するウィンドウハンドルです。
- bufferDepth:
- これは、メッセージコールバックに割り振られるWacomMTBlobAggregateデータ構造体の数です。
- 戻り値:
- WacomMTError列挙型定義を参照してください。
6.12 WacomMTRegisterRawReadHWND(Windows専用の呼出し)
- WacomMTError WacomMTRegisterRawReadHWND( int deviceID, WacomMTProcessingMode mode, HWND hWnd, int bufferDepth );
- この関数を使用すると、RAWデータを受信するためのウィンドウハンドルを登録できます。指定されたデバイスのデータフレームの準備が整ったら、WM_RAWDATAメッセージがウィンドウハンドルに送信されます。lParamパラメータは、WacomMTRawData構造体へのポインタになります。bufferDepthパラメータは、作成されるコールバックバッファーの数を決定します。バッファーはリング形式で使用されます。ウィンドウハンドルにつき、デバイスごとに使用できるRAWデータコールバックの数は1つのみです。bufferDepthが変更されると、既存のすべてのバッファーが無効になります。デバイスコールバックをキャンセルするには、ゼロのbufferDepthを指定して、この関数を呼び出す必要があります。
この関数はCintiq 24HD touchのみ対応しています。
deviceID:
デバイスのdeviceID。
mode:
コールバック中にAPIがデータに対して行うことを指定します。
hWnd:
これは、WM_RAWDATAメッセージを受信するウィンドウハンドルです。
bufferDepth:
これは、メッセージコールバックに割り振られるRawDataデータ構造体の数です。
WacomMTError列挙型定義を参照してください。