메인 콘텐츠로 건너뛰기
v0부터 v4까지의 각 GameInput API 버전은 고유한 COM 인터페이스 세트를 정의합니다. GameInput 런타임은 모든 버전을 동일한 기본 개체에 구현하므로, 장치와 같은 단일 개체에는 v0 인터페이스, v4 인터페이스, 그리고 그 사이의 각 버전에 대한 인터페이스가 있습니다. 개체를 한 버전에서 다른 버전으로 전환하려면 해당 개체에서 QueryInterface를 호출하세요. 이를 통해 다음을 수행할 수 있습니다.
  • 전체 애플리케이션을 한 번에 마이그레이션하지 않고도 v0과 같은 이전 API 버전을 기반으로 빌드된 애플리케이션에 v4 기능을 추가합니다.
  • 애플리케이션의 나머지 부분이 v4를 사용하더라도 이전 버전의 GameInput을 대상으로 빌드된 SDK, 미들웨어 또는 엔진 플러그 인을 호출합니다.

지원되는 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>와 같이 버전별 폴더에 있습니다. 라이브러리는 요청한 모든 API 버전에 대해 GameInput을 생성하는 GameInputInitialize를 내보냅니다. GDK에 포함된 라이브러리와 같은 이전 릴리스의 라이브러리도 계속 작동합니다. 자세한 내용은 이전 라이브러리 유지를 참조하세요.

v0 헤더 포함

v1부터 각 GameInput 헤더는 GameInput::v4와 같은 버전별 네임스페이스에 형식을 선언합니다. 반면 v0 헤더는 전역 네임스페이스에 형식을 선언합니다. v0 헤더를 최신 헤더와 함께 사용하려면 GameInputV0.h와 같은 자체 헤더에 다음 상용구 코드를 넣으세요.
이 헤더는 다음과 같이 작동합니다.
  • 먼저 최신 <GameInput.h>를 포함합니다. 이렇게 하면 최신 API가 자체 네임스페이스에 선언되고, v0 헤더가 의존하는 Windows 및 COM 헤더가 포함되므로 v0 헤더가 네임스페이스 내부에서 이를 다시 포함하지 않습니다.
  • 전방 선언을 통해 v0 헤더의 typedef가 최신 헤더에서 이미 선언한 인터페이스를 참조하는 대신 GameInput::v0에 새 인터페이스를 선언하도록 합니다.
  • 네임스페이스 내부에 <v0/GameInput.h>를 포함하면 GameInput::v0::IGameInput 및 GameInput::v0::GameInputKindGamepad처럼 모든 v0 형식, 열거형, 상수가 GameInput::v0으로 이동합니다.
v0 소스 파일에서는 <GameInput.h> 대신 GameInputV0.h를 포함하고, 기존 코드가 정규화되지 않은 이름을 계속 사용할 수 있도록 using namespace GameInput::v0;를 추가하세요. GameInputV0.h를 포함하는 소스 파일은 GameInput::v4::IGameInput과 같은 전체 이름으로 최신 API를 사용할 수도 있습니다.

예제: v0 애플리케이션에 v4 기능 추가

v4 기능을 사용하기 시작하기 위해 v0 코드를 다시 작성할 필요는 없습니다. v0 코드는 해당 소스 파일에 그대로 두고, 새 v4 코드는 별도의 소스 파일에 넣으세요. 두 코드 간에 GameInput 개체를 IUnknown*으로 전달하고, 각 쪽에서 필요한 버전에 대해 QueryInterface를 호출하도록 합니다.

기존 v0 코드

다음 v0 코드는 GameInput을 생성하고 게임패드를 읽습니다. 원래 v0 코드와 비교하면 다음 세 가지만 변경됩니다.
  • <GameInput.h> 대신 GameInputV0.h를 포함합니다.
  • 최신 라이브러리는 v0 GameInputCreate 함수를 내보내지 않으므로 v0 IID로 GameInputInitialize를 호출하여 GameInput을 생성합니다.
  • 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를 내보내지 않습니다. v4 인터페이스는 QueryInterface를 호출해서만 가져오고, GameInputInitialize를 호출하는 v4 GameInputCreate는 호출하지 마세요.

버전 간 전환 규칙

서로 다른 API 버전의 인터페이스는 IGameInput 및 IGameInputDevice처럼 이름이 같지만, 메서드가 다른 서로 다른 형식입니다. v0 인터페이스에 대한 포인터와 v4 인터페이스에 대한 포인터는 둘 다 같은 개체를 참조하더라도 서로 다릅니다.
캐스팅은 QueryInterface 호출과 같지 않습니다. 다른 API 버전의 인터페이스를 가져오려면 항상 QueryInterface를 사용하세요. 버전 간 변환에 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*)를 선언하며, 애플리케이션의 나머지 부분은 GameInput 개체를 IUnknown*으로 전달합니다.
같은 방법은 반대 방향으로도 작동합니다. 구성 요소가 애플리케이션에 이전 버전의 GameInput 개체를 제공하는 경우 해당 개체에서 QueryInterface를 호출하여 v4 인터페이스를 가져오세요. 모든 버전이 같은 개체에 의해 구현되므로 SDK와 애플리케이션은 장치, 판독값, 상태를 공유합니다. 또한 SDK의 API 버전은 설치된 런타임 버전보다 낮거나 같아야 합니다.

참고 항목

GameInput API 버전 관리
GameInput NuGet 패키지
GameInput 사이드로딩
GameInputInitialize
GameInput API 참조
마지막 수정일 2026년 11월 6일