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 only support,
_WIN32_WINNTis 0x0602 which is the default with the Windows 8.0 SDK and is the value you expect to use for Windows Store apps as well.For Windows 7 and Windows 8 Win32 desktop support,
_WIN32_WINNTshould be 0x0601.For Windows Vista, Windows 7, and Windows 8 Win32 desktop support,
_WIN32_WINNTshould be 0x0600.
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 | GetFileInformationByHandleEx | 0x0600 (Windows Vista) |
GetTickCount | GetTickCount64 | 0x0600 (Windows Vista) |
InitializeCriticalSection | 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, | MapViewOfFileFromApp | 0x0602 (Windows 8) |
Here are some additional notes on Win32 APIs commonly used by games.
Win32 API | Notes |
CreateThread | Windows Store apps do not support POSIX-style threading APIs. These applications must use the Windows Runtime (WinRT) ThreadPool API in 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. |
CreateProcess | Windows Store apps do not support POSIX-style process, command-line or environment variable APIs. These applications must use the Launcher class in the |
FindResource(Ex) | 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
|
LoadLibrary(Ex) | Windows Store apps must use You have to use implicit linking with system DLLs, although you can use |
LoadString | Windows Store apps do not use Win32 style resource files for localization. These applications use Dual-use shared code should avoid directly displaying strings and should leave localization to the client application. |
| OpenGL | OpenGL is not supported for Windows Store apps. |
QueryPerformanceCounter | These functions are supported for Windows Store apps as well as Win32 desktop apps as the basis for high-resolution timers. |
timeBeginPeriod | 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 DirectPlay is not supported for Windows Store apps and its use is not recommended for Win32 desktop apps. Note: The Windows phone 8 platform does 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, Windows 7, and Windows Vista SP2+KB971644. Direct3D 9 and Direct3D 10.x are not supported for Windows Store apps or Windows phone 8. Note: Windows phone 8 does 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. 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. Note: Windows phone 8 supports Direct3D 11.1 and DXGI 1.2. |
| D3DX | All versions of the D3DX utility library (D3DX9, D3DX10, and D3DX11) are not supported for Windows Store apps or Windows phone 8. DirectXTK and DirectXTex both support Windows Store apps as well as Win32 desktop applications on Windows 8, Windows 7, and Windows Vista. DirectXTK also supports Windows phone 8. 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 ( Note that for Windows Store apps and Windows phone 8, the HLSL compiler / D3DCompile APIs are only supported for development and not for deployment. See “HLSL, FXC, and D3DCompile” for more information. |
| Effects 11 (FX11) | The Effects 11 technology relies on runtime shader reflection via |
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. See “Introducing DirectXMath” for more information. |
XAudio2 | Windows 8 includes XAudio2 .8 which is supported for Windows Store apps and Windows phone 8. 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. |
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. Note: XINPUT is not supported by Windows phone 8. |
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 Note: Windows phone 8 does not support 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. Note: Windows phone 8 has partial support for the Media Foundation API, specifically IMFMediaEngine |
(continued in part 3)