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

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 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)

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)
CreateFile CreateFile2 0x0602 (Windows 8)
CreateFileMapping CreateFileMappingFromApp 0x0602 (Windows 8)
GetOverlappedResult GetOverlappedResultEx 0x0602 (Windows 8)
MapViewOfFile,
MapViewOfFileEx
MapViewOfFileFromApp 0x0602 (Windows 8)

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
SetThreadAffinityMask
Sleep(Ex)
SetPriorityClass
TlsAlloc

Windows Store apps 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.

Note: There is a sample available that emulates a small subset of the Win32 threading APIs using the WinRT threadpool which may be useful for porting existing threading codebases. See CreateThread for Windows 8. Xbox One XDK supports some of these Win32 threading APIs.

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)
LockResource

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.

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 use by Windows Store apps

LocalAlloc, GlobalAlloc, and VirtualAlloc are not available for Windows Store apps.

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

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.

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.

QueryPerformanceCounter
QueryPeformanceFrequency

These functions are supported for Windows Store apps as well as Win32 desktop apps 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 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.

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

Note: Windows phone 8.x and Xbox One XDK do support WinSock.

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 and Win32 desktop apps for 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, 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 and Win32 desktop apps on Windows 8.x. 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 and Win32 desktop apps for Windows 8.1.

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 do not support Direct3D 11.2 / DXGI 1.3

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, or Xbox One.

DirectXTK, DirectXTex, and DirectXMesh support Windows Store apps as well as Win32 desktop applications on Windows 8.x, Windows 7, and Windows Vista. DirectXTK also supports Windows phone 8.x and Xbox One. 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 and Windows Phone 8.1 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, Windows phone 8.0, or dual-use code.

DirectXMath

The DirectXMath library is supported for Windows Store 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 includes XAudio2 .8 which is supported for Windows Store apps and Windows phone 8.x. See “XAudio2 and Windows 8” for more details.

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

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

XINPUT

Windows 8 includes XInput 1.4 which is supported for Windows store apps and Win32 desktop apps. Windows Vista, Windows 7, and Windows 8 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, Windows phone 8.x, or Xbox One

Note: XINPUT is not supported by Windows phone 8.x or Xbox One. Xbox One makes use of a new WinRT gamepad API which has similar functionality.

Windows Imaging Component (WIC)

This technology is available for Windows Store apps and Win32 desktop apps for 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 and Win32 desktop applications on 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, or Xbox One.

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)