Updated: November 2, 2017
Step 1. Move your title to the new XDK
Step 2. Enable 4K rendering (optional)
Step 3. Run on Xbox One X hardware
Xbox One X will be available to consumers in Holiday 2017. The design goals for Xbox One X are to provide enough power for a 4x resolution increase with the smallest amount of code changes.
Xbox One X will run the same OS binaries, title binaries, shader binaries, and other on-disk assets as other members of the Xbox One family. To enable Xbox One X, we recommend that you add support in the following increments:
Move your title to a Xbox One X-capable XDK.
Optionally, enable 4K rendering.
Test on Xbox One X hardware.
Each stage eliminates sources of risk and helps maintain a known state. You can complete the first two phases without Xbox One X hardware.
All Xbox One titles built against existing, approved XDKs are guaranteed by policy to run on Xbox One X hardware without modification by the developer. Titles built with new XDKs from June 2017 XDK previews onward (see The Path to Xbox One X white paper) will run with full access to the new hardware capabilities. This document focuses on building those Xbox One X capability-aware titles.
Before starting, you must have:
The latest Xbox One X-capable XDK from Game Developer Network (GDN). These start with June 1706 XDKs, available in April.
If your title plans to go beyond 1080p video resolution, Xbox One S development kits to test 4K rendering.
Keep a “ground truth” version of your title runnable—that is, a version of the title that runs on Xbox One with the existing XDK. This provides reference for performance and functionality baselines.
In addition, during development, have the entire existing QA process running on Xbox One and Xbox One X throughout the project.
Titles can programmatically detect the version of the Xbox hardware by calling either:
The GetConsoleType() function. This returns a CONSOLE_TYPE enumeration that identifies an Xbox One, Xbox One S, Xbox One X, or Xbox One X XDK device.
The GetGpuHardwareConfigurationX method on the ID3D12Device object. This returns a D3D12XBOX_GPU_HARDWARE_CONFIGURATION structure containing the GPU frequency and D3D12XBOX_HARDWARE_VERSION enumeration.
Xbox One X-aware tiles can require different layouts for certain texture-tiling modes. See Texture tiling later in this document. To help generate correctly swizzled textures:
From October 2016 XDK onward, the XG texture library exposes the XGSetHardwareVersion method to allow an offline tool or title to set either Xbox One mode or Xbox One X mode. Xbox One mode is the default.
The driver automatically sets the XG hardware version upon device creation when running on Xbox One or Xbox One X.
Your first task is to install a Xbox One X-capable XDK and rebuild your title.
This is a mechanical step and will involve changes to reflect API differences.
The age of the title’s current XDK will determine how much effort is required here.
After you verify that the title runs on the new XDK on Xbox One X, any new issues are likely to be hardware or resolution specific.
Xbox One X-aware titles have access to a maximum of 9 GB of RAM. Make sure your title:
Does implement a flexible memory pool, especially for systems like texture streaming.
Does account for larger render-target sizes
Does use TitleMemoryStatus method to query for total memory available.
Does not make hard-coded assumptions about total memory available.
By default, 8 GB are available for titles, but this value can be changed to 9 GB via the mx:TitleMemory setting in the application manifest. Any remainder from the 9 GB is allocated to a system-memory cache, which can boost reads in the game OS. For more information, see Configuring title memory and the system memory cache on Xbox One X.
Except for specific cases, only a shader ABI version change will require the title to rebuild shaders.
A shader ABI version change affects existing titles, and is not related to Xbox One X. The version number is occasionally updated by the driver team when performance or functionality fixes require a change in the driver/shader interface.
The move to Xbox One X has not prompted a version change. As of the June 2017 XDK, the shader microcode version is unchanged since the February 2016 XDK.
If the tile is currently running on:
a. An XDK from February 2016 or later, no changes are required
b. An XDK from before February 2016, a shader version change will take effect, and the title will need to ship new shaders in a content update.
Xbox One X-specific shaders are required only if one or more of the following is true:
The title has a Xbox One X-only shader effect.
The shader has constants with hard-coded assumptions about resolution or filter size. (Such assumptions should be avoided for implementing dynamic resolution anyway.)
The shader directly accesses metadata surfaces like CMASK, HTILE, or FMASK.
The second task, if your plans require it, is to prepare the title for 4K rendering. Depending on your development hardware, you can test the following scenarios.
| Hardware | Scenario |
|---|---|
| Xbox One | 4K output is not supported |
| Xbox One S | 4K non-HDR output, single display plane |
| Xbox One X | 4K HDR output, single display plane |
Note: On Xbox One S and Xbox One X, bandwidth restrictions in the display engine prevent multiple display planes at 4K on both consoles and prevent HDR at 4K on Xbox One S.
If the title already supports multiple resolutions or dynamic resolution, you can extend the back buffer maximum resolution to 3840 x
Note: DXGIX_PRESENTARRAY_PARAMETERS will use logical units of 3840 x 2160 for any buffers with width > 1920 or height > 1080 when calculating ScaleFactorHorz or ScaleFactorVert parameters.
After upsizing the render targets, check the increased memory requirements for the title.
Not all primary render targets may need to be expanded to match 4K. Particle systems and effects, and full-screen lighting, may look acceptable at 1080p.
Conversely, non-primary render targets (like shadow and reflection maps) may need to be increased to match the primary resolution increase.
The final stage is to deploy and run the title on Xbox One X hardware, and fix breaking changes. Most of these can be anticipated, fixed and tested on Xbox One hardware.
Titles can be affected by the following breaking changes when moving to Xbox One X hardware. ESRAM and memory-alignment issues are the most likely to affect a title; other issues are listed here for completeness.
Note: Ideally, your title should not emit any D3D validation errors when running on Xbox One. Any validation messages could indicate undefined behavior on different hardware. If the title emits new validation errors running on Xbox One X, address them immediately.
ESRAM does not exist on Xbox One X hardware. To simulate ESRAM in compatibility mode, older Xbox One titles running on Xbox One X will be passed through to a GPU-only, 32 MB buffer outside the title address space.
For Xbox One X-enabled titles, the ESRAM APIs behave differently from Xbox One APIs in two key ways:
D3D11X_RESOURCE_MISC_ESRAM_RESIDENT flagged resources will fail and generate a validation error.
Calls to D3DMapEsramMemory will fail with E_OUT_OF_MEMORY.
Titles that are Xbox One X-aware should programmatically disable the ESRAM allocation path when they detect a Xbox One X console. Also, if your title performs shuffling of resources in and out of ESRAM, it no longer needs to do so for Xbox One X.
Note: It’s likely that resources that were aliased in ESRAM are now no longer aliased, and this may cause side effects if the title has made assumptions about this memory layout.
Xbox One X has a different memory configuration which causes some texture-tiling layouts to differ. Always use the XG library to compute correct texture layouts and swizzling.
All 1D (for example, XG_TILE_MODE_1D_THIN) microtiled and linear mode surfaces remain the same across Xbox One X and Xbox One. Note that 1D tiling has been the default (and recommended) tiling mode for non-render targets since August 2015.
Any 2D micro- and macro-tiled layouts can be different.
If you are upgrading a title from before the August 2015 XDK, audit your existing textures to ensure that the texture layout matches XGComputeOptimalTileMode running in Xbox One X mode.
The maximum alignment for a resource can be 128 KB on Xbox One X; the maximum alignment on Xbox One was 64 KB. Always use the alignment returned by the XGTextureAddressComputer method.
On Xbox One, the maximum alignment coincided with 64KB page sizes, but on Xbox One X this may no longer be the case. VirtualAlloc and XMemAlloc return 128 KB-aligned addresses only if 4 MB pages are used. Either use 4MB pages or use your own memory managers to handle 128 KB-aligned requests.
Metadata address calculation is different on Xbox One X due to memory-pipe count differences. See the CMask Decode, MiniEngine, and Hi ZDecode samples for more information.
These final breaking changes are rare and won’t affect most titles. For more details about breaking changes, see the “The Xbox Scorpio Graphics hardware In-Depth” presentation from Xfest 2017.
SetGraphicsShaderLimits must be set higher than before to achieve the same effect, because the Xbox One X GPU has more compute units.
If your title has overridden the size for the graphics scratch (GraphicsScratchMemorySizeBytes) or tessellation ring buffers, these buffers will need to be larger for Xbox One X.
If your title has serialized Pipeline State Objects, note that only the main PSO blob has Xbox One X-specific microcode. The Individual shader blobs are platform independent.
You’ll find that moving from Xbox One to Xbox One X can be done in a matter of hours or days. Using a staged approach—updating your XDK, then updating to 4K, and then testing on real hardware—will help you keep your title in a known state and ease the transition further.