Installing DirectX with DirectSetup
Installing DirectX with DirectSetup
Applications and games that depend on DirectX can use the DirectXSetup function to install the necessary system components into an existing Windows installation.
Checking the Installed Version of DirectX
Before you install, here are some ways to find out what version of DirectX is installed:
Use D3DXCheckVersion to make sure that the D3DX headers that you build against match the D3DX library that you're linking with.
Standard Install
DXSetup.exe is a standard installer that comes with the DirectX SDK. It provides an easy way for developers to install the DirectX runtime without having to write a custom installer. The standard installer is included in the following folder:
SDK root\Redist
The installer uses the DirectSetup API for version checking, setting up the type of installation, displaying the end user license agreement (EULA), installing DirectX, reporting progress, and handling messages. The installer displays all of the user interface (UI) components during the installation, including the click-through EULA, progress meter, and message handling.
The standard install is easy:
- If your application requires managed code, verify that the Microsoft .NET Framework is installed. Otherwise, skip to the next step.
- Call DXSetup.exe from the command line.
The installer supports Microsoft Windows 2000 and newer releases. The installer also supports languages shown in the following table.
| Chinese (Simplified) | Chinese (Traditional) | Czech |
| Dutch | English (American) | French |
| German | Italian | Japanese |
| Korean | Polish | Portuguese (Brazil) |
| Russian | Spanish | Swedish |
Note The EULA will be displayed in English on machines that support the use of multiple languages.
The standard installation supports one command line option, /silent, which specifies a non-interactive installation.
After installing the DirectX SDK, before building a project in Visual Studio, you must initialize the directories in Visual Studio by doing the following:
- Select Tools -> Options -> Projects and Solutions -> VC++ Directories
- Show Executable files and add: %ProgramFiles%\Microsoft DirectX SDK (March 2008)\Utilities\Bin\x86
- Show Include files and add: %ProgramFiles%\Microsoft DirectX SDK (March 2008)\Include
- Show Library files and add: %ProgramFiles%\Microsoft DirectX SDK (March 2008)\Lib\x86
This example shows how to fix this for the March 2008 SDK, replace that with the date of the current SDK.
Custom Install
DirectSetup facilitates one-call installation of the DirectX components. DirectSetup Reference includes several API functions and structures as well as a callback function for customizing the user interface during the installation process. The DirectX SDK includes a sample application that demonstrates the use of this callback function (see DXInstall Sample). Follow the instructions for Redistributable Code contained in the license agreements within the following folder:
SDK root\Documentation\License Agreements.
The DirectXSetup function takes a parameter (lpszRootPath), that points to the root directory of the installation. It can be NULL to indicate that the root path is the current directory.
The root directory must contain DXupdate.cab, DXDllreg_x86.cab, Dsetup.dll, Dsetup32.dll, and any of the optional DirectX SDK redistributable files. To create the proper structure on your application setup disk, copy the redistributable code from one of the following locations into the root path of your setup program:
- If the SDK is installed, the installed location is SDK root\Redist
- The location on the DirectX CD is CD root\Redist
- If you download the SDK, the location is Extracted location\Redist
- The latest Redist download can be obtained at http://msdn2.microsoft.com/en-us/directx/default.aspxsdk
DirectSetup enables you to define a callback function for customizing the DirectX setup process. This callback function is referred to as DirectXSetupCallbackFunction, but you can give it any name.
You can use the callback function to do the following:
- Employ a custom interface. Your setup program might display messages in ways other than by using a message Box or standard dialog boxes. The callback function enables you to integrate messages for the DirectX component of your installation into your own interface.
- Update a progress indicator.
- Suppress the display of status and error messages. Designers of programs for novice users might want to suppress error messages and let the setup program handle errors and make upgrade choices silently. This approach requires a greater development effort for the setup program, but it might be appropriate for the target audience.
If a callback function is not provided by the setup program, the DirectXSetup function displays status and error information in a dialog box and obtains user input by calling the MessageBox function. If a callback is provided, the information that would have been used to create the status dialog or message box is instead passed to the callback. The callback function is called once for each DirectX component that can be installed or upgraded.
Create a callback function that conforms to the DirectXSetupCallbackFunction prototype, as in the following declaration.
DWORD WINAPI DirectXSetupCallbackFunction(
DWORD dwReason,
DWORD dwMsgType,
LPSTR szMessage,
LPSTR szName,
void *pInfo);
In the DXInstall Sample, the name of the function is the same as that of the prototype, but this is optional. The way your callback function interprets the parameters is entirely up to you. Typically, you would choose which messages to display (based on dwReason) and when to present the user with alternatives, and you would modify the interface accordingly.
The callback function must return:
- IDOK if there are no choices to be made by the user.
- MB_OK or MB_OK | MB_ICONERROR if there are errors.
Before calling DirectXSetup, notify DirectSetup that you want to use a callback by calling the DirectXSetupCallbackFunction and passing a pointer to the callback.
Removing the DirectX SDK
To remove the DirectX SDK, use Add/Remove Programs in Control Panel to remove the SDK.
Enabling AutoPlay
If you are building an AutoPlay compact disc title, copy the Autorun.inf file in the root directory of the SDK compact disc to the root of your application directory. This text file contains the following information.
[autorun]
OPEN=SETUP.EXE
If your application's setup program is called Setup.exe, you do not have to make any changes to this file; otherwise, edit this file to contain the name of your setup program.
DirectX Redistribution
Stand-alone developer runtime installers only install the DirectX developer and debug runtime for redistribution purposes. These installers are available for all supported platforms and are located in the following folder:
SDK root\Developer Runtime\
Applications can use the supplied standard installer, DXSetup.exe, to redistribute DirectX. Be sure to follow the instructions for Redistributable Code contained in the license agreements in the following folder:
SDK root\Documentation\License Agreements
These files must be included in any distribution of DirectX as explained in the file DirectX Redist.txt, found in the following folder:
CD root\Documentation\License Agreements
Note The D3DX library included in this release is dependant on the Direct3D runtimes that shipped with this SDK. Applications linking against the version of D3DX in this release must also redistribute the runtime from this SDK.
Naming Convention
The following naming convention is used for the optional redistributable components that are included in the DirectX redist folder:
D3DX
For D3DX files, the naming convention is MonthYear_Component_HeaderVersion_Platform.file-extension.
So, for example, if you were installing the D3DX components from the December 2005 SDK release, you would use the following file names:
Dec2005_d3dx9_28_x86.cab
Dec2005_d3dx9_28_x64.cab
Note There were no changes to the D3DX component for the October 2005 SDK release.
If you were installing the D3DX components from the August 2005 SDK release, you would use the following file names:
Aug2005_d3dx9_27_x86.cab
Aug2005_d3dx9_27_x64.cab
If you were installing the D3DX components from the June 2005 SDK release, you would use the following file names:
Jun2005_d3dx9_26_x86.cab
Jun2005_d3dx9_26_x64.cab
If you were installing the D3DX components from the April 2005 SDK release, you would use the following file names:
Apr2005_d3dx9_25_x86.cab
Apr2005_d3dx9_25_x64.cab
If you were installing the D3DX components from the Feb 2005 SDK release, you would use the following file names:
Feb2005_d3dx9_24_x86.cab
Feb2005_d3dx9_24_x64.cab
Follow this naming convention for future SDK releases.
DirectX for Managed Code
For DirectX for Managed Code, the naming convention for files is MonthYear_Component_Platform.file-extension.
MonthYear_Component_Platform.Ext
Note Starting with the December release, managed components are named MDX1.
So if you were installing the managed code components from the December 2005 SDK release, you would use the follwing file name:
Dec2005_MDX1_x86.cab
Starting with the December release, older managed code components are contained in a .cab file with Archive in its name. Use this .cab file instead of previous release .cab files to support older MDX components:
Dec2005_MDX1_x86_Archive.cab
XInput
For XInput files, the naming convention is MonthYear_Component_Platforms.file-extension.
So, if you were installing the XInput components from the December 2005 SDK release, you would use the following file names:
Oct2005_xinput_x86.cab
Oct2005_xinput_x64.cab
Note There were no behavioral changes to XInput in the December 2005 SDK release.
Reducing the DirectX Redistribution Size
The DirectX redist default file set contains all the files that are needed to support all DirectX applications. It is highly recommend that developers use all the files in the DirectX Redist folder. To reduce the size of the DirectX redist footprint, you may remove optional DirectX SDK redistributable files. These files are listed in the CD root\Documentation\License Agreements\DirectX Redist.txt.
For example, here are several common scenarios:
- No BDA Support (3 megabyte savings)
- If your application does not require broadcast driver architecture (BDA) support then the following can be removed BDA.CAB, BDANT.CAB, and BDAXP.CAB.
- No Managed DirectX (approximately 5 megabyte savings)
- If your application does not require Managed DirectX then the MonthYear_MDX1_x86.CAB and MonthYear_MDX1_x86_Archive.cab files may be removed from the redist folder.
- D3DX Support (approximately 17 megabyte savings)
- If your application does not require D3DX 9 or if you only require a specific month's release, then the older MonthYear_d3dx9_HeaderVersion_x86.cab and the MonthYear_d3dx9_HeaderVersion_x64.cab files may be removed from the redist folder.
- No 64-bit support (approximately 10 megabyte savings)
- If your application is NOT a native 64-bit (x64) application then *_x64.cab files may be removed from the redist folder.
- DirectX 9.0c is installed
- If your application requires DirectX 9.0c (or higher), then you may remove the DirectX.cab and the DXnt.cab from the redist folder. However, if you remove these cabs from the redist folder (and DirectX 9.0c (or higher) is not installed), DirectXSetup will fail.
- No XInput support ( less than 1 megabyte savings)
- If your application does not require the XInput API, you may remove the MonthYear_xinput_x86.cab and MonthYear_xinput_x64.cab files from the redist folder.
- No XACT Support (approximately 1 megabyte savings)
- If your application does not require the XACT API, you may remove the MonthYear_xact_86.cab and MonthYear_xact_x64.cab files from the Redist folder.
For instance, suppose you know that your customer has DirectX 9.0c installed, and you want the smallest redist that only includes the 32-bit version of the D3DX library from the December 2005 SDK release. For this scenario, you need to include the following CAB files in the redist folder:
- dxsetup.exe
- dsetup32.dll
- dsetup.dll
- dxupdate.cab
- dxdllreg_x86.cab
- Dec2005_d3dx9_28_x86.cab
Your installation can use the DirectXSetup API or run DXSetup.exe to install the D3DX component.
Dependency on previous released optional SDK components
By default the DirectX Redist includes the previous versions of SDK redistributable components.
All the developer would need to do is include the default DirectX redist, which includes the all of the previously released SDK redist component packages (.cab files). No other changes are required by the developer.
DirectX Setup detects that the component's .cab package is available and installs the component's files appropriately via file version checking of the DLLs. These files would only be installed if they had higher versions. If for instance, a component of your application requires an optional component from the August 2005 release of the SDK, you would need to copy the appropriate .cab files from the August 2005 release redist folder to the current redist folder.
An application that uses D3DX requires the following files:
Aug2005_d3dx9_27_x86.CAB
Aug2005_d3dx9_27_x64.CAB
Furthermore, an application that compiles shaders by calling D3DX 9 shader functions with the D3DXSHADER_USE_LEGACY_D3DX9_31_DLL flag, depends on the October 2006 version of D3DX 9, and requires the following files:
OCT2006_d3dx9_31_x86.cab
OCT2006_d3dx9_31_x64.cab (for 64-bit native applications)
Managed DirectX applications require the following files:
Dec2005_MDX1_x86_Archive.cab
Aug2005_d3dx9_27_x86.CAB
Aug2005_d3dx9_27_x64.CAB