More information about the WiX v3.0 DirectX extension

  • Article

A little while ago, Bob Arnson posted a description of the WixGamingExtension, which was added to WiX v3.0 to allow setup developers to integrate their game with the Windows Vista Game Explorer.  When he created the WixGamingExtension, he also created another smaller extension that he didn't publicize outside of the WiX help documentation (wix.chm).

The other extension is called the WixDirectXExtension, and I want to describe it in more detail here because it contains a couple of system configuration detection custom actions that are typically useful for game developers who are creating MSI-based installers for their games.

Description of the WixDirectXExtension

The WixDirectXExtension has been available in WiX v3.0 since the 3.0.4014.0 build.  The WixDirectXExtension contains a custom action named WixQueryDirectXCaps.  This custom action queries the DirectX capabilities of the video card on a user's system and then set the following MSI properties:

  • WIX_DIRECTX_PIXELSHADERVERSION - Pixel shader version capability, expressed as major*100 + minor. For example, a shader model 3.0-compliant system would have a WIX_DIRECTX_PIXELSHADERVERSION value of 300.
  • WIX_DIRECTX_VERTEXSHADERVERSION - Vertex shader version capability, expressed as major*100 + minor. For example, a shader model 3.0-compliant system would have a WIX_DIRECTX_VERTEXSHADERVERSION value of 300.

How to use WixDirectXExtension in your setup authoring

To use the WixDirectXExtension properties in your WiX v3.0-based setup, you can use the following steps:

  1. Add PropertyRef elements for items listed above that you want to use in your MSI.
  2. Add authoring to your MSI to use the resulting property somehow (such as to warn the user if the pixel shader version is less than what is required by the product being installed).
  3. Add the -ext <path to WixDirectXExtension.dll> command line parameter when calling light.exe to include the WixDirectXExtension in the MSI linking process.  Or, using an MSBuild-based .wixproj project, add <path to WixDirectXExtension.dll> to the WixExtension item group.  When using Votive in Visual Studio 2005 or Visual Studio 2008, this can be done by right-clicking on the References node in a WiX project, choosing Add Reference... then browsing for WixDirectXExtension.dll and adding a reference.

For example:

<PropertyRef Id="WIX_DIRECTX_PIXELSHADERVERSION" />

<CustomAction Id="CA_CheckPixelShaderVersion" Error="[ProductName] requires pixel shader version 3.0 or greater." />

<InstallExecuteSequence>
  <Custom Action="CA_CheckPixelShaderVersion" After="WixQueryDirectXCaps">
    <![CDATA[WIX_DIRECTX_PIXELSHADERVERSION < 300]]>
  </Custom>
</InstallExecuteSequence>

<InstallUISequence>
  <Custom Action="CA_CheckPixelShaderVersion" After="WixQueryDirectXCaps">
    <![CDATA[WIX_DIRECTX_PIXELSHADERVERSION < 300]]>
  </Custom>
</InstallUISequence>

A note about error handling in WixDirectXExtension

Note that the WixDirectXExtension properties are set to the value NotSet by default.  The WixDirectXExtension custom action is configured to not fail if it encounters any errors when trying to determine DirectX capabilities.  In this type of scenario, the properties will be set to their NotSet default values.  In your setup authoring, you can compare the property values to the NotSet value or to a specific value to determine whether WixDirectXExtension was able to query DirectX capabilities and if so, what they are.

What WixDirectXExtension does behind the scenes

If you're interested, the WixQueryDirectXCaps custom action does the following behind the scenes:

  1. Instantiates an IDirect3D9 object by calling the Direct3D9 API
  2. Calls the  IDirect3D9::GetDeviceCaps API to get a D3DCAPS9 structure
  3. Computes the property values using the PixelShaderVersion and VertexShaderVersion properties in the D3DCAPS9 structure and the D3DSHADER_VERSION_MAJOR and D3DSHADER_VERSION_MINOR macros