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

各デバイスから受け取った生の入力パケットは、「読み取り」オブジェクトにカプセル化されます。読み取りには、元の生パケットデータと、(通常は) より高レベルの形式への生データの 1 つ以上の変換が含まれます。データコンテナとしての役割に加えて、読み取りは入力ストリーム内の特定の位置を参照する識別子としても機能します。

<a id="acquisitionSection" />

## 読み取りの取得

GameInput API は読み取りを取得する 2 つの方法を提供します。最も一般的な方法は、[IGameInput](/reference/input/gameinput/interfaces/igameinput/igameinput) インターフェイスのメソッドを介して、入力ストリームから直接それらにアクセスすることです。

```c++ theme={null}
HRESULT GetCurrentReading(
    _In_ GameInputKind inputKind,
    _In_opt_ IGameInputDevice * device,
    _COM_Outptr_ IGameInputReading ** reading);
```

[GetCurrentReading](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getcurrentreading) を呼び出すと、入力ストリームから最新の読み取りを取得します。返される読み取りをゲームパッドやキーボードなどの特定の種類の入力に制限する、オプションの [GameInputKind](/reference/input/gameinput/enums/gameinputkind) フィルターを渡すことができます。返される読み取りを指定したデバイスによって生成されたものだけに制限する、オプションの [IGameInputDevice](/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) フィルターを渡すこともできます。これらのフィルターは個別または一緒に適用できます。

[IGameInputReading](/reference/input/gameinput/interfaces/igameinputreading/igameinputreading) インスタンスは参照カウント方式のシングルトンです。読み取りの取得は非常に高速で軽量な操作です。メモリ割り当てもコピーも行われず、API 呼び出しはロックフリーでカーネルモードへの遷移もありません。読み取りはシングルトンであるため、アプリケーションは読み取りポインターの等価性を比較して、[GetCurrentReading](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getcurrentreading) への 2 つの呼び出しが同じ読み取りを返したかどうか (つまり、新しい入力が生成されなかったかどうか) を判別できます。

比較的シンプルな入力ニーズを持つゲームは、フレームごとに新しい入力を単純にポーリングし、2 つの読み取り (同じ読み取りでない場合) に保存された状態の違いを比較するだけかもしれません。しかし、より複雑な入力ニーズを持つゲームでは、前のフレーム以降に発生したすべての入力状態変化を完全に把握するために、入力ストリームを歩く必要があるかもしれません。これは、[GetNextReading](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getnextreading) および [GetPreviousReading](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getpreviousreading) メソッドによって可能になります。これらは [GetCurrentReading](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getcurrentreading) と同じフィルターを許可します。入力ストリームはバッファ内で最後の 0.5 秒の履歴読み取りを維持します。

```c++ theme={null}
HRESULT GetNextReading(
    _In_ IGameInputReading * referenceReading,
    _In_ GameInputKind inputKind,
    _In_opt_ IGameInputDevice * device,
    _COM_Outptr_ IGameInputReading ** reading);

HRESULT GetPreviousReading(
    _In_ IGameInputReading * referenceReading,
    _In_ GameInputKind inputKind,
    _In_opt_ IGameInputDevice * device,
    _COM_Outptr_ IGameInputReading ** reading);
```

あるいは、アプリケーションは入力が生成されるたびに呼び出されるコールバックを登録できます。以前の同期メソッドと同様に、返される読み取りの種類とデバイスを制御するために、いくつかのフィルターを適用できます。詳細については、GameInput の高度なトピックセクションの [GameInput コールバック](/build/core-features/common/input/advanced/input-callbacks) を参照してください。

<a id="gettingStateSection" />

## 読み取りからのデータの取得

すべての読み取りにはデバイスからの生の入力パケットデータが含まれていますが、読み取りには通常、そのデータの 1 つ以上の高レベル変換も含まれます。たとえば、ゲームパッドから受け取った入力は、既知のボタンとサムスティック識別子を持つ標準的な固定形式構造体にも解析されます。読み取りには同じ生の入力データの複数の異なる表現が含まれていることが多く、アプリケーションはニーズに最適な形式を選択できます。

アプリケーションは、[GetInputKind](/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getinputkind) メソッドを呼び出すことで、読み取りに含まれるデータの種類を問い合わせることができます。これは [GameInputKind](/reference/input/gameinput/enums/gameinputkind) 列挙型の 1 つ以上のフラグ値を返します。

```c++ theme={null}
typedef enum GameInputKind
{
    GameInputKindUnknown         = 0x00000000,
    GameInputKindRawDeviceReport = 0x00000001,
    GameInputKindController      = 0x00000002,
    GameInputKindKeyboard        = 0x00000004,
    GameInputKindMouse           = 0x00000008,
    GameInputKindTouch           = 0x00000100,
    GameInputKindMotion          = 0x00001000,
    GameInputKindArcadeStick     = 0x00010000,
    GameInputKindFlightStick     = 0x00020000,
    GameInputKindGamepad         = 0x00040000,
    GameInputKindRacingWheel     = 0x00080000,
    GameInputKindUiNavigation    = 0x01000000
} GameInputKind;
```

読み取りで利用可能なデータの種類は、入力デバイスとその物理的特性によって異なります。たとえば、標準的なキーボードからの読み取りにはキーボードデータのみが含まれる場合がありますが、統合トラックボール付きキーボードからの読み取りにはキーボードとマウスの両方のデータが含まれる場合があります。

ほぼすべてのゲームコントローラーは、匿名の軸とボタン状態の集まりである汎用的な「コントローラー」データを含む読み取りを生成します。これにより、入力マッピング UI を持つアプリケーションに対して幅広いデバイスサポートが可能になります。ただし、多くのゲームコントローラー (ゲームパッドなど) は、読み取りに馴染みのある固定形式の状態も公開しており、これは典型的なゲームが利用しやすいものです。

```c++ theme={null}
typedef struct GameInputGamepadState
{
    GameInputGamepadButtons buttons;
    float leftTrigger;
    float rightTrigger;
    float leftThumbstickX;
    float leftThumbstickY;
    float rightThumbstickX;
    float rightThumbstickY;
} GameInputGamepadState;
```

[IGameInputReading](/reference/input/gameinput/interfaces/igameinputreading/igameinputreading) インターフェイスには、読み取りがサポートするあらゆる形式で状態を取得するためのメソッドが含まれています。読み取りから利用可能なすべての異なる表現は事前に計算されているため、これらのメソッドは数バイトのデータをコピーして返すだけです。

<a id="sampleSection" />

## シンプルなゲームパッド入力ループ

以下のサンプルコードは、ゲームパッド用に完全に機能する入力ループの一例です。このサンプルで注目すべき点の 1 つは、明示的なデバイス列挙がないことです。[IGameInputDevice](/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice) の唯一の使用はデバイス識別子としてです。そのメソッドは一度も呼び出されません。これは、GameInput API の入力中心の性質と、一般的な入力シナリオでコードをどのように簡素化できるかを示しています。

```c++ theme={null}
IGameInput* g_gameInput = nullptr;
IGameInputDevice* g_gamepad = nullptr;

HRESULT InitializeInput()
{
    return GameInputCreate(&g_gameInput);
}

void ShutdownInput()
{
    if (g_gamepad) g_gamepad->Release();
    if (g_gameInput) g_gameInput->Release();
}

void PollGamepadInput()
{
    // Ask for the latest reading from devices that provide fixed-format
    // gamepad state. If a device has been assigned to g_gamepad, filter
    // readings to just the ones coming from that device. Otherwise, if
    // g_gamepad is null, it will allow readings from any device.
    IGameInputReading * reading;
    if (SUCCEEDED(g_gameInput->GetCurrentReading(GameInputKindGamepad, g_gamepad, &reading)))
    {
        // If no device has been assigned to g_gamepad yet, set it
        // to the first device we receive input from. (This must be
        // the one the player is using because it's generating input.)
        if (!g_gamepad) reading->GetDevice(&g_gamepad);

        // Retrieve the fixed-format gamepad state from the reading.
        GameInputGamepadState state;
        reading->GetGamepadState(&state);
        reading->Release();

        // Application-specific code to process the gamepad state goes here.
    }

    // If an error is returned from GetCurrentReading(), it means the
    // gamepad we were reading from has disconnected. Reset the
    // device pointer, and go back to looking for an active gamepad.
    else if (g_gamepad)
    {
        g_gamepad->Release();
        g_gamepad = nullptr;
    }
}
```

<a id="seeAlsoSection" />

## リファレンス API ドキュメント

* [GameInput (API 内容)](/reference/input/gameinput/gameinput_members)

## 関連項目

[GameInput の基礎](/build/core-features/common/input/overviews/input-fundamentals)

[GameInput の高度なトピック](/build/core-features/common/input/advanced/input-advanced-topics)

[GameInput API リファレンス](/reference/input/gc-reference-input-toc)


## Related topics

- [Windows.XBOX.Input から GameInput への移植](/ja-jp/build/core-features/common/input/porting/input-porting-wxi.md)
- [GameInputArcadeStickButtons](/ja-jp/reference/input/gameinput/enums/gameinputarcadestickbuttons.md)
- [Input](/ja-jp/build/core-features/common/input/gc-input-toc.md)
- [概要](/ja-jp/build/core-features/common/input/overviews/index.md)
- [IGameInput::GetNextReading](/ja-jp/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getnextreading.md)