跳轉到主要內容
每個 GameInput API 版本 (v0 到 v4) 都定義了自己的一組 COM 介面。GameInput 執行階段會在相同的基礎物件上實作每個版本,因此單一物件 (例如裝置) 具有 v0 介面、v4 介面,以及介於兩者之間每個版本的介面。若要將物件從一個版本切換到另一個版本,請在該物件上呼叫 QueryInterface。 這可讓您:
  • 將 v4 功能新增至以較早 API 版本 (例如 v0) 建置的應用程式,而不需一次移轉整個應用程式。
  • 呼叫以較早版本 GameInput 建置的 SDK、中介軟體或引擎外掛程式,即使應用程式的其餘部分使用 v4 也沒問題。

支援的 API 版本

GameInput 執行階段支援低於或等於其本身主要版本的每個 API 版本。例如,安裝 GameInput 4.0 執行階段時,每個 GameInput 物件都會實作 v0、v1、v2、v3 和 v4 介面,而您的應用程式可以使用它們的任意組合。 如果您要求比已安裝執行階段更新的 API 版本,QueryInterface 和 GameInputInitialize 會失敗並傳回 E_NOINTERFACE。您的應用程式所使用的最高 API 版本,決定了它所需的最低執行階段版本。 在 PC 上,已安裝的執行階段是 GameInput 可轉散發套件,或您隨遊戲部署的執行階段。如需詳細資訊,請參閱 GameInput NuGet 套件和 GameInput 側載。在 XBOX 上,執行階段隨附於 GDK,而您也可以隨遊戲部署較新的執行階段。如需詳細資訊,請參閱 XBOX 主機上的 GameInput。

設定您的專案

對於新的實作,請使用最新 Microsoft.GameInput NuGet 套件中的標頭和 GameInput.lib。在套件中,<GameInput.h> 是最新的標頭,而每個較早的標頭則位於具版本編號的資料夾中,例如 <v0/GameInput.h> 或 <v2/GameInput.h>。程式庫會匯出 GameInputInitialize,它會為您要求的任何 API 版本建立 GameInput。 較早版本的程式庫 (例如 GDK 中的程式庫) 也可以繼續運作。如需詳細資訊,請參閱保留較早的程式庫。

包含 v0 標頭

從 v1 開始,每個 GameInput 標頭都會在具版本編號的命名空間 (例如 GameInput::v4) 中宣告其類型。v0 標頭則是在全域命名空間中宣告其類型。若要將 v0 標頭與最新的標頭一起使用,請將下列樣板程式碼放入您自己的標頭 (例如 GameInputV0.h) 中:
此標頭的運作方式如下:
  • 它會先包含最新的 <GameInput.h>。這會在最新 API 自己的命名空間中宣告該 API,並包含 v0 標頭所依賴的 Windows 和 COM 標頭,因此 v0 標頭不會在命名空間內再次包含它們。
  • 前向宣告會讓 v0 標頭中的 typedef 在 GameInput::v0 中宣告新的介面,而不是參考最新標頭已宣告的介面。
  • 在命名空間內包含 <v0/GameInput.h>,會將每個 v0 類型、列舉和常數移至 GameInput::v0 中,例如 GameInput::v0::IGameInput 和 GameInput::v0::GameInputKindGamepad。
在您的 v0 原始程式檔中,請包含 GameInputV0.h 而不是 <GameInput.h>,並新增 using namespace GameInput::v0;,讓現有的程式碼可以繼續使用不限定的名稱。任何包含 GameInputV0.h 的原始程式檔,也都可以透過完整名稱 (例如 GameInput::v4::IGameInput) 使用最新的 API。

範例:將 v4 功能新增至 v0 應用程式

您不需要重寫 v0 程式碼即可開始使用 v4 功能。請將 v0 程式碼保留在其自己的原始程式檔中,並將新的 v4 程式碼放在個別的原始程式檔中。在兩者之間以 IUnknown* 傳遞 GameInput 物件,並讓每一方針對其所需的版本呼叫 QueryInterface。

現有的 v0 程式碼

下列 v0 程式碼會建立 GameInput 並讀取遊戲台。與原始的 v0 程式碼相比,只有三處變更:
  • 它包含 GameInputV0.h 而不是 <GameInput.h>。
  • 它透過以 v0 IID 呼叫 GameInputInitialize 來建立 GameInput,因為最新的程式庫不會匯出 v0 GameInputCreate 函式。
  • 按下 A 按鈕時,它會呼叫新的 v4 程式碼。

新的 v4 程式碼

新的原始程式檔會包含 v4 標頭,並在 v0 程式碼傳入的裝置上呼叫 QueryInterface。接著,它會使用 v4 新增的 IGameInputDevice::SetLightingColor 和 IGameInputDevice::ApplyLightingColors 變更控制器中央燈的色彩。如果裝置沒有中央燈,則會忽略此呼叫。
如果 QueryInterface 失敗,表示已安裝的執行階段不支援 v4。您的 v0 程式碼會繼續運作,而您的應用程式可以略過 v4 功能。 當您所有的程式碼都使用 v4 時,就可以移除 GameInputV0.h 和 QueryInterface 呼叫。

保留較早的程式庫

如果您繼續連結較早版本的程式庫 (例如 GDK 中的程式庫),則現有的 v0 程式碼完全不需要變更。請繼續包含該版本的 v0 標頭並呼叫 GameInputCreate。該呼叫會轉送至已安裝的執行階段,因此當執行階段為 4.0 或更新版本時,它傳回的物件也會實作 v4 介面,而先前所示的新 v4 程式碼無需變更即可運作。 較早的程式庫不會匯出 GameInputInitialize。請只透過呼叫 QueryInterface 來取得 v4 介面,且不要呼叫會呼叫 GameInputInitialize 的 v4 GameInputCreate。

在版本之間切換的規則

不同 API 版本的介面具有相同的名稱 (例如 IGameInput 和 IGameInputDevice),但它們是具有不同方法的不同類型。即使 v0 介面的指標和 v4 介面的指標參考的是相同的物件,v0 介面的指標也不是 v4 介面的指標。
轉換 (cast) 與呼叫 QueryInterface 不同。請一律使用 QueryInterface 來取得不同 API 版本的介面。絕對不要使用 static_cast、reinterpret_cast 或 C 樣式轉換在版本之間進行轉換。轉換雖然可以編譯,但透過轉換後的指標呼叫方法可能會呼叫錯誤的方法,進而導致未定義的行為。
也請記住下列規則:
  • 不要在 v0 標頭之後包含其他 GameInput 標頭。 v0 標頭會將其錯誤碼 (例如 GAMEINPUT_E_DEVICE_DISCONNECTED) 定義為巨集,而這些巨集會破壞在其後包含之任何 GameInput 標頭中的宣告。GameInputV0.h 會先包含最新的標頭,以遵循此規則。
  • 傳回的物件會使用您所呼叫的版本。 例如,在 v4 讀數上呼叫 GetDevice 會傳回 v4 裝置,而向 v4 IGameInput 註冊的裝置回呼會收到 v4 裝置。將這些物件傳遞給使用其他版本的程式碼之前,請先呼叫 QueryInterface。
  • 每次呼叫 QueryInterface 都會新增一個參考。 不再需要傳回的指標時,請將其釋放,就像處理任何其他 COM 介面指標一樣。
  • 檢查結果。 當您要求較新的 API 版本時,失敗表示已安裝的執行階段不支援該版本。
  • GameInputV0.h 中的 v0 類型是個別的 C++ 類型。 GameInput::v0::IGameInput 和僅來自 <v0/GameInput.h> 的全域 IGameInput 描述的是相同的介面,但 C++ 會將它們視為不同的類型。如果現有的程式碼或其他程式庫使用全域 v0 類型宣告函式,請從只包含 <v0/GameInput.h> 的原始程式檔呼叫這些函式。

呼叫使用較早 API 版本的 SDK

某些 SDK、中介軟體和引擎外掛程式是針對特定 GameInput API 版本建置的,並預期取得該版本的 GameInput 介面。您的應用程式可以使用較新的版本,並且仍然呼叫這些元件。請呼叫 QueryInterface 以取得元件所預期的版本,然後傳遞該指標。 請將此呼叫放在包含與元件所使用相同 GameInput 標頭的原始程式檔中。在下列範例中,ThirdPartySdk.h 宣告了 ThirdPartySdkInitialize(GameInput::v2::IGameInput*),而應用程式的其餘部分會以 IUnknown* 傳遞其 GameInput 物件:
相同的方法也適用於相反的方向。如果元件提供您的應用程式較早版本的 GameInput 物件,請在其上呼叫 QueryInterface 以取得 v4 介面。 由於每個版本都由同一個物件實作,因此 SDK 和您的應用程式會共用裝置、讀數和狀態。SDK 的 API 版本也必須低於或等於已安裝的執行階段版本。

另請參閱

GameInput API 版本控制
GameInput NuGet 套件
GameInput 側載
GameInputInitialize
GameInput API 參考
最後修改於 2026年11月6日