By: Advanced Technology Group
Updated: April 28, 2017
Porting from Windows 8.1 Store apps
Porting from Xbox One ADK apps
Porting from Xbox One XDK apps
Porting from Windows desktop applications
The Universal Windows Platform (UWP) introduced with Windows 10 is designed to work across PCs, tablets, phones, Xbox One, and other devices. While similar to the Windows 8.1 Store development model, the UWP provides a more expansive API surface that more closely matches Xbox One development and modern Windows desktop APIs. This white paper covers the new development model, and highlights key differences for planning and executing a port to Windows 10 from existing Xbox One apps and titles, Windows 8 Store apps, and Windows desktop apps.
UWP allows you to target the entire Windows 10 ecosystem of devices with a single set of sources running on PCs, Xbox One, tablets, phones, and other device families (such as HoloLens). This application model is an evolution of the universal Windows apps for Windows 8.1 and Windows Phone 8.1. Windows apps and games are built for the UWP by using a consistent set of APIs, and are deployed in an AppX package containing per-architecture binaries and optional per-device family assets. For developers already targeting Xbox One, many of these properties should be familiar and already well understood.
In this paper, we will explore various aspects of planning a port to the new Universal Windows Platform app development model, as well as other things to consider for such a project.
A UWP app runs on a Windows 10 device making use of isolated per-user storage and process lifetime management (PLM), with an ICoreWindow presentation and swap chain similar to Xbox One apps and Windows 8 Store apps today.
One of the defining characteristics of the Universal Windows Platform is the list of APIs exposed for development. UWP apps use a consistent set of APIs across all Windows 10 devices, and can perform runtime feature detection for device-family-specific extension APIs as well.
Table 1: Comparison of API surface between Xbox and Windows development kits.
| API | Xbox One XDK | Xbox One ADK | UWP app |
|---|---|---|---|
| Standard C++11 Library / STL | ✓ | ✓ | ✓ |
| Windows Runtime Library (WRL) | ✓ | ✓ | ✓ |
| C++ AMP | ✓ | ✓ | ✓ |
| OpenMP | ✓ | ✓ | ✓ |
| Parallel Patterns Library (PPL) | ✓ | ✓ | ✓ |
| Direct3D | 11.1 11.x 12.x |
11.1 | 11.0 - 11.4 12.0 |
| Direct2D DirectWrite |
✓ | ✓ | |
| XAML | ✓ | ✓ | |
| D3DCompile | ✓ | ✓ | ✓ |
| DirectXMath | ✓ | ✓ | ✓ |
| XAudio2 | ✓ + XMA | ✓ | ✓ |
| WASAPI | ✓ | ✓ | ✓ |
| Windows Imaging Component (WIC) | ✓ | ✓ | ✓ |
| Windows Media Foundation | ✓ | ✓ | ✓ |
| CreateThread* Get/SetThreadPriority ExitThread GetExitCodeThread SetThreadIdealPrcoessorExSleep(Ex) SuspendThread SwitchToThread ResumeThreadTlsAlloc TlsFree TlsGet/SetValueCoC |
✓ | ✓ | ✓ |
| CreateProcess | ✓ | ✓ | ✗ |
| Windows 7 Thread Pools | ✓ | ✓ | |
| HeapAlloc HeapReAlloc HeapFree HeapSize HeapCreate HeapDestroy HeapCompact HeapSetInformation |
✓ | ✓ | ✓ |
| VirtualAlloc APIs | ✓ | ✓ | ✓ |
| WinSock 2.x* (IP agnostic) | ✓ | ✓ | ✓ |
| QueryPerformanceCounter QueryPerformanceFrequency GetTickCount64** |
✓ | ✓ | ✓ |
| BCrypt | ✓ | ✓ |
*These APIs were originally not available for Windows 8 Store apps, but were added for Windows 8.1 Store apps as of Visual Studio 2013 Update 4. They were already supported by Xbox One and Windows Phone 8 apps.
** GetTickCount has known roll-over issues, so all uses of this API should be replaced with GetTickCount64 on all platforms.
The WINAPI_FAMILY for Universal Windows Platform apps is set to WINAPI_FAMILY_APP, but contains a significant number of APIs beyond those in the original Windows 8 Store app partition. Therefore, porting to this new partition should require far less churn than previous attempts to target Windows Store might have induced in your existing codebases. A number of older APIs are automatically remapped at compile time so that more existing code should build with the Windows 10 SDK.
Table 2: List of APIs automatically remapped at compile time for Windows 10 SDK compatibility.
| Supported | Not supported (remapped by header) |
|---|---|
| CoCreateInstanceFromApp | CoCreateInstance CoCreateInstanceEx |
| CreateFileMappingFromApp OpenFileMappingFromApp |
CreateFileMapping OpenFileMapping |
| MapViewOfFileFromApp | MapViewOfFile MapViewOfFileEx |
| VirtualAllocFromApp VirtualProtectFromApp |
VirtualAlloc VirtualProtect |
Note With Window 10, you can make use of “execute” permissions for virtual memory pages if your application requests the required capability (codeGeneration).
There are some API cases that are supported for Xbox One apps that are not supported for the Universal Windows Platform, but do have replacements.
Table 3: Key differences between Xbox One and the Windows 10 SDK.
| Supported | Not Supported |
|---|---|
| CopyFile2 | CopyFile CopyFileEx |
| LoadPackagedLibrary Note that paths are relative from the AppX root |
LoadLibrary |
| GetSystemCpuSetInformation SetProcessDefaultCpuSets SetThreadSelectedCpuSets |
SetThreadAffinityMask |
| Windows.Gaming.Input | XInput* Windows.Xbox.Input |
| Microsoft.Xbox.Services Multiplayer 2015 APIs (WinRT and C++)* |
Multiplayer 2014 APIs |
| Connected Storage, Secure Sockets, etc. | Windows.Xbox |
*An adapter library (xinputuap.lib) is available that allows Windows 8 Store apps that use XInput and are ported to Windows 10 to continue to work “as is,” but ideally they should be updated to use Windows.Gaming.Input’s IGamePad.
As with Xbox One apps and Windows 8 Store apps, you cannot make use of Microsoft Foundation Classes (MFC), Active Template Library (ATL), Direct3D 9, DirectSound, DirectShow, or GDI in Universal Windows Platform apps. Win32 resources and registry functions are also not available.
Development of Universal Windows Platform apps is done with Visual Studio 2017 using the Windows 10 Creators Update SDK (15063). This new compiler toolset includes a number of new features and improved C++11 / C99 conformance.
When compiling source code with the Visual Studio 2017 toolset, you might encounter some new warnings or errors that need to be resolved if you previously used a compiler older than Visual Studio 2015 Update 3.
Table 4: Common Visual Studio warnings and errors when migrating code from older compilers.
| Warning/Error | Notes |
|---|---|
| C4473 | not enough arguments passed for format string |
| C4474 | too many arguments passed for format string |
| C4475 | length modifier ‘X’ cannot be used with type field character ‘Y’ in format specifier |
| C4476 | unknown type field character ‘X’ in format specifier |
| C4477 | format string ‘%X’ requires an argument of type ‘T1’, but variadic argument |
| C4478 | positional and non-positional placeholders cannot be mixed in the same format string |
| C4775 | nonstandard extension used in format string ‘%X’ |
| C4776 | ‘%X’ is not allowed in format string of function ‘printf_s’ |
| C4778 | unterminated format string ‘%X’ These warnings are the result of validation of the printf format strings vs. the passed parameters. Prior versions of Visual Studio only validated these format strings when using Static Code Analysis (/analyze). These warnings should be fixed. An example of the kind of code that generates this warning: printf(“%s %d %u\n”, “Hello”, 2 ); See Format Specifiers Checking (Visual C++ Team Blog). |
| C2082 | redefinition of formal parameter ‘X’ |
| C4456 | declaration of ‘X’ hides previous local declaration |
| C4457 | declaration of ‘X’ hides function parameter |
| C4458 | declaration of ‘X’ hides class member |
| C4459 | declaration of ‘X’ hides global declaration These warnings highlight places where variables are “shadowed” by another variable in the same scope with the same name. Ideally you should change one of the variable names, but you could also suppress these warnings. An example of the kind of code that generates these warnings: struct { int x; void Set( int x) { this->x = x; } } |
| C4838 | conversion from ‘X’ to ‘Y’ requires a narrowing conversion C++11 conformance requires warnings in cases that didn’t generate warnings in older versions of Visual Studio. The fix is to change the target type, using a type-specifier, or adding a cast. An example of code that generates the warning: int foo[ ] = { 0xA59D10D4 }; |
| C2632 | ‘X’ followed by ‘char16_t’ is illegal |
| C2632 | ‘X’ followed by ‘char32_t’ is illegal In Visual Studio 2015/2017, char16_t and char32_t are supported and are built-in keywords. If the codebase has a typedef for these types or an item with that name, you will get one of these errors. The fix is to remove the typedef and use the built-in type, or to rename the item. An example of code that generates this error: typedef short char16_t; |
| C2137 | empty character constant Empty character constants are not supported by C/C++; however, older Visual C++ compilers would treat L’’ as the null character. You must use L’\0’ instead. L”” remains a valid empty wide-character string. An example of code that generates this error: L ‘ ‘ |
| C2338 | The C++ Standard forbids containers of const elements because allocator<const T> is ill-formed. In older versions of Visual Studio, std::vector<const X> and std::set<const X> would compile despite the fact that containers must have copyable types. With Visual Studio 2015/2017, these will fail to compile. The fix is to remove the const. |
| C3688 | invalid literal suffix ‘X’; literal operator or literal operator template “operator ‘X’” not found With Visual Studio 2015/2017 support for the C++11 user-defined literal language construct, some string concatenation scenarios that previously compiled will now break with this error. The fix is simply to add whitespace between the strings. An example of code that generates this warning: L”Hello”L”World” |
| LNK2019 | unresolved external symbol “X” referenced in function Y Visual Studio 2015/2017 uses the /Zc:inline semantics by default for C++11 conformance. This means that any function declared inline must have the body in the compilation unit if it is called. Non-conforming code will result in this link error. The fix is to either remove the inline keyword from the function declaration, or to ensure the body of the function is included in the compilation unit. |
| C2280 | private virtual base classes and indirect inheritance |
| C2323 | ‘operator new’: non-member operator new or delete functions may not be declared static or in a namespace other than the global namespace |
| C2228 | left of ‘.operator type’ must have class/struct/union |
| C2668 | ‘X’: ambiguous call to overloaded function |
| C3406 | ‘typename’ cannot be used in an elaborated type specifier These warnings were introduced with Visual Studio 2015 Update 1. See MSDN for details. |
For more information about the new complier, see these blog posts:
Note that with Visual Studio 2015/2017, the “Win32” configuration is now called “x86.”
If your source is a working Windows 8.1 Store app, you can upgrade to a Universal Windows Platform app. The WINAPI_FAMILY_APP partition has been expanded with many more APIs. While there will be some in-place upgrade support for universal Windows app (Windows 8.1) projects, you might find that creating a new solution based on the new Windows 10 template is more effective.
Consider the following:
Windows 8.1 Store apps already support touch, mouse, and keyboard. To run on Xbox One as a UWP app, they also need support for game controller input. Any existing use of XInput can be upgraded to IGamePad, or you can utilize the XInput adapter (although this loses access to some features of the controller).
If you are already building x86, x64, and ARM configurations for your Windows 8.1 Store app, you should be in good shape for shipping. For Xbox One and Windows 10 desktop, both x86 and x64 are supported. For Windows 10 mobile, you will need x86 and ARM.
Starting from an Xbox One ADK (Application Development Kit) app should be a straight-forward port, although there are APIs in the WINAPI_FAMILY_TV_APP partition that are not present in WINAPI_FAMILY_APP. This will require creating a new solution by using the Windows 10 project template and building the project.
Note For Xbox One with the Windows 10 update, the existing Xbox One ADK apps (aka WINAPI_FAMILY_TV_APP) model is being retired in favor of Universal Windows Platform apps.
Consider the following:
The Xbox One ADK app already uses game controller input, so it needs to be upgraded to use the latest version of IGamePad in Windows.Gaming.Input. Support for pointer (unified touch and mouse) and keyboard input will need to be added to support desktop and mobile users.
The Xbox One ADK app is already building as an x64 native application, which might be sufficient for both Xbox One and Windows 10 desktop. To support Windows 10 mobile and low-end PCs, you will need an x86 and ARM binary as well.
Xbox One ADK apps use Feature Level 10.0 (no DirectCompute), which would be fine for most Windows 10 desktop systems and of course Xbox One, but you will need at least Feature Level 9.3 support for the broad set of Windows 10 mobile devices.
For Xbox One, the Full display is 1920 x 1080, Fill display is 1440 x 1080, and Snap display is 480 x 1080. For UWP apps, the application will need to handle arbitrary display sizes.
Moving a codebase from Xbox One XDK (Xbox Development Kit) apps to Universal Windows Platform apps can be a significant amount of work, depending on exactly the scope of API use and Xbox One specific optimization. The WINAPI_FAMILY_TV_TITLE has many APIs not in WINAPI_FAMILY_APP that need to be mitigated, although this should be much easier than it was with WINAPI_FAMILY_APP (Windows 8.x). This will require creating a new solution by using the Windows 10 project template and building the projects.
Note Xbox One XDK titles continue to use WINAPI_FAMILY_TV_TITLE and run “as is” on the Xbox One platform. You will want both a UWP app and Xbox One XDK title build for such a product to get maximum API and hardware support on the Xbox One platform.
Consider the following:
The Xbox One XDK app already uses game controller input, so it needs to be upgraded to use the latest version of IGamePad in Windows.Gaming.Input. Support for pointer (unified touch and mouse) and keyboard input will need to be added to support desktop and mobile users.
The Xbox One XDK app is already building as an x64 native application, which might be sufficient for both Xbox One and Windows 10 desktop. To support Windows 10 mobile and low-end PCs, you will need an x86 and ARM binary as well.
Xbox One XDK apps can make use of Direct3D 11.X and 12.X Xbox One extensions, which are not available for UWP apps. This means that the UWP app version has to use linear, untiled textures; shaders need to be compiled with the Windows version of FXC; and you will need to broaden the set of Feature Level support beyond just 11.1.
For Xbox One, the Full display is 1920 x 1080, Fill display is 1440 x 1080, and Snap display is 480 x 1080. For UWP apps, the application will need to handle arbitrary display sizes.
Xbox One XDK apps can make use of the XMA format, which is not available for UWP apps. Instead, you will need to use PCM, ADPCM, or xWMA.
Xbox One XDK apps can use multiple processes that are not supported for UWP apps. Multithreading is encouraged, but you will need to use CPU sets rather than hard affinity.
The new UWP apps version will need to (re)introduce performance and feature scaling behavior because you can no longer rely on fixed memory size, processing core count, or GPU.
Note Developers familiar with building Windows Store app packages may know that the current limit in Windows 8.1 is 8 GB per app, far below the potential size for games. This was increased to over 50 GB in Windows 10.
If starting from a Windows desktop application, the amount of work to port to Universal Windows Platform apps could be quite significant and require extensive code changes. Much of the basic work is the same as bringing a Windows desktop application to the Xbox One platform in the first place.
Consider the following:
You can use only Direct3D 11.0 – 11.3 or 12.0. You can’t use Direct3D 9 or earlier, or OpenGL—see the ANGLE project for OpenGL ES 2.0 support.
You will need to purge deprecated APIs from the codebase.
You must remove all use of the legacy DirectX SDK, particularly D3DX9, D3DX10, D3DX11, and XACT (see Where is the DirectX SDK 2015 Edition?).
You must eliminate all usage of Win32 resources (such as FindResource and LoadString).
You must remove registry usage.
You must delay load DLLs rather than using explicit linking to system DLLs with LoadLibrary. For application-specific DLLs, you can make use of LoadPackagedLibrary.
You must replace the Win32-based window and swapchain with an ICoreWindow and swapchain.
You must handle arbitrary window sizes and aspect ratios. UWP apps cannot change the display mode.
You must implement the application lifetime model, startup, and process lifetime management (PLM) interactions.
You will need to update the input model for touch and game controllers; existing mouse input processing can be updated to use the unified pointer for touch support (see Developing mouse controls (DirectX and C++) on MSDN).
UWP apps must be DPI-aware, and most information is provided in ‘device independent pixels’ rather than true pixel locations.
You will need to rewrite the Win32-based user interface code. You can make use of the DirectX / XAML application model for complex UI support.
You must convert to using AppX packaging and deployment.
You must restrict system calls to APIs in the WINAPI_FAMILY_APP partition rather than the WINAPI_FAMILY_DESKTOP_APP partition. The WINAPI_FAMILY_APP partition has been expanded greatly in Windows 10, with many ANSI and non-ex versions of APIs reintroduced, and the header fix-ups for *FromApp APIs should remove code churn from the process.
When writing Xbox One applications, developers could focus on the x64 native development model, which is what the vast majority of consumer Windows 10 desktop computers will run as well. To get Windows 10 mobile devices and low-end PCs, binaries for x86 (32-bit) and ARM (32-bit) are also required.
Table 5: Nomenclature for processor architectures supported by platform.
| Processor | Platform | Instructions |
|---|---|---|
| x86 (32-bit) | Windows 10 desktop Windows 10 mobile |
SSE, SSE2, NX, PAE |
| x64 (64-bit) | Windows 10 desktop Xbox One |
SSE, SSE2, NX, PAE CMPXCHG16B PREFETCHW LAHF/SAHF |
| ARM (32-bit) | Windows 10 mobile | Thumb-2 VFPv3 ARM-NEON Little-endian |
To build code for all of these architectures, you should follow the recommendations in the Dual-use Coding Techniques for Games article on MSDN for using portable types, grouping pointers, using C++ style-casts, exception-safe coding practices, and conditional compilation guards.
Note For Windows 10, _WIN32_WINNT is set to 0x0A00 (_WIN32_WINNT_WIN10).
For the modern DirectX 11 and 12 APIs, the primary hardware feature scaling is the Direct3D feature level. The range of feature levels depends on the device family in use.
Table 6: Direct3D feature levels by platform.
| Platform | Feature Level |
|---|---|
| Windows 10 mobile | Feature Level 9.3, 11.x |
| Xbox One apps | Feature Level 10.0 (no DirectCompute) This is the same as the existing Xbox One ADK feature level support. |
| Xbox One XDK | Feature Level 11.1 / 12.0 |
| Windows 10 desktop | Feature Level 10.0 – 12.1 While there might be some older computers and low-end PCs with 9.1 – 9.3 Feature Levels, these are likely to be business machines. |
For more information about the history and meaning of feature levels, see Direct3D Feature Levels on MSDN.
When planning a port to the Universal Windows Platform, a key consideration is existing middleware and third-party dependencies on your application.
All middleware and third-party libraries need to be built by using the Visual Studio 2015 toolset. DLLs and static libraries all have to use the latest Visual C/C++ Runtime.
Executable binaries (exe/dll) files need to be built with the /APPCONTAINER linker flag.
All middleware and third-party libraries need to pass the new version of the Windows Application Certification Kit (WACK) tool for API usage. This means building against the Windows 10 SDK by using the updated WINAPI_FAMILY_APP partition and _WIN32_WINNT set to 0x0A00.
Note Dependencies that are not part of your title’s package must be enumerated in the manifest as PackageDependencies. Such dependencies must be manually deployed on test machines if not already present.
In addition to using debugging support in Visual Studio 2015 for Universal Windows Platform apps, you should make use of the following tools:
PowerShell commands add-appxpackage, remove-appxpackage, get-appxpackage
Debugging Tools for Windows (optional feature in the Windows SDK), in particular plmdebug.exe and gflags.exe
The overview of differences outlined in this white paper should enable you to estimate the time required to port to Windows 10 from your existing codebase, as well as provide support for your migration to the latest compiler toolset (Visual Studio 2017) by using the Windows 10 SDK (Windows 10 Creators Update SDK). For more information, see the following resources and be sure to visit the “Windows 10” section of the developer forums for more help, answers, and news.
Building Apps for Windows 10 with Visual Studio 2015
Developing for Windows 10 with Visual C++ 2015
Visual Studio 2015 and Graphics Tools for Windows 10
Developing Games for Windows 10
Designing Games for a Windows Core World
Better Power, Better Performance: Your Game on DirectX12
Advanced DirectX12 Graphics and Performance
Developing with Xbox Live for Windows 10
Xbox Live Multiplayer: Introducing services for cross-platform matchmaking and gameplay
Fast and Effective Introduction to the Universal Windows Platform (UWP)
Code Generation for Xbox One: Best Practices (GDNP Xbox One)
64-bit programming for Game Developers (MSDN)
Lessons on development of 64-bit C/C++ applications (Intel)
Universal Windows Platform app samples (GitHub)
Xbox ATG samples (GitHub)
DirectX Tool Kit for DirectX 11 (GitHub)
DirectX Tool Kit for DirectX 12 (GitHub)
| Date | Updates |
|---|---|
| April 2017 | Updated for Visual Studio 2017 and the Windows 10 Creators Update SDK (15063) |
| August 2016 | Updated for Visual Studio 2015 Update 3 and the Windows 10 Anniversary Update SDK (14393) |
| October 2015 | Updates to Tables 1 and 3; more resources |
| July 2015 | Updates to Table 4 |
| April 2015 | Original release |