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

> 특정 GameInput API 버전에 대한 IGameInput 인터페이스의 인스턴스를 가져옵니다.

특정 GameInput API 버전에 대한 `IGameInput` 인터페이스의 인스턴스를 가져옵니다.

## 구문

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

### 매개변수

*riid*   \_In\_\
형식: REFIID

가져올 `IGameInput` 인터페이스의 인터페이스 ID(IID)입니다. IID는 GameInput API 버전을 선택합니다. 예를 들어 v4의 경우 `__uuidof(GameInput::v4::IGameInput)`, v0의 경우 `__uuidof(GameInput::v0::IGameInput)`입니다.

*ppv*   \_COM\_Outptr\_\
형식: LPVOID\*

기본 프로세스당 싱글톤의 요청된 인터페이스를 받습니다. 함수가 실패하면 `nullptr`로 설정됩니다.

### 반환값

형식: HRESULT

성공하면 `S_OK`를 반환합니다. *riid*가 `IGameInput` 인터페이스의 IID가 아니거나 설치된 GameInput 런타임이 요청된 API 버전을 지원하지 않으면 `E_NOINTERFACE`를 반환합니다. GameInput 런타임을 로드할 수 없으면 다른 오류 코드를 반환합니다.

## 설명

`GameInputInitialize`는 [GameInputCreate](https://docs.xbox.com/ko/reference/input/gameinput/functions/gameinputcreate.md)처럼 작동하지만 원하는 `IGameInput` 버전의 IID를 받습니다. 두 함수 모두 동일한 프로세스당 싱글톤에 대한 인터페이스를 반환합니다. 첫 번째 호출에서 싱글톤이 생성되고, 이후 호출에서는 싱글톤에 대한 참조가 추가됩니다. 이러한 함수를 호출할 시점과 참조를 유지할 기간에 대한 지침은 [GameInputCreate](https://docs.xbox.com/ko/reference/input/gameinput/functions/gameinputcreate.md)를 참조하세요.

GameInput 런타임은 자신의 주 버전 이하인 모든 API 버전을 지원합니다. 예를 들어 GameInput 4.0 런타임은 v0부터 v4까지 모든 `IGameInput` 버전의 IID를 허용합니다. 설치된 런타임보다 최신 버전을 요청하면 함수는 `E_NOINTERFACE`로 실패합니다. 이를 사용하여 런타임에 최신 API 버전을 사용할 수 있는지 확인할 수 있습니다.

### GameInputCreate와의 관계

v3부터 GameInput 헤더의 `GameInputCreate`는 헤더가 선언하는 `IGameInput` 인터페이스의 IID로 `GameInputInitialize`를 호출하는 인라인 함수입니다.

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

따라서 v3 이상에서 `GameInputCreate`를 호출하면 포함하는 헤더와 일치하는 버전의 `IGameInput`이 생성됩니다. 해당 헤더를 포함하지 않고 다른 버전을 만들려면 `GameInputInitialize`를 직접 호출하세요.

v0에서 `GameInputCreate`는 `GameInput.lib`에서 내보내는 함수이며 항상 v0 인터페이스를 만듭니다. [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 패키지의 `GameInput.lib`는 대신 `GameInputInitialize`를 내보냅니다. 해당 라이브러리에 링크할 때 v0 인터페이스를 만들려면 v0 IID로 `GameInputInitialize`를 호출하세요. v0 헤더는 `GameInputInitialize`를 선언하지 않으므로 직접 선언해야 합니다.

```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));
}
```

설치된 런타임이 너무 오래되어 `GameInputInitialize`를 제공하지 않는 경우, 라이브러리는 v0 IID에 대해서는 런타임의 `GameInputCreate`로 대체하고, 다른 IID에 대해서는 `E_NOINTERFACE`를 반환합니다.

이미 가지고 있는 `IGameInput` 개체의 다른 API 버전을 가져오려면 `GameInputInitialize`를 다시 호출하는 대신 해당 개체에서 `QueryInterface`를 호출하세요. 자세한 내용과 예제는 [하나의 애플리케이션에서 여러 GameInput API 버전 사용](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-version-interop.md)을 참조하세요.

## 요구 사항

**헤더:** GameInput.h

**라이브러리:** GameInput.lib

**지원되는 플랫폼:** Windows, XBOX One 제품군 콘솔 및 XBOX Series 콘솔

## 함께 보기

[GameInputCreate](https://docs.xbox.com/ko/reference/input/gameinput/functions/gameinputcreate.md)\
[GameInput API 버전 관리](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-versioning.md)\
[하나의 애플리케이션에서 여러 GameInput API 버전 사용](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInput](https://docs.xbox.com/ko/reference/input/gameinput/gameinput_members.md)

## 버전 기록

| 버전 | 변경 사항 |
| - | - |
| **v3** | 도입됨. |


## Related topics

- [GameInputCreate](https://docs.xbox.com/ko/reference/input/gameinput/functions/gameinputcreate.md)
- [XBOX 콘솔의 GameInput](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-xbox.md)
- [GameInput API 멤버](https://docs.xbox.com/ko/reference/input/gameinput/gameinput_members.md)
- [하나의 애플리케이션에서 여러 GameInput API 버전 사용](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-version-interop.md)
- [XInputOnGameInputInitialize](https://docs.xbox.com/ko/reference/input/xinputongameinput/functions/xinputongameinputinitialize.md)