GameInputDeviceInfo

描述輸入裝置的所有相關資訊。

語法

struct GameInputDeviceInfo
{
    uint16_t               vendorId;
    uint16_t               productId;
    uint16_t               revisionNumber;
    GameInputUsage         usage;
    GameInputVersion       hardwareVersion;
    GameInputVersion       firmwareVersion;
    APP_LOCAL_DEVICE_ID    deviceId;
    APP_LOCAL_DEVICE_ID    deviceRootId;
    GameInputDeviceFamily  deviceFamily;
    GameInputKind          supportedInput;
    GameInputRumbleMotors  supportedRumbleMotors;
    GameInputSystemButtons supportedSystemButtons;
    GUID                   containerId;
    const char*            displayName;
    const char*            pnpPath;

    const GameInputKeyboardInfo* keyboardInfo;
    const GameInputMouseInfo*    mouseInfo;
    const GameInputSensorsInfo*  sensorsInfo;

    const GameInputControllerInfo*  controllerInfo;
    const GameInputArcadeStickInfo* arcadeStickInfo;
    const GameInputFlightStickInfo* flightStickInfo;
    const GameInputGamepadInfo*     gamepadInfo;
    const GameInputRacingWheelInfo* racingWheelInfo;

    uint32_t                               forceFeedbackMotorCount;
    const GameInputForceFeedbackMotorInfo* forceFeedbackMotorInfo;

    uint32_t                            inputReportCount;
    const GameInputRawDeviceReportInfo* inputReportInfo;

    uint32_t                            outputReportCount;
    const GameInputRawDeviceReportInfo* outputReportInfo;
};

成員

vendorId
類型：uint16_t 識別輸入裝置的廠商。 productId
類型：uint16_t 識別輸入裝置的產品。 revisionNumber
類型：uint16_t 裝置的硬體修訂編號 (如果有的話)。 usage
類型：GameInputUsage 描述所使用輸入的兩部分索引。 hardwareVersion
類型：GameInputVersion 裝置的硬體版本 (如果有的話)。 firmwareVersion
類型：GameInputVersion 裝置的韌體版本 (如果有的話)。 deviceId
類型：APP_LOCAL_DEVICE_ID 輸入裝置的裝置識別碼。 deviceRootId
類型：APP_LOCAL_DEVICE_ID 輸入裝置的根識別碼。 deviceFamily
類型：GameInputDeviceFamily 指定輸入裝置所屬的輸入裝置系列。 supportedInput
類型：GameInputKind 描述裝置支援的一或多種輸入類型。 supportedRumbleMotors
類型：GameInputRumbleMotors 描述裝置上可存取的震動馬達 (如果有的話)。 supportedSystemButtons
類型：GameInputSystemButtons 描述用來控制系統的可用按鈕，通常在遊戲之外使用。 containerId
類型：GUID 輸入裝置的容器識別碼。 displayName
類型：const char* 描述裝置的易記名稱。 pnpPath
類型：const char* 描述裝置的隨插即用功能。使用此路徑可透過其他 API 參考基礎裝置。 keyboardInfo
類型：GameInputKeyboardInfo const * 鍵盤輸入裝置的相關資訊。 mouseInfo
類型：GameInputMouseInfo const * 滑鼠輸入裝置的相關資訊。 sensorsInfo
類型：GameInputSensorsInfo const * 裝置上感應器的相關資訊。 controllerInfo
類型：GameInputControllerInfo const * 一般控制器輸入裝置的相關資訊。控制器代表裝置上未經對應的原始軸、按鈕和開關。 arcadeStickInfo
類型：GameInputArcadeStickInfo const * 大型機台搖桿輸入裝置的相關資訊。 flightStickInfo
類型：GameInputFlightStickInfo const * 飛行搖桿輸入裝置的相關資訊。 gamepadInfo
類型：GameInputGamepadInfo const * 遊戲台輸入裝置的相關資訊。 racingWheelInfo
類型：GameInputRacingWheelInfo const * 賽車方向盤輸入裝置的相關資訊。 forceFeedbackMotorCount
類型：uint32_t 輸入裝置上的力回饋馬達數目。 forceFeedbackMotorInfo
類型：GameInputForceFeedbackMotorInfo const * 裝置上所有力回饋馬達的相關資訊。 inputReportCount
類型：uint32_t 裝置的輸入報告數目。 inputReportInfo
類型：GameInputRawDeviceReportInfo const * 輸入報告資訊物件。 outputReportCount
類型：uint32_t 裝置的輸出報告數目。 outputReportInfo
類型：GameInputRawDeviceReportInfo const * 輸出報告。

備註

此結構中的所有字串成員都使用 UTF-8 編碼。 deviceId 是應用程式本機識別碼：一個可唯一識別裝置的 256 位元雜湊值。只要裝置連接至相同的 USB 連接埠，即使在應用程式的多次執行或系統重新開機之間，指定裝置的此識別碼也始終保持不變。應用程式會產生應用程式本機識別碼雜湊，其中部分使用呼叫端應用程式和系統特有的資訊。 deviceRootId 是另一個應用程式本機識別碼，用來識別複合裝置的根裝置節點。這可讓應用程式推斷個別裝置之間的關係。例如，某些遊戲鍵盤會將自己公開為具有多個鍵盤節點的複合裝置，藉此因應舊版 USB 同時按鍵數最多八個的限制。這些節點會合併成「系統」鍵盤，因此通常對使用者而言是透明的。但在透過 GameInput API 處理個別鍵盤的輸入時，了解這一點可讓應用程式在將功能對應至按鍵時，避免做出不當的假設 (例如，按鍵一律來自特定裝置)。如果裝置不是複合裝置上眾多介面之一，則 deviceId 和 deviceRootId 會相同。 displayName 字串包含裝置的「易記」名稱。您可以在應用程式的 UI 中顯示此字串，但無法保證它已當地語系化。缺少當地語系化的原因在於 GameInput API 會在數個位置搜尋此字串，而最終的後援來源之一是裝置的韌體。 GameInputDeviceInfo 結構中的最後幾個欄位是指向裝置相關資訊之可變大小陣列的指標，例如力回饋和觸覺回饋支援的相關資訊。NULL 指標表示裝置不提供或不支援對應的功能。結構中對應的欄位會指示每個陣列中的元素數目，如原始程式碼註釋語言 (SAL) 註釋中所述。沒有任何輸入裝置會為所有屬性提供可讀取的值。某些裝置只包含相關屬性的值。系統會透過 IGameInputDevice::GetDeviceInfo 傳回此資訊。

概念文件

另請參閱

輸入 API 概觀
GameInput
IGameInputDevice::GetDeviceInfo

版本歷程記錄

版本	變更
v3	將 `uiNavigationInfo` 取代為 `controllerInfo` 指標。將個別的軸/按鈕/開關計數與資訊欄位取代為 `controllerInfo`。新增 `inputReportCount`/`inputReportInfo` 和 `outputReportCount`/`outputReportInfo`。移除 `hapticFeedbackMotorInfo`。
v2	已新增 `revisionNumber`、`hardwareVersion`、`firmwareVersion`、`containerId` (GUID) 和 `sensorsInfo` 指標。
v1	相較於 v0 的大幅簡化：移除 `infoSize`、`interfaceNumber`、`collectionNumber`、`capabilities` (GameInputDeviceCapabilities)、觸控/觸覺/字串/描述元計數欄位；新增 `supportedSystemButtons`、`const char*` 類型的 `displayName`、`pnpPath`。
v0	推出。

附錄：先前版本

v2

struct GameInputDeviceInfo
{
    uint16_t               vendorId;
    uint16_t               productId;
    uint16_t               revisionNumber;
    GameInputUsage         usage;
    GameInputVersion       hardwareVersion;
    GameInputVersion       firmwareVersion;
    APP_LOCAL_DEVICE_ID    deviceId;
    APP_LOCAL_DEVICE_ID    deviceRootId;
    GameInputDeviceFamily  deviceFamily;
    GameInputKind          supportedInput;
    GameInputRumbleMotors  supportedRumbleMotors;
    GameInputSystemButtons supportedSystemButtons;
    GUID                   containerId;
    const char*            displayName;
    const char*            pnpPath;

    const GameInputKeyboardInfo* keyboardInfo;
    const GameInputMouseInfo*    mouseInfo;
    const GameInputSensorsInfo*  sensorsInfo;

    const GameInputUiNavigationInfo* uiNavigationInfo;
    const GameInputArcadeStickInfo*  arcadeStickInfo;
    const GameInputFlightStickInfo*  flightStickInfo;
    const GameInputGamepadInfo*      gamepadInfo;
    const GameInputRacingWheelInfo*  racingWheelInfo;

    uint32_t                              controllerAxisCount;
    const GameInputControllerAxisInfo*    controllerAxisInfo;
    uint32_t                              controllerButtonCount;
    const GameInputControllerButtonInfo*  controllerButtonInfo;
    uint32_t                              controllerSwitchCount;
    const GameInputControllerSwitchInfo*  controllerSwitchInfo;

    uint32_t                               forceFeedbackMotorCount;
    const GameInputForceFeedbackMotorInfo* forceFeedbackMotorInfo;

    uint32_t                                hapticFeedbackMotorCount;
    const GameInputHapticFeedbackMotorInfo* hapticFeedbackMotorInfo;
};

v1

struct GameInputDeviceInfo
{
    uint16_t               vendorId;
    uint16_t               productId;
    GameInputUsage         usage;
    APP_LOCAL_DEVICE_ID    deviceId;
    APP_LOCAL_DEVICE_ID    deviceRootId;
    GameInputDeviceFamily  deviceFamily;
    GameInputKind          supportedInput;
    GameInputRumbleMotors  supportedRumbleMotors;
    GameInputSystemButtons supportedSystemButtons;
    const char*            displayName;
    const char*            pnpPath;

    const GameInputKeyboardInfo* keyboardInfo;
    const GameInputMouseInfo*    mouseInfo;

    const GameInputUiNavigationInfo* uiNavigationInfo;
    const GameInputArcadeStickInfo*  arcadeStickInfo;
    const GameInputFlightStickInfo*  flightStickInfo;
    const GameInputGamepadInfo*      gamepadInfo;
    const GameInputRacingWheelInfo*  racingWheelInfo;

    uint32_t                              controllerAxisCount;
    const GameInputControllerAxisInfo*    controllerAxisInfo;
    uint32_t                              controllerButtonCount;
    const GameInputControllerButtonInfo*  controllerButtonInfo;
    uint32_t                              controllerSwitchCount;
    const GameInputControllerSwitchInfo*  controllerSwitchInfo;

    uint32_t                               forceFeedbackMotorCount;
    const GameInputForceFeedbackMotorInfo* forceFeedbackMotorInfo;

    uint32_t                                hapticFeedbackMotorCount;
    const GameInputHapticFeedbackMotorInfo* hapticFeedbackMotorInfo;
};

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

GameInputDeviceInfo

GameInputDeviceInfo

語法

成員

備註

概念文件

另請參閱

版本歷程記錄

附錄：先前版本

v2

v1

​GameInputDeviceInfo

​語法

​成員

​備註

​概念文件

​另請參閱

​版本歷程記錄

​附錄：先前版本

​v2

​v1

GameInputDeviceInfo

語法

成員

備註

概念文件

另請參閱

版本歷程記錄

附錄：先前版本

v2

v1