ハプティクス ペン実装ガイド
このドキュメントでは、互換性のある Windows 11 ホストに接続するハプティクス ペン デバイスのプロトコル実装について詳しく説明します。 これには、ペン変換器内でハプティクス応答を生成するための機械的な制約、電気的な制約、またはコンポーネントの選択に関するガイダンスは含まれません。 この実装ガイダンスは、ペン変換器とペン デジタイザーの間で使用されるペン プロトコルに依存しませんが、実装では、ハプティクス応答を調整する目的でペン デジタイザーがペン変換器に追加のパラメーターを提供できるアップリンク機能があるペン プロトコルを使用することもできます。
デバイス クラス
ハプティクス ペンは、Windows 上のペン デバイス クラスの拡張機能です。 この実装ガイドは「ペン実装ガイド」への追加であり、ペン変換器内にハプティクスを実装することに重点を置いているため、ハプティクス ペンは、ここに含まれているものに加えて「ペン実装ガイド」の要件を満たす必要があります。
デバイスのバス接続
ハプティクス ペンは、Microsoft が提供するインボックス ドライバーを使用して、HID over Bluetooth を使用して Windows ホストに接続します。
ハプティクス ペン プロトコルの実装
ここに記載されている情報を理解できるように、HID プロトコルを十分に理解しておく必要があります。 HID プロトコルの詳細については、次のリソースを参照してください。
Windows には、HID クラス ドライバーおよび対応する HID Bluetooth 対応ミニポート ドライバーが含まれているため、サードパーティ製のミニポート ドライバーは必要ありません。 ハプティクス ペン デバイスのファームウェアは、このトピックで説明されている用途のみを報告する必要があります。 Windows は、ファームウェアとその固有の HID ドライバーを使用してデバイスを有効にし、Windows アプリケーションにデバイスへのアクセスを許可します。
サンプルの記述子が、下にあるサンプルのレポート記述子のセクションに用意されています。
必要な最上位レベルの HID コレクション
ハプティクス ペン デバイスでは、デジタイザー/スタイラス (ページ 0x0D、用途 0x20) として表示される最上位レベルのコレクションをデバイスが提供するように、Windows 10 システムで HID プロトコルを使用する必要があります。
ペン デジタイザーの入力レポート
ペン デジタイザー コレクションでは、OS に報告された入力レポート内の、変換器のシリアル番号と変換器ベンダー ID で構成されるスタイラス識別子を報告する必要があります。 同じスタイラス識別子を、スタイラス コレクションを通じて報告する必要があります。 これにより、OS は、デジタイザーによって生成されたペン入力をスタイラスに関連付けることができます。 ペン実装ガイドの詳細については、「ペン プロトコルの実装」を参照してください。
変換器のシリアル番号
変換器のシリアル番号は、ペン デジタイザーと通信するペン アクセサリで使用される変換器の一意の永続的な識別子です。 これは 32 ビットにする必要があり、変換器ベンダー ID で識別されるベンダーまたはエンティティによって定義されます。 ペンアクセサリがこの値の送信をサポートしていないか、または送信が完全に受信されていないために、デジタイザーにトランスデューサシリアル番号が不明な状況では、デジタイザーはホストに0を報告しなければなりません。 Null 位置は、ホストではサポートされていません。
探触子シリアル番号 – パート 2
トランスデューサシリアル番号 – パート2では、ペンアクセサリで使用されるトランスデューサの一意の永続的識別子の一部として追加の32ビットを指定できます。 ペンアクセサリがこの値の送信をサポートしていないか、または送信が完全に受信されていないために、デジタイザーにトランスデューサシリアル番号 - パート2が不明な状況では、デジタイザーはホストに0を報告しなければなりません。 Null 位置は、ホストではサポートされていません。
| ページ | id | メモ |
|---|---|---|
| 0xD | 0x5B | 一意のペン ID に依存する機能の場合は必須 (下記を参照) |
| 0xD | 0x6E | 追加の 32 ビットによるシリアル番号の省略可能な拡張 |
変換器ベンダー ID
変換器ベンダー ID は、ペン デジタイザーと通信するペン アクセサリで使用される変換器の製造元を伝えるためのフィールドです。 これは、製造元またはこの目的で USB IF ベンダー ID の使用を承認している IHV/OEM に割り当てられた 2 バイトの USB-IF ベンダー ID である必要があります。
| ページ | id | メモ |
|---|---|---|
| 0xD | 0x91 | 一意のペン ID に依存する機能の場合は必須 (下記を参照) |
一意のペン ID に依存する機能
ペン ハプティクス (このガイドのハプティクス機能に必要) などのシナリオを有効にするには、PenID の報告が必須です。
これは、インク操作に複数のペンを使用するシナリオでも必須です。 次に例を示します。
- 各ペンを特定のインク ツールにマップできる複数のペン用途をサポートしている Windows 上のホワイトボード アプリ
- 一般に、デジタイザーにより画面上で一度に 1 つのペンのみがサポートされている場合でも、属性または動作をさまざまな物理ペンに割り当てる必要があるアプリ
- サポートされるデジタイザーで複数の同時ペンを追跡する必要があるアプリ
ハプティクス出力レポート
ペン デバイスでハプティクス フィードバックがサポートされている場合は、スタイラス TLC 内にハプティクス フィードバック コレクション (ページ 0x0E、用途 0x01) を含めると、システムとアプリケーションでこのフィードバックを利用できます。 HID 仕様がどのようにハプティクス フィードバックをサポートしているかの詳細については、「Haptics page」の HID 仕様への準拠を参照してください。
ホストは、出力レポート (ハプティクス フィードバック コレクション経由) で次の用途を使用して、ホストがハプティクス ペン デバイスに対してハプティクス フィードバック イベントを発行できるようにします。 デバイスでハプティクス フィードバック コレクションを公開する場合、ホスト側で開始したハプティクス フィードバックをサポートするには一部の用途が必須になります。
| メンバー | 説明 | ページ | id | 必須/省略可能 |
|---|---|---|---|---|
| 波形リスト | デバイスでサポートされるハプティクス波形の順序付きリスト | 0x0E | 0x10 | Mandatory |
| 時間長リスト | 波形リストの波形の時間長の順序付きリスト | 0x0E | 0x11 | Mandatory |
| 自動トリガー | デバイスが自由裁量で自動起動する波形 | 0x0E | 0x20 | Mandatory |
| 自動トリガー関連コントロール | ハプティクス フィードバックに関連付けられているコントロールの HID 用途 | 0x0E | 0x22 | Mandatory |
| 強度 | 出力 - 手動トリガー波形の強度の割合 | 0x0E | 0x23 | オプション |
| 繰り返し回数 | 出力 - 初期再生後に手動トリガー波形を再生する回数 | 0x0E | 0x24 | オプション |
| 再トリガー周期 | 出力 - 手動トリガーを繰り返すときに待機する時間長 | 0x0E | 0x25 | オプション |
| 波形カットオフ時間 | 手動トリガーの波形が打ち切られる前に再生する最大時間 | 0x0E | 0x28 | オプション |
波形リスト
波形リスト用途は、サポートされている波形の HID 用途のコレクションを表し、序数を使用して順序付けされています。 事前定義済みのハプティクス波形は、HID 仕様で定義されます。 ペン ハプティクス デバイスの場合、これらの波形は、さまざまなシナリオに対応する次の 2 つのセグメントに分類できます。
- WAVEFORM_*CONTINOUS - ユーザーがペン、鉛筆などのさまざまなツールでアクティブにインクを使用している間に、さまざまなテクスチャをシミュレートするためのインク ベースのフィードバック。
- WAVEFORM_* - ユーザーが何らかの入力駆動タスク (ボタンの上にマウス ポインターを置く、無効なボタンをクリックする、インクの形状認識に成功するなど) を実行するときの、個別の非継続的な相互作用ベースのフィードバック。
ペンハプティクス デバイスでサポートされている波形の詳細な一覧を次に示します。
| 波形 | 説明 | ページ | id | 必須/省略可能 |
|---|---|---|---|---|
| WAVEFORM_NONE | 何もしません。 進行中の波形の再生状態に影響を与えません | 0x0E | 0x1001 | Mandatory |
| WAVEFORM_STOP | 進行中の波形の再生を停止します | 0x0E | 0x1002 | Mandatory |
| WAVEFORM_CLICK | 短い "クリック" フィードバックを作成します。 アプリによって選ばれた対話フィードバック波形がハプティクス ペンでサポートされていないときの既定のフォールバック | 0x0E | 0x1003 | Mandatory |
| WAVEFORM_INKCONTINUOUS | 物理的なボールペンを使用したインクの感覚をシミュレートします。 ハプティクス ペンでインク波形がサポートされていない場合の既定のフォールバック | 0x0E | 0x100B | Mandatory |
| WAVEFORM_SUCCESS | アクションが成功したことをユーザーに通知する強いハプティクス信号 | 0x0E | 0x1009 | オプション |
| WAVEFORM_ERROR | アクションが失敗したか、エラーが発生したことをユーザーに通知する強いハプティクス信号 | 0x0E | 0x100A | オプション |
| WAVEFORM_HOVER | ユーザーがハプティクス ペンを使用して対話型 UI 要素の上にマウス ポインターを置いたときのハプティクス信号 | 0x0E | 0x1008 | オプション |
| WAVEFORM_PRESS | ユーザーがインクリメンタル アクションで対話型 UI 要素を押したこときのハプティクス信号 (WAVEFORM_RELEASE を参照) | 0x0E | 0x1006 | オプション |
| WAVEFORM_RELEASE | ユーザーがインクリメンタル アクションで対話型 UI 要素を解放したときのハプティクス信号 (WAVEFORM_PRESS を参照) | 0x0E | 0x1007 | 省略可能 |
| WAVEFORM_PENCILCONTINUOUS | ユーザーがインク ツールとして鉛筆を選択したときの連続的なハプティクス信号 | 0x0E | 0x100C | 省略可能 |
| WAVEFORM_MARKERCONTINUOUS | ユーザーがインク ツールとしてマーカーを選択したときの連続的なハプティクス信号 | 0x0E | 0x100D | 省略可能 |
| WAVEFORM_CHISELMARKERCONTINUOUS | ユーザーがインク ツールとしてチゼル マーカー/蛍光ペンを選択したときの連続的なハプティクス信号 | 0x0E | 0x100E | 省略可能 |
| WAVEFORM_BRUSHCONTINUOUS | ユーザーがインク ツールとしてブラシを選択したときの連続的なハプティクス信号 | 0x0E | 0x100F | 省略可能 |
| WAVEFORM_ERASERCONTINUOUS | ユーザーがインク ツールとして消しゴムを選択したときの連続的なハプティクス信号 | 0x0E | 0x1010 | 省略可能 |
| WAVEFORM_SPARKLECONTINUOUS | 多色のブラシなどの、特殊なインク ツールの連続的なハプティクス信号 | 0x0E | 0x1011 | 省略可能 |
Note
必須ではありませんが、より快適なユーザー エクスペリエンスを提供するために、他の列挙された波形も実装することをお勧めします。 特に、WAVEFORM_PRESS と WAVEFORM_RELEASE は、重要な対話フィードバックをもたらすため、強くお勧めします。
HID 準拠のすべてのハプティクス デバイスには、WAVEFORM_NONE と WAVEFORM_STOP の両方が必須です。 序数 1 と 2 は、暗黙的に WAVEFORM_NONE と WAVEFORM_STOP に設定されます。 これらは、波形リストや時間長リストで宣言する必要はありません。 波形リストでは、サポートされている波形がリスト内の各序数の物理的な最小値と最大値で宣言されます。
時間長リスト
時間長リスト用途は、波形リストでサポートされている波形の時間長のコレクションを表し、序数を使用して順序付けされています。 波形の時間長の単位はミリ秒で、時間長は連続しない任意の波形に対して 0 以外の正の値である必要があります。 波形が連続している (ホストによって停止されるか、波形打ち切り時間を超えるまで再生される) 場合、その時間長は 0 と定義されます。
WAVEFORM_NONE と WAVEFORM_STOP は、時間長が 0 であると見なされます。 これらは、時間長リストで宣言する必要はありません。
強度
強度用途は、波形に適用する最大強度の割合を表します。 この値の変動幅は、0 から 100% である必要があります。 100% はデバイスが最大強度で波形をトリガーすることを、0% はハプティクス変換器が有効になっていないことを示します。
繰り返し回数
繰り返し回数用途は、波形を繰り返す回数を表します。 繰り返し回数が 0 の場合、手動トリガーの波形の再生は 1 回のみ (繰り返しなし) にする必要があることを示します。 波形打ち切り時間を超えた場合、完了していない繰り返しは無視されると想定されています。
再トリガー周期
再トリガー周期用途は、繰り返し回数で指定された値ごとに、出力レポートで手動トリガーの波形を繰り返す前にデバイスが待機する時間を表します。 この値の単位はミリ秒です。 再トリガー周期が再生される波形の時間長よりも短い場合は、再トリガー周期で指定されている周期で波形を停止してから再開する必要があります。
波形打ち切り時間
波形打ち切り時間用途は、デバイスが再生を終了する前に手動トリガーの波形を繰り返し実行できる最大時間を表します。 これはデバイスの定数値であり、時間長が設定されていない連続波形と、何度も繰り返すように設定された任意の時間長を持つ波形の両方が含まれます。 この値の単位はミリ秒です。
ハプティクス出力レポート
ホストは、出力レポートで次の用途を使用して、ハプティクス ペン デバイスに対してハプティクス フィードバック イベントを発行します。 一部の用途は、Windows ホスト実装との互換性のために必須です。
| メンバー | 説明 | ページ | id | 必須/省略可能 |
|---|---|---|---|---|
| 手動トリガー | ホスト側からの明示的なコマンドとして起動する波形 | 0x0E | 0x21 | Mandatory |
| 強度 | 手動トリガー波形の強度の割合 | 0x0E | 0x23 | Mandatory |
| 繰り返し回数 | 初期再生後に手動トリガー波形を再生する回数 | 0x0E | 0x24 | オプション |
| 再トリガー周期 | 手動トリガーを繰り返すときに待機する時間長 | 0x0E | 0x25 | 省略可能 |
手動トリガー
手動トリガーの使用法は、ホストによって再生が要求されている波形リストのサポートされている波形の使用法です。 WAVEFORM_NONE 以外の手動トリガーを含む出力レポートがデバイスに送信されると、出力レポートに含まれるその他のプロパティ (強度、繰り返し回数、再トリガー周期) を使用して、指定された波形の再生がすぐに開始します。 出力レポートに WAVEFORM_STOP の手動トリガーが含まれているときは、進行中の波形の再生が停止します。
強度、繰り返し回数、および再トリガー周期用途については、出力機能レポートに関する前のセクションを参照してください。
ハプティクスの開始と停止
次のフローチャートでは、ペンのハプティクス信号を構成、クリア、開始、停止する必要があるタイミングについて説明します。
以下で説明するさまざまなハプティクス状態は、次のとおりです。
- 再生中: ペンは、ハプティクスの波形をアクティブに再生しています
- 一時停止: ペンは波形で構成されていますが、アクティブに再生されていません
- 停止: ペンは波形で構成されていなくて、何もアクティブに再生されていません
デジタイザーに関するペンの状態については、「Windows のペンの状態」を参照してください。
Note
ペンが範囲を外れた場合は、ハプティクス構成をクリアすることをお勧めしますが、必須ではありません。 これは、次の図で、ペンが範囲を外したときに "ペン: 範囲内、ハプティクス: 一時停止" 状態から出る 2 本の代替パスによって示されています。
Note
ホストは、連続しない波形の再生をいつでも要求する可能性があります。 その場合、ペンで再生してから、前の状態に戻ります。
Note
ホストは、連続する波形のみを構成します。 個別/不連続の波形のトリガーは、手動のみです。
キーボード コレクション (省略可能)
HID キーボード レポートを使用して、末端のボタン クリックのホストへの報告を有効にするオプション機能。
互換性のあるデバイスは、3 種のボタン アクションに対応する 3 種のキーボードの組み合わせを、ホストに公開されている HID Bluetooth キーボード デバイス経由で報告します。 アクションと対応するキーボードの組み合わせの概要を以下に示します。
| ボタン アクション | キーの組み合わせ |
|---|---|
| シングル クリック | WIN+F20 |
| ダブル クリック | WIN+F19 |
| 長押し | WIN+F18 |
Bluetooth ボタンの実装
末端の Bluetooth ボタンを実装するために、デバイスは 3 種のボタン アクションに対応する 3 種のキーボード組み合わせを、ホストに公開されている HID Bluetooth LE キーボード デバイス経由で報告します。 アクションと対応するキーボードの組み合わせの概要を以下に示します。
| Bluetooth ボタンのアクション | 報告するキーの組み合わせ |
|---|---|
| 1 回のクリックで | WIN+F20 |
| ダブルクリック | WIN+F19 |
| 長押し | WIN+F18 |
ペン収納
Windows 10 バージョン 1903 から、Windows は、互換性のあるペン収納を組み込むデバイスの通知をサポートしています。 このメカニズムは、ペンの取り外しまたは再収納を検出し、ショートカットの組み合わせペアに対応する HID キーボード レポートを生成するハードウェアに依存します。 ドック (ペンを保管場所に戻す) をシグナル送信するには、WIN+CTRL+F20 を報告し、ドック解除 (ペンを保管場所から取り外す) をシグナル送信するには、WIN+CTRL+F19 を報告します。 これは、ファームウェアまたはドライバーを使用して実装できます。
これらのドック解除/ドック イベントは、シェルの Ink ワークスペース メニューを表示/非表示にします。 Windows 10 以降、収納イベントの認識のために開発者がアプリケーションを拡張できるようにするプラットフォーム API を使用することで、バージョン 2004 の Office もこれらのイベントに対応します。 ペンがドックに存在するかどうかをクエリで確認するサポートはありません。アプリは、フォアグラウンドにある場合にのみ、取り外しと再設置のイベントを通知されます。
サンプルの 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 ()