XBOX One용 Microsoft Game Development Kit 이식 가이드
이 항목은 기존 코드베이스를 XBOX용 Microsoft Game Development Kit (GDK) 플랫폼으로 이식하기 위한 기술 개요를 제공합니다. 이미 XBOX One 개발을 진행 중인 개발자에게는 대부분의 서브시스템이 익숙할 것이지만, 다른 API 디자인을 사용합니다. Direct3D 그래픽과 같은 일부 영역은 크게 변경되지 않았습니다. 이 항목은 전체 이식 프로세스에 대한 개괄, 특정 영역에 대한 링크, 그리고 흔히 겪을 수 있는 함정을 피하기 위한 몇 가지 팁을 제공합니다. 이 가이드에 대한 피드백이 있으신가요? Microsoft Game Development Kit (GDK) 개발자 포럼에 알려주세요. 기존 타이틀을 이식하는 것이 아니라 Microsoft Game Development Kit (GDK) 플랫폼으로 새로운 타이틀을 개발하는 경우, Developing a new title with the GDK를 참조하세요.Microsoft Game Development Kit (GDK) 소개
여러분과 같은 게임 개발 파트너들은 Microsoft의 Gaming 팀에게 잘하고 있는 점과 개선이 필요한 부분에 대한 귀중한 피드백을 제공해 왔습니다. Microsoft Game Development Kit (GDK)의 주요 목표는 여러분의 피드백을 직접 다루고 다음을 보장하는 것입니다.- 지금과 동일하게 게임을 계속 개발할 수 있도록 함
- 오늘의 콘솔과 PC, 그리고 내일의 콘솔과 XBOX Game Streaming까지 모든 Microsoft Gaming 이니셔티브 및 프로그램에서 가능한 한 많은 코드를 쉽게 공유
- 빠르고 안정적이며 개발자 중심의 환경을 제공하는 개발 도구 및 플랫폼을 신뢰
- 새로운 다중 플랫폼 서비스 및 경험을 가능한 한 빠르고 쉽게 활용
목차
- 이식 프로젝트 계획
- 개발 환경
- 애플리케이션 시작
- 애플리케이션 초기화
- Windows 메시지 루프
- Direct3D 디바이스 생성
- 프레젠테이션
- 프로세스 수명 관리(PLM)
- 메모리 관리
- 프로그래밍 모델
- HLSL 셰이더
- 사용자 관리
- 네트워킹 및 XBOX 서비스 통합
- 다음 단계
- 팁 및 요령
- 바이너리 호환성 및 컴포넌트 재사용
- 코딩 스타일 및 모범 사례
- 참고 항목
이 이식 가이드의 목적을 위해 Gaming.Xbox.XboxOne.x64 및/또는 Gaming.Xbox.Scarlett.x64 플랫폼을 대상으로 한다고 가정합니다. Microsoft Game Development Kit (GDK)에는 Gaming.Desktop.x64 플랫폼도 포함되어 있습니다. 이는 표준 x64 Win32 플랫폼의 변형이며, 이 이식 가이드에서는 다루지 않습니다.Gaming.Desktop.x64의 주요 가치는 PC를 대상으로 할 때 빌드 설정, Visual Studio 통합, 느슨한 레이아웃 동작 등의 측면에서 Gaming.Xbox.*.x64와 유사한 경험을 제공하는 것입니다. 대안적으로, ‘표준’ x64 플랫폼을 사용하고 PC용 모든 설정/패키징을 직접 구현할 수 있습니다.
이식 프로젝트 계획
기존 코드베이스를 Microsoft Game Development Kit (GDK)로 이식할 때 일반적으로 기존 XBOX One Software Development Kit 프로젝트 또는 클래식 Win32 데스크톱 애플리케이션에서 시작합니다. 기존 XBOX One 타이틀이 있는 많은 개발자의 경우, Windows Runtime API의 사용이 비교적 고립되어 있는 한Durango 코드베이스에서 시작하는 것이 더 나은 시작점이 될 것입니다. 클래식 Win32 데스크톱 코드베이스는 Microsoft Game Development Kit (GDK) 프로그래밍 모델에 훨씬 가깝지만, 종종 콘솔용으로 수정해야 하는 데스크톱 중심의 UI 및 컨트롤 스키마를 가정합니다. 클래식 Win32 데스크톱 코드베이스는 또한 특히 XBOX용 Microsoft Game Development Kit (GDK)에서 지원되지 않는 API 세트를 활용하는 게임의 편집 도구 스위트의 일부로 사용될 때 많은 데스크톱 중심 통합을 가지는 경향이 있습니다. 각각 시작에는 장단점이 있습니다. 경우에 따라 코드베이스의 여러 부분에 두 유형에서 가져오는 것이 더 쉬울 수 있습니다.
XBOX One Software Development Kit에서 이식
코드베이스가 이미 XBOX One Software Development Kit(즉Durango 플랫폼)를 통해 XBOX One을 지원한다면, 애플리케이션의 API 사용을 현대화하는 작업의 대부분이 이미 수행되었습니다. 코드는 또한 콘솔의 특정 제약에 잘 최적화되어 있어야 하며, 다음과 같이 XBOX One 전용 확장을 상당히 활용할 가능성이 큽니다.
- DirectX 12.X가 필요합니다. XBOX One 타이틀에 이미 DirectX 12.X를 사용하고 있다면, Direct3D 사용에 대한 프레젠테이션 API 외에는 변경이 필요하지 않습니다.
현재 DirectX 11.X를 사용하고 있다면, 먼저 DirectX 12.X로 업그레이드하세요. 이는 Microsoft Game Development Kit (GDK)로 이동하기 전에 기존 XBOX One Software Development Kit 빌드로 하는 것이 더 쉬울 수 있습니다. 자세한 내용은 다음 항목을 참조하세요. Direct3D 11에서 Direct3D 12로 이식 및 Introduction to Direct3D 12 on XBOX One Xfest talk (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos), Porting from Direct3D 11 to Direct3D 12 Xfest talk (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos).
- DXGI swap chain을 사용하는 대신 프레젠테이션 로직은 PresentX API를 사용해야 합니다.
- Microsoft Game Development Kit (GDK) GDK Game OS의 메모리 서브시스템에 몇 가지 중요한 변경 사항이 있습니다. 메모리 관리자 구현을 재검토하세요.
- 컨트롤러 입력의 경우
Windows.Xbox.Input대신 새로운 GameInput API를 사용하세요. - 대부분의 시나리오에서 Windows Runtime API를 더 이상 사용하지 않으므로 기존 C++/CX 또는 C++/WinRT 코드를 새로운 Win32 스타일 또는 DirectX 스타일 COM API로 교체하세요.
- Core Audio 기능은 변경되지 않았습니다. 그러나 audio API 비교에 설명된 대로 일부 API 변경이 필요할 수 있습니다. XMA 확장을 사용하는 XAudio2, WASAPI 및
ISpatialAudioClient가 지원됩니다. - Visual Studio에서 빌드할 때
Durango플랫폼 구성 대신Gaming.Xbox.XboxOne.x64및/또는Gaming.Xbox.Scarlett.x64플랫폼 구성을 추가하고 Visual Studio 2019 또는 Visual Studio 2022로 업그레이드하세요.
새로운 플랫폼 구성을 추가하는 데 도움이 되도록 SolutionUpdater라는 샘플을 만들었습니다. 이 샘플 도구는 기존 Visual Studio Solution 파일을 가져와 솔루션에서 참조하는 모든 관련 프로젝트 파일에 대해 자동으로 새 플랫폼 구성을 생성하여 프로세스 속도를 크게 높이고 수동 오류의 가능성을 줄여줍니다. 자세한 내용은 샘플과 함께 포함된 문서를 검토하세요.
코드베이스가 UWP(Universal Windows Platform) 앱 모델을 지원하는 경우 XBOX One Software Development Kit에서와 유사한 이식 경로가 있습니다.
클래식 Win32 데스크톱에서 이식
코드베이스가 클래식 Win32 데스크톱만 지원하는 경우, 이식 프로세스는 사용되지 않는 API 및 기타 기능과 관련하여 코드베이스가 얼마나 최신인지에 따라 매우 광범위할 수 있습니다. 클래식 Win32 데스크톱 코드베이스는 Windows 9x/ME 시대까지 거슬러 올라가는 매우 넓은 범위의 API를 가질 수 있음을 명심하세요. 이 목록은 발생할 수 있는 모든 잠재적 문제를 포괄하지 않습니다. XBOX를 대상으로 할 때는 UI, 입력 모델, 고정 해상도 디스플레이, 제약된 메모리 등 PC에서 콘솔로 이식할 때의 일반적인 고려 사항도 있을 것입니다. 자세한 내용은 Coming to XBOX from PC - What You Need to Know를 참조하세요.- x64 네이티브가 필요합니다. 자세한 내용은 게임 개발자를 위한 64비트 프로그래밍을 참조하세요.
- DirectX 12.X가 필요합니다. DirectX 11, Direct3D 10, Direct3D 9 또는 그 이전 버전은 사용할 수 없습니다. 또한 OpenGL과 Vulkan은 지원되지 않습니다. 자세한 내용은 DirectX11 및 DirectX12 이식 가이드를 참조하세요.
- 레거시 DirectX SDK 컴포넌트 D3DX9, D3DX10, D3DX11, XACT는 사용할 수 없습니다. 자세한 내용은 Microsoft Docs, Where is the DirectX SDK (2021 Edition)?, Living without D3DX, The Zombie DirectX SDK를 참조하세요.
WINAPI_FAMILY_GAMES는 전체 Win32 API 계열의 하위 집합입니다. 이러한 API로 자신을 제한하세요.- AppX 패키징이 필요합니다. 패키징 및 배포 프로세스를 업데이트하세요.
- 컨트롤러 입력의 경우
Windows.Gaming.Input또는 DirectInput 대신 새로운 GameInput API를 사용하세요. - 오디오의 경우 XAudio2, WASAPI, ISpatialAudioClient 또는 호환되는 오디오 미들웨어를 사용하세요.
- 레지스트리 사용 인스턴스를 제거하세요.
WndProc메시지 처리를 줄여야 합니다. 특히 창 위치 지정, 크기 조정 및 셸 통합을 다루는 많은 메시지는 XBOX용 Microsoft Game Development Kit (GDK)에 적용되지 않습니다.- Visual Studio로 빌드하는 경우 Visual Studio 2019 또는 Visual Studio 2022와 함께 작동하도록 코드를 업그레이드하세요. 그렇지 않으면 빌드가 새 전처리기 정의를 사용하고
xgameplatform.lib우산 라이브러리와 같은GXDK\gameKit\lib\amd64의 라이브러리와 링크하도록 하세요. - COM 컴포넌트의 경우 다중 스레드 아파트(MTA) 스레딩 모델만 지원됩니다.
COINITBASE_MULTITHREADED는 Direct3D 애플리케이션에 일반적입니다. - 단일 창 인스턴스만 지원됩니다. 여러 동시 창 인스턴스나 대화 상자는 지원되지 않습니다.
개발 환경
Visual Studio 2019 (16.11 업데이트) 또는 Visual Studio 2022는 Microsoft Game Development Kit (GDK)에서 지원되는 개발 환경입니다. 다음을 설치하세요.- Workload: 코어 도구 세트용 Game development with C++
- Workload: 패키징 도구용 UWP development
- Workload (선택 사항): PC 측 도구 및 샘플용 desktop development with C++
Visual Studio 2017을 사용한 XBOX One Software Development Kit 개발에는 선택적 컴포넌트 _Windows 8.1 SDK and UCRT SDK_도 필요했습니다. 이 컴포넌트는 Microsoft Game Development Kit (GDK)에는 필요하지 않습니다.여전히 Visual Studio 2015 이하 버전을 사용하고 있다면, 이식 작업의 첫 번째 단계는 Visual Studio 2019 이상으로 업그레이드하는 것입니다.
Visual Studio 플랫폼
Microsoft Game Development Kit (GDK)는 Visual Studio와 통합하여 XBOX의 Microsoft GDK Game OS를 대상으로 하는Gaming.Xbox.XboxOne.x64 및 Gaming.Xbox.Scarlett.x64 플랫폼을 제공합니다. 이는 XBOX One Software Development Kit Durango 플랫폼을 대체합니다.
사용자 지정 빌드 솔루션
Visual Studio 외부에서 코드를 빌드하기 위한 위치용 환경 도우미가 변경되었습니다. XBOX One Software Development Kit:위의 예제 경로에서 _build_number_는 시스템에 설치된 빌드를 나타냅니다(예: 190700).
%GameDKLatest%\GXDK\gameKit에는 콘솔 전용 확장에 대한 모든 헤더와 lib, 그리고 Microsoft Game Development Kit (GDK) 바이너리 링킹을 위한 주요 플랫폼 우산 lib이 포함되어 있습니다. %GameDKLatest%\GRDK\gameKit에는 유사하게 콘솔 개발에 특정하지 않은 모든 기능에 대한 헤더와 lib이 포함되어 있습니다. Microsoft Game Development Kit (GDK)는 종속성으로 Windows 10 SDK (10.0.19041.0) 이상 설치가 필요합니다. %GameDKLatest%\GXDK\toolKit에서 PC 측 콘솔 도구를 위한 몇 가지 추가 헤더/lib을 사용할 수 있습니다.
2023년 10월 릴리스부터 Windows 11 SDK (10.0.22000.0)이 최소 지원 버전입니다.사용해야 할 여러 옵션과 정의가 있습니다. 모든 세부 정보는 Visual C++ 컴파일러 및 링커 스위치 권장 사항과 CMakeExample 샘플을 참조하세요.
컴파일러 (cl.exe)
/D_GAMING_XBOX는/D_XBOX_ONE /D_TITLE및/D_DURANGO를 모두 대체합니다./D_GAMING_XBOX_XBOXONE은Gaming.Xbox.XboxOne.x64플랫폼에만 정의됩니다./D_GAMING_XBOX_SCARLETT는Gaming.Xbox.Scarlett.x64플랫폼에만 정의됩니다./DWINAPI_FAMILY=WINAPI_FAMILY_GAMES는WINAPI_FAMILY_TV_TITLEAPI 계열 대신 API 파티셔닝을 제어합니다./DWIN32_LEAN_AND_MEAN,/D_ATL_NO_DEFAULT_LIBS,/D__WRL_NO_DEFAULT_LIB__를 정의해야 합니다.- Microsoft Game Development Kit (GDK)의 경우
/AI,/FU,/ZW와 같은 Windows Runtime 스위치를 더 이상 사용하지 않습니다. /favor:AMD64,/EHsc,/fp:fast를 계속 사용하세요.Gaming.Xbox.XboxOne.x64플랫폼의 경우 계속/arch:AVX를 사용하세요.Gaming.Xbox.Scarlett.x64플랫폼의 경우/arch:AVX2를 사용하세요.
VS 2019 Update 3 이상 및Gaming.Xbox.Scarlett.x64플랫폼에서는/d2vzeroupper도 사용하세요. Whole Program Optimization (WPO) / Link Time Code Generation (LTCG)을 사용하는 경우/d2:-vzeroupper여야 합니다.
VS 2022 및Gaming.Xbox.XboxOne.x64플랫폼에서는/d2vzeroupper-도 사용하세요. Whole Program Optimization (WPO) / Link Time Code Generation (LTCG)을 사용하는 경우/d2:-vzeroupper-여야 합니다.
링커 (link.exe)
xgameplatform.lib,xgameruntime.lib,d3d12_x.lib또는d3d12_xs.lib,xmem.lib,pixevt.lib에 링크하세요.kernel32.lib,kernelx.lib,onecore.lib,WindowsApp.lib는 사용하지 마세요.- XGraphics 라이브러리의 경우
xg_x.lib또는xg_xs.lib를 사용하세요. - Windows Runtime API용이었던
/WINMD또는/WINMDFILE을 사용할 필요가 없습니다. - XBOX용 Microsoft Game Development Kit (GDK)는 포함된 매니페스트를 사용하지 않으므로
/MANIFEST:NO를 사용하세요. /DYNAMICBASE,/NXCOMPAT를 계속 사용하세요.
advapi32.lib comctl32.lib comsupp.lib dbghelp.lib gdi32.lib gdiplus.lib guardcfw.lib kernel32.lib mmc.lib msimg32.lib msvcole.lib msvcoled.lib mswsock.lib ntstrsafe.lib ole2.lib ole2autd.lib ole2auto.lib ole2d.lib ole2ui.lib ole2uid.lib ole32.lib oleacc.lib oleaut32.lib oledlg.lib oledlgd.lib oldnames.lib runtimeobject.lib shell32.lib shlwapi.lib strsafe.lib urlmon.lib user32.lib userenv.lib wlmole.lib wlmoled.lib onecore.lib등 지원되지 않는 Win32 라이브러리와 링크되지 않도록/NODEFAULTLIB를 사용하는 것을 고려하세요.
Windows 헤더 사용 최적화
Microsoft Game Development Kit (GDK)는 표준<Windows.h> 헤더를 사용합니다. 앞서 언급한 WIN32_LEAN_AND_MEAN 외에 다양한 lean and mean 전처리기 정의를 정의하여 가져오는 전체 Win32 시스템 헤더 수를 제어할 수 있도록 하는 것이 유용합니다.
Visual C++ 런타임
XBOX One Software Development Kit에서 Visual C++ 런타임 헤더 및 라이브러리는 XBOX One Software Development Kit의 일부였으며, 런타임 DLL은 Game OS 내부에 배치되었습니다. 이로 인해 코드를 빌드하는 데 사용되는 Visual Studio의 minor update 버전과 일치하도록 더 새로운 XBOX One Software Development Kit 릴리스 또는 QFE 레벨로 업데이트해야 했습니다. Microsoft Game Development Kit (GDK)에서 Visual C++ 런타임 DLL은 게임 패키지의 일부로 포함되며 빌드 머신에 로컬로 설치된 Visual Studio 버전과 일치합니다.VCRuntime*.dll및msvcp*.dll은 Visual C++ 컴파일러 런타임과 Standard C++ Library DLL입니다. Game OS에 포함된ucrtbase.dll도 사용됩니다.- 디버그 빌드의 경우 패키지에는
VCRuntime*d.dll,msvcp*d.dll,ucrbased.dll이 포함됩니다.
_ERA Migration Library_를 사용하는 경우/ZW로 빌드할 때 컴파일러가 사용하는vccorlib*.dll도 필요합니다.
AMP는 XBOX에서 지원되지 않으며 최신 Visual C++ 릴리스에서 사용 중단되었습니다.
애플리케이션 시작
Microsoft Game Development Kit (GDK) 프로젝트는 Windows Runtime 스타일 CoreWindow 이벤트가 아닌 Win32 데스크톱 스타일 애플리케이션 시작 및 메시지 루프의 간소화된 버전을 사용합니다. 기존 코드베이스는 다음 진입점 중 하나를 가지고 있어야 합니다.Win32 데스크톱 개발
C++/CX를 사용하는 XBOX One Software Development Kit 또는 UWP 앱
C++/WinRT를 사용하는 XBOX One Software Development Kit 또는 UWP 앱
XBOX용 Microsoft Game Development Kit (GDK)
GDK 타이틀의 경우 진입점은 Win32 클래식 데스크톱과 동일합니다.애플리케이션 초기화
일반적인 매우 기본적인 Win32 진입점 함수는 다음과 같습니다.- 창 클래스 및 스타일 사용 최소화
- UTF-16LE가 아닌 UTF-8 문자열
- Game Runtime 서브시스템 초기화
XBOX의 Microsoft Game Development Kit (GDK) 타이틀의 경우 하나의 Win32 창만 가질 수 있습니다.
Windows 메시지 루프
많은 메시지가 적용되지 않기 때문에 XBOX의 Microsoft Game Development Kit (GDK) 애플리케이션은 매우 기본적인 Win32 메시징 루프를 사용할 수 있습니다.Direct3D 디바이스 생성
XBOX의 Microsoft Game Development Kit (GDK)로 빌드된 게임은 XBOX One Software Development Kit로 구현된 것과 마찬가지로 모놀리식 런타임으로 구현된 Direct3D 12.X API를 사용합니다.
Stock Direct3D 12 및 Direct3D 11은 XBOX의 Microsoft Game Development Kit (GDK)로 빌드된 게임에는 지원되지 않습니다. DirectX 12.X용 Direct3D 12 디바이스를 만들 때
D3D12XboxCreateDevice 메서드를 사용하세요.
XMem* API
XMEM_GRAPHICS를 사용하는 XMem* API 호출에는 사용하기 전에 Direct3D 디바이스가 생성되어야 합니다. 대안적으로, Direct3D 디바이스가 존재하기 전에 해당 호출을 사용해야 하는 경우 D3DConfigureVirtualMemory를 호출할 수 있습니다.
CPU/GPU 예약
모든 Microsoft Game Development Kit (GDK) 타이틀은 전체 리소스(즉, Kinect GPU 예약 없음)와 7번째 CPU 코어를 얻습니다. 기본적으로 다음 XBOX One Software Development Kit 매니페스트 설정과 동등한 것을 얻습니다.XBOX One 대 XBOX Series X|S Direct3D 차이점
Gaming.Xbox.XboxOne.x64 플랫폼의 Direct3D 12.x 모놀리식 런타임 구현은 Direct3D 12.x의 XBOX One Software Development Kit 구현과 거의 동일합니다. XBOX의 Microsoft Game Development Kit (GDK)로 초기 이식할 때 이 플랫폼은 시작하기에 가장 쉬운 곳일 수 있습니다.
Gaming.Xbox.Scarlett.x64는 ID3D12Device8 및 ID3D12GraphicsCommandList5 인터페이스 또는 그 이상 버전까지 지원합니다.Gaming.Xbox.XboxOne.x64는 ID3D12Device, ID3D12Device1, ID3D12Device2 및 ID3D12GraphicsCommandList까지 지원합니다.
Gaming.Xbox.Scarlett.x64 플랫폼으로 이동할 때 Direct3D 12.x 구현에 몇 가지 추가 기능과 차이점이 있습니다.
- 다른 버전의 Direct3D 헤더 및 라이브러리(예:
d3d12_xs.h,d3dx12_xs.h,xg_xs.h,d3d12_xs.lib등)를 사용해야 합니다. 동일한 바이너리에서 두 버전의 Direct3D 12.x를 혼합할 수 없습니다. - Direct3D 12.x 모놀리식 런타임이 처음 구현되었을 때 Direct3D 11.x 모놀리식 런타임 위에 구축되었기 때문에
Durango또는Gaming.Xbox.XboxOne.x64플랫폼으로 빌드할 때 여러 Direct3D 11 유형이 정의됩니다. 이러한 것들은 XBOX Series X|S 구현에서 제거되었으므로d3d11_x.h헤더,D3D11_*정의,CD3D11_*클래스 또는ID3D11*인터페이스에 대한 남아 있는 참조로 인해 빌드 문제가 발생할 수 있습니다. 이러한 것들은 제거할 수 있으며 여전히 두 플랫폼 모두에 대해 빌드할 수 있습니다. - ESRAM은 XBOX Series X|S의 기능이 아니므로 ESRAM과 관련된 확장은 이 플랫폼에 대해 정의되지 않습니다. 이는 또한
xgmemory.h(ESRAM 활용을 위한 도우미)가Gaming.Xbox.XboxOne.x64플랫폼에서만 지원됨을 의미합니다.
최적의 렌더링 성능을 위해 XBOX One / XBOX One S 디바이스에서 ESRAM을 활용하는 것은 여전히 중요합니다. SimpleESRAM 및 AdvancedESRAM 샘플을 참조하세요.
- GPU 메모리 레이아웃, 특히 H-tile 및 C-Mask 기술에 여러 차이가 있습니다. 자세한 내용은 CMaskDecode, HiZDecode, HiStencil, PrimeHTile 샘플을 참조하세요.
프레젠테이션
XBOX의 Microsoft Game Development Kit (GDK)는 프레젠테이션을 위한 레거시 DXGI swap chain을 지원하지 않지만 PresentX API를 사용합니다. 새로운 PresentX API는 DXGI swap chain의 지연 문제를 해결하도록 설계되었으며, 개발자에게 프레젠테이션 버퍼에 대한 더 직접적인 제어를 제공합니다. 이 API는 또한 향후 스트리밍 애플리케이션에 대응하도록 설계되었습니다. PresentX를 사용하는 첫 번째 단계는 Direct3D 디바이스가 생성된 후 프레임 이벤트에 등록하는 것입니다.D3D12_HEAP_FLAG_ALLOW_DISPLAY 플래그로 직접 만듭니다.
WaitFrameEventX를 사용하여 파이프라인 토큰을 먼저 설정합니다.
DXGI_ERROR_DEVICE_REMOVED 및 DXGI_ERROR_DEVICE_RESET 오류를 경험하지 않습니다.
일부 다른 관련 DXGI 기능이 제거되었으며 앞서 언급한 ScheduleFrameEventX 함수는 XBOX One Software Development Kit의 DXGIXSetFrameNotification을 대체합니다.
프레임 flip 알림용 XBOX One Software Development Kit 코드입니다.
프로세스 수명 관리(PLM)
XBOX의 Microsoft Game Development Kit (GDK)로 빌드된 게임은 XBOX One XDK 앱 및 UWP 앱에서 사용되는 것과 동일한 기본 프로세스 수명 관리(PLM) 모델을 사용합니다. 앱은 제약 없이, 제약된 상태로, 일시 중지된 상태로 또는 종료된 상태로 실행됩니다. 즉, 종료를 위한 코드가 실행되지 않고 프로세스가 단순히 파괴됩니다. XBOX One Software Development Kit 앱과 UWP 앱은 Windows Runtime CoreWindow를 통해 알림을 받습니다. XBOX의 Microsoft Game Development Kit (GDK) 게임은 등록된 콜백을 통해 알림을 받습니다. suspend와 resume 이벤트만 있으며 더 이상 명시적인 activation 단계는 없습니다. 간단한 구현 방식은WM_USER 메시지를 게시하여 이를 처리하는 것입니다.
WM_USER 메시지를 처리하여 Resume까지 루프가 일시 중지되도록 하고, 렌더 루프의 안전한 시점에 적절한 GPU suspend/resume 동작이 발생하도록 합니다.
제약된 상태 대 전체 상태
제약된 리소스 대 전체 리소스에 대한 알림은 유사한 API를 통해 처리됩니다.프로세스 종료
소매 타이틀의 경우 프로세스 종료는 이전 XBOX One Software Development Kit 플랫폼과 동일한 방식으로 처리됩니다. 프로세스가 일시 중지된 다음 종료됩니다. C++ 소멸자나 정리는 처리되지 않습니다. 이는Windows::ApplicationModel::Core::CoreApplication::Exit를 호출한 경우에도 해당됐습니다.
Microsoft Game Development Kit (GDK)를 사용하면 PostQuitMessage를 통해 클래식 Win32 데스크톱 앱처럼 깔끔한 종료를 달성할 수 있습니다. 이로 인해 메시지 루프가 종료되고 정상적인 코드 정리 및 프로세스 해제가 발생합니다. 이는 그렇지 않으면 찾기 어려운 누수 및 기타 정리 문제를 감지하는 데 개발에 유용합니다. 그러나 이 동작은 이전 XBOX One Software Development Kit 플랫폼에서 실행되지 않는 코드 경로를 호출할 가능성이 큽니다.
메모리 관리
메모리 관리에 대한 자세한 내용은 Memory Overview를 참조하세요.메모리 모델의 변경
Microsoft Game Development Kit (GDK) 플랫폼에는 원래 XBOX One Game OS에서 메모리 모델에 많은 변경 사항이 포함되어 있습니다. 이러한 노력의 대부분은 타이틀에서 사용하는 메모리와 시스템에서 사용하는 메모리 간의 격리를 개선하는 데 소비되었습니다. 격리를 개선하면 타이틀과 시스템 전반에 걸쳐 메모리 사용을 더 예측 가능하게 만들고 시스템 호출로 인한 예상치 못한 사용을 방지할 수 있습니다. 이 작업의 일환으로 Windows 메모리 관리 서브시스템의 최신 버전으로 이동하고 있습니다. 많은 게임에서 큰 변경이 필요하지는 않겠지만 이러한 메모리 API의 사용을 주의 깊게 조사해야 합니다. 플래그의 의미와 동작이 변경되었습니다. 물리 페이지를 수동으로 할당하고 매핑하는 경우, 매핑에 대한 몇 가지 제약이 변경되었으며 API에 대해 다른 패턴을 따라야 함을 명심하세요.- 물리 페이지가 가상 주소 공간에 두 번 이상 매핑되면 모든 할당은 동일한 캐시 일관성 설정을 공유해야 합니다. 예를 들어 동일한 물리 메모리에 Write Combined 및 일반 CPU Read/Write 페이지 설정을 혼합할 수 없습니다.
- 페이지 설정 및 캐시 일관성 값은 이제 페이지가 매핑되는 가상 주소 영역에 있습니다. 이 영역은 XMemVirtualAlloc을 호출하고
MEM_RESERVE패턴을 사용하여 미리 예약해야 합니다. 이 단계는 이전 버전의 OS에서는 필요하지 않았습니다.
MEM_LARGE_PAGES 상수를 사용한 위치를 파악하도록 유의하세요. 그 값과 의미는 Windows 전반에서 사용되는 의미와 일치하도록 변경되었습니다.
XBOX One Game OS의 4 MB에서 XBOX의 Microsoft Game Development Kit (GDK) OS의 2 MB로 대형 페이지가 변경됨에 따라 XMemAlloc 크기 지정자도 대형 페이지에 대해
XALLOC_PAGESIZE_4MB에서 XALLOC_PAGESIZE_2MB로 변경되었습니다.
메모리 맵도 변경되었으며 더 이상 Legacy, Title, Graphics, Physical 영역으로 분할되지 않습니다. 이제 전체 8-TB 주소 공간을 포괄합니다.
API 변경
Microsoft Game Development Kit (GDK) 메모리 API는 XMem 접두사로 시작하며 대부분 동작이 변경되었더라도 기존 XBOX One XDK OS에 이미 있는 API를 반영합니다.
새로운 API는 다음 표에 나와 있습니다.
VirtualAlloc 대신 XMemVirtualAlloc 사용
Microsoft Game Development Kit (GDK)에서 새로운XMemVirtualAlloc API는 XBOX 그래픽 메모리 할당에 대한 VirtualAlloc의 모든 사용을 대체합니다. 나중에 물리적 매핑으로 뒷받침되는 예약에 대해 GPU 페이지 및 캐시 일관성 요구 사항을 지정하기 위한 이전 요구 사항을 참고하세요.
XBOX One Software Development Kit에서 그러한 예약의 비교:
VirtualFree 사용
VirtualAlloc 또는 XMemVirtualAlloc으로 할당된 메모리는 여전히 VirtualFree로 해제됩니다. XMemVirtualFree API는 없습니다.
XMemAlloc 사용법
Attributes 매크로에는 이제 추가 매개변수가 있습니다. 예를 들어:XMemAllocatePhysicalPages 및 XMemMapPhysicalPages
페이지 플래그와 캐시 일관성을 예약 시간으로 이동함에 따라 물리 메모리를 할당하고 매핑하는 호출이 단순화되었지만 그 외에는 XBOX One Software Development Kit와 유사합니다.XMemAllocatePhysicalPages는 AllocateTitlePhysicalPages를 대체합니다. XMemMapPhysicalPages는 MapTitlePhysicalPages를 대체합니다.
이 XBOX One Software Development Kit 코드:
프로그래밍 모델
프로그래밍 모델에 대한 자세한 내용은 Asynchronous Programming Model 항목을 참조하세요.GameRuntime을 사용한 동기(블로킹) 코드
블로킹이 합리적인 옵션인 API의 경우, 호출이 오래 실행되더라도 모든 라이브러리 기능의 블로킹(동기) 버전이 제공되었습니다. 개발자는 스레드를 생성하고 스케줄러를 사용하여 동시성을 관리하며 해당 스레드에서 블로킹 함수를 호출할 수 있으며, 이는 종종 C++11 스타일 futures 및 promises보다 구현하기 더 쉽습니다. 함수의 런타임이 비결정적으로 알려진 경우(예: 네트워크 호출)가 있으므로 비동기 버전만 제공됩니다.GameRuntime을 사용한 비동기 코드
Microsoft Game Development Kit (GDK) 플랫폼에는 비동기 작업을 수행하고 콜백을 통해 결과를 보고하는 새로운 모델이 포함되어 있습니다. 이 모델은 Windows Runtime을 대체합니다. GameRuntime API를 사용하여 비동기 작업 및 콜백이 어떻게 그리고 어디에서 발생하는지 지정합니다. 다음 샘플 코드에는 Game Runtime Task Queue가 시스템 호출을 처리하도록 설정되는 방식의 간단한 정형화된 예제가 포함되어 있습니다. 이 큐는 시스템 작업을 처리하는 데 그리고 콜백이 실행되는 위치로 사용할 수 있습니다. 개념적으로 콜백은 시스템 작업에 대한 응답으로 여러분의 코드를 실행하는 작업입니다. 필요한 경우 여러 Task Queue를 만들어 다른 코어에서의 작업을 관리하거나 호출별로 콜백을 실행하는 큐를 지정할 수 있습니다. 큐잉된 작업 항목의 디스패치는 여러분의 코드에 의해 수동으로 펌핑되거나(이는 Windows 메시지 큐와 유사) 자동으로 펌핑될 수 있습니다. 다음은 수동으로 펌핑되는 큐가 생성된 다음 펌핑되는 방식의 간단한 예제입니다.비동기 API 호출의 일반적인 이름 지정 패턴
다음 표는 Microsoft Game Development Kit (GDK) 및 Game Runtime에서 비동기 호출의 이름을 지정하는 데 사용되는 일반적인 패턴을 보여줍니다.XAsyncBlock은 IAsyncOperation과 IAsyncAction을 대체함
비동기 함수를 호출할 때 완료되거나 취소되거나 실패할 때까지 호출 기간 동안 계속 살아있어야 하는XAsyncBlock 구조를 만듭니다.
XAsyncBlock 유형에는 즉각 관련된 세 가지 매개변수가 포함되어 있습니다.
사용 예제:
XAsyncBlock 구조체를 만들 때 ‘zero-fill’하는 것이 중요합니다. 따라서()대신{}를 사용합니다.
시간에 민감한 작업
Microsoft Game Development Kit (GDK) 라이브러리를 사용하면 호출하는 스레드가 시간에 민감한지 여부를 지정할 수 있습니다. 시간에 민감하지 않은 함수를 시간에 민감한 스레드에서 호출하면 런타임 경고가 보고될 수 있습니다.SetTimeSensitiveThread(true)를 호출합니다. 자체 코드의 오래 실행되는 함수 내에서 VerifyNotTimeSensitiveThread()를 호출하여 시간 위기 스레드에서 부적절한 사용을 보고할 수도 있습니다.
HLSL 셰이더
XBOX One Software Development Kit 플랫폼은 Shader Model 5.1 프로그래머블 셰이더를 ATI 마이크로코드로 사전 컴파일하는 것을 지원하는FXC.EXE HLSL 컴파일러의 사용자 지정 버전을 사용했습니다. 또한 Shader Model 6용 DXC.EXE DXIL 컴파일러에 대한 미리 보기가 지원되었습니다.
XBOX의 Microsoft Game Development Kit (GDK)의 경우 DXC.EXE를 통한 DXIL 컴파일러 및 Shader Model 6 사용이 권장됩니다. FXC.EXE Shader Model 5.1 컴파일러는 이제 레거시로 간주됩니다. 새 컴파일러는 이전 컴파일러가 지원하는 대부분의 명령줄 플래그를 지원하지만 일부 XBOX 전용 확장 defines는 적용되지 않거나 지원되지 않습니다. Shader Model 6 및 DXIL에 대한 자세한 내용은 GitHub 프로젝트를 참조하세요.
PC에서 Shader Model 6 사용: Windows 10 Creators Update 이상 버전은 많은 소매 드라이버와 마찬가지로 Shader Model 6.x DXIL 셰이더를 지원합니다. 이 기능에 대해 Windows Update WHQL 드라이버에 의존하는 대신 공급업체에서 직접 최신 드라이버를 설치해야 합니다. Windows용
DXC.EXE 컴파일러는 Windows 10 April 2018 Update SDK 이상 버전에 포함되어 있습니다. 런타임에는 D3D12_FEATURE_SHADER_MODEL을 사용하여 CheckFeatureSupport를 통해 PC가 Shader Model 6.x를 지원하는지 확인할 수 있지만 함수를 호출하기 전에 shaderModel.HighestShaderModel을 반드시 초기화해야 합니다!%GameDKLatest%\GXDK\bin\XboxOne\DXC.exe.
XBOX Series X|S 버전의 DXIL 컴파일러는 여기에 있습니다: %GameDKLatest%\GXDK\bin\Scarlett\DXC.exe.
D3DCompile API
Shader Model 6의 경우d3dcompiler_x.lib가 아닌 dxcompiler_x.lib 또는 dxcompiler_xs.lib 라이브러리를 사용해야 합니다.
사용자 관리
Microsoft Game Development Kit (GDK)의 사용자 모델은 XBOX One Software Development Kit에서 익숙했던 것과 다릅니다. 이는 부분적으로 사용자의 개인 정보 보호 기대치를 더 잘 관리하고 타이틀이 신경 쓰지 않아야 할 사용자에 대해 시스템이 백그라운드에서 하는 일을 항상 추적하는 부담을 줄이기 위함입니다. 타이틀이 어떤 사용자와 게스트가 콘솔에 로그인했는지에 대한 시스템 전체 컬렉션을 모니터링하는 대신, 시스템은 요청 시에만 사용자를 노출합니다. 타이틀에 대해 사용자를 획득하려면(예: 사용자가 게임 세션을 시작하기 위해 컨트롤러의 A 버튼을 누르고 컨트롤러가 아직 사용자와 연결되지 않은 경우), XUserAddAsync를 호출합니다. 이 호출은 두 가지 중요한 작업을 수행합니다. 사용자를 타이틀에 로그인시키고 사용자 입력 디바이스 페어링을 업데이트합니다. 사용자는 한 번에 임의의 수의 입력 디바이스를 페어링할 수 있습니다. 그러나 타이틀은 XUserAddAsync로 로그인한 사용자에 대한 연결만 인식합니다. 시스템 가이드가 사용자를 로그인시키거나 타이틀이 인식하지 못하는 사용자로 타이틀 외부에서 연결을 변경하는 데 사용되는 경우, 타이틀은 입력 디바이스의 페어링이 해제되었다는 것만 통보받습니다. 그러나 타이틀 외부의 시스템은 여전히 시스템 사용을 위해 페어링을 알고 있습니다. 타이틀은XUserChangeEvent를 구독하여 사용자의 상태 또는 사용자의 관련 정보(예: 게이머태그, 게이머 사진, 권한)의 변경을 모니터링할 수 있습니다(사용자 로그인 상태와 같은 이 정보의 일부는 폴링으로 모니터링할 수 있음). XUserRegisterForChangeEvent를 호출하여 이를 수행합니다.
대부분의 타이틀은 자체 사용자 컬렉션을 구축하고, 사용자가 타이틀에 로그인할 때 추적하고, 입력 디바이스 연결을 추적하고, 사용자가 로그아웃할 때 처리해야 할 것으로 예상해야 합니다.
이러한 변경에 대한 자세한 논의는 Users and input devices를 참조하세요. 또한 UserManagement 샘플도 참조하세요.
네트워킹 및 XBOX 서비스 통합
네트워킹 전송
XBOX의 Microsoft Game Development Kit (GDK)는 WinSock2와 CNG를 통한 BCrypt를 모두 지원합니다. UDP를 사용하는 경우, 멀티플레이어 소켓 바인딩을 위해 3074와 같은 포트를 하드 코딩하는 대신 Microsoft Game Development Kit (GDK)의 경우 다음 새 flat C API를 사용해야 합니다.Windows.Networking.Connectivity 네임스페이스가 아닌 IPHelper를 사용합니다. 샘플 코드는 Network Initialization & Connectivity를 참조하세요.
Secure Sockets(
Windows.Xbox.Networking 네임스페이스)는 Microsoft Game Development Kit (GDK)에서 제거되었습니다.HTTP를 통한 웹 요청
Microsoft Game Development Kit (GDK)는 더 이상IXMLHTTPRequest2 또는 MessageWebSocket / StreamWebSocket(Windows.Networking.Sockets 네임스페이스)를 지원하지 않습니다. 대신 WinHTTP를 사용해야 합니다.
자세한 내용은 Web Requests를 참조하세요.
XBOX 서비스 API
현재 XSAPI의 Windows Runtime 또는 C++ 버전을 사용하는 개발자는 XBOX 서비스 통합 기능에 대해 flat C 버전 사용으로 이동해야 합니다.- Achievements
- Presence
- Profile
- Social
- Social Manager
다음 단계
ERA에서의 초기 이식을 완료한 후 XBOX의 Microsoft Game Development Kit (GDK)에 대해 여러 기능을 사용할 수 있는 훌륭한 위치에 있게 됩니다. 타이틀이 XBOX One S / XBOX One X 하드웨어에서 잘 실행되는 경우 이는 XBOX Series X|S 콘솔에서 경험을 개선하는 쉬운 방법입니다. 이러한 기능 중 다수는 레거시 ERA 타이틀에 대해 자동으로 활성화되지만 XBOX의 Microsoft Game Development Kit (GDK) 타이틀에 대해서는 옵트인해야 합니다. 이제 타이틀이 네이티브 XBOX용 Microsoft Game Development Kit (GDK)이므로 반드시 활성화하세요!- AutoHDR: 이 기능은 SDR 타이틀을 시스템 수준에서 HDR로 자동 변환하여 HDR10 지원 디스플레이에서 재생될 때 게임의 시각적 품질을 향상시킵니다. XBOX Series X|S 전용 하드웨어를 사용하므로 추가 CPU, GPU, 메모리, 대역폭 또는 지연 시간이 없습니다. 시각적 향상은 원래의 예술적 의도를 변경하지 않으며 밝기를 최대 1000 nits까지, 색상을 P3-D65 색 공간까지 확장합니다. 완전한 예술적 통제를 허용하는 네이티브 HDR 구현은 항상 더 좋지만, 네이티브 HDR을 구현할 리소스나 시간이 없다면 AutoHDR은 향상된 경험을 달성하는 쉽고 효과적인 방법입니다.
- Aniso Boost: XBOX Series X|S 콘솔의 이미지 품질 개선은 선형 텍스처 필터링을 완전한 이방성 필터링으로 승격함으로써 달성됩니다. 이는 기존 게임 타이틀에 추가 GPU 파워를 적용하는 빠르고 쉬운 방법입니다. XBOX의 Microsoft Game Development Kit (GDK) 타이틀로서 XBOX Series X|S에서 실행할 때 샘플러 상태에 대해
D3D12_FILTER_MIN_MAG_MIP_LINEAR대신D3D12_FILTER_ANISOTROPIC설정을 사용하여 이를 달성합니다.
- FPS Boost: 또 다른 간단한 개선은 XBOX Series X|S 콘솔의 렌더 프레임 속도를 높이는 것입니다. 타이틀이 XBOX One S / XBOX One X에서 30 fps(
D3D12XBOX_FRAME_INTERVAL_30_HZ)로 실행되는 경우 일반적으로 XBOX Series X|S에서 60 fps(D3D12XBOX_FRAME_INTERVAL_60_HZ)로 실행할 수 있습니다. XBOX One S/X에서 60 fps로 실행된다면 XBOX Series X|S에서 120 fps로 실행될 수 있습니다. 자세한 내용은 120Hz Support와 Simple120Hz 샘플을 참조하세요.
프레임 속도 향상 외에도, XBOX One S / XBOX Series S에서 1080p로 실행할 수 있는 동일한 성능으로 XBOX One X와 XBOX Series X에서 4K로 렌더링할 수 있습니다.
- Quick Resume: 타이틀이 프로세스 수명 관리(PLM)를 제대로 구현하는 한 이 기능은 대부분 자동입니다. 자세한 내용은 XBOX Game Life Cycle을 참조하세요.
팁 및 요령
Microsoft Game Config 패키징 파일
Microsoft Game Development Kit (GDK)는 더 이상 Visual Studio 빌드 도구 체인 중에Package.appxmanifest 파일을 사용하여 AppxManifest.xml을 생성하지 않습니다. 대신 MicrosoftGameConfig 파일이 개발 시간에 모든 앱 패키지 설정을 저장하는 데 사용됩니다.
Executable Name 요소는 패키지 레이아웃의 EXE 이름과 일치해야 합니다.
Visual Studio를 사용하여 새 프로젝트를 만들 수 있습니다. File, New Project를 선택한 다음 Microsoft Game Development Kit (GDK)에서 Direct3D 12 XBOX Game 템플릿을 선택합니다. 그런 다음 템플릿으로 만든 MicrosoftGame.config를 프로젝트에 추가할 수 있습니다.
옵션으로, <ShellVisuals> 섹션을 추가하여 패키지에 있어야 하는 다양한 UI 및 Store 관련 자산을 추가할 수 있습니다.
XBOX One Software Development Kit에는 WideLogo 요소가 있었는데, 이는 이제 Square480x480Logo 속성으로 참조됩니다.
XBOX 서비스 통합의 경우 Title ID도 제공해야 합니다.
.config 파일로 전송할 수 있습니다. 허용되는 옵션의 전체 정의는 MicrosoftGameConfig file을 참조하세요.
디바이스 유형 가져오기
XBOX One Software Development Kit의 GetConsoleType 메서드는 Microsoft Game Development Kit (GDK)에서 사용할 수 없습니다. 대신 GameRuntime API XSystemGetDeviceType을 사용하세요.xdk.h 및 _XDK_VER에 대한 GDK 대체
XBOX One Software Development Kit에서 xdk.h 헤더는 XDK 빌드 번호, QFE 레벨 등과 관련된 여러 빌드 심볼을 제공했습니다.
Gaming.*.x64 플랫폼의 경우 grdk.h를 사용할 수 있습니다.
_GRDK_VER는 바이너리를 빌드하는 데 사용된 Gaming GDK의 버전 인코딩입니다(HIWORD.LOWORD). 예를 들어0x4A610479는 빌드 번호 19041.1145입니다.- 이 빌드의
_GRDK_VER_STRING은 “April 2020 GRDK”입니다. _GRDK_VER_STRING_W는_GRDK_VER_STRING과 동등한 UTF16-LE 와이드 문자열입니다.- 해당 빌드의
_GRDK_VER_STRING_COMPACT_W는 “April 2020”을 포함하는 UTF16-LE 와이드 문자열입니다.
Gaming.Xbox.*.x64 플랫폼의 경우 gxdk.h도 사용할 수 있습니다.
_GXDK_VER는 바이너리를 빌드하는 데 사용된 Gaming GDK의 버전 인코딩입니다(HIWORD.LOWORD). 예를 들어0x4A610479는 빌드 번호 19041.1145입니다.- 이 빌드의
_GXDK_VER_STRING은 “April 2020 GXDK”입니다. _GXDK_VER_STRING_W는_GXDK_VER_STRING과 동등한 UTF16-LE 와이드 문자열입니다.- 해당 빌드의
_GXDK_VER_STRING_COMPACT_W는 “April 2020”을 포함하는 UTF16-LE 와이드 문자열입니다.
기본 오디오 렌더링 엔드포인트 ID 가져오기
Windows Runtime API Windows.Media.Devices 및 Windows.Devices.Enumeration은 XBOX의 Microsoft Game Development Kit (GDK)에서 사용되지 않습니다. 기본 렌더러를 얻으려면 다음 코드를 사용하세요.MapVirtualKey
MapVirtualKey 및 MapVirtualKeyEx 메서드는 XBOX의 Microsoft Game Development Kit (GDK)에서 지원되지 않습니다. 가장 일반적으로 키보드를 처리하는 코드에서 왼쪽 및 오른쪽 VK_SHIFT 키를 감지하는 데 사용됩니다.
MultiByteToWideChar 및 WideCharToMultiByte
와이드 문자 문자열(UTF-16 LE)과 좁은 문자 문자열 간의 변환 시 Win32 개발자는 종종 MultiByteToWideChar 및 WideCharToMultiByte를 사용합니다. 최신 코드베이스의 경우 특정 코드 페이지 또는CP_ACP 대신 CP_UTF8을 사용하는 것이 좋습니다.
다음 코드는 Windows 7 Service Pack 1 이상에서 작동합니다.
CP_ACP는 CP_UTF8의 별칭으로 취급됩니다. 최신 Windows 10 및 Microsoft Game Development Kit (GDK)에서는 찾기 및 바꾸기를 사용하여 CP_ACP의 모든 인스턴스를 CP_UTF8로 교체할 수 있습니다. 이러한 종류의 이식을 단순화하기 위해 다른 CP_UTF8 관련 매개변수의 유효성 검사가 제거되었습니다.
C++11은 문자열 변환 문제에 대한 더 이식 가능한 솔루션으로 <codecvt> 헤더를 추가했지만, 이는 이미 C++17에서 사용 중단되었습니다. 권장 사항은 플랫폼 문자열 함수를 계속 사용하는 것입니다.
지역화 및 세계화 API
ERA에서는 단순한 코드 페이지 선택, 코드 포인트 변환(multibyte에서 widechar로의 변환), 시스템/사용자 로케일 보고를 넘어선 지역화에 대한 대부분의 기본 제공 Windows 지원이 누락되었습니다. Microsoft Game Development Kit (GDK)의 경우 이 지역화 기능이 완전히 지원되며,GetCurrencyFormatEx, GetNumberFormatEx, 날짜 및 시간 형식 열거 및 기타 기능도 지원됩니다.
XMA2 오디오 노트
SHAPE_XMA_INPUT_BUFFER_ALIGNMENT의 정의가 누락된 경우 shapexmacontext.h 헤더에 대한 참조를 명시적으로 추가해야 합니다.
UI 메시지 상자 지원
타이틀 내에서 크래시와 초기 초기화 실패의 디버깅을 개선하는 데 도움을 주기 위해XGameUiShowMessageDialogAsync가 title-callable UI (TCUI) API 컬렉션에 추가되었습니다. 이 API는 XGameRuntimeInitialize가 호출된 후 D3D 초기화 전에도 언제든 사용할 수 있습니다. API는 시스템 파티션 내에서 렌더링되고 게임의 출력 위에 합성됩니다. 게임 루프가 중단되었거나 아직 렌더링되지 않은 경우에도 여전히 작동합니다. 이는 크래싱 오류 정보를 보고하거나 오류 지점에서 블로킹하는 동안 디버거 attach를 위해 프롬프트할 수 있어 매우 유용할 수 있습니다. 주로 개발 시간 진단 도구로 사용됩니다.
이 예제는 조사를 위해 개발자에게 attach를 요청하는 블로킹 스타일 오류 대화 상자를 보여줍니다.
확장 라이브러리
Windows Runtime API를 사용하는 XBOX One Software Development Kit에서 XSAPI 또는 Game Chat과 같은 확장 라이브러리를 추가하려면 Visual Studio의 ‘References…’ 대화 상자를 사용해야 했습니다. Microsoft Game Development Kit (GDK)의 경우 이 메커니즘은 더 이상 사용되지 않습니다. 대신 Visual Studio 프로젝트 속성을 통해 추가할 수 있습니다. 이는vcxproj의 Globals 섹션에서 속성 요소를 편집합니다.
바이너리 호환성 및 컴포넌트 재사용
Microsoft Game Development Kit (GDK)의 지침 원칙 중 하나는 데스크톱 Windows와 XBOX 콘솔 타이틀 간에 작업을 재사용할 수 있는 개발자의 능력을 최대화하는 것입니다. 이전에 논의되지 않은 한 가지 측면은 데스크톱 Windows와 XBOX의 Microsoft Game Development Kit (GDK) OS 간의 바이너리 호환성을 개선하기 위한 작업이 수행되었다는 것입니다. XBOX One Software Development Kit 타이틀과 달리, XBOX의 Microsoft Game Development Kit (GDK)는 원래 x64 데스크톱 Windows용으로 빌드된 다양한 컴포넌트를 재사용할 수 있습니다. 이는 프로토타이핑, 도구 또는 성능이 중요하지 않은 기타 시나리오에 시간을 절약하는 귀중한 기능이 될 수 있습니다. Microsoft Game Development Kit (GDK)에는 데스크톱 Windows 컴포넌트를 재사용할 수 있는지 여부를 확인하는 도구가 없지만, 해당 컴포넌트에서 사용하는 운영 체제 API에 의해 결정됩니다. XBOX의 Microsoft Game Development Kit (GDK) OS의 지원되는 API는 Microsoft Game Development Kit (GDK)에 포함된 lib에서dumpbin.exe /exports를 실행하여 얻을 수 있습니다. 일부 영역별 API는 자체 lib(예: d3d12_x.lib 또는 d3d12_xs.lib 내의 D3D12XboxCreateDevice)에 있지만, 대부분의 레거시 Win32 API는 xgameplatform.lib이라는 단일 라이브러리에 집계되어 있습니다. Visual Studio Developer Command Prompt에서 실행할 때 다음 명령은 지원되는 Win32 API의 주요 풀(다른 import lib에 있는 API 제외)을 보여줍니다.
dumpbin.exe /exports "c:\Program Files (x86)\Microsoft GDK\build_number\GXDK\gameKit\lib\amd64\xgameplatform.lib"
위의 예제 경로에서 _build_number_는 시스템에 설치된 빌드를 나타냅니다(예: 190700).
코딩 스타일 및 모범 사례
Code Generation for XBOX One - Best Practices (XBOX Developer Downloads->XBOX One->All XBOX One XDK CHMs)의 지침은 Microsoft Game Development Kit (GDK)에 적용됩니다. 컴파일러 설정의 주요 차이는 이러한 프로젝트가 대부분의 게임 API가 Win32 또는 DirectX 스타일 COM으로 스타일링되어 있기 때문에 C++/CX(/ZW) 또는 C++/WinRT 사용이 필요하지 않다는 것입니다. 다음은 몇 가지 일반 권장 사항입니다.
- C++14와, 선택적으로 C++17 언어 준수를 활용하세요. Microsoft Game Development Kit (GDK)의 API 디자인은 C++11 이상의 컴파일러를 가정합니다.
- x64 네이티브, 부동 소수점 코드를 생성하는 프로세스는 항상 SSE/SSE2를 사용합니다. XBOX One은 F16C뿐 아니라
/arch:AVX도 지원합니다. - C++ Exception Handling(
/EHsc)은 x64 네이티브 코드에서 거의 오버헤드가 없습니다. 그러나 런타임에 예외 던지기는 성능 시나리오가 아니므로 흐름을 제어하는 데 사용해서는 안 됩니다. - Objects Own Resources (RAII) 및 Resource Acquisition Is Initialization에 설명된 것과 같은 예외 안전 코딩 기법의 사용은
std::unique_ptr,Microsoft::WRL::ComPtr및 기타 스마트 포인터 클래스를 사용하여 강력히 권장되는 모범 사례입니다. size_t,ptrdiff_t,int8_t,uint8_t,int16_t,uint16_t,int32_t,uint32_t,int64_t,uint64_t,intptr_t,uintptr_t와 같은 표준 이식 가능한 유형을 우선적으로 사용하세요.- 내부 패딩을 최소화하려면 포인터를 구조체와 클래스로 그룹화하세요.
- 레거시 C 스타일 캐스팅 대신
const_cast<>,static_cast<>,reinterpret_cast<>,dynamic_cast<>와 같은 C++ 캐스트를 우선적으로 사용하세요. - 가능한 경우 인트린식을 사용하세요. x64 네이티브 코드는 인라인 어셈블리를 지원하지 않습니다.
컴파일러 및 링커 스위치
다음 스위치를 사용하세요.- 일반 최적화용
/O1 /Oi및 핫 모듈용/O2 /fp:fast- XBOX One 계열 디바이스용
/arch:AVX; XBOX Series X|S용/arch:AVX2. /favor:AMD- Whole Program Optimization 및 Profile-guided Optimization
/OPT:REF,ICF링커 스위치
/Ox는 /O2와 거의 동일하지만 /GF(Eliminate Duplicate Strings)와 /Gy(Enable Function-Level Linking)가 모두 누락되었습니다. /Ox보다 /O2를 우선적으로 사용하세요. /Ox를 사용하는 경우 링커 최적화를 활성화하는 데 중요한 최소한 /Gy를 명시적으로 활성화해야 합니다.
XBOX One Software Development Kit 출시 이후 Visual C++에 여러 새로운 컴파일러 스위치가 추가되었으므로 반드시 읽어보세요: /Zc:inline, /Zc:throwingNew, /Zc:__cplusplus, /volatile:iso, /permissive-, /Zc:twoPhase-, /Debug:FASTLINK.
조건부 코드
경로가 분기되는 조건부 코드의 경우 다음 규칙을 명심하세요.
코드베이스가 이미 XBOX One Software Development Kit를 지원하는 경우 시작하기에 좋은 곳은 다음과 같습니다.
- 코드베이스에서
_XBOX_ONE의 모든 인스턴스를 검색합니다. - DirectX 12.X 확장을 사용하는 코드에서
#if defined(_XBOX_ONE) && defined(_TITLE)과 같은 인스턴스를 다음과 같이 변경합니다:
#if (defined(_XBOX_ONE) && defined(_TITLE)) || defined(_GAMING_XBOX)
모든 곳에서 UTF-8
Windows 플랫폼의 오랜 역사에서 원래 ANSI 함수는 오래전부터 사용 중단되었으며 CreateFileA가 아닌 CreateFileW라고도 알려진 와이드 문자 유니코드 솔루션을 선호합니다. 이는 무수히 많은 다른 코드 페이지를 다루는 문제를 해결하고 모든 지역화 가능한 문자열을wchar_t*(UTF-16 LE, little endian)로 단순화했습니다. UTF-8 Everywhere manifesto는 char*를 사용한 UTF-8 멀티바이트 인코딩이 메모리 풋프린트와 이식성 측면에서 더 나은 솔루션이라고 주장합니다.
XBOX의 Microsoft Game Development Kit (GDK) 플랫폼의 경우 기본 코드 페이지가 CP_UTF8로 설정되어 있으므로 Win32 플랫폼 API의 ANSI 버전은 모두 UTF-8을 사용합니다. UTF-16 LE와 함께 와이드 문자 API를 계속 사용할 수 있지만 UTF-8을 사용하는 옵션도 있습니다.
Windows용 완전한 UTF-8 지원은 매우 최근에 추가된 것이므로 아직 널리 사용되지 않습니다. 현재로서는 사용자가 옵트인해야 하는 것이기도 하므로, 이식성을 위해서는 Win32 API의 저수준 사용을 와이드 문자 API로 유지하는 것이 최선의 옵션일 수 있습니다.
- API에서 UTF-8 사용을 우선시하고 Win32 와이드 문자 API를 호출할 때만 UTF-16 LE로 변환합니다.
std::wstring및wchar_t*대신std::string및char*를 UTF-8로 사용합니다. - 좁은 문자열 리터럴의 경우 접두사 없이 또는
L대신 C++ 접두사u8을 사용하여 UTF-8 준수를 보장합니다. - 안전 조치로 존재하는
UNICODE및_UNICODE빌드 전처리기defines(Visual Studio에서는<CharSet>속성)를 유지하되, 매크로에 의존하지 말고 항상 명시적으로W()또는A()버전을 호출합니다. TCHAR,TEXT(),LPTSTR및 기타 레거시 텍스트 유형 및 매크로를 피합니다. 자세한 내용은 Microsoft Game Development Kit (GDK)의 UTF-8 지원을 참조하세요.
이름 지정 규칙: 성능 및 동작 힌트
XBOX의 Microsoft Game Development Kit (GDK) 플랫폼용 API는 함수 이름이 호출되는 함수의 성능에 대한 암묵적 진술을 하도록 설계되었습니다. 이름에Get 또는 Set 구문이 포함된 함수는 오버헤드가 낮고 예측 가능할 것으로 예상됩니다. 또한 결과를 복사하기 위한 memcpy 작업과 함께 C++ 속성 래퍼 함수 대신 호출된 것과 대략 동일한 수준의 성능을 가질 것으로 예상됩니다. 함수가 Get이 아닌 Query를 사용한다면 이는 완료될 때까지 블로킹할 수 있는 오래 실행되는 작업임을 의미합니다.
간단한 쿼리가 아닌 계산을 수행하는 함수의 경우, 문서에 달리 명시되어 있지 않은 한 성능은 입력 매개변수와 수행하는 작업 유형을 검사한 후 예상하는 것과 대략 같다고 일반적으로 가정합니다.
이름이 Async로 끝나는 함수는 비동기 작업이며 완료하는 데 매우 오래 걸리거나 불확정한 시간이 걸릴 수 있습니다. 대부분의 경우 실행하는 데 오래 걸릴 수 있는 함수의 블로킹 및 비동기 버전을 제공합니다. 코드베이스에 어떤 종류가 가장 잘 작동하는지 결정할 수 있습니다. 어떤 경우(예: 네트워크 API)에는 하나를 제공하는 것이 의미가 없기 때문에 블로킹 버전을 완전히 생략할 수 있습니다.
함수 이름이 Show로 시작하고 Async로 끝나는 경우, 이 함수는 UI 어포던스를 표시하며 반환하려면 일반적으로 사용자의 상호 작용이 필요합니다. 어떤 경우에는 시스템이 UI 작업을 취소할 수 있습니다.
참고 항목
- What is the Microsoft Game Development Kit?
- Getting started with the Microsoft Game Development Kit (GDK)
