4. Linux 遊戲手柄規範¶
- 作者:
2013 David Herrmann <dh.herrmann@gmail.com>
4.1. 介紹¶
Linux 提供了許多不同的遊戲手柄硬體輸入驅動程式。為了避免使用者空間處理每個遊戲手柄的不同按鈕對映，本文件定義了遊戲手柄應如何報告其資料。
4.2. 幾何形狀¶
我們將“遊戲手柄”定義為大致如下的裝置
____________________________ __
/ [__ZL__] [__ZR__] \ |
/ [__ TL __] [__ TR __] \ | Front Triggers
__/________________________________\__ __|
/ _ \ |
/ /\ __ (N) \ |
/ || __ |MO| __ _ _ \ | Main Pad
| <===DP===> |SE| |ST| (W) -|- (E) | |
\ || ___ ___ _ / |
/\ \/ / \ / \ (S) /\ __|
/ \________ | LS | ____ | RS | ________/ \ |
| / \ \___/ / \ \___/ / \ | | Control Sticks
| / \_____/ \_____/ \ | __|
| / \ |
\_____/ \_____/
|________|______| |______|___________|
D-Pad Left Right Action Pad
Stick Stick
|_____________|
Menu Pad
大多數遊戲手柄具有以下功能
操作板：4 個按鈕，呈菱形排列（在右側）。這些按鈕在大多數裝置上的標籤都不同，因此我們將它們定義為 NORTH、SOUTH、WEST 和 EAST。
方向鍵（D-Pad）：4 個按鈕（在左側），分別指向上、下、左和右。
菜單板：不同的組合，但大多數時候是 2 個按鈕：SELECT - START 此外，許多遊戲手柄都有一個花哨的品牌按鈕，用作特殊的系統按鈕。它通常與其他按鈕看起來不同，用於彈出系統選單或系統設定。
模擬搖桿：模擬搖桿提供可自由移動的搖桿來控制方向。並非所有裝置都具有兩個或任何一個，但它們在大多數時候都存在。如果按下模擬搖桿，它們也可能提供一個數字按鈕。
扳機鍵：扳機鍵位於手柄的上側，呈垂直方向。並非所有裝置都提供它們，但上面的按鈕通常被命名為左扳機鍵和右扳機鍵，下面的按鈕是 Z-Left 和 Z-Right。
震動：許多裝置提供力反饋功能。但大多數只是簡單的震動馬達。
4.3. 檢測¶
所有遵循此處描述的協議的遊戲手柄都對映 BTN_GAMEPAD。這是 BTN_SOUTH/BTN_A 的別名。它可以用於識別遊戲手柄。但是，並非所有遊戲手柄都提供所有功能，因此您需要首先測試您需要的所有功能。下面描述了每個功能的對映方式。
舊驅動程式通常不符合這些規則。由於我們無法出於向後相容性原因而更改它們，因此您需要在使用者空間中自行提供修復對映。其中一些可能還提供模組選項來更改對映，因此您可以建議使用者設定這些選項。
所有新的遊戲手柄都應該符合此對映。如果它們不符合，請報告任何錯誤。
有很多功能較少/功能較弱的裝置，它們重複使用此協議中的按鈕。但是，它們試圖以相容的方式執行此操作。例如，“Nintendo Wii Nunchuk”提供兩個扳機按鈕和一個模擬搖桿。它報告它們，就好像它是一個只有一個模擬搖桿和兩個扳機按鈕在右側的遊戲手柄。但這意味著，如果您只支援“真正的”遊戲手柄，則必須測試裝置是否具有您需要的所有報告事件。否則，您還將獲得報告事件小子集的裝置。
任何其他看起來/感覺不像遊戲手柄的裝置都不得報告這些事件。
4.4. 事件¶
遊戲手柄報告以下事件
操作板
每個遊戲手柄裝置至少有 2 個操作按鈕。這意味著每個裝置都會報告 BTN_SOUTH（BTN_GAMEPAD 是它的別名）。無論按鈕上的標籤如何，程式碼都會根據按鈕的物理位置傳送。
請注意，2 鍵和 3 鍵手柄非常罕見和古老。您可能想要過濾掉不報告所有四個按鈕的遊戲手柄。
2 鍵手柄
如果只有 2 個操作按鈕，則它們被報告為 BTN_SOUTH 和 BTN_EAST。對於垂直佈局，上面的按鈕是 BTN_EAST。對於水平佈局，右側的按鈕是 BTN_EAST。
3 鍵手柄
如果只有 3 個操作按鈕，則它們被報告為（從左到右）：BTN_WEST、BTN_SOUTH、BTN_EAST 如果這些按鈕完全垂直對齊，則它們被報告為（從上到下）：BTN_WEST、BTN_SOUTH、BTN_EAST
4 鍵手柄
如果所有 4 個操作按鈕都存在，則它們可以以兩種不同的形式對齊。如果是菱形，則根據它們的物理位置報告為 BTN_NORTH、BTN_WEST、BTN_SOUTH、BTN_EAST。如果是矩形，則左上角的按鈕是 BTN_NORTH，左下角是 BTN_WEST，右下角是 BTN_SOUTH，右上角是 BTN_EAST。
方向鍵
每個遊戲手柄都提供一個具有四個方向的方向鍵：上、下、左、右 其中一些可用作數字按鈕，另一些可用作模擬按鈕。有些甚至可能同時報告兩者。核心不會在兩者之間進行轉換，因此應用程式應同時支援兩者，並在報告兩者時選擇更合適的選項。
數字按鈕報告為
BTN_DPAD_*
模擬按鈕報告為
ABS_HAT0X 和 ABS_HAT0Y
（對於 ABS 值，負數為左/上，正數為右/下）
模擬搖桿
左模擬搖桿報告為 ABS_X、ABS_Y。右模擬搖桿報告為 ABS_RX、ABS_RY。可以存在零個、一個或兩個搖桿。如果模擬搖桿提供數字按鈕，則它們會相應地對映為 BTN_THUMBL（第一個/左側）和 BTN_THUMBR（第二個/右側）。
（對於 ABS 值，負數為左/上，正數為右/下）
扳機鍵
扳機鍵可以作為數字或模擬按鈕提供，或兩者兼有。使用者空間必須正確處理任何情況並選擇最合適的模式。
上扳機鍵報告為 BTN_TR 或 ABS_HAT1X（右）和 BTN_TL 或 ABS_HAT1Y（左）。下扳機鍵報告為 BTN_TR2 或 ABS_HAT2X（右/ZR）和 BTN_TL2 或 ABS_HAT2Y（左/ZL）。
如果只有一種扳機鍵組合（上+下），則它們被報告為“右”扳機鍵 (BTN_TR/ABS_HAT1X)。
（ABS 扳機鍵值從 0 開始，壓力報告為正值）
菜單板
選單按鈕始終是數字的，並且根據其位置而不是標籤進行對映。那就是
1 鍵手柄
對映為 BTN_START
2 鍵手柄
左側按鈕對映為 BTN_SELECT，右側按鈕對映為 BTN_START
許多手柄還有一個第三個按鈕，該按鈕帶有品牌或具有特殊符號和含義。此類按鈕對映為 BTN_MODE。例如，Nintendo “HOME” 按鈕、Xbox “X” 按鈕或 Sony PlayStation “PS” 按鈕。
震動
震動被宣傳為 FF_RUMBLE。
配置檔案
某些手柄提供多值配置檔案選擇開關。一個例子是 XBox Adaptive 和 XBox Elite 2 控制器。當切換活動配置檔案時，其新選擇的值將作為 ABS_PROFILE 事件發出。