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

# GameInputInitialize

> Gets an instance of the IGameInput interface for a specific GameInput API version.

Gets an instance of the `IGameInput` interface for a specific GameInput API version.

## Syntax

```cpp theme={null}
HRESULT GameInputInitialize(
    REFIID riid,
    LPVOID* ppv
);
```

### Parameters

*riid*   \_In\_\
Type: REFIID

The interface ID (IID) of the `IGameInput` interface to get. The IID selects the GameInput API version, for example `__uuidof(GameInput::v4::IGameInput)` for v4 or `__uuidof(GameInput::v0::IGameInput)` for v0.

*ppv*   \_COM\_Outptr\_\
Type: LPVOID\*

Receives the requested interface of the underlying per-process singleton. Set to `nullptr` if the function fails.

### Return value

Type: HRESULT

Returns `S_OK` on success. Returns `E_NOINTERFACE` if *riid* isn't the IID of an `IGameInput` interface, or if the installed GameInput runtime doesn't support the requested API version. Returns another error code if the GameInput runtime can't be loaded.

## Remarks

`GameInputInitialize` works like [GameInputCreate](https://docs.xbox.com/reference/input/gameinput/functions/gameinputcreate.md), but takes the IID of the `IGameInput` version that you want. Both functions return an interface on the same per-process singleton. The first call creates the singleton, and later calls add a reference to it. For guidance on when to call these functions and how long to keep the reference, see [GameInputCreate](https://docs.xbox.com/reference/input/gameinput/functions/gameinputcreate.md).

A GameInput runtime supports every API version that's lower than or equal to its own major version. For example, the GameInput 4.0 runtime accepts the IID of any `IGameInput` version from v0 through v4. If you request a version that's newer than the installed runtime, the function fails with `E_NOINTERFACE`. You can use this to check at run time whether a newer API version is available.

### Relationship to GameInputCreate

Starting with v3, `GameInputCreate` in the GameInput header is an inline function that calls `GameInputInitialize` with the IID of the `IGameInput` interface that the header declares:

```cpp theme={null}
inline HRESULT GameInputCreate(
    _COM_Outptr_ IGameInput** gameInput)
{
    return GameInputInitialize(
        IID_IGameInput,
        reinterpret_cast<void**>(gameInput));
}
```

Because of this, calling `GameInputCreate` in v3 and later creates the version of `IGameInput` that matches the header you include. To create a different version without including its header, call `GameInputInitialize` directly.

In v0, `GameInputCreate` is a function that's exported by `GameInput.lib` and always creates the v0 interface. The `GameInput.lib` in the [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet package exports `GameInputInitialize` instead. To create the v0 interface when you link that library, call `GameInputInitialize` with the v0 IID. The v0 header doesn't declare `GameInputInitialize`, so declare it yourself:

```cpp theme={null}
#include <v0/GameInput.h>

STDAPI GameInputInitialize(_In_ REFIID riid, _COM_Outptr_ LPVOID* ppv);

HRESULT CreateLegacyGameInput(IGameInput** gameInput)
{
    return GameInputInitialize(__uuidof(IGameInput), reinterpret_cast<void**>(gameInput));
}
```

If the installed runtime is too old to provide `GameInputInitialize`, the library falls back to the runtime's `GameInputCreate` for the v0 IID, and returns `E_NOINTERFACE` for any other IID.

To get another API version of an `IGameInput` object that you already have, call `QueryInterface` on it instead of calling `GameInputInitialize` again. For more information and examples, see [Using multiple GameInput API versions in one application](https://docs.xbox.com/build/core-features/common/input/overviews/input-version-interop.md).

## Requirements

**Header:** GameInput.h

**Library:** GameInput.lib

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## See also

[GameInputCreate](https://docs.xbox.com/reference/input/gameinput/functions/gameinputcreate.md)\
[GameInput API versioning](https://docs.xbox.com/build/core-features/common/input/overviews/input-versioning.md)\
[Using multiple GameInput API versions in one application](https://docs.xbox.com/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInput](https://docs.xbox.com/reference/input/gameinput/gameinput_members.md)

## Version History

| Version | Changes |
| - | - |
| **v3** | Introduced. |


## Related topics

- [GameInputCreate](https://docs.xbox.com/reference/input/gameinput/functions/gameinputcreate.md)
- [GameInput on XBOX consoles](https://docs.xbox.com/build/core-features/common/input/overviews/input-xbox.md)
- [GameInput API members](https://docs.xbox.com/reference/input/gameinput/gameinput_members.md)
- [Using multiple GameInput API versions in one application](https://docs.xbox.com/build/core-features/common/input/overviews/input-version-interop.md)
- [XInputOnGameInputInitialize](https://docs.xbox.com/reference/input/xinputongameinput/functions/xinputongameinputinitialize.md)