觸覺畫筆實作指南
本文件詳細說明連線到相容 Windows 11 主機的觸覺手寫筆裝置通訊協議實作。 這不包括機械條件約束、電氣條件約束或元件選擇的指引，以在畫筆換能內產生觸覺回應。 此實作指引與手寫筆換能器與畫筆數位板之間所使用的畫筆通訊協定無關，不過實作可以選擇使用具有上行連結功能的畫筆通訊協定，讓畫筆數位板針對調調觸覺回應的目的，為畫筆換能提供額外的參數。
裝置類別
觸覺畫筆是 Windows 上畫筆裝置類別的延伸模組。 本實作指南會新增至手寫筆實作指南，並著重於在手寫筆換能內實作觸覺，因此觸覺畫筆除了此處所包含的筆實作指南之外，還必須符合畫筆實作指南中的需求。
裝置匯流排連線
觸覺筆應使用 Microsoft 提供的收件匣驅動程式，透過 藍牙 使用 HID 連線到 Windows 主機。
觸覺畫筆通訊協議實作
必須充分瞭解 HID 通訊協定，才能瞭解這裡提供的資訊。 如需 HID 通訊協定的相關信息，請參閱下列資源：
Windows 包含 HID 類別驅動程式和對應的 HID 藍牙 啟用迷你埠驅動程式，因此不需要任何第三方迷你埠驅動程式。 觸覺畫筆裝置韌體只需要報告本主題中所述的使用方式。 Windows 會使用韌體及其本身的 HID 驅動程式來啟用裝置，並提供 Windows 應用程式對裝置的存取權。
下列範例報表描述項一節提供範例描述元。
必要最上層 HID 集合
觸覺畫筆裝置應該在 Windows 10 系統上使用 HID 通訊協定，讓裝置提供最上層集合，以數位板/手寫筆的形式出現（Page 0x0D、Usage 0x20）。
畫筆數位板輸入報表
畫筆數位板集合必須報告手寫筆標識元，其中包含向OS報告的輸入報告中的換位序號和換位廠商標識碼。 相同的手寫筆標識碼必須透過手寫筆集合來報告。 這可讓OS將數位板所產生的手寫筆輸入與手寫筆相互關聯。 如需畫筆實作指南的詳細資訊，請參閱： 手寫筆通訊協議實作。
換位器序號
換位器序號是與畫筆數位板通訊之畫筆配件中所使用的換能器的唯一持續性標識符。 這必須是32位，並由廠商或廠商標識碼所識別的實體所定義。 如果數位板的換能序號未知，可能是因為畫筆配件不支援傳輸此值，或者尚未完全接收傳輸，數位板應向主機報告 0。 主機不支援 Null 位置。
換位器序號 – 第 2 部分
換能序號 – 第 2 部分允許指定額外的 32 位，作為筆配件中所用換能器的唯一持續性標識符的一部分。 如果數位板序號 – 數位板第 2 部分未知，因為畫筆配件不支援傳輸此值，或傳輸尚未完全接收，數位板應向主機報告 0。 主機不支援 Null 位置。
| 頁 | 識別碼 | 備註 |
|---|---|---|
| 0xD | 0x5B | 相依於唯一畫筆識別功能的必要專案（請參閱下方） |
| 0xD | 0x6E | 依額外32位選擇性擴充序號 |
換位廠商標識碼
「換位器廠商標識碼」是一個字段，用來與畫筆數位板通訊之畫筆配件中使用的換能器製造商。 這必須是製造商的 2 位元組 USB-IF 指派廠商識別碼，或是 IHV/OEM 授權基於此目的使用其 USB-IF 廠商標識碼的 IHV/OEM 識別符。
| 頁 | 識別碼 | 備註 |
|---|---|---|
| 0xD | 0x91 | 相依於唯一畫筆識別功能的必要專案（請參閱下方） |
與唯一畫筆識別相依的功能
報告 PenID 是必要條件，才能啟用畫筆觸覺等案例（本指南中觸覺功能的必要專案）。
對於使用多個手寫筆進行筆跡的案例，這也是必要專案。 例如：
- Windows 上的白板應用程式支援多個畫筆使用方式，其中每個畫筆都可以對應至特定筆跡工具
- 一般而言，想要將屬性或行為指派給不同實體畫筆的應用程式，即使數位板當時可能只支持螢幕上的單一畫筆
- 想要追蹤支援數位板上多個同時手寫筆的應用程式
觸覺輸出報告
如果畫筆裝置支援觸覺回饋，它可以允許系統和應用程式利用它，方法是在手寫筆 TLC 中包含觸覺回饋集合（Page 0x0E，Usage 0x01）。 如需 HID 規格如何支援觸覺回饋的詳細資訊，請參閱 觸覺頁面 批准 HID 規格。
主機會在輸出報告中使用下列用法（透過觸覺意見反應集合），讓主機向觸覺畫筆裝置發出觸覺回饋事件。 如果裝置選擇公開觸覺意見反應集合，則必須使用某些方式，才能支援主機起始的觸覺回饋。
| member | 描述 | 頁 | 識別碼 | 強制/選擇性 |
|---|---|---|---|---|
| 波波清單 | 裝置支援的觸覺超聲波排序列表 | 0x0E | 0x10 | 必要 |
| 工期清單 | 在[電壓清單] 中為超聲波的已排序持續時間清單 | 0x0E | 0x11 | 必要 |
| 自動觸發程式 | 在裝置的任意時間自動引發的電壓 | 0x0E | 0x20 | 必要 |
| 自動觸發相關聯的控件 | 與觸覺意見反應相關聯的控件 HID 使用方式 | 0x0E | 0x22 | 必要 |
| 強度 | 輸出 - 手動觸發波的強度百分比 | 0x0E | 0x23 | 選擇性 |
| 重複計數 | 輸出 - 在初始播放之後播放手動觸發電壓的次數 | 0x0E | 0x24 | 選擇性 |
| Retrigger 期間 | 輸出 -重複時重新觸發手動觸發程式之前等待的時間持續時間 | 0x0E | 0x25 | 選擇性 |
| 波波截止時間 | 手動觸發波波在被切斷之前可以播放的時間上限 | 0x0E | 0x28 | 選擇性 |
波波清單
電壓清單使用方式代表支援之超聲波的 HID 使用量集合，使用序數排序。 預先定義的觸覺電壓定義於 HID 規格中。 對於手寫筆觸覺裝置，這些超聲波可以分類為對應至不同案例的兩個區段：
- WAVEFORM_*CONTINOUS - 在用戶主動使用手寫筆、鉛筆等不同工具時，模擬各種紋理的筆跡型意見反應。
- WAVEFORM_* - 當使用者執行某些輸入驅動工作時，例如將滑鼠停留在按鈕上、按兩下停用的按鈕，以及成功的筆跡圖形辨識時，會針對離散的非連續互動型意見反應。
手寫筆觸覺裝置支援的完整超聲波清單如下：
| 波形 | 描述 | 頁 | 識別碼 | 強制/選擇性 |
|---|---|---|---|---|
| WAVEFORM_NONE | No-op。 不應該影響持續電壓的播放狀態 | 0x0E | 0x1001 | 必要 |
| WAVEFORM_STOP | 停止持續之超聲波的播放 | 0x0E | 0x1002 | 必要 |
| WAVEFORM_CLICK | 建立簡短的「按兩下」意見反應。 觸覺手寫筆不支持互動回饋超聲波時的預設後援 | 0x0E | 0x1003 | 必要 |
| WAVEFORM_INKCONTINUOUS | 模擬使用實體球點筆跡的感覺。 觸覺筆不支援手寫筆時的預設值後援 | 0x0E | 0x100B | 必要 |
| WAVEFORM_SUCCESS | 強觸覺訊號，以警示用戶動作已成功 | 0x0E | 0x1009 | 選擇性 |
| WAVEFORM_ERROR | 警示使用者動作失敗或發生錯誤的強觸覺訊號 | 0x0E | 0x100A | 選擇性 |
| WAVEFORM_HOVER | 當使用者將滑鼠停留在具有觸覺筆的互動式 UI 元素上時，觸覺訊號 | 0x0E | 0x1008 | 選擇性 |
| WAVEFORM_PRESS | 當使用者在累加動作中按下互動式 UI 元素時的觸覺訊號（請參閱釋放） | 0x0E | 0x1006 | 選擇性 |
| WAVEFORM_RELEASE | 當使用者在累加動作中釋放互動式 UI 元素時的觸覺訊號 （請參閱 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 | 選擇性 |
注意
雖然並非必要，但建議您也實作其他列舉的超聲波，以提供更完整的用戶體驗。 特別是，強烈建議WAVEFORM_PRESS和WAVEFORM_RELEASE，因為它們提供寶貴的互動意見反應。
所有符合 HID 規範的觸覺裝置都需要WAVEFORM_NONE和WAVEFORM_STOP。 序數 1 和 2 會隱含地設定為 WAVEFORM_NONE 和 WAVEFORM_STOP。 它們不需要在[電壓清單] 或 [持續時間清單] 中宣告。 [電壓清單] 會依清單中每個序數的實體最小值和最大值，宣告支援的超聲波。
工期清單
持續時間清單使用方式代表使用序數排序的[電壓] 清單中所支援之電壓持續時間的集合。 電壓持續時間的單位為毫秒，而且持續時間必須是任何非連續電壓的正非零值。 如果電壓是連續的（將播放直到主機停止或超過電壓截止時間），則其持續時間定義為零。
假設WAVEFORM_NONE和WAVEFORM_STOP持續時間為零。 它們不需要在 [持續時間清單] 中宣告。
強度
強度使用量代表要套用至超聲波的最大強度百分比。 此值應介於 0 和 100% 之間。 100% 表示裝置會以最大強度觸發超聲波，0% 表示觸覺換能器未啟用。
重複計數
重複計數使用量代表重複超聲波的次數。 重複計數為零，表示手動觸發程式電壓應該只播放一次（不重複）。 如果超過電壓截斷時間，則預期會忽略任何不完整的重複。
Retrigger 期間
Retrigger 期間使用量代表裝置在輸出報表中重複手動觸發波紋之前所等待的時間量，根據重複計數所指定的值。 此值的單位為毫秒。 如果 Retrigger 期間小於所播放之電壓的持續時間，則應該在重試器期間所指示的時間週期停止並重新啟動電壓。
波波截止時間
[電壓截止時間] 使用量代表裝置允許手動觸發波波在結束播放之前重複的時間上限。 這是裝置的常數值，包含連續的電壓，不含設定的持續時間，以及將離散持續時間設定為重複多次的電壓。 此值的單位為毫秒。
觸覺輸出報告
主機會在輸出報告中使用下列使用方式，向觸覺畫筆裝置發出觸覺回饋事件。 某些用法是「強制」與 Windows 主機實作的相容性。
| member | 描述 | 頁 | 識別碼 | 強制/選擇性 |
|---|---|---|---|---|
| 手動觸發程式 | 從主機以明確命令引發的波波 | 0x0E | 0x21 | 必要 |
| 強度 | 手動觸發電壓的強度以百分比表示 | 0x0E | 0x23 | 必要 |
| 重複計數 | 在初始播放之後播放手動觸發電壓的次數 | 0x0E | 0x24 | 選擇性 |
| Retrigger 期間 | 重複時重試手動觸發程式之前等候的時間持續時間 | 0x0E | 0x25 | 選擇性 |
手動觸發程式
手動觸發程式使用方式代表由主機要求播放的電壓清單支援的電壓使用量。 當輸出報表包含非WAVEFORM_NONE的手動觸發程式傳送到裝置時，它應該立即開始播放指定的波浪線與輸出報表中包含的其他屬性（強度、重複計數、重試週期）。 當輸出報表包含手動觸發程式WAVEFORM_STOP時，應該停止任何進行中的超聲波播放。
如需 強度、 重複計數和 重試週期 使用量，請參閱上一節的輸出功能報告。
啟動和停止觸覺
以下流程圖說明何時應該設定、清除、啟動和停止手寫筆的觸覺訊號。
以下所述的各種觸覺狀態如下：
- 播放：筆正在積極播放觸覺超聲波
- 已暫停：手寫筆已設定為超聲波，但未主動播放
- 已停止：手寫筆未設定為超聲波，且未主動播放任何專案
如需數位器方面的畫筆狀態，請參閱 Windows 手寫筆狀態。
注意
當畫筆超出範圍時，建議您清除觸覺設定，但並非必要。 下圖中的兩個替代路徑會從 “Pen： In range：觸覺：當畫筆超出範圍時，暫停了“狀態。
注意
主機隨時可能會要求播放非連續的電壓。 在該事件中，畫筆應該播放它，然後回到先前的狀態。
注意
主機只能設定連續的超聲波。 離散/非連續的電壓只能手動觸發。
鍵盤集合（選擇性）
選擇性功能，可讓您透過 HID 鍵盤報告來向主機報告尾端按鈕。
相容的裝置應該透過向主機公開的 HID 藍牙 鍵盤裝置，報告 3 個不同的鍵盤組合，對應至 3 個不同的按鈕動作。 動作與對應的鍵盤組合如下所述：
| 按鈕動作 | 按鍵組合 |
|---|---|
| 單鍵 | WIN+F20 |
| 按兩下 | WIN+F19 |
| 按住 | Win+F18 |
藍牙 按鈕實作
為了實作尾端 藍牙 按鈕，裝置會透過向主機公開的 HID 藍牙 LE 鍵盤裝置，報告對應至 3 個不同按鈕動作的 3 個不同的鍵盤組合。 動作與對應的鍵盤組合如下所述：
| 藍牙 按鈕動作 | 報表的按鍵組合 |
|---|---|
| 單鍵 | WIN+F20 |
| 按兩下 | WIN+F19 |
| 按住 | WIN+F18 |
畫筆 Stowage
從 Windows 10 版本 1903 開始，Windows 支援包含相容手寫筆存放裝置的通知。 此機制依賴硬體偵測要移除或取代的手寫筆，並針對一組快捷方式組合產生對應的 HID 鍵盤報告。 若要發出停駐訊號（手寫筆取代在 stowage 中），請報告 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 ()