ハプティクス ペン実装ガイド

このドキュメントでは、互換性のある Windows 11 ホストに接続する触覚ペン デバイスのプロトコル実装について詳しく説明します。 これには、ペントランスデューサ内で触覚応答を生成するための機械的制約、電気的制約、またはコンポーネント選択に関するガイダンスは含まれません。 この実装ガイダンスは、ペン トランスデューサーとペン デジタイザーの間で使用されるペン プロトコルに依存しませんが、実装では、ペン デジタイザーが触覚応答を調整するためにペン トランスデューサに追加のパラメーターを提供できるようにするアップリンク機能を備えたペン プロトコルを使用することを選択できます。

デバイス クラス

触覚ペンは、Windows 上の Pen Device クラスの拡張機能です。 この実装ガイドは 、ペン実装ガイド に追加され、ペン の振動子内での触覚の実装に重点を置いているため、触覚ペンは、ここに含まれているものに加えて 、ペン実装ガイド の要件を満たす必要があります。

デバイスのバス接続

Haptic Pen は、Microsoft が提供する受信トレイ ドライバーを使用して、Bluetooth経由で HID を使用して Windows ホストに接続する必要があります。

触覚ペン プロトコルの実装

ここに示されている情報を理解するには、HID プロトコルを十分に理解する必要があります。 HID プロトコルの詳細については、次のリソースを参照してください。

• ヒューマン インターフェイス デバイス (HID) のデバイス クラス定義
• HID 使用法テーブル

Windows には HID クラス ドライバーと対応する HID Bluetooth対応ミニポート ドライバーが含まれているため、サード パーティ製のミニポート ドライバーは必要ありません。 触覚ペン デバイスファームウェアは、このトピックで説明されている使用状況のみを報告する必要があります。 Windows では、ファームウェアと独自の HID ドライバーを使用してデバイスを有効にし、Windows アプリケーションにデバイスへのアクセス権を付与します。

サンプル記述子については、以下の「サンプル レポート記述子」セクションを参照してください。

必須の最上位レベルの HID コレクション

触覚ペン デバイスでは、デバイスがデジタイザー/スタイラスとして表示される最上位レベルのコレクションを提供するように、Windows 10 システムで HID プロトコルを使用する必要があります (ページ 0x0D、使用状況 0x20)。

ペン デジタイザー入力レポート

ペン デジタイザー コレクションは、OS に報告される入力レポートで、探触子のシリアル番号とトランスデューサベンダー ID で構成されるスタイラス識別子を報告する必要があります。 スタイラス コレクションから同じスタイラス識別子を報告する必要があります。 これにより、OS はデジタイザーによって生成されたペン入力をスタイラスに関連付けることができます。 ペン実装ガイドの詳細については、 Pen Protocol の実装に関するページを参照してください。

探触子のシリアル番号

トランスデューサシリアル番号は、ペンデジタイザーと通信するペンアクセサリで使用されるトランスデューサの一意の永続的な識別子です。 これは 32 ビットである必要があり、トランスデューサーベンダー ID によって識別されるベンダーまたはエンティティによって定義されます。 ペンアクセサリがこの値の送信をサポートしていないか、または送信が完全に受信されていないために、デジタイザーにトランスデューサシリアル番号が不明な状況では、デジタイザーはホストに0を報告しなければなりません。 Null 位置は、ホストではサポートされていません。

探触子シリアル番号 – パート 2

トランスデューサシリアル番号 – パート2では、ペンアクセサリで使用されるトランスデューサの一意の永続的識別子の一部として追加の32ビットを指定できます。 ペンアクセサリがこの値の送信をサポートしていないか、または送信が完全に受信されていないために、デジタイザーにトランスデューサシリアル番号 - パート2が不明な状況では、デジタイザーはホストに0を報告しなければなりません。 Null 位置は、ホストではサポートされていません。

トランスデューサーベンダーID

トランスデューサーベンダーIDは、ペンデジタイザーと通信するペンアクセサリで使用されるトランスデューサの製造元と通信するためのフィールドです。 これは、2 バイトの USB-IF によって割り当てられたベンダー ID で、製造元または IHV/OEM のいずれかがこの目的のために USB-IF ベンダー ID の使用を許可したものである必要があります。

一意のペン識別に依存する機能

ペン触覚などのシナリオを有効にするには、PenID のレポートが必須です (このガイドの触覚機能に必要)。

また、手描き入力に複数のペンを使用するシナリオでも必須です。 例えば次が挙げられます。

• Windows 上のホワイトボード アプリでは、各ペンを特定の手描き入力ツールにマップできる複数のペン使用法がサポートされています
• 一般に、デジタイザーが画面上のペンを 1 つだけサポートしている場合でも、さまざまな物理ペンに属性や動作を割り当てるアプリ
• サポートされているデジタイザーで複数の同時ペンを追跡するアプリ

触覚出力レポート

ペン デバイスが触覚フィードバックをサポートしている場合、スタイラス TLC 内に触覚フィードバック コレクション (ページ 0x0E、使用状況0x01) を含めることで、システムとアプリケーションが触覚フィードバックを利用できるようにします。 HID 仕様が触覚フィードバックをサポートする方法の詳細については、HID 仕様の触覚ページが承認されたことを確認してください。

ホストは、(触覚フィードバック収集を通じて) 出力レポートで次の使用法を使用して、ホストが触覚ペン デバイスに触覚フィードバック イベントを発行できるようにします。 デバイスが触覚フィードバック コレクションを公開することを選択した場合は、ホストによって開始される触覚フィードバックをサポートできるようにするために、一部の使用法が必須です。

波形リスト

波形リストの使用法は、序数を使用して並べ替えられた、サポートされている波形の HID 使用法のコレクションを表します。 事前に定義された触覚波形は HID 仕様で定義されています。 ペン触覚デバイスの場合、これらの波形は、異なるシナリオに対応する 2 つのセグメントとして分類できます。

• WAVEFORM_*CONTINOUS - ユーザーがペン、鉛筆などのさまざまなツールを使用してアクティブに手描き入力を行っている間に、さまざまなテクスチャをシミュレートするためのインク ベースのフィードバック。
• WAVEFORM_* - ユーザーがボタンの上にマウス ポインターを合わせたり、無効なボタンをクリックしたり、インク形状の認識に成功したりなど、入力ドリブン タスクを実行した場合の、連続しない対話ベースの個別のフィードバックです。

ペン触覚デバイスでサポートされている波形の完全な一覧を次に示します。

すべての HID 準拠触覚デバイスには、WAVEFORM_NONEとWAVEFORM_STOPの両方が必要です。 序数 1 と 2 は暗黙的にWAVEFORM_NONEおよびWAVEFORM_STOPに設定されます。 波形リストまたは継続時間リストで宣言する必要はありません。 波形リストは、リスト内の各序数の物理最小値と最大値でサポートされている波形を宣言します。

期間リスト

期間リストの使用法は、序数を使用して並べ替えられた、波形リストでサポートされている波形の継続時間のコレクションを表します。 波形継続時間の単位はミリ秒で、継続時間は連続しない波形の場合はゼロ以外の正の値である必要があります。 波形が連続している場合 (ホストによって停止するか、波形カットオフ時間を超えるまで再生されます)、その継続時間はゼロとして定義されます。

WAVEFORM_NONEとWAVEFORM_STOPは、期間が 0 であると見なされます。 期間リストで宣言する必要はありません。

強度

強度の使用量は、波形に適用する最大強度の割合を表します。 この値は、0 ~ 100% の間で異なる必要があります。 100%は、デバイスが最大強度で波形をトリガーすることを示し、0%は触覚トランスデューサが有効でないことを示します。

繰り返し回数

繰り返しカウント使用量は、波形を繰り返す回数を表します。 繰り返し回数が 0 の場合は、手動トリガー波形を 1 回だけ再生する必要があることを示します (繰り返しなし)。 波形カットオフ時間を超えた場合、不完全な繰り返しは無視されることが予想されます。

リトリガー期間

リトリガー期間の使用は、繰り返しカウントで指定された値に従って、出力レポートで手動トリガー波形を繰り返す前にデバイスが待機する時間を表します。 この値の単位はミリ秒です。 リトリガー期間が再生中の波形の継続時間よりも短い場合は、波形を停止し、リトリガー期間で示された期間に再起動する必要があります。

波形カットオフ時間

波形カットオフ時間の使用は、デバイスが手動トリガ波形を再生を終了する前に繰り返し可能にする最大時間を表します。 これはデバイスの定数値であり、設定された継続時間のない連続波形と、何度も繰り返されるように設定された個別の継続時間を持つ波形の両方が含まれます。 この値の単位はミリ秒です。

触覚出力レポート

ホストは、出力レポートで次の使用法を使用して、触覚ペン デバイスに触覚フィードバック イベントを発行します。 一部の使用法は、Windows ホストの実装との互換性のために必須です。

手動トリガー

手動トリガーの使用法は、ホストによって再生されるように要求された波形リストからサポートされている波形の使用状況を表します。 WAVEFORM_NONE以外の手動トリガーを含む出力レポートがデバイスに送信されると、出力レポートに含まれる追加のプロパティ (強度、繰り返しカウント、リトリガー期間) を使用して、指定された波形の再生をすぐに開始する必要があります。 出力レポートにWAVEFORM_STOPの手動トリガーが含まれている場合は、進行中の波形再生を停止する必要があります。

強度、繰り返しカウント、およびリトリガー期間の使用状況については、出力機能レポートに関する前のセクションを参照してください。

ハプティクスの開始と停止

次のフローチャートでは、ペンの触覚信号を構成、クリア、開始、停止するタイミングについて説明します。

以下に示すさまざまな触覚状態は次のとおりです。

• 再生中: ペンが触覚波形をアクティブに再生しています
• 一時停止: ペンは波形が設定されていますが、再生中ではありません
• 停止:ペンは波形で構成されておらず、アクティブに何も再生していません

ディジットザーに関するペンの状態については、 Windows ペンの状態を参照してください。

キーボード コレクション (省略可能)

末端ボタンのクリックをホストに報告するためのオプションの機能をHIDキーボードレポートを使用して有効にする。

互換性のあるデバイスは、ホストに公開されている HID Bluetooth キーボード デバイスを介して 3 つの個別のボタン 操作に対応する 3 つの個別のキーボードの組み合わせを報告しなければなりません。 アクションと対応するキーボードの組み合わせの概要を次に示します。

Bluetooth ボタンの実装

テイルエンド Bluetooth ボタンを実装するために、デバイスは、ホストに公開されている HID Bluetooth LE キーボードデバイスを介して、3 つの異なるボタン操作に対応する 3 つの異なるキーボードの組み合わせを送信します。 アクションと対応するキーボードの組み合わせの概要を次に示します。

ペンの収納

Windows 10 バージョン 1903 以降、Windows では、互換性のあるペン収納を組み込んだデバイスの通知がサポートされています。 このメカニズムは、ペンが削除または交換されていることを検出し、ショートカットの組み合わせに対応する HID キーボード レポートを生成するハードウェアに依存します。 ドックを通知するには (ペンが収納に置き換えられました)、 WIN + Ctrl + F20 を報告し、ドッキング解除 (収納から取り外されたペン) を通知するには、 WIN + Ctrl + F19 を報告します。 これは、ファームウェアまたはドライバーを使用して実装できます。

これらのドッキング解除/ドッキング イベントは、シェル インク ワークスペース メニューを起動/閉じます。 Windows 10 バージョン 2004 以降、Office も、開発者が保存イベントに気づくためにアプリケーションを拡張できる プラットフォーム API を使用して、これらのイベントに対応します。 ペンがドックに存在するかどうかを照会するサポートはなく、アプリは削除の通知のみを受け取り、フォアグラウンドにある場合はイベントを返します。

HID レポート記述子のサンプル

05,0D,                      // Usage Page (Digitizers)
09,20,                      // Usage (Stylus)
A1,01,                      // Collection (Application)
85,40,                      //   Report ID (64)
95,01,                      //   Report Count (1)
75,20,                      //   Report Size (32)
17,00,00,00,80,             //   Logical Minimum (-2147483648)
27,FF,FF,FF,7F,             //   Logical Maximum (2147483647)
09,5B,                      //   Transducer Serial Number
81,02,                      //   Input (Data,Var,Abs)
75,10,                      //   Report Size (16)
15,01,                      //   Logical Minimum (1)
27,FF,FF,00,00,             //   Logical Maximum (65535)
09,91,                      //   Transducer Vendor ID
81,02,                      //   Input (Data,Var,Abs)
05,0E,                      //   Usage Page (Haptics)
09,01,                      //   Usage (0x01)
A1,02,                      //   Collection (Logical)
85,41,                      //     Report ID (65)
95,01,                      //     Report Count (1)
75,08,                      //     Report Size (8)
15,01,                      //     Logical Minimum (1)
26,FF,00,                   //     Logical Maximum (255)
09,24,                      //     Usage (0x24)
B1,02,                      //     Feature (Data,Var,Abs)
09,24,                      //     Usage (0x24)
91,02,                      //     Output (Data,Var,Abs)
09,23,                      //     Usage (0x23)
B1,02,                      //     Feature (Data,Var,Abs)
09,23,                      //     Usage (0x23)
91,02,                      //     Output (Data,Var,Abs)
15,01,                      //     Logical Minimum (1)
25,12,                      //     Logical Maximum (18)
09,20,                      //     Usage (0x20)
B1,02,                      //     Feature (Data,Var,Abs)
09,21,                      //     Usage (0x21)
91,02,                      //     Output (Data,Var,Abs)
15,00,                      //     Logical Minimum (0)
26,FE,00,                   //     Logical Maximum (254)
66,01,10,                   //     Unit (SI Linear)
55,FD,                      //     Unit Exponent (253)
35,00,                      //     Physical Minimum (0)
46,EC,09,                   //     Physical Maximum (2540)
09,28,                      //     Usage (0x28)
91,02,                      //     Output (Data,Var,Abs)
75,10,                      //     Report Size (16)
26,D0,07,                   //     Logical Maximum (2000)
46,D0,07,                   //     Physical Maximum (2000)
09,25,                      //     Usage (0x25)
91,02,                      //     Output (Data,Var,Abs)
09,25,                      //     Usage (0x25)
B1,02,                      //     Feature (Data,Var,Abs)
45,00,                      //     Physical Maximum (0)
85,42,                      //     Report ID (66)
75,20,                      //     Report Size (32)
17,42,00,0D,00,             //     Logical Minimum (852034)
27,42,00,0D,00,             //     Logical Maximum (852034)
09,22,                      //     Usage (0x22)
B1,02,                      //     Feature (Data,Var,Abs)
09,11,                      //     Usage (0x11)
A1,02,                      //     Collection (Logical)
05,0A,                      //       Usage Page (Ordinal)
75,10,                      //       Report Size (16)
95,10,                      //       Report Count (16)
15,01,                      //       Logical Minimum (1)
27,FF,FF,00,00,             //       Logical Maximum (65535)
19,03,                      //       Usage Minimum (0x03)
29,12,                      //       Usage Maximum (0x12)
B1,02,                      //       Feature (Data,Var,Abs)
C0,                         //     End Collection ()
05,0E,                      //     Usage Page (Haptics)
09,10,                      //     Usage (0x10)
A1,02,                      //     Collection (Logical)
05,0A,                      //       Usage Page (Ordinal)
16,03,10,                   //       Logical Minimum (4099)
26,FF,2F,                   //       Logical Maximum (12287)
19,03,                      //       Usage Minimum (0x03)
29,12,                      //       Usage Maximum (0x12)
B1,02,                      //       Feature (Data,Var,Abs)
C0,                         //     End Collection ()
C0,                         //   End Collection ()
C0                          // End Collection ()

関連トピック

• 入力デバイス触覚実装ガイド