GameInput API のバージョン管理

注意

Xbox 用に開発している場合、バージョン v.0 は 2510 GDK 以降の GDK で使用可能な既定のバージョンです。 v1.0 以降の API を利用するタイトルは、Microsoft.GameInput NuGet パッケージと統合することで、PC (v1.0 以降) およびコンソール (v2.2 以降) の両方で対応できます。 この NuGet パッケージをコンソールで使用するには、GDK 2510 以降が必要です。 PC アプリは、NuGet パッケージに含まれている最新の GameInput 再頒布可能パッケージをターゲット コンピューターにインストールする必要があります。 コンソール アプリは、NuGet パッケージ内の最新の GameInput ヘッダーおよびライブラリに対してコンパイルおよびリンクする必要がありますが、Xbox の GDK イメージに最新の GameInput ランタイムが含まれているため、再頒布可能パッケージは必要ありません。

GameInput は発展中の API で、時間の経過と共に新しい機能が追加され、不要または古くなった機能は削除されています。 GameInput の最新バージョンは、公式の NuGet パッケージ内で見つかります。 このパッケージには、最新の更新されたバージョン履歴も含まれています。 パッケージには、最新の GameInput ヘッダー、バイナリ、および再頒布可能ファイルが常に含まれており、タイトルにインクルードできます。

GameInput の新しいバージョンへのアップグレードは、迅速かつ簡単に行えます。 さらに、最新の GameInput ヘッダーで説明されている API に関係なく、以前のバージョンの GameInput に対してコンパイルされたアプリケーションでは、バイナリと機能の互換性が維持されます。 このモデルでは、出荷されたゲームは GameInput の改善を享受でき、必要に応じて最新バージョンの GameInput に移行して新機能を利用できます。

ランタイムと API バージョンのアップグレード

異なるバージョンの GameInput が似たような名前とメソッドを持っていますが、それらは別々の UUID で明確にバージョン管理されいます。 GameInput API v.1 以降では、各バージョンが一意の名前空間 (GameInput::v1 など) の中で定義されています。 GameInput 内での同じ基盤オブジェクトには、以下のインターフェイスが実装されています。 QueryInterface を使用するとバージョンを切り替えることができます。つまり、必要に応じてゲーム内で API の使用を混在させることが可能です。

API がグローバルな名前空間で定義されている GameInput v.0 からアップグレードする場合、using namespace GameInput::v1 ステートメントを追加することで、v.1 以降のリビジョンの API を導入するために更新する必要がある GameInput 呼び出しサイトの数を減らせる場合があります。

ランタイム バージョン チェックに加えて、GAMEINPUT_API_VERSION プロセッサ定義をチェックすることで、条件付きコンパイルを使用できます。 この定義は、現在使用中の GameInput API バージョンおよび GameInput メジャー バージョンに対応しています。 v.0 API にはこの定義が含まれていないため、バージョンの条件付きテストが必要な場合は、GameInput ヘッダー インクルードの後に次のスニペットを追加することで実現できます。

#ifndef GAMEINPUT_API_VERSION
#define GAMEINPUT_API_VERSION 0
#endif

ランタイムのみのアップグレード

GameInput を使用すると、API の使用を更新しなくても、最新のバグ修正を取得できます。 これらのバグ修正を取得するには、最新の Microsoft.GameInput NuGet パッケージにバンドルされている、GameInput 再頒布可能ファイルをインストールします。 GameInput は以前のバージョンの API とのバイナリ互換性を維持しているため、新しいランタイムで既存のヘッダーを引き続き使用できます。 テスト環境における機能が運用環境でも一貫するように保証するため、タイトルと共に最新の GameInput バイナリを再頒布することを忘れないでください。

GameInput v.1 での変更点

以前のバージョンの GameInput を使用している場合は、実装されていない多くの関数とそれに対応する列挙型と定数が、v.1 API 以降では削除されることに注意してください。 さらに、API は GameInput::v1 名前空間に配置されており、バージョン管理をしやすくしています。 これらの変更により、この (および将来の) バージョンを使用してコードをビルドするときに、コンパイル エラーが発生する可能性があります。 注目すべき変更点は次のとおりです:

  1. 以前、IGameInputDevice::GetDeviceInfo では、関数の戻り値として結果の IGameInputDeviceInfo 構造体を返していました。 この構造体は関数の out パラメーターとして返され、関数の戻り値は HRESULT になりました。

  2. 以前、IGameInput::UnregisterCallback は 2 番目のパラメーターとしてタイムアウト値を受け取っていましたが、このパラメーターは削除されました。

  3. IGameInputReading::GetSequenceNumber は削除されました。 代わりに IGameInputReading::GetTimestamp を使用してください。

バージョン管理のヒント

  • v.0 と v.1 の間の使用可能な API サーフェスの変更は最小限であり、前述の関数シグネチャの変更と合わせ、実装されたことのない機能が削除された程度です。
  • 元の GameInput.h ヘッダーからの元の v.0 API は引き続きサポートされていますが、その API は静的なままです。 この場合、GDK、古い NuGet パッケージ、または Windows SDK からそのままヘッダーを使用します。
  • 使用する API のバージョンに関係なく、開発中に NuGet パッケージから最新の再頒布可能ファイルをインストールし、その再頒布可能ファイル (またはそれ以降) をエンド ユーザーに対するゲームのインストール プロセスの一部として含める必要があります。 この再頒布可能ファイルは、新しい GameInput ランタイム実装が存在する場所であり、拡張されたコントローラーのサポート、トラックパッドのサポート、リモート デスクトップのサポート、その他のさまざまなバグ修正などにより、API のすべてのバージョンを強化します。

関連項目

GameInput NuGet パッケージ

  • Last updated on