Updating your Xbox One title to take advantage of Xbox One X

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 an 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.

Getting Started

Compatibility

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 Project Scorpio white paper) will run with full access to the new hardware capabilities. This document focuses on building those Xbox One X capability-aware titles.

Requirements

Before starting, you must have:

The latest Xbox One X-capable XDK from the Xbox Game Developer (XGD) site. These start with June 2017 XDKs.
If your title plans to go beyond 1080p video resolution, Xbox One S development kits to test 4K rendering.

Baseline and testing

Keep a baseline 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.

Detecting Xbox One X hardware

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 structure containing the GPU frequency, GPU CU count and D3D12XBOX_HARDWARE_VERSION enumeration.

Note: Both Xbox One X Dev Kit Modes (40CU & 44CU) return CONSOLE_TYPE::CONSOLE_TYPE_XBOX_ONE_X_DEVKIT from the GetConsoleType API. You can determine how many CUs are available to your title using the GetGpuHardwareConfigurationX method.

XG library

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.

Step 1. Move your title to the new XDK

Your first task is to install an 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.

Memory

Xbox One X-aware titles have access to more RAM than Xbox One titles do. By default titles will get access to 8GB of memory, configurable via a manifest setting to enable up to 9GB of title addressable memory. For more information see Configuring Title Memory on Xbox One X.

Shaders

Except for specific cases, only a shader ABI version change will require the title to rebuild shaders.

Shader ABI versions

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:

An XDK from February 2016 or later, no changes are required.
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

Xbox One X-specific shaders are required only if one or more of the following is true:

The title has an 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.

Step 2. Enable 4K rendering (optional)

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 2160. If the title uses multiple display planes above 1080p (for UI and gameplay), they’ll need to be composited manually before presenting as a single swapchain buffer/display plane.

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.

Step 3. Run on Xbox One X hardware

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.

1. ESRAM

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 an 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.

2. Texture tiling

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.

3. Memory alignment

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.

4. CMASK/HTILE

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.

5. Other breaking changes

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.

Summary

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.