> ## 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" />

大部分舊版 Microsoft 輸入 API 都是以裝置為中心，這表示應用程式程式碼必須先找到其支援的輸入裝置 (通常透過某種列舉模式)，才能讀取任何輸入。對於大多數輸入需求相對簡單的遊戲而言，這會增加許多額外的程式碼和複雜度。

另一方面，GameInput API 是以輸入為中心的 API。應用程式會先找到其感興趣的輸入，然後可選擇性地查詢產生該輸入的裝置。這會產生更自然的演算法，進而產生更簡單的程式碼。

<a id="inputStreamSection" />

## 輸入串流架構

GameInput 是以輸入串流的概念為基礎而建置：來自所有連線至系統之裝置的輸入，都會依照輸入發生的順序，導向單一連續的輸入事件串流。當多個裝置同時產生輸入時，就會自然地交錯輸入事件。以下是來自多個輸入裝置的輸入串流範例。

<img src="https://mintcdn.com/microsoft-4404708b/UZTRJSf0emX1fheE/images/gdk/features/common/input-stream-resized.png?fit=max&auto=format&n=UZTRJSf0emX1fheE&q=85&s=10804efb80fb93d2de12e3ce1053e15a" alt="來自多個輸入裝置的輸入串流範例" width="1203" height="294" data-path="images/gdk/features/common/input-stream-resized.png" />

在此範例中，四個裝置同時傳送輸入。每個方塊的數字代表輸入的傳送順序，色彩則代表傳送輸入的裝置。因此在此範例中，第一個遊戲台傳送第一個輸入，鍵盤傳送第二個輸入，滑鼠傳送第三個輸入，第二個遊戲台傳送第四個輸入。

輸入串流中的每個元素都以「讀數」表示。應用程式一開始會從輸入串流取得最新的讀數。之後，應用程式可以繼續定期取得最新的讀數，也可以在輸入串流中向前和向後移動，檢查相鄰的讀數。無論哪種情況，應用程式通常會比較感興趣的讀數之間的差異，然後採取適當的動作。

例如，第一人稱射擊遊戲可能只需要知道每個畫面開始時是否按下按鈕，以判斷玩家的武器是否應該開火。在此情況下，只有最新的讀數才重要 (任何中間讀數都可以忽略)。另一方面，競技格鬥遊戲可能會基於下列任何原因，想要檢查上一個畫面與目前畫面之間發生的每個輸入狀態變更。

* 連按兩下按鈕可能會對應到與單按不同的連段/招式。
* 兩個按鈕的按下順序可能很重要。
* 兩次按下按鈕之間經過的時間可能很重要。

從輸入串流擷取讀數時，應用程式可以套用選擇性篩選條件，將結果限制為來自特定輸入類型 (例如遊戲台或鍵盤) 及/或特定裝置的讀數。如需詳細資訊，請參閱 [GameInput 讀數](/zh-TW/build/core-features/common/input/overviews/input-readings)。

應用程式只能從輸入串流要求過去半秒內發生的歷程讀數。無論每個已連線裝置的最新讀數有多舊，一律都可存取。

<a id="interfacesSection" />

## 介面

GameInput API 是透過一組相關介面公開的，類似於圖形和音訊 API，如下圖所示。

<img src="https://mintcdn.com/microsoft-4404708b/UZTRJSf0emX1fheE/images/gdk/features/common/input-interfaces.png?fit=max&auto=format&n=UZTRJSf0emX1fheE&q=85&s=386a765ccea0fa73a66140cf6c04075f" alt="透過一組相關介面公開之 GameInput API 的圖表" width="1173" height="483" data-path="images/gdk/features/common/input-interfaces.png" />

構成 GameInput API 介面大部分內容的主要介面有三個。

* [`IGameInput`](/zh-TW/reference/input/gameinput/interfaces/igameinput/igameinput) 是透過呼叫 [`GameInputCreate`](/zh-TW/reference/input/gameinput/functions/gameinputcreate) Factory 函式取得的基礎介面。它包含從輸入串流擷取讀數、註冊回呼，以及存取其他全域功能的方法。

* [`IGameInputReading`](/zh-TW/reference/input/gameinput/interfaces/igameinputreading/igameinputreading) 代表輸入串流中的單一元素。它包含擷取讀數中所儲存之輸入狀態資料的方法，以及存取產生讀數之裝置的方法。在串流的其他讀數中向前和向後移動時，讀數也會作為輸入串流中的參考點。

* [`IGameInputDevice`](/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) 代表連線至系統的單一輸入裝置。它包含擷取裝置屬性和目前狀態的方法，以及控制裝置上觸覺回饋和力回饋的方法。它也包含執行低階原始裝置 I/O 的方法。

其餘介面用於特定內容，相關內容會在[進階 GameInput 主題](/zh-TW/build/core-features/common/input/advanced/input-advanced-topics)一節中討論。

<Note>
  與圖形和音訊 API 一樣，GameInput 不是真正的 COM API，即使它公開衍生自 IUnknown 的介面。這種 API 樣式有時稱為「COM lite」或「nano-COM」。雖然 IUnknown 用於參考計數和反映，但 GameInput 不會使用 COM 執行階段基礎結構。具體而言，這表示下列事項。

  * 應用程式不會呼叫 `CoInitialize` 或 `CoCreateInstance` 來取得物件執行個體。
  * 不支援彙總和呼叫端提供的介面實作等 COM 功能。
  * 沒有跨處理序封送處理支援，也沒有 Apartment/執行緒模型。所有物件都是 Agile 物件。
  * 可以直接比較介面指標以判斷物件身分識別，而不需透過 IUnknown。
  * 方法不需要傳回 `HRESULT` 代碼，這通常會產生更簡單的函式簽章。
</Note>

<a id="appFocusSection" />

## 應用程式焦點

在主機上，GameInput 只會在應用程式取得焦點時提供輸入給該應用程式。否則，傳回的狀態會包含中性或「靜止」值，就像使用者完全沒有碰觸裝置一樣。這樣就不需要額外的輸入程式碼來處理焦點變更。

在 PC 上，預設情況下，輸入 (包括系統按鈕) 會傳送至取得焦點的應用程式。您可以使用 [SetFocusPolicy](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_setfocuspolicy) 方法變更此行為。

當應用程式失去焦點時，傳送至裝置的任何觸覺回饋或力回饋都會停用。應用程式仍可呼叫 GameInput API 來設定新的回饋狀態，但新狀態不會傳送至裝置。當應用程式再次取得焦點時，應用程式最近要求的回饋狀態會自動傳送至裝置。

因此，應用程式在取得和失去焦點時，不需要執行任何與輸入或觸覺/力回饋相關的特殊動作。GameInput API 一律會代表應用程式正確處理。

<a id="seeAlsoSection" />

## 參考 API 文件

* [GameInput (API 內容)](/zh-TW/reference/input/gameinput/gameinput_members)
  * 函式
    * [gameinputcreate](/zh-TW/reference/input/gameinput/functions/gameinputcreate)

## 另請參閱

[GameInput 讀數](/zh-TW/build/core-features/common/input/overviews/input-readings)

[GameInput 裝置](/zh-TW/build/core-features/common/input/overviews/input-devices)

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

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


## Related topics

- [基于事件的玩家数据概述](/zh-CN/services/xbox-services/player-data/stats-leaderboards/event-based/live-how-data-platform-works.md)
- [イベントベースのプレイヤー データの概要](/ja-jp/services/xbox-services/player-data/stats-leaderboards/event-based/live-how-data-platform-works.md)
- [GameInput](/zh-CN/reference/input/gameinput/gameinput_members.md)
- [XR-013 將 Microsoft 帳戶與發行者帳戶連結](/zh-TW/publishing/certification/xr/xr-013.md)
- [XInputOnGameInput](/zh-CN/reference/input/xinputongameinput/xinputongameinput_members.md)