> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GameInput 裝置

> GameInput 裝置

<a id="introductionSection" />

連接到系統的每個實體輸入裝置，都由 [IGameInputDevice](/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) 介面表示。與讀數一樣，裝置執行個體是參考計數的單一執行個體，這表示可以比較介面指標是否相等。一般應用程式的大部分輸入程式碼只會以這種方式使用裝置執行個體，在呼叫其他 API 時作為一種裝置識別碼 (例如在擷取讀數時作為篩選條件)。

[IGameInputDevice](/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) 介面方法通常只會在應用程式需要以某種方式直接與特定裝置互動時呼叫。最常見的原因是將觸覺回饋或力回饋命令傳送至裝置。不過，此介面也會公開裝置屬性，並提供低階裝置 I/O 的存取權，這可能是較進階的程式碼所需要的。

<a id="propertiesSection" />

## 裝置屬性

需要知道裝置特定詳細資料的應用程式，可以存取裝置的 [GameInputDeviceInfo](/zh-TW/reference/input/gameinput/structs/gameinputdeviceinfo) 結構。此結構包含有關裝置的大量資訊，但使用時有幾件事需要了解。

裝置資訊可能很大，有時達 10 KB 以上。基於效率考量，GameInput API 不會複製裝置資料，而是暫時授與應用程式直接存取 GameInput 內部所儲存資料的權限。此方法可避免緩衝區配置和大量記憶體傳輸，有利於高效能程式碼，因為應用程式通常只對資料的一小部分感興趣。這也讓 [GameInputDeviceInfo](/zh-TW/reference/input/gameinput/structs/gameinputdeviceinfo) 結構能夠包含巢狀指標，指向裝置資訊資料區塊內可找到各種支援資訊陣列的其他區域，而不會增加可變大小輸出和深層複製的複雜度。

<a id="deviceIdsSection" />

## 裝置識別碼

裝置資訊中提供的一項重要資訊，是裝置的*應用程式本機裝置識別碼*。這是一個特殊的 32 位元組值，可唯一識別裝置，即使在應用程式重新啟動或系統重新開機後也是如此。此識別碼在無線裝置中斷連線及重新連線後也保持穩定，有線 USB 裝置只要插回相同的 USB 連接埠也是如此。

應用程式本機裝置識別碼最常用於在應用程式存留期之外識別特定裝置。例如，具有輸入對應 UI 的遊戲可以使用裝置識別碼，確保每次應用程式啟動時，都將使用者的輸入設定套用至相同的裝置。對於支援跨多個裝置進行複雜對應的應用程式而言，這一點尤其重要，因為這些裝置在其他情況下可能看起來完全相同 (例如，飛行模擬器的一組同質儀表板裝置)。

<a id="enumerationSection" />

## 裝置列舉

雖然大多數應用程式應該永遠不需要，但 GameInput 確實支援明確列舉已連線的裝置。這可以透過 [IGameInput](/zh-TW/reference/input/gameinput/interfaces/igameinput/igameinput) 介面的 [RegisterDeviceCallback](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registerdevicecallback) 方法來執行。

```c++ theme={null}
HRESULT RegisterDeviceCallback(
    _In_opt_ IGameInputDevice * device,
    _In_ GameInputKind inputKind,
    _In_ GameInputDeviceStatus statusFilter,
    _In_ GameInputEnumerationKind enumerationKind,
    _In_opt_ void * context,
    _In_ GameInputDeviceCallback callbackFunc,
    _Out_opt_ _Result_zeroonfailure_ GameInputCallbackToken * callbackToken);
```

此方法會同時處理裝置列舉和裝置連線/中斷連線通知：首先為每個已連線的裝置觸發一系列初始回呼，然後在新裝置連線或中斷連線時觸發後續回呼。應用程式可以使用 [GameInputEnumerationKind](/zh-TW/reference/input/gameinput/enums/gameinputenumerationkind) 參數，控制函式是否要封鎖直到所有初始回呼都已分派，或是立即傳回並以非同步方式分派回呼。

有數個篩選條件可用來控制列舉中包含哪些種類的裝置，以及哪些裝置狀態變更會觸發回呼。如需詳細資訊，請參閱 [RegisterDeviceCallback](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registerdevicecallback)。如需回呼運作方式的一般資訊，請參閱 [GameInput 回呼](/zh-TW/build/core-features/common/input/advanced/input-callbacks)。

\<!-- <a id="aggregateDevicesSection" />

## 彙總裝置

當同時連接多個鍵盤時，大多數輸入 API 會以合併的方式將輸入呈現給應用程式，就好像所有輸入都來自單一虛擬\_系統鍵盤\_。(滑鼠也是如此。) 不過，GameInput 通常會個別公開每個裝置及其輸入。這開啟了許多可能性 (例如，能夠分辨在本機多人遊戲中是哪個使用者的 chatpad 產生輸入)，但也為不需要此功能的應用程式增加了許多複雜度。

為了解決此問題，GameInput 支援彙總裝置的概念。[IGameInput](/zh-TW/reference/input/gameinput/interfaces/igameinput/igameinput) 介面上的 [CreateAggregateDevice](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_createaggregatedevice) 方法，可讓應用程式建立虛擬 [IGameInputDevice](/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) 執行個體，以公開單一 [GameInputKind](/zh-TW/reference/input/gameinput/enums/gameinputkind) 之所有裝置的合併輸入。接著，此彙總裝置可作為其他 GameInput API 函式的篩選條件，以便與彙總裝置互動 (例如擷取讀數)。雖然這最常用於鍵盤和滑鼠輸入，但也可以搭配大多數其他類型的輸入使用。

<Note>
  在目前的版本中，[`CreateAggregateDevice`](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_createaggregatedevice) 尚未實作。 -->
</Note>

<a id="seeAlsoSection" />

## 參考 API 文件

* [GameInput (API 內容)](/zh-TW/reference/input/gameinput/gameinput_members)
  * 結構
    * [GameInputDeviceInfo](/zh-TW/reference/input/gameinput/structs/gameinputdeviceinfo)

## 另請參閱

[GameInput 基本概念](/zh-TW/build/core-features/common/input/overviews/input-fundamentals)

[進階 GameInput 主題](/zh-TW/build/core-features/common/input/advanced/input-advanced-topics)

[GameInput API 參考](/zh-TW/reference/input/gc-reference-input-toc)


## Related topics

- [移植到 XBOX GDK 的指南](/zh-TW/home/build-first-title/porting-guides.md)
- [GameInput](/reference/input/gameinput/gameinput_members.md)
- [Overview of GameInput](/build/core-features/common/input/overviews/input-overview.md)
- [GameInput fundamentals](/build/core-features/common/input/overviews/input-fundamentals.md)
- [GameInput 概述](/zh-CN/build/core-features/common/input/overviews/input-overview.md)