Writing shared code for Windows Store and Win32 desktop apps

(continued from part 1)

Win32 APIs

The majority of the “core” API family are new Windows Runtime (WinRT) style APIs which are not available for down-level Win32 desktop applications. Therefore the overlap is in Win32 APIs that are available to both kinds of applications. In many cases, the Windows Store apps ‘core’ API family contains a Win32 API that is very recent. Therefore, a key technique for writing dual-use code properly is learning to leverage the _WIN32_WINNT control define for Windows Headers.

  • For Windows 8.1 support, _WIN32_WINNT is 0x0603 which is the default with the Windows 8.1 SDK / VS 2013 and is the value you expect to use for Windows Store apps for Windows 8.1 and Windows phone 8.1.

  • For Windows 8.x support, _WIN32_WINNT is 0x0602 which is the default with the Windows 8.0 SDK / VS 2012 and is the value you expect to use for Windows Store apps for Windows 8.0, Windows phone 8.0, and Xbox One.

  • For Windows 7 and Windows 8.x Win32 desktop support, _WIN32_WINNT should be 0x0601.

  • For Windows Vista, Windows 7, and Windows 8.x Win32 desktop support, _WIN32_WINNT should be 0x0600.

  • For Windows XP SP3 or Windows Server 2003 SP2, you must set _WIN32_WINNT to 0x0501 and use a Platform Toolset of "v110_xp" or "v120_xp" which selects the Windows 7.1 SDK that has limited DirectX integration. The Windows 8.x SDK does not support any platform prior to Windows Vista.

Windows 10: For Windows 10 support, _WIN32_WINNT is 0x0A00 which is the default with the Windows 10 SDK / VS 2015 and is the value you expect to use for universal Windows apps.

Note: There are defines for these version constants, but be aware of the mix of Windows SDK versions you are building your code against. For example, _WIN32_WINNT_WIN10 is only defined for Windows 10 SDK, _WIN32_WINNT_WINBLUE is missing from the Windows 8.0 SDK, and _WIN32_WINNT_WIN8 is not in the Windows 7.1 SDK. You can define your own symbol if it is not already defined, but particularly in 'public' headers the direct use of the version numbers is the most robust choice.

Note: For Win32 APIs, you should prefer the use of the standard _WIN32_WINNT control define to conditional compile for Windows Store apps rather than symbol trying to make use of WINAPI_FAMILY macros directly.

For example, for Windows Store apps CreateFile2 must be used which is a Windows 8 only API. For down-level support, you will want to use CreateFile.

 #if (_WIN32_WINNT >= 0x0602 /*_WIN32_WINNT_WIN8*/)

ScopedHandle hFile( safe_handle(
CreateFile2( szFile, GENERIC_READ, FILE_SHARE_READ,
OPEN_EXISTING, nullptr ) ) );

#else

ScopedHandle hFile( safe_handle(
CreateFile( szFile, GENERIC_READ, FILE_SHARE_READ, nullptr,
OPEN_EXISTING, FILE_FLAG_SEQUENTIAL_SCAN, nullptr ) ) );

#endif

if ( !hFile )
{
return HRESULT_FROM_WIN32( GetLastError() );
}

Note: There's one more detail in this particular case. For Windows Store apps, the typical default dwShareMode of 0 is likely to cause problems when you are trying to open a file for read-only access because ‘exclusive’ mode is only granted for files which the app has write privileges. If using a dwDesiredAccess of GENERIC_READ, you want to use dwShareMode of FILE_SHARE_READ as shown here.

Dual-use shared code should always make use of Unicode to support Windows Store apps (UNICODE and _UNICODE are defined) and is fully supported on down-level Win32 desktop apps. Universal use of Unicode and wchar_t is recommended, although TCHAR is still available if legacy ASCII/multi-byte support is required for some Win32 desktop scenario.

Here are a number of Win32 APIs that are available to Windows Store apps when using the latest version.

Older API “Core” Win32 API _WIN32_WINNT Required
GetDiskFreeSpace GetDiskFreeSpaceEx  
GetFileAttributes GetFileAttributesEx  
FindFirstFile FindFirstFileEx  
LockFile LockFileEx  
MoveFile MoveFileEx  
SetFilePointer SetFilePointerEx  
UnlockFile UnlockFileEx  
WaitForMultipleObjects WaitForMultipleObjectsEx  
WaitForSingleObject* WaitForSingleObjectEx  
CreateEvent CreateEventEx 0x0600 (Windows Vista)
CreateMutex* CreateMutexEx 0x0600 (Windows Vista)
CreateSemaphore* CreateSemaphoreEx 0x0600 (Windows Vista)
GetFileSize
GetFileSizeEx*
GetFileInformationByHandleEx 0x0600 (Windows Vista)
GetTickCount
timeGetTime
GetTickCount64 0x0600 (Windows Vista)
InitializeCriticalSection*
InitializeCriticalSectionAndSpinCount*
InitializeCriticalSectionEx 0x0600 (Windows Vista)
CopyFile, CopyFileEx CopyFile2 0x0601 (Windows 7)
CoCreateInstance*
CoCreateInstanceEx*
CoCreateInstanceFromApp 0x0602 (Windows 8)
CreateFile CreateFile2 0x0602 (Windows 8)
CreateFileMapping* CreateFileMappingFromApp 0x0602 (Windows 8)
GetOverlappedResult GetOverlappedResultEx 0x0602 (Windows 8)
MapViewOfFile*
MapViewOfFileEx
MapViewOfFileFromApp 0x0602 (Windows 8)

Windows 10: The APIs denoted by * above were added back for universal Windows apps for Windows 10 to reduce porting changes.

Note: ReadFile and WriteFile are available for Windows Store apps and Windows phone 8, but ReadFileEx and WriteFileEx are not.

Here are some additional notes on Win32 APIs commonly used by games.

Win32 API

Description

CreateThread
SetThreadIdealProcessor
SetThreadPriority
Sleep(Ex)
TlsAlloc

Windows Store apps for Windows 8.0 do not support POSIX-style threading APIs. These applications must use the Windows Runtime (WinRT) ThreadPool API in Windows.System.Threading.

For dual-use coding, you can make use of the C++11 Standard Library threading support and/or the Concurrency Runtime (ConcRT) which is supported for both Windows Store apps and Win32 desktop apps.

Update: Windows Store apps for Windows 8.1 can now use these threading APIs as of VS 2013 Update 4. They are also supported for Windows phone 8.1, Xbox One apps, and universal Windows apps for Windows 10.

CreateProcess
GetCommandLine
GetEnvironmentStrings

Windows Store apps do not support POSIX-style process, command-line or environment variable APIs. These applications must use the Launcher class in the Windows.System namespace.

Note: Xbox One XDK supports some of these Win32 process APIs.

FindResource(Ex)
LoadResource
LockResource

etc.

Windows Store apps do not use Win32 style resource files. The recommendation is to include the required data as part of the AppX package and use standard file I/O to access them.

RegOpenKey(Ex)
RegQueryKey(Ex)
RegSetKey(Ex)

etc.

Windows Store apps do not use the Win32 registry. The recommendation is to store settings data in the application local directory using standard file I/O.

GlobalMemoryStatus(Ex)

There is no Windows Store app function available that will return physical or virtual memory information.

HeapAlloc

This is the standard memory allocation routine family is available for all applications.

LocalAlloc, GlobalAlloc are only available for Win32 desktop applications..

VirtualAlloc is not available for Windows 8.x Store apps or Windows phone 8.x apps.

Note: Xbox One XDK does support VirtualAlloc but does not allow EXECUTE page-level permission.

Windows 10: VirtualAlloc is supported for universal Windows apps for Windows 10 as a remap for the new VirtualAllocFromApp.

LoadLibrary(Ex)

Windows Store apps must use LoadPackagedLibrary and the target DLL must be present in the application package or listed in the AppX manifest. The target DLL must therefore pass the Windows App Certification Kit (WACK) tool validation.

You have to use implicit linking with system DLLs, although you can use /DELAYLOAD if desired.

LoadString

Windows Store apps do not use Win32 style resource files for localization. These applications use ResourceLoader in the Windows.ApplicationModel.Resources namespace. See MSDN for more details.

Dual-use shared code should avoid directly displaying strings and should leave localization to the client application.

GetLogicalProcessorInformation

Windows store apps can't call GLPI. They can use GetNativeSystemInfo to get a rough count of the number of logical processors.

OpenGL

OpenGL is not supported for Windows Store apps, Windows phone 8.x, Xbox One, or universal Windows apps for Windows 10.

Note: For OpenGL ES applications, you may find the Angle project useful.

QueryPerformanceCounter
QueryPeformanceFrequency

These functions are supported for all applications as the basis for high-resolution timers.

timeBeginPeriod
timeEndPeriod

Windows Store apps cannot change the global system timer resolution as this can negatively impact power-saving modes.

WinSock

The Windows Sockets 2 API is not available for Windows Store apps for Windows 8.0 and they must use the Windows Runtime (WinRT) API Windows.Networking.Sockets instead. TCP and UDP layer network communications are therefore not a good candidate for dual-use shared code, although an abstraction could be written with two different implementations.

Update: Windows Store apps for Windows 8.1 can now use WinSock 2.x as of VS 2013 Update 3. See this post. Winsock 2.x is also supported for Windows phone 8.x, Xbox One apps, and universal Windows apps for Windows 10. Note that this support requires an IP-neutral dual-stack implementation (i.e. not legacy IPv4 only)

DirectPlay is not supported for Windows Store apps, Windows phone 8.x, Xbox One, or universal Windows apps for Windows 10. DirectPlay is not recommended for Win32 desktop apps.

DirectX and Media Technologies

One of the reasons that dual-use shared code is possible for game technology is because many of the traditional DirectX Win32 APIs are available for Windows Store apps as well as down level for Win32 desktop apps.

DirectX Technology Notes
Direct3D 11.0, DXGI 1.1, Direct2D, and DirectWrite

These technologies are available for Windows Store apps, universal Windows apps for Windows 10, and Win32 desktop apps for Windows 10, Windows 8.x, Windows 7, and Windows Vista SP2+KB971644.

Direct3D 9 and Direct3D 10.x are not supported for Windows Store apps, Windows phone 8.x, universal Windows apps for Windows 10, or Xbox One.

Note: Windows phone 8.0 and Xbox One XDK do not support Direct2D or DirectWrite.

Direct3D 11.1, DXGI 1.2, improved Direct2D and DirectWrite

These technologies are available for Windows Store apps, universal Windows apps for Windows 10, and Win32 desktop apps on Windows 8.x and Windows 10. Partial support for these APIs is available for Win32 desktop applications on Windows 7 Service Pack 1 via KB 2670838.

Windows Store apps can rely on these technologies always being present, while Win32 desktop applications need to provide suitable fallbacks for older versions of Windows.

Direct3D 11.2, DXGI 1.3

These technologies are available for Windows Store apps, universal Windows apps for Windows 10, and Win32 desktop apps for Windows 8.1 and Windows 10.

Windows Store apps for Windows 8.1 can rely on these technologies always being present, while Win32 desktop applications need to provide suitable fallbacks for older versions of Windows.

Note: Windows phone 8.0 and Xbox One XDK do not support Direct3D 11.2 / DXGI 1.3

Diret3D 12, Direct3D 11.3, DXGI 1.4

These technologies are available for universal Windows apps for Windows 10 and Win32 desktop apps for Windows 10.

Universal Windows apps for Windows 10 can rely on these technologies always being present, while Win32 desktop applications need to provide suitable fallbacks for older versions of Windows.

D3DX

All versions of the D3DX utility library (D3DX9, D3DX10, and D3DX11) are deprecated, and are not supported for Windows Store apps, Windows phone 8, Xbox One, or universal Windows apps for Windows 10.

DirectXTK, DirectXTex, and DirectXMesh support Windows Store apps, universal Windows apps for Windows 10, Windows phone 8.x, Xbox One, and Win32 desktop applications on Windows 10, Windows 8.x, Windows 7, and Windows Vista. These provide replacements for much of the functionality in D3DX for Direct3D 11. See "Direct3D 11 Textures and Block Compression" for more information.

The D3DCSX Compute Shader helper utility is available for Win32 desktop applications, but not for Windows Store apps or Windows phone 8.

HLSL Compiler / D3DCompile

The HLSL compiler (FXC.EXE) and the D3DCompile (D3DCompiler_*.DLL) APIs are supported for both Windows Store apps and Win32 desktop apps.

Note that for Windows Store apps on Windows 8.0 and Windows phone 8.0, the HLSL compiler / D3DCompile APIs are only supported for development and not for deployment.

Windows Store apps for Windows 8.1, Windows Phone 8.1, Xbox One, and universal Windows apps for Windows 10 have complete support for D3DCompile APIs. See “HLSL, FXC, and D3DCompile” for more information.

Effects 11 (FX11)

The Effects 11 technology relies on runtime shader reflection via D3DReflect in the D3DCompiler. Due to the limitations above, this makes Effects 11 library unsuited to use in Windows Store apps for Windows 8.0 or Windows phone 8.0.

Note: HLSL Compiler support for the fx_5_0 profile required to use Effects 11 is deprecated.

DirectXMath

The DirectXMath library is supported for Windows Store, universal Windows apps for Windows 10, Windows phone 8.x, Xbox One, and Win32 desktop apps. This library provides SSE/SSE2 optimizations for Windows x86 and x64 native, as well as ARM-NEON optimizations for Windows RT and Windows phone 8.x. See “Introducing DirectXMath” for more information.

Note: DirectXMath on Xbox One also makes use of SSE3, SSSE3, SSE 4.1, AVX, and F16C as described in this blog series.

XAudio2

Windows 8.x and Windows 10 includes XAudio 2.8 which is supported for Windows Store apps, universal Windows apps for Windows 10, Windows phone 8.x, and Xbox One. See “XAudio2 and Windows 8” for more details.

Windows Core Audio (WASAPI) is also available for use by low-level audio libraries.

DirectSound is not supported for Windows Store apps, Windows phone 8.x, Xbox One, or universal Windows apps for Windows 10.

XINPUT

Windows 8.x and Windows 10 includes XInput 1.4 which is supported for Windows store apps and Win32 desktop apps. Windows Vista, Windows 7, Windows 8.x, and Windows 10 also include XInput 9.1.0 which is supported for Win32 desktop applications. See “XInput and Windows 8” for more details.

DirectInput is not supported for Windows Store apps, universal Windows apps for Windows 10, Windows phone 8.x, or Xbox One

Note: XINPUT is not supported by Windows phone 8.x or Xbox One.

Xbox One and universal Windows apps for Windows 10 make use of a WinRT gamepad API which has similar functionality.

Windows Imaging Component (WIC)

This technology is available for Windows Store apps, universal Windows apps for Windows 10, and Win32 desktop apps for Windows 10, Windows 8, Windows 7, and Windows Vista. Be sure to set the _WIN32_WINNT definition properly to ensure use of the correct version of the WIC factory. See "Windows Imaging Component and Windows 8" for more information.

Note: Windows phone 8.0 does not support WIC, but this is supported for Windows phone 8.1. Xbox One XDK does not support the JPEG XR / HD Photo codec and a few other aspects of 'standard' WIC.

Windows Media Foundation (MF)

The Windows Media Foundation is available for Windows Store apps, universal Windows apps for Windows 10, and Win32 desktop applications on Windows 10, Windows 8, Windows 7, and Windows Vista. Be sure to read this post for some additional guidance.

DirectShow is not supported for Windows Store apps, Windows phone 8.x, Xbox One, or universal Windows apps for Windows 10.

Note: Windows phone 8.0 has partial support for the Media Foundation API, specifically IMFMediaEngine. Xbox One XDK also has partial support for the Media Foundation API.

 

(continued in part 3)