Skip to main content

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) プラットフォームで新しいタイトルを開発する場合は、GDK での新しいタイトルの開発を参照してください。

Microsoft Game Development Kit (GDK) について

ゲーム開発パートナーである皆様は、Microsoft のゲーミング チームに対して、当社が上手に行っていることと改善する必要があることについて貴重なフィードバックを提供してくださいました。Microsoft Game Development Kit (GDK) の主要目標は、皆様のフィードバックに直接対応し、次のことを実現できるようにすることです。
  • 今日と同じようにゲームの開発を継続する
  • 現在のコンソールと PC、および将来のコンソールと XBOX Game Streaming のすべての Microsoft ゲーミング取り組みおよびプログラムで、可能な限り多くのコードを容易に共有する
  • 高速で信頼性があり開発者中心の環境を提供する当社の開発ツールとプラットフォームを信頼する
  • 新しいマルチ プラットフォームのサービスと体験を可能な限り迅速かつ簡単に活用する
Microsoft は、皆様が既に使用しているプログラミング パラダイムを使って、皆様が望むあらゆるプラットフォームでゲームを開発する支援をしたいと考えています。Microsoft は、皆様のゲームを今日存在するすべてのゲーミング プラットフォーム、そして現在取り組んでいる将来のゲーマーを喜ばせるすべてのプラットフォームに提供する支援をしたいと考えています。 Microsoft Game Development Kit (GDK) の詳細については、What is the Microsoft Game Development Kit? および Microsoft Game Development Kit (GDK) の入門を参照してください。

目次

この移植ガイドでは、Gaming.Xbox.XboxOne.x64 または Gaming.Xbox.Scarlett.x64 プラットフォームをターゲットにしていることを想定します。Microsoft Game Development Kit (GDK) には Gaming.Desktop.x64 プラットフォームも含まれます。これは標準の x64 Win32 プラットフォームの派生で、本移植ガイドでは扱いません。Gaming.Desktop.x64 の主要な価値は、PC をターゲットとする場合に、ビルド設定、Visual Studio 統合、loose レイアウトの動作などの点で Gaming.Xbox.*.x64 と類似の体験を提供することです。代わりに、「stock」x64 プラットフォームを使用し、PC 向けにすべての設定/パッケージングを直接実装することもできます。

移植プロジェクトの計画

When you port an existing codebase to the Microsoft Game Development Kit (GDK), you typically start from either an existing XBOX One Software Development Kit project or a classic Win32 desktop application. For many developers with an existing XBOX One title, they will find their Durango codebase is a better place to start as long as the use of Windows Runtime APIs is relatively isolated. Classic Win32 desktop codebases are much closer than the Microsoft Game Development Kit (GDK) programming model, but often assume desktop-centric UI and control schemes that have to be modified for the console. Classic Win32 desktop codebases also tend to have a lot of desktop-centric integration, particularly when they’re being used as part of the game’s editing tool suite that utilizes API sets not supported for the Microsoft Game Development Kit (GDK) on Xbox. There are pros and cons to starting with each. In some cases, you may find it easier to pull from both types for different parts of your codebase.

XBOX One Software Development Kit からの移植

If your codebase already supports XBOX One through the XBOX One Software Development Kit (also known as the Durango platform), you’ve already done most of the work of modernizing your application’s API usage. The code should also be well-optimized for the specific constraints of the console, and likely makes significant use of XBOX One-specific extensions as follows.
  • DirectX 12.X is required. If you are already using DirectX 12.X for your XBOX One title, no changes should be needed beyond the presentation API for your Direct3D usage.
If you’re using DirectX 11.X now, upgrade to DirectX 12.X first. This may be easier to do with your existing XBOX One Software Development Kit build before you move to the Microsoft Game Development Kit (GDK). For details, see these topics: Porting from Direct3D 11 to Direct3D 12 and Introduction to Direct3D 12 on XBOX One Xfest talk (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos), and Porting from Direct3D 11 to Direct3D 12 Xfest talk (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos).
  • Instead of using a DXGI swap chain, your presentation logic must use the PresentX API.
  • Some significant changes have been made to the memory subsystem for the Microsoft Game Development Kit (GDK) GDK Game OS. Revisit your memory manager implementation.
  • For controller input, use the new GameInput API rather than Windows.Xbox.Input.
  • Because Windows Runtime APIs are no longer used for most scenarios, replace your existing C++/CX or C++/WinRT code with the new Win32-style or DirectX-style COM APIs.
  • Core Audio functionality is unchanged. However, some API changes may be required as outlined in the audio API comparison. XAudio2 with XMA extensions, WASAPI, and ISpatialAudioClient are supported.
  • When building in Visual Studio, add the Gaming.Xbox.XboxOne.x64 and/or Gaming.Xbox.Scarlett.x64 platform configurations in place of your Durango platform configurations and upgrade to Visual Studio 2019 or Visual Studio 2022.
To assist in adding new platform configurations we have produced a sample called SolutionUpdater. This sample tool takes an existing Visual Studio Solution file and automatically creates the new platform configurations for all associated Project files that are referenced by the Solution, greatly speeding up the process and reducing the possibility for manual errors. For further information please review the document included with the sample.
If your codebase supports the Universal Windows Platform (UWP) app model, you have a similar porting path as from the XBOX One Software Development Kit.

Porting from the classic Win32 desktop

If your codebase supports only the classic Win32 desktop, the porting process could be quite extensive, depending on how recent the codebase is with respect to deprecated APIs and other features. Keep in mind that classic Win32 desktop codebases can have a very large span of APIs that date all the way back to the Windows 9x/ME-era. This list isn’t comprehensive for all the potential issues you might encounter. When targeting XBOX, you’ll also have the usual considerations for porting from PC to console: UI, input models, fixed-resolution display, constrained memory, and so on. For more information, see Coming to XBOX from PC - What You Need to Know.
  • x64 native is required. For more information, see 64-bit programming for Game Developers.
  • DirectX 12.X is required. DirectX 11, Direct3D 10, Direct3D 9 or earlier can’t be used. In addition, OpenGL and Vulkan are not supported. For details, see the porting guides for DirectX11 and DirectX12.
  • Legacy DirectX SDK components D3DX9, D3DX10, D3DX11, and XACT can’t be used. For more information, see Microsoft Docs, Where is the DirectX SDK (2021 Edition)?, Living without D3DX, and The Zombie DirectX SDK.
  • WINAPI_FAMILY_GAMES is a subset of the full Win32 API family. Restrict yourself to those APIs.
  • AppX packaging is required. Update your process for packaging and deployment.
  • For controller input, use the new GameInput API rather than Windows.Gaming.Input or DirectInput.
  • For Audio, use XAudio2, WASAPI, ISpatialAudioClient, or compatible audio middleware.
  • Remove instances of registry usage.
  • Handling of the WndProc messages is to be reduced. Many of the messages, particularly those that deal with windows’ positioning, sizing, and shell integration, don’t apply to the Microsoft Game Development Kit (GDK) on Xbox.
  • If you build with Visual Studio, upgrade your code to work with Visual Studio 2019 or Visual Studio 2022. Otherwise, ensure your build uses the new preprocessor defines and links with libraries in GXDK\gameKit\lib\amd64, such as the xgameplatform.lib umbrella library.
  • For COM components, only the multithreaded apartment (MTA) threading model is supported. Note that COINITBASE_MULTITHREADED is typical for a Direct3D application.
  • Only a single window instance is supported. Multiple concurrent window instances or dialog boxes aren’t supported.

開発環境

Visual Studio 2019 (16.11 update) or Visual Studio 2022 is the development environment supported for the Microsoft Game Development Kit (GDK). Install the following:
  • Workload: Game development with C++ for the core tool set
  • Workload: UWP development for the packaging tools.
  • Workload (optional): desktop development with C++ PC-side tools and samples.
XBOX One Software Development Kit development with Visual Studio 2017 also required the optional component Windows 8.1 SDK and UCRT SDK. This component is not required for the Microsoft Game Development Kit (GDK).
If you’re still using Visual Studio 2015 or earlier, the first step for your porting effort is to upgrade to Visual Studio 2019 or later.

Visual Studio platform

The Microsoft Game Development Kit (GDK) integrates with Visual Studio to provide the Gaming.Xbox.XboxOne.x64 and Gaming.Xbox.Scarlett.x64 platforms for targeting Microsoft GDK Game OS on Xbox. This replaces the XBOX One Software Development Kit Durango platform.

Custom build solutions

For building code outside of Visual Studio, the environment helpers for locations have been changed. XBOX One Software Development Kit:
Microsoft Game Development Kit (GDK):
In the example path above, build_number represents the build installed on your system (e.g. 190700).
There are several locations in the Microsoft Game Development Kit (GDK) that will need to be referenced by custom build systems. %GameDKLatest%\GXDK\gameKit contains all the headers and libs for console-specific extensions, and the main platform umbrella lib for linking a Microsoft Game Development Kit (GDK) binary. %GameDKLatest%\GRDK\gameKit similarly contains the headers and libs for all functionality that isn’t specific to console development. The Microsoft Game Development Kit (GDK) requires the Windows 10 SDK (10.0.19041.0) or later to be installed as a dependency. Some additional headers/libs are available in %GameDKLatest%\GXDK\toolKit for PC-side console tools.
As of the October 2023 release, the Windows 11 SDK (10.0.22000.0) is the minimum supported version.
There are also a number of options and defines you should use. See Visual C++ compiler and linker switch recommendations for all the details, as well as the CMakeExample sample.

Compiler (cl.exe)

  • /D_GAMING_XBOX replaces both /D_XBOX_ONE /D_TITLE and /D_DURANGO.
  • /D_GAMING_XBOX_XBOXONE is defined only for the Gaming.Xbox.XboxOne.x64 platform.
  • /D_GAMING_XBOX_SCARLETT is defined only for the Gaming.Xbox.Scarlett.x64 platform.
  • /DWINAPI_FAMILY=WINAPI_FAMILY_GAMES controls the API partitioning in place of the WINAPI_FAMILY_TV_TITLE API family.
  • You should define /DWIN32_LEAN_AND_MEAN, /D_ATL_NO_DEFAULT_LIBS, and /D__WRL_NO_DEFAULT_LIB__
  • For the Microsoft Game Development Kit (GDK), you no longer use any Windows Runtime switches such as /AI, /FU, or /ZW.
  • Continue to use /favor:AMD64, /EHsc, and /fp:fast.
  • For the Gaming.Xbox.XboxOne.x64 platform continue to use /arch:AVX
  • For the Gaming.Xbox.Scarlett.x64 platform use /arch:AVX2
With VS 2019 Update 3 or later and the Gaming.Xbox.Scarlett.x64 platform, also use /d2vzeroupper. If you are using Whole Program Optimization (WPO) / Link Time Code Generation (LTCG) then it needs to be /d2:-vzeroupper.
With VS 2022 and the Gaming.Xbox.XboxOne.x64 platform, also use /d2vzeroupper-. If you are using Whole Program Optimization (WPO) / Link Time Code Generation (LTCG) then it needs to be /d2:-vzeroupper-.
  • Link against xgameplatform.lib, xgameruntime.lib, d3d12_x.lib or d3d12_xs.lib, xmem.lib, and pixevt.lib. Don’t use kernel32.lib, kernelx.lib, onecore.lib, or WindowsApp.lib.
  • For the XGraphics library use xg_x.lib or xg_xs.lib.
  • You don’t need to use /WINMD or /WINMDFILE, which were for Windows Runtime APIs.
  • The Microsoft Game Development Kit (GDK) on XBOX doesn’t use embedded manifests, so use /MANIFEST:NO.
  • Continue to use /DYNAMICBASE, /NXCOMPAT.
You should consider using /NODEFAULTLIB to ensure you aren’t linking with any unsupported Win32 libraries including 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.

Optimizing Windows header Usage

The Microsoft Game Development Kit (GDK) uses the standard <Windows.h> header. It’s useful to define the various lean and mean preprocessor defines in addition to WIN32_LEAN_AND_MEAN as previously mentioned to keep the overall number of Win32 system headers you pull in under control.

Visual C++ runtime

With the XBOX One Software Development Kit, the Visual C++ Runtime headers and libraries were part of the XBOX One Software Development Kit, with the runtime DLLs placed inside the Game OS. This required updating to a newer XBOX One Software Development Kit release or QFE level to match the minor update version of Visual Studio being used to build the code. With the Microsoft Game Development Kit (GDK), the Visual C++ Runtime DLLs are included as part of your game package and match whatever version of Visual Studio that is installed locally on the build machine.
  • VCRuntime*.dll and msvcp*.dll are the Visual C++ compiler runtime and Standard C++ Library DLLs. There is a ucrtbase.dll included in the Game OS that is also used.
  • For debug builds, your package will contain VCRuntime*d.dll, msvcp*d.dll, and ucrbased.dll
If you make use of the ERA Migration Library, you also need vccorlib*.dll which is used by the compiler when building with /ZW.
AMP is not supported for XBOX, and has been deprecated in the latest Visual C++ release.

アプリケーションの起動

Microsoft Game Development Kit (GDK) projects use a streamlined version of the Win32 desktop-style application startup and message loop, not Windows Runtime-style CoreWindow events. Your existing codebase should have one of the following entry-points.

Win32 desktop development

XBOX One Software Development Kit or UWP app using C++/CX

XBOX One Software Development Kit or UWP app using C++/WinRT

Microsoft Game Development Kit (GDK) on XBOX

For GDK titles, the entry point is the same as the Win32 classic desktop.

アプリケーションの初期化

A typical, very basic Win32 entry point function looks like this.
This pattern is mostly the same for Microsoft Game Development Kit (GDK) titles on XBOX, but we can simplify it somewhat:
  • Minimal use of window class and styles
  • UTF-8 rather than UTF-16LE strings
  • Initialization of the Game Runtime subsystem
For Microsoft Game Development Kit (GDK) titles on XBOX, you can have only one Win32 window.

Windows メッセージング ループ

Because many messages don’t apply, Microsoft Game Development Kit (GDK) applications on XBOX can use a very basic Win32 messaging loop.
The use of a Win32 messaging loop is optional, but it’s a useful place to start if you’re moving from an existing Win32 codebase. The following table shows a list of common Win32 messages found in classic Win32 desktop games, and the application (or lack thereof) of these messages to Microsoft Game Development Kit (GDK) titles on Xbox.

Direct3D デバイスの作成

Games built with the Microsoft Game Development Kit (GDK) on XBOX use the Direct3D 12.X API, which is implemented as the monolithic runtime, just as it’s implemented with the XBOX One Software Development Kit. Stock Direct3D 12 and Direct3D 11 aren’t supported for games built with the Microsoft Game Development Kit (GDK) on Xbox. When you create a Direct3D 12 device for DirectX 12.X, use the D3D12XboxCreateDevice method.
From here, the command queue, command list, and other items will continue to be created as they would with standard Direct3D 12. To support 4k rendering, you simply use a larger swapchain width & height, but you should continue to support 1080p for lower-end consoles. A recommended way to determine when to use 4k vs. 1440p vs. 1080p is as follows:
For more details, see the SimpleDeviceAndSwapChain sample.

XMem* APIs

Any calls to XMem* APIs that use XMEM_GRAPHICS require that the Direct3D device has been created before they are used. Alternatively, you can call D3DConfigureVirtualMemory if you need to use those calls before the Direct3D device exists.

CPU/GPU Reservation

All Microsoft Game Development Kit (GDK) titles get full resources (that is, no Kinect GPU reservation) and the seventh CPU core. By default, you get the equivalent of the following XBOX One Software Development Kit manifest settings.

XBOX One vs. XBOX Series X|S Direct3D Differences

The Direct3D 12.x monolithic runtime implementation for the Gaming.Xbox.XboxOne.x64 platform is almost identical to the XBOX One Software Development Kit implementation of Direct3D 12.x. For your initial port to the Microsoft Game Development Kit (GDK) on XBOX this platform is likely the easiest place to start.
  • Gaming.Xbox.Scarlett.x64 supports up to ID3D12Device8 and ID3D12GraphicsCommandList5 interface or later versions.
  • Gaming.Xbox.XboxOne.x64 supports up to ID3D12Device, ID3D12Device1, ID3D12Device2 and ID3D12GraphicsCommandList.
When moving to the Gaming.Xbox.Scarlett.x64 platform, there are some additional capabilities as well as some differences in the Direct3D 12.x implementation.
  • You need to use a different version of the Direct3D headers and libraries (i.e. d3d12_xs.h, d3dx12_xs.h, xg_xs.h, d3d12_xs.lib, etc.). You cannot mix the two versions of Direct3D 12.x in the same binary.
  • When the Direct3D 12.x monolithic runtime was first implemented, it was built on top of the Direct3D 11.x monolithic runtime, so a number of Direct3D 11 types are defined when building with the Durango or Gaming.Xbox.XboxOne.x64 platforms. These have been removed from the XBOX Series X|S implementation so you may encounter build issues with any lingering references to the d3d11_x.h header, D3D11_* defines, CD3D11_* classes or ID3D11* interfaces. These can be removed and still build for both platforms.
  • ESRAM is not a feature of XBOX Series X|S so extensions related to ESRAM are not defined for this platform. This also means xgmemory.h (a helper for utilizing ESRAM) is only supported for the Gaming.Xbox.XboxOne.x64 platform.
It remains important to utilize ESRAM on XBOX One / XBOX One S devices for optimal rendering performance. See the SimpleESRAM and AdvancedESRAM samples.
  • There are a number of differences in GPU memory layouts, in particular H-tile and C-Mask techniques. For details, see the CMaskDecode, HiZDecode, HiStencil, and PrimeHTile samples.

プレゼンテーション

The Microsoft Game Development Kit (GDK) on XBOX doesn’t support legacy DXGI swap chains for presentation, but it does use the PresentX API. The new PresentX APIs are designed to address latency concerns with DXGI swap chains, and provides the developer more direct control of the presentation buffers. This API is also designed to scale for future streaming applications. The first step in using PresentX is to register for frame events after the Direct3D device is created.
Instead of creating a DXGI swap chain and requesting the back-buffer resources, create them directly with the D3D12_HEAP_FLAG_ALLOW_DISPLAY flag.
At the start of each rendering frame, set a pipeline token first by using WaitFrameEventX.
At the end of the frame, use the same token to call PresentX.
As with XBOX One Software Development Kit titles, Microsoft Game Development Kit (GDK) games on XBOX don’t encounter DXGI_ERROR_DEVICE_REMOVED and DXGI_ERROR_DEVICE_RESET errors, which must be handled for PC games. Some other related DXGI functionality has been removed, and the previously mentioned ScheduleFrameEventX function supersedes DXGIXSetFrameNotification from the XBOX One Software Development Kit. Here’s the XBOX One Software Development Kit code for frame flip notification.
Equivalent code for Microsoft Game Development Kit (GDK) titles on Xbox.
For more details, see Frame scheduling and presentation on XBOX One, and the SimpleDeviceAndSwapChain, HDR10, and SimpleHDR samples.

Process lifetime management (PLM)

Games built with the Microsoft Game Development Kit (GDK) on XBOX use the same basic process lifetime management (PLM) model that’s used by XBOX One XDK apps and UWP apps. Apps run unconstrained, constrained, suspended, or terminated; that is, no code executes for termination, and the process is simply destroyed. XBOX One Software Development Kit apps and UWP apps receive notifications through their Windows Runtime CoreWindow. Microsoft Game Development Kit (GDK) games on XBOX receive notifications through registered callbacks. Note that there is only a suspend and a resume event, and there’s no longer an explicit activation phase. A simple implementation approach is to handle this by posting a WM_USER message.
Subsequently, the message loop would handle the WM_USER message to ensure that the loop is paused until Resume, and that the proper GPU suspend/resume behavior takes place at a safe time in the render loop.
For more details, see the SimplePLM sample.

Constrained vs. full

Notification of constrained versus full resources is handled through a similar API.
Here we use a message for the same reasons as we did previously in the suspend/resume case.
For more details, see the SimplePLM sample.

Process termination

For retail titles, process termination is handled the same as it was for the older XBOX One Software Development Kit platform. The process is suspended and then terminated. None of the C++ destructors or cleanup are processed. This was true if you also called Windows::ApplicationModel::Core::CoreApplication::Exit. With the Microsoft Game Development Kit (GDK), you can achieve a clean exit like you can with classic Win32 desktop apps via PostQuitMessage. This results in your message loop exiting and normal code cleanup and process teardown will take place. This is useful for development to help detect leaks and other cleanup problems that can otherwise be difficult to find. This behavior, however, likely invokes code paths that are never executed in the older XBOX One Software Development Kit platform.

メモリ管理

For more information about memory management, see Memory Overview.

Changes in the memory model

The Microsoft Game Development Kit (GDK) platform includes many changes made to the memory model from the original XBOX One Game OS. Most of this effort has been spent on improving the isolation of memory used by the title from memory used by the system. Improving isolation would make memory usage more predictable across the title and system, and would prevent unexpected usage by system calls. As part of this work, we’re moving to the latest version of the Windows Memory Management subsystem. Although many games won’t require any major changes, you should examine your use of these memory APIs carefully. The meanings and behavior of the flags have changed. If you’re allocating and mapping physical pages manually, keep in mind that some constraints on mappings have changed, and that a different pattern is to be followed for the APIs.
  • When physical pages are mapped into the Virtual Address Space more than once, all allocations must share the same cache coherency settings. For example, you can’t mix and match Write Combined and normal CPU Read/Write page settings on the same physical memory.
  • Page settings and cache coherency values now live in the virtual-address region that the pages are mapped into. This region must be reserved ahead of time by calling XMemVirtualAlloc and using the MEM_RESERVE pattern. This step wasn’t required in the previous version of the OS.
For all allocations that are mapped for access by the GPU, explicit GPU access flags are now required. There is no longer a default based on the CPU protection settings. Take care to identify, anywhere in your codebase, that you’ve used the MEM_LARGE_PAGES constant. Its values and meanings have changed to match the meanings used across Windows. With the change of large pages from 4 MB in the XBOX One Game OS to 2 MB in the Microsoft Game Development Kit (GDK) on XBOX OS, the XMemAlloc size specifiers have also changed for large pages from XALLOC_PAGESIZE_4MB to XALLOC_PAGESIZE_2MB. Our memory map has also changed and is no longer segmented into Legacy, Title, Graphics, and Physical regions. They now cover the entire 8-TB address space.

Changes in APIs

The Microsoft Game Development Kit (GDK) memory APIs begin with the XMem prefix and, for the most part, mirror the APIs already in the existing XBOX One XDK OS, even though their behavior has changed. The new APIs are shown in the following table.

Use XMemVirtualAlloc instead of VirtualAlloc

In the Microsoft Game Development Kit (GDK), the new XMemVirtualAlloc API replaces all uses of VirtualAlloc for allocating XBOX graphics memory. Note the previous requirements for specifying GPU page and cache coherency requirements for reserves later backed by physical mappings. A comparison of such a reservation on XBOX One Software Development Kit:
and Microsoft Game Development Kit (GDK):
Or for an allocation not backed by mapped physical pages and committed at reserve time:
Changes to:

Use VirtualFree

The memory allocated by VirtualAlloc or XMemVirtualAlloc is still freed with VirtualFree. There’s no XMemVirtualFree API.

XMemAlloc usage

The Attributes macro now has an additional parameter. For example:
Changes to:

XMemAllocatePhysicalPages and XMemMapPhysicalPages

With the change of moving page flags and cache coherency to reservation time, the calls for allocating and mapping physical memory are simplified, but otherwise is similar to XBOX One Software Development Kit. XMemAllocatePhysicalPages replaces AllocateTitlePhysicalPages. XMemMapPhysicalPages replaces MapTitlePhysicalPages. This XBOX One Software Development Kit code:
Changes to this for Microsoft Game Development Kit (GDK) titles:

プログラミング モデル

For more information about the programming model, see the Asynchronous Programming Model topic.

Synchronous (blocking) code with GameRuntime

For APIs where blocking is a reasonable option, the blocking (synchronous) versions of all library functionality have been provided, even if the calls would be long-running. The developer can spawn threads and call the blocking functions from those threads by using the scheduler to manage concurrency, which is often simpler to implement than C++11 style futures and promises. There are some cases (such as network calls) where the runtime of the functions is known to be non-deterministic, so only asynchronous versions are provided.

Asynchronous code with GameRuntime

The Microsoft Game Development Kit (GDK) platform includes a new model for performing asynchronous tasks and reporting their results via callbacks. This model replaces Windows Runtime. Use the GameRuntime APIs to specify how and where asynchronous work and callbacks occur. The following sample code includes simple boiler-plate examples of how a Game Runtime Task Queue is set up to process your system calls. This queue can be used to process system tasks and as the location where callbacks are executed. Conceptually, a callback is a task that runs your code in response to system actions. If necessary, you can create multiple Task Queues to manage work on different cores, or to specify the queue that executes callbacks on a call-by-call basis. Dispatching queued work items can be pumped manually by your code (this is similar to a Windows message queue), or pumped automatically. The following are simple examples of how a manually pumped queue is created and then pumped.
For more information, see the SimplePLM sample, which triggers the settings as well as title-callable UI (TCUI) for sign-in using an XTask async queue. For details on the Asynchronous Programming Model, see the Asynchronous Programming Model and Async task queue design topics. See also the AsynchronousProgramming sample.

General naming pattern for asynchronous API calls

The following table shows the general pattern used by the Microsoft Game Development Kit (GDK) and the Game Runtime for naming asynchronous calls.

XAsyncBlock replaces IAsyncOperation and IAsyncAction

When calling an asynchronous function, create an XAsyncBlock structure, which must be kept alive for the duration of the call until it has completed, been canceled, or failed. The XAsyncBlock type contains three parameters of immediate relevance. Example usage:
Note that it is critical that you ‘zero-fill’ the XAsyncBlock structure when you create it, hence the use of {} instead of ().

Time sensitive operations

The Microsoft Game Development Kit (GDK) libraries let you specify whether the thread you’re calling from is time sensitive. Runtime warnings can be reported if you call functions that are not time sensitive from a time sensitive thread.
To mark a thread as time sensitive, call SetTimeSensitiveThread(true) on the thread. You can also call VerifyNotTimeSensitiveThread() from within long-running functions in your own code to report improper usage from time-critical threads.

HLSL シェーダー

The XBOX One Software Development Kit platform used a customized version of the FXC.EXE HLSL compiler that supported precompiling of Shader Model 5.1 programmable shaders to ATI microcode. In addition, preview was supported for the DXC.EXE DXIL compiler for Shader Model 6. For the Microsoft Game Development Kit (GDK) on XBOX, use of the DXIL compiler and Shader Model 6 is recommended via DXC.EXE. The FXC.EXE Shader Model 5.1 compiler is now considered legacy. The new compiler supports most of the command-line flags supported by the old compiler, although some of the Xbox-specific extension defines are not applicable or not supported. For details on Shader Model 6 and DXIL, see the GitHub project.
For PC usage of Shader Model 6: Windows 10 Creators Update and later versions support Shader Model 6.x DXIL shaders, as do many retail drivers. Instead of relying on the Windows Update WHQL drivers for this feature, you need to install the latest driver directly from its vendor. The DXC.EXE compiler for Windows is included in the Windows 10 April 2018 Update SDK and later versions. At runtime, you can determine whether your PC supports Shader Model 6.x via CheckFeatureSupport using D3D12_FEATURE_SHADER_MODEL, but be sure to initialize shaderModel.HighestShaderModel before calling the function!
The XBOX One version of the DXIL compiler is located here: %GameDKLatest%\GXDK\bin\XboxOne\DXC.exe. The XBOX Series X|S version of the DXIL compiler is located here: %GameDKLatest%\GXDK\bin\Scarlett\DXC.exe.

D3DCompile APIs

For Shader Model 6, you should use the dxcompiler_x.lib or dxcompiler_xs.lib library rather than d3dcompiler_x.lib.

User Management

The user model has changed for the Microsoft Game Development Kit (GDK) from what you may be used to in the XBOX One Software Development Kit. This is in part to better manage users’ privacy expectations and to ease the burden of always keeping track of what the system is doing in the background with users that the title shouldn’t care about. Rather than having titles monitor a system-wide collection of which users and guests are signed into the console, the system only exposes users on-demand. To acquire a user for your title (for example, when the user presses the A button on a controller to start a game session, and the controller has not yet been associated with a user), make a call to XUserAddAsync. This call will perform two important actions: it signs users into the title and updates user input device pairing. Users may have any number of input devices paired to them at a time. However, the title is only made aware of associations for users that have been signed in with XUserAddAsync. If the system Guide is used to sign in a user or change associations outside of the title to a user that the title is unaware of, then the title is only told that the input device has been unpaired. The system outside of the title, however, still knows of the pairing for system usage. Titles can monitor changes in a user’s state, or a user’s associated information (such as their Gamertag, Gamer Picture, or Privileges) by subscribing to XUserChangeEvent (although some of this information, such as user sign-in state, could be monitored by polling). You do this by calling XUserRegisterForChangeEvent. Most titles should expect to need to build their own collection of users, track when users become signed in to the title, track input device associations, and handle when users are signed out. For an in-depth discussion of these changes, see Users and input devices. See also the UserManagement sample.

Networking and XBOX services Integration

Networking Transport

The Microsoft Game Development Kit (GDK) on XBOX supports both WinSock2 and BCrypt via CNG. If using UDP, rather than hard-coding a port such as 3074 for your multiplayer socket binding, for the Microsoft Game Development Kit (GDK) you should make use of this new flat C API:
To detect network connectivity with the Microsoft Game Development Kit (GDK), make use of IPHelper rather than the Windows.Networking.Connectivity namespace. For sample code, see Network Initialization & Connectivity.
Secure Sockets (Windows.Xbox.Networking namespace) has been removed for the Microsoft Game Development Kit (GDK).
For more details, see Introduction to WinSock networking.

Web Requests via HTTP

The Microsoft Game Development Kit (GDK) no longer supports IXMLHTTPRequest2 or MessageWebSocket / StreamWebSocket (Windows.Networking.Sockets namespace). Instead you should make use of WinHTTP. For more details, see Web Requests.

XBOX services APIs

Developers currently using the Windows Runtime or C++ versions of XSAPI will need to move to using the flat C version for XBOX services integration features:
  • Achievements
  • Presence
  • Profile
  • Social
  • Social Manager
See Introduction to the XBOX services C APIs and XSAPI reference. If you are making use of Game Chat 2, be aware that a few classes were renamed as shown in the following table.

次のステップ

After completing your initial port from ERA, you will be in a great position to enable a number of features for Microsoft Game Development Kit (GDK) on Xbox. If your title is running well on XBOX One S / XBOX One X hardware, these are easy ways to improve the experience on XBOX Series X|S consoles. Note that many of these features are enabled automatically for legacy ERA titles, but are opt-in for Microsoft Game Development Kit (GDK) on XBOX titles. Now that your title is native Microsoft Game Development Kit (GDK) on XBOX, be sure to enable them!
  • AutoHDR: This feature automatically converts an SDR title to HDR at a system level, enhancing the visual quality of the game when played on an HDR10 capable display. It uses XBOX Series X|S specific hardware so there is no extra CPU, GPU, memory, bandwidth or latency. The visual enhancement doesn’t change the original artistic intent and expands brightness up to 1000 nits and colors into the P3-D65 color space. A native HDR implementation will always be better, allowing full artistic control, but if you don’t have the resources or time to implement native HDR, AutoHDR is an easy and effective way to achieve an enhanced experience.
See High dynamic range (HDR) output and the AutoHDR sample for more details.
  • Aniso Boost: An improvement in image quality on XBOX Series X|S consoles is given by promoting linear texture filtering to full anisotropic filtering. This is a quick & easy way to apply extra GPU power to an existing game title. As a Microsoft Game Development Kit (GDK) on XBOX title, you achieve this by using the D3D12_FILTER_ANISOTROPIC setting for your sampler states instead of D3D12_FILTER_MIN_MAG_MIP_LINEAR when running on XBOX Series X|S:
  • FPS Boost: Another simple improvement is increasing the render framerate on XBOX Series X|S consoles. If your title runs at 30 fps on XBOX One S / XBOX One X (D3D12XBOX_FRAME_INTERVAL_30_HZ), then it can usually run at 60 fps on XBOX Series X|S (D3D12XBOX_FRAME_INTERVAL_60_HZ). If it’s running 60 fps on XBOX One S/X, then it can likely run at 120 fps on XBOX Series X|S. See 120Hz Support and the Simple120Hz sample for more information.
In addition to frame-rate boost, you can likely also render at 4K on XBOX One X and XBOX Series X at the same performance that you can at 1080p on XBOX One S / XBOX Series S.
  • Quick Resume: This feature is automatic for the most part, as long as your title properly implements Process Lifecycle Management (PLM). See XBOX Game Life Cycle for more details.

ヒントとコツ

Microsoft Game Config packaging file

The Microsoft Game Development Kit (GDK) no longer uses a Package.appxmanifest file during the Visual Studio build toolchain to generate AppxManifest.xml. Instead, a MicrosoftGameConfig file is used to house all app package settings at development time.
The Executable Name element must match the name of the EXE in the package layout.
Note you can create a new project by using Visual Studio. Select File, New Project, and then select the Direct3D 12 XBOX Game template from the Microsoft Game Development Kit (GDK). You can then add MicrosoftGame.config that was created by the template to your project.
As an option, you can add the various UI and Store-related assets, which need to be present in the package, by adding a <ShellVisuals> section.
Note that the XBOX One Software Development Kit had a WideLogo element, this is now referenced as the Square480x480Logo attribute.
For XBOX services integration, you also need to provide a Title ID.
As noted above, you no longer need to use manifest elements to get 7th core and extended GPU resource availability, but you can use the manifest to control title memory.
The appxmanifest element above has been replaced by an element which defaults to “Standard” for the title memory control.
Some manifest extensions from the XBOX One Software Development Kit can also be transferred into the .config file. For a full definition of allowable options, see MicrosoftGameConfig file.

Getting the device type

The GetConsoleType method in the XBOX One Software Development Kit isn’t available for the Microsoft Game Development Kit (GDK). Use the GameRuntime API XSystemGetDeviceType instead.

GDK replacement for xdk.h and _XDK_VER

In the XBOX One Software Development Kit, the xdk.h header provided a number of build symbols related to the XDK build number, QFE level, etc. For Gaming.*.x64 platforms, you can make use of grdk.h:
  • _GRDK_VER is the version encoding of the Gaming GDK used to build the binary (HIWORD.LOWORD). For example, 0x4A610479 is build number 19041.1145.
  • _GRDK_VER_STRING for this build is “April 2020 GRDK”.
  • _GRDK_VER_STRING_W UTF16-LE wide string equivalent to _GRDK_VER_STRING.
  • _GRDK_VER_STRING_COMPACT_W for that build is a UTF16-LE wide string containing “April 2020”.
For Gaming.Xbox.*.x64 platforms, you can also make use of gxdk.h:
  • _GXDK_VER is the version encoding of the Gaming GDK used to build the binary (HIWORD.LOWORD). For example, 0x4A610479 is build number 19041.1145.
  • _GXDK_VER_STRING for this build is “April 2020 GXDK”.
  • _GXDK_VER_STRING_W UTF16-LE wide string equivalent to _GXDK_VER_STRING.
  • _GXDK_VER_STRING_COMPACT_W for that build is a UTF16-LE wide string containing “April 2020”.

Getting the default audio rendering endpoint ID

The Windows Runtime APIs Windows.Media.Devices and Windows.Devices.Enumeration aren’t used for the Microsoft Game Development Kit (GDK) on Xbox. To obtain the default renderer, use the following code.

MapVirtualKey

The MapVirtualKey and MapVirtualKeyEx methods aren’t supported for the Microsoft Game Development Kit (GDK) on Xbox. Most commonly, they’re used to detect the left and right VK_SHIFT keys in the code that handles the keyboard.

MultiByteToWideChar and WideCharToMultiByte

When converting between wide-character strings (UTF-16 LE) and narrow-character strings, Win32 developers often use MultiByteToWideChar and WideCharToMultiByte. For modern codebases, we recommend that you use CP_UTF8 instead of a specific code page or CP_ACP. The following code works on Windows 7 Service Pack 1 and later.
Sometimes 437 and 1252 are used directly. 437 isn’t supported for the XBOX One Software Development Kit or for the Microsoft Game Development Kit (GDK) on Xbox. 1252 worked on the XBOX One XDK but isn’t supported for the Microsoft Game Development Kit (GDK) on Xbox. For the Microsoft Game Development Kit (GDK) on XBOX, CP_ACP is treated as an alias for CP_UTF8. On modern Windows 10 and with the Microsoft Game Development Kit (GDK), you can usually replace all instances of CP_ACP with CP_UTF8 by using find and replace. To simplify this kind of porting, the validation of other CP_UTF8-related parameters was removed. C++11 added the <codecvt> header as a more portable solution to the problem of converting strings, but this has already been deprecated in C++17. The recommendation is to stick with platform string functions.

Localization and globalization APIs

In ERA, the majority of built-in Windows support for localization beyond simple code-page selection, codepoint translation (the conversion of multibyte to widechar), and system/user locale reporting was missing. For the Microsoft Game Development Kit (GDK), this localization functionality is fully supported, as are GetCurrencyFormatEx, GetNumberFormatEx, the date and time format enumeration, and other features.

XMA2 audio notes

If you’re missing the definition of SHAPE_XMA_INPUT_BUFFER_ALIGNMENT, you’ll have to explicitly add a reference to the shapexmacontext.h header.
With the XBOX One Software Development Kit, this header was implicitly included by some other audio headers.

UI message box support

To help improve debugging of crashes and early initialization failures within a title, XGameUiShowMessageDialogAsync has been added to the collection of title-callable UI (TCUI) APIs. This API can be used at any point after XGameRuntimeInitialize has been called, even before D3D initialization. The API renders within the system partition and is composited over the game’s output. It still functions even if the game loop is halted or not yet rendering. This can be highly useful for reporting crashing error information, or even for prompting for debugger attach while blocking at the site of the error. It’s intended primarily as a development-time diagnostic tool. This example shows a blocking style error dialog, prompting for the developer to attach for investigation.

Extension libraries

In the XBOX One Software Development Kit with the use of Windows Runtime APIs, adding extension libraries like XSAPI or Game Chat required using the ‘References…’ dialog in Visual Studio. For Microsoft Game Development Kit (GDK) this mechanism is no longer used. Instead these can be added via the Visual Studio project properties. This edits a property element in the Globals section of the vcxproj:
If this element is not present, the default is to include only XSAPI.

バイナリ互換性とコンポーネントの再利用

One of the guiding principles of the Microsoft Game Development Kit (GDK) is maximizing developers’ ability to reuse their work between desktop Windows and XBOX console titles. One aspect of this not previously discussed is that work has been done to improve binary compatibility between desktop Windows and the Microsoft Game Development Kit (GDK) on XBOX OS. Unlike XBOX One Software Development Kit titles, Microsoft Game Development Kit (GDK) on XBOX can reuse a variety of components that were originally built for x64 desktop Windows. This can be a valuable time-saving feature for prototyping, tooling, or other scenarios that aren’t performance-critical. There is no tooling in the Microsoft Game Development Kit (GDK) to determine whether a desktop Windows component can be reused, but it’s determined by the operating system APIs that are consumed by the component in question. The supported APIs of the Microsoft Game Development Kit (GDK) on XBOX OS can be obtained by running dumpbin.exe /exports on the libs that ship with the Microsoft Game Development Kit (GDK). While some area-specific APIs reside in their own libs (such as D3D12XboxCreateDevice within d3d12_x.lib or d3d12_xs.lib), the majority of legacy Win32 APIs are aggregated in a single library named xgameplatform.lib. The following command, when run from a Visual Studio Developer Command Prompt, shows the main pool of supported Win32 APIs (aside from those that reside in another import lib). dumpbin.exe /exports "c:\Program Files (x86)\Microsoft GDK\build_number\GXDK\gameKit\lib\amd64\xgameplatform.lib"
In the example path above, build_number represents the build installed on your system (e.g. 190700).
Static libraries originally built for desktop Windows, which only make use of APIs within the approved list, can generally be linked directly into a Microsoft Game Development Kit (GDK) binary intended for Xbox. However, this isn’t universally true, as behavior differences (such as the single window limitation) may cause runtime failures of the component if it hasn’t been designed to handle such differences. Dynamic-link libraries (DLLs) that have an import list that falls entirely within the supported APIs will also generally load and function as-is. The Microsoft Game Development Kit (GDK) on XBOX OS contains forwarding logic to correctly retarget this set of APIs to their implementation locations if different from desktop Windows. While being able to reuse desktop Windows components on the console can save time in many scenarios, this isn’t advised for performance-critical paths within a shipping title. Most components built with desktop Windows in mind will not have been built with the most optimal flags for execution with the Microsoft Game Development Kit (GDK). Most notably, because desktop components target a broader range of CPUs, those components may have been built without AVX optimizations. Reusing desktop DLLs may also lead to larger overall code size, compared with rebuilding for the Microsoft Game Development Kit (GDK).

コーディング スタイルとベスト プラクティス

The guidance in Code Generation for XBOX One - Best Practices (XBOX Developer Downloads->XBOX One->All XBOX One XDK CHMs) applies to the Microsoft Game Development Kit (GDK). The primary difference in compiler settings is that these projects don’t require the use of C++/CX (/ZW) or C++/WinRT, because most game APIs are styled as Win32 or DirectX-style COM. Here are some general recommendations:
  • Take advantage of C++14 and, optionally, of C++17 language conformance. Note that the API design for the Microsoft Game Development Kit (GDK) assumes a C++11 or better compiler.
  • The process for generating x64-native, floating-point code always uses SSE/SSE2. XBOX One supports /arch:AVX as well as F16C.
  • C++ Exception Handling (/EHsc) has little to no overhead in x64-native code. Throwing of exceptions at runtime, however, isn’t a performance scenario, so it shouldn’t be used to control the flow.
  • The use of exception-safe coding techniques like those described in Objects Own Resources (RAII) and Resource Acquisition Is Initialization is a strongly recommended best practice using std::unique_ptr, Microsoft::WRL::ComPtr, and other smart-pointer classes.
  • Give preference to the use of standard portable types like size_t, ptrdiff_t, int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, and uintptr_t.
  • To minimize internal padding, group pointers into structures and classes.
  • Instead of legacy C-style casting, give preference to C++ casts like const_cast<>, static_cast<>, reinterpret_cast<>, and dynamic_cast<>.
  • Use intrinsics where possible. x64-native code doesn’t support inline assembly.

Compiler and linker switches

Use the following switches:
  • /O1 /Oi for general optimization and /O2 for hot modules
  • /fp:fast
  • /arch:AVX for the XBOX One family of devices; /arch:AVX2 for XBOX Series X|S.
  • /favor:AMD
  • Whole Program Optimization and Profile-guided Optimization
  • /OPT:REF,ICF linker switches
For historical reasons, /Ox is almost the same as /O2 but is missing both /GF (Eliminate Duplicate Strings) and /Gy (Enable Function-Level Linking). Give preference to /O2 over /Ox. If you use /Ox, be sure to explicitly enable at least /Gy, which is important for enabling linker optimization. There have also been a number of new compiler switches added to Visual C++ since the launch of the XBOX One Software Development Kit, so be sure to read up on them: /Zc:inline, /Zc:throwingNew, /Zc:__cplusplus, /volatile:iso, /permissive-, /Zc:twoPhase-, and /Debug:FASTLINK.

Conditional code

For conditional code where paths diverge, keep the following conventions in mind. If your codebase already supports the XBOX One Software Development Kit, a good place to start is to do the following:
  1. Search for all instances of _XBOX_ONE in your codebase
  2. Change instances like #if defined(_XBOX_ONE) && defined(_TITLE) where the code is using DirectX 12.X extensions, and making these cases:
    #if (defined(_XBOX_ONE) && defined(_TITLE)) || defined(_GAMING_XBOX)

UTF-8 everywhere

In the long history of the Windows platform, the original ANSI functions have long been deprecated in favor of the wide-character Unicode solution, also known as CreateFileW rather than CreateFileA. This resolved the problem of dealing with a myriad of different code pages and simplified all localizable strings to wchar_t* (UTF-16 LE, little endian). The UTF-8 Everywhere manifesto makes the case that the UTF-8 multibyte encoding with char* is a better solution in terms of memory footprint and portability. For the Microsoft Game Development Kit (GDK) on XBOX platform, the default code page is set to CP_UTF8, so any ANSI versions of Win32 platform APIs use UTF-8. You can continue to use the wide-character APIs with UTF-16 LE, but you also have the option to use UTF-8.
Full UTF-8 support for Windows is a very recent addition, so it’s not yet widely used. It’s also something that a user has to opt in for at this time, so you might find that keeping your low-level use of Win32 APIs to the wide-character APIs is the best option for portability.
We recommend the following:
  • Give preference to the use of UTF-8 in your APIs, and convert to UTF-16 LE only when calling Win32 wide-character APIs. Instead of using std::wstring and wchar_t*, use std::string and char* as UTF-8.
  • For narrow string literals, ensure adherence to UTF-8 by using the C++ prefix u8 rather than no prefix or L.
  • Keep the UNICODE and _UNICODE build preprocessor defines that are in place (in Visual Studio, this is the <CharSet> property) as a safety measure, but instead of relying on the macros, always explicitly call the W() or A() version.
  • Avoid TCHAR, TEXT(), LPTSTR, and other legacy text types and macros. For more information, see UTF-8 support in the Microsoft Game Development Kit (GDK).

Naming convention: performance and behavioral hints

The APIs for the Microsoft Game Development Kit (GDK) on XBOX platform have been designed for the purpose of having function names make implicit statements about the performance of functions that are called. A function that includes the phrase Get or Set in its name is expected to be low-overhead and predictable. It’s also expected to have roughly the same level of performance as if called in place of a C++ property-wrapper function with any memcpy operation for copying the result. If a function were to use Query rather than Get, this would imply that it’s a long-running operation that might block until it’s completed. For functions that perform calculations rather than simple queries, we usually assume that performance is roughly what you’d expect after inspecting their input parameters and the kinds of operations they perform, unless the documentation states otherwise. A function whose name ends in Async is an asynchronous operation and could take a very long or an indeterminate amount of time to complete. In most cases, we provide blocking and asynchronous versions of functions that can take a long time to execute. We let you decide which variety works best for your codebase. In some cases (as with network APIs), we might omit the blocking version entirely, because providing one would make no sense. If a function’s name begins with Show and ends with Async, the function displays UI affordances and, to return, typically requires interaction from the user. In some cases, the system can cancel UI operations.

関連項目

  • What is the Microsoft Game Development Kit?
  • Getting started with the Microsoft Game Development Kit (GDK)
最終更新日 2026年10月5日