DirectX Vista Compatibility

DirectX Windows Vista Compatibility

To create applications that will run quickly and smoothly on the Windows Vista® platform, it is important to be aware of certain best practices and issues when developing in DirectX®. Many of these points reflect a common-sense approach to Windows Vista development, but they are important to remember for providing a consistent Windows Vista user experience.

Use Direct3D

Applications that require robust 3D rendering on Windows Vista should be developed using Direct3D®. The Windows Vista core graphics architecture is designed around Direct3D, the most performant and stable method for direct access to the Graphics Processing Unit (GPU). Direct3D 10 offers the latest graphics innovations and performance optimizations, though Direct3D 9 is the minimum recommended previous version to use for developing any new application. Legacy interfaces (earlier than Direct3D 9) are supported, but may not offer the same features and performance benefits later interfaces do.

Developers can verify which version of DirectX their applications rely on by using the Depends.exe tool in the Windows Server 2003 R2 Platform SDK, available here:

https://www.microsoft.com/downloads/details.aspx?FamilyID=0baf2b35-c656-4969-ace8-e4c0c0716adb&DisplayLang=en

Use App Verifier

The Application Verifier tool can find many common errors in applications, such as exceptions, heap, lock, memory errors, local thread storage errors, use of DangerousAPIs, and dirty stacks. The Application Verifier can help verify proper file paths, identify drivers that need to be signed, and assist with versioning maintenance.

If your application can pass all the appropriate Application Verifier tests and eliminate all failures, you have gone a long way toward insuring compatibility with Windows Vista.

The Application Verifier tool can be found at the Microsoft Download Center here:

https://www.microsoft.com/downloads

Detect Game Settings

For better resolution, developers should follow certain best practices when determining game settings on Windows Vista.

Use of widescreen and HDTV is increasing in the PC market. Games should support aspect ratios and resolutions for these new mediums. The following aspect ratios and associated minimum screen resolutions should be supported:

Games should detect the native aspect ratio and resolution of the user's display when game applications first start.

The following code demonstrates how to retrieve the aspect ratio and screen resolution of the desktop. This is the most reliable way of determining the monitor's aspect ratio and compatible resolutions.

C++

bool success = false;

//The displayDevice is used to retrieve the device name
DISPLAY_DEVICE displayDevice;
displayDevice.cb = sizeof(DISPLAY_DEVICE);
WCHAR strDeviceName[256] = {0};

//device index, this code finds only the first monitor
DWORD devIndex = 0; 

success = EnumDisplayDevices(0,devIndex,&displayDevice,0);

//Making sure we have the correct device.
if (displayDevice.StateFlags & DISPLAY_DEVICE_ATTACHED_TO_DESKTOP)
{
StringCchCopy( strDeviceName, 256, displayDevice.DeviceName );

//devMode retrieve monitor settings
DEVMODE devMode;
devMode.dmSize = sizeof(DEVMODE);

success = EnumDisplaySettings( strDeviceName, ENUM_REGISTRY_SETTINGS, &devMode );

float fDesktopAspectRatio = devMode.dmPelsWidth / (float)devMode.dmPelsHeight;
}

Projects using DXUT can use the DXUTGetDesktopResolution function to retrieve information about the desktop.

Any time users make changes to game settings, it is a best practice on Windows Vista to prompt them to confirm the changes, and program game settings to revert to the original setting if there is no response.

Offer 64-bit Compatibility

The number of 64-bit processors in use is expected to explode with Windows Vista. Both AMD and Intel are focusing on developing only 64-bit, multicore-CPUs. This means developers should ensure their applications run on the 64-bit version of Windows Vista.

Make sure any DirectX applications and their installers do not contain any 16-bit code or rely upon any 16-bit component. If the game is dependent on middleware or drivers, be sure to verify that they are compatible with 64-bit processors. Also, be sure the application can manage situations in which the PC has more than 2 GB of RAM available.

See the section Application Compatibility: Windows Vista 64-Bit of the article Landing: Application Compatibility Cookbook for more details about writing Windows Vista 64-bit compatible applications.

Accommodate Long File Names

Any game developed for Windows Vista that supports saving any kind of user information should be sure to support long file names. Users playing a game on Windows Vista will be accustomed to this feature, and it is likely they will enter long file names into any file name field. A game could potentially allocate an internal variable that provides too little space. This can be a source of "buffer overrun" bugs.

Additionally, games must work properly when users enter long user names. In Windows Vista, user names and paths can be up to 260 characters long.

Also be sure to confirm that special symbols or Unicode text works properly when users enter game data.

Support Concurrent User Sessions

Windows Vista encourages shared PC experiences through features like concurrent user sessions and Fast User Switching. Users should be able to run concurrent sessions without crashes, conflicts, or disruption. DirectX applications on Windows Vista should allow multiple sessions unless architectural issues prevent it. If running your application concurrently is impossible, the application should at least notify users before it fails or before users attempt to start another session. If multiple sessions are supported, the application should also support Fast User Switching.

Applications should not depend on any globally named OS or kernel objects to prevent conflicts with concurrent user sessions. For instance, a game that is dependent on creating or maintaining a named Mutex or shared pipe could fail if another user launches the same program in a different user session. Avoiding globally named objects is also important because an application running in a Standard User context cannot create a globally named object. Any application that requires such an object must be run with greater permissions assigned, which is more likely to force individuals to have to revert from running as a Standard User.

Another important consideration in an application or game that continuously plays music or sound effects while running is to remember to turn off the sound when another user is active.

Developers can test whether the application is being launched in a remote session by calling GetSystemMetrics(SM_REMOTESESSION) when starting up. A nonzero value indicates the session is remote.

For more information, see the article "Test Your Application with Fast User Switching" at the following URL:

https://msdn.microsoft.com/library/default.asp?url=/library/en-us/apcompat/apcompat/test_your_application_with_fast_user_switching.asp

Avoid Installation Issues

Windows Vista has been designed to make the process of installing software quicker and easier. A developer can implement a number of best practices to create a better experience for Windows Vista users when installing a new DirectX application.

As a first consideration, developers should always support Autorun as a part of the installation process. When the media that contains the DirectX application is first inserted into a computer, an Autorun script should launch to begin the installation process. If the application installer spans several disks, automatically prompt for the next disk insertion, and end the installation process with the gameplay disk in the drive. In general, try to minimize the amount of disk-swapping forced upon the user.

Include the DirectX redistributable and DirectSetup files to update DirectX on the user's system.

After installation, the Autorun should launch the game or configuration settings when the media is inserted. If the game is launched by the installer, test this process as a Standard User to ensure that elevated permissions are not required. The game should always be launched in the context of the Standard User, not as an elevated user (Administrator).

As for the installation process itself, try to make it as easy as possible. A little bit of common sense goes a long way here. Don’t insert unnecessary or redundant questions. Provide an automated, default Install option that can take users through the process in three clicks or less. A Custom Install option should be provided for more advanced installations. Try to avoid delays caused by copying data onto the hard drive. Consider where you can make lengthy data copying optional. Game cut scenes often can be streamed from the media. Data copying also can take place behind the scenes during game idle time.

Avoid unnecessary rebooting during installation. Rebooting often is unnecessary, so don’t assume that it is required after the installation of a component. If the installation process calls for a reboot, investigate to make sure it is necessary. The primary reason for restarting the system during an installation is that some files that must be updated are in use by a running application or service. Windows Vista implements a new feature called the Restart Manager. The Restart Manager can free up the files in use by shutting down and restarting all but the critical system services. This allows the installation to access the files that were in use without going through a full system restart. Installers can direct the Restart Manager to shut down and restart applications or services based on the file in use, the process ID (PID), or the short-name of a Windows service.

For more information about the Restart Manager, see the "Restart Manager" section of the Windows SDK documentation.

Because game installations often require a change to user permissions―often requiring elevated or Administrator permissions―DirectX applications must perform per-user tasks first, separate from the installation.

Game files always should be installed to an appropriate directory in Program Files by default. Typically this involves creating a Game Name folder inside a Company Name folder. All program files should go inside the Game Name folder. Be aware that the Program Files directory is not always located at C:\Program Files.

User files such as Saved Games and User Profiles should be stored in the appropriate user directories.

All EXE and DLL files installed should be signed with an Authenticode certificate, and all installed drivers must have a WHQL or DRS signature. This requirement avoids tampering that can lead to security risks and is required by Game Explorer, Parental Controls, and Windows Error Reporting. Non-signed drivers may not load in Windows Vista. Verify valid certificates by checking the file properties for certificate information or use the Signtool.exe with "verify /a /v" options.

For more information about Authenticode signing, see "Authenticode Signing for Game Developers" in the Windows SDK.

Uninstallation should be available in Windows Vista only via Programs Applet in the Control Panel. When uninstalling, make sure that all installed files are removed and all settings are cleared. This can include registry settings and firewall setting. Also, be sure to prompt the user before deleting any user-created files, such as Save Games.

A goal in developing an installation process for DirectX games in Windows Vista is to provide users with an experience as close as possible to a console gaming experience; try to make the process as quick and painless as possible, so your users can get to the fun part of the game without unnecessary delays.

Perform Proper Version Checking

A number of version-checking issues can occur when developing a DirectX application for Windows Vista, and programmers should be aware of them. These issues sort into three basic categories: operating system, DirectX, and file version checking.

In the past, some games have read registry keys to try to determine the version of the operating system. Now, applications that need to check the current version of the operating system should use version-checking APIs such as GetVersionEx.

Also important is that any code in the game that checks the operating system version allows that the OS version could increase in the future. Users should not be stopped from playing current games just because the OS version increased.

The following code uses GetVersionEx to see if the operating system is Windows Vista or later.

C++

OSVERSIONINFO OSVer;
OSVer.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);
BOOL bIsWindowsVistaOrLater;
if(GetVersionEx(&OSVer))
{
   bIsWindowsVistaOrLater = (OSVer.dwMajorVersion >=6);
}

Applications developed in DirectX should not explicitly check to see which version of DirectX that they will be running under. In the past, assumptions about DirectX versions built into game code have caused failed installations. The DirectX version number that some applications read when setting themselves up changed between Windows Vista and prior Windows operating system releases.

Use DirectX Setup to configure DirectX on a user's machine. This allows code provided by Microsoft to perform any required version updates and detect or install any other necessary DirectX SDK components. Improper version checking can make an otherwise compatible game fail. Always launch DirectX Setup during installation (preferably using the /silent mode), as it will determine whether users need to update their DirectX files or not. See the "Installing DirectX with DirectSetup" topic in the DirectX 9 documentation for more details about configuring DirectX Setup.

Installations on Windows Vista should check to see that the latest versions of any files are installed. Shared files and system files should never be regressed during an installation. The version number of shared and system components are often updated when a version is released that expands functionality or fixes security problems. Overwriting these files will destroy that functionality and reintroduce those security vulnerabilities.

Take Advantage of Windows Error Reporting

Windows Error Reporting (WER) in Windows Vista is a mechanism for creating standardized error reporting. When an error in an application occurs, WER gathers information about the hardware, software, and the circumstances of the error and sends a report to Windows Error Reporting Services. That information then can be accessed by developers through the Windows Quality Online Services (WinQual) site (https://winqual.microsoft.com/default.aspx). Additionally, developers can provide solutions to common errors. These solutions can be presented to users at the time of the error.

To take advantage of WER, DirectX developers should keep a few tips in mind:

• First, when an error occurs in an application, do not hide it. Unhandled exceptions will be reported automatically by Windows Vista. If exceptions are broadly handled in the application, it is likely that an exception generated by an unanticipated error condition will never make it to the operating system level, and thus possibly prevents users from addressing the issue. Of course, an application can include custom unhandled exception handlers to perform custom support and recovery, but if this is the case, error information should be passed on to the ReportFault API.

• Applications should contain accurate Product Name, Company Name, and File Versions. This ensures that WER reports are collated accurately.

• Ensure that exiting the game under normal conditions does not result in an unknown exception fault.

Windows Error Reporting is a powerful tool for improving the quality of software and reducing support costs by essentially turning the entire user base into testers.

For more information and implementation details, see the "Windows Error Reporting" topic in the Windows SDK documentation.

See the DirectX SDK article "Crash Dump Analysis":

https://msdn.microsoft.com/library/default.asp?url=/library/en-us/directx9_c/Crash_Dump_Analysis.asp

Support Xbox 360 Controller and Peripherals

Windows Vista applications can easily support the Xbox 360 controller through the XInput API. XInput is the same API for both Windows Vista and Xbox, and this saves development time by streamlining controller coding when porting games to or from the Xbox. Additionally, because of the standardized nature of XInput, applications that support the 360 controller will be able to support other controller peripherals in the future. If your DirectX application supports controllers, consider adding support for the 360 Controller.

To fully realize these benefits, developers should keep the following in mind:

• Users should be able to access all the application's functionality using the controller. This should include paging through and selecting items from in-game menus, choosing names for characters and saved games, and accessing settings.

• The program should gracefully handle the controller being added or removed while the application is running.

• Use widely-accepted standard button configurations.

• If vibration features of the controller are used, make sure to turn them off when the game is paused.

• If the game presents text tutorials or on-screen hints that contain buttons or required key presses, ensure that these text strings or images properly reflect the controller or input device currently in use by the user.

• For more information, see the "XInput" section of the DirectX SDK documentation.

Develop for Game Explorer Integration

The Game Explorer is a new feature for games in Windows Vista. Similar to My Documents or My Pictures folders, Game Explorer centralizes and standardizes all game content and activities installed on the computer, allowing for easier organization. Locating all game information in one place makes context-sensitive activities possible, such as robust search, game configuration, game documentation, save games, patching, and more. Game Explorer enables gamers to view, organize, modify, and interact with all installed games in one central place.

Games can populate the Game Explorer by embedding a Game Definition File (GDF) within an EXE or DLL binary as a resource, along with a thumbnail image. GDF files can be created using the GDFMaker tool provided with the DirectX SDK and then registering them with the Game Explorer.

Games should not create shortcuts on the desktop, in the Start menu, or in any other location when they are installed to Windows Vista. But in Windows operating system releases of Windows XP and earlier, do create shortcuts still.

The uninstaller should be available only through Programs in Control Panel.

For more information, see the "Windows Game Explorer Integration" in the DirectX SDK documentation or "Game Explorer" in the Windows SDK.

Support Parental Controls

Another Game Explorer feature that developers can benefit from is Parental Controls. Games must include any ratings from the ESRB, PEGI, or other regional rating systems and descriptors (as appropriate for each rating system) in their Game Definition File (GDF). All major ratings systems are supported by Parental Controls. A user whose settings do not meet or exceed the ratings or descriptors for a game should not be permitted to launch that game. If running in Standard User mode is not the game's default start setting, users will be able to override parental controls, so make sure that the game can run as Standard User during normal play.

To prevent the game from launching if the user does not meet the Parental Controls criteria, the game must call VerifyAccess on launch in Windows Vista. If VerifyAccess returns false, force the game to exit or quit the installation and provide an appropriate message to the user stating why the game ended.

Parental Controls enables parents to regulate their children's game activities.

Additional Information:

For more details on the Game Definition File (GDF), see "Integrating with Windows Game Explorer" at:

https://msdn.microsoft.com/library/default.asp?url=/library/en-us/directx9_c/Windows_Game_Explorer_Integration.asp

For more information about making a game compatible when starting as a Standard User, see the DirectX SDK article "Gaming with Least-Privileged User Accounts" at:

https://msdn.microsoft.com/library/default.asp?url=/library/en-us/directx9_c/Gaming_with_Least_Privileged_User_Accounts.asp

Other Useful Links