With the retirement of D3DX (See “Where is the DirectX SDK?”), there is some confusion about how applications access the High-Level Shader Language (HLSL) compiler. As mentioned in an earlier post (See “What’s up with D3DCompiler_xx.DLL?”), the HLSL compilation functions, shader reflection, and some support functions for the compiler were pulled out of D3DX as of the DirectX SDK (August 2009) release. While many developers continue to use the D3DX functions to compile HLSL and Effects, they are just pass-through functions to the D3DCompile API which can be used directly instead. The latest version of the D3DCompile API includes some new functions as well such as D3DCompileFromFile and D3DCompile2.

Windows 8.1 Preview: The latest version of the D3DCompiler (#47) is now included with the Windows 8.1 OS and is available for runtime use by Windows Store apps. Runtime compilation of HLSL is supported by using async IO and D3DCompile, which is why D3DCompileFromFile is not available for submitted applications. There is a new HLSL linker option as well that provides some of this flexibility to compose shaders at runtime without recompiling from the HLSL source.

Visual Studio 2012 and HLSL

With Visual Studio 2012, HLSL and the FXC.EXE tool is now integrated into build environment and the Windows 8.0 SDK. If you add .hlsl and .fx extension files to your project, there are properties for controlling how the HLSL compiler is invoked as part of your build including target profile, entry point name, etc. The resulting compiled shader uses the default extension of .cso (Compiled Shader Object). The texture editor supports HLSL colorization, and the Visual Studio Graphics Diagnostics feature provides support for debugging HLSL as well.

There is one quirk of having HLSL integrated into MSBuild that requires some restructuring of existing HLSL source files. The MSBuild system assumes that each source files is built exactly once. If you need to build the same HLSL source multiple times, you'll need individual .hlsl or .fx files for each instance you want to build added to your project. Judicious use of the #include directive should make it fairly easy to share the same source where needed, but this is a bit of a move away from the .fx file model where all variations of shaders were kept in a single file. You of course can still make use of some custom build script and integrate a custom build step for more sophisticated generation of shaders, but this "one .hlsl file per shader combination" model is going to be seen in a lot of samples.

Note: This automatic integration only works for C++ projects, not C# projects.

Build-time vs. Runtime Compilation

As we have recommended for many years, developers should compile their HLSL shaders at build-time rather than rely on runtime compilation. There is little benefit to doing runtime compilation for most scenarios, as vendor-specific micro-optimizations are done by the driver at runtime when converting the HLSL binary shader blobs to vendor-specific instructions as part of the shader object creation step. Developers don’t generally want the HLSL compiler results to change ‘in the field’ over time, so it makes more sense to do compilation at build-time. That is the primary usage scenario expected with the Windows 8.0 SDK and Visual Studio 11, and is the only supported scenario for Windows Store apps (a.k.a Metro style apps) in Windows 8. FXC and the MSBuild rules above are well suited to this usage.

For development purposes, it is often very convenient to use runtime compilation. Such applications typically keep a ‘shader cache’ file that is generated during execution, and a ‘final’ version of the shader cache is then shipped with the title. This scenario is supported by the D3DCompile API hosted in the D3DComplier_*.DLL. This is fully supported for Win32 desktop applications, and can even be used for Windows Store apps during development although not in deployment. In this case, the D3DCompiler_*.DLL from the Windows 8.0 SDK should be included side-by-side with the application itself (i.e. application local deployment). The d3dcomplier.h header and d3dcompiler.lib are part of the Windows 8.0 SDK include and lib paths, and the D3DCompiler_*.DLL itself is located in "%WindowsSdkDir%\redist\d3d". If your application makes use of the D3DCompile API, you will want to add a Custom Build Step for the project to make sure the right DLL is copied as part of your build.

Platform: Win32 (All Configurations)
Command Line: copy “$(WindowsSdkDir)redist\d3d\x86\D3DCompile*.DLL” “$(TargetDir)”
Outputs: D3DCompile_46.DLL;%(Outputs)

Platform: x64 (All Configurations)
Command Line: copy “$(WindowsSdkDir)redist\d3d\x64\D3DCompile*.DLL” “$(TargetDir)”
Outputs: D3DCompile_46.DLL;%(Outputs)

Platform: ARM (All Configurations)
Command Line: copy “$(WindowsSdkDir)redist\d3d\arm\D3DCompile*.DLL” “$(TargetDir)”
Outputs: D3DCompile_46.DLL;%(Outputs)

Note this assumes you are using the Windows 8.0 SDK RTM

Redistribution

The legacy DirectX SDK versions of D3DCompile (#33 - #43) were deployed using the DirectSetup technology and installed to the %WINDIR%\System32 (and %WINDIR%\SysWow64) folders using the redistribution package (which requires administrator rights at installation time). With the Windows 8.0 SDK, the D3DCompile DLL is never installed to the %WINDIR% folders. Instead, you should copy it into your applications folder and deploy it 'application local' with your Win32 desktop application.

Effects

The Effects 11 (aka FX11) shared source library requires the "Effect" Shader Type and the "Shader Model 5" profile. It also requires the D3DCompiler_*.DLL at runtime for the shader reflection APIs, which makes it unsuitable for Windows Store apps.

Note: The "fx" profiles (fx_2_0, fx_4_0, fx_4_1, and fx_5_0) are deprecated and may be removed from a future update of the HLSL compiler.

Platform Support

The shader binaries built by the current FXC.EXE and D3DCompile API using the Shader Model 2.0 and Shader Model 3.0 profiles will work on all Direct3D 9.0c compatible platforms including Windows XP. The actual D3DCompiler_*.DLL in the Windows 8.0 SDK itself only supports Windows Vista, Windows 7, and Windows 8. The same is true of the Visual Studio 11 compiler toolset, although the VS 11 IDE can build using the Visual Studio 2010 toolset which supports Windows XP Service Pack 3 via a Platform Toolset setting of "v100" assuming Visual Studio 2010 is installed side-by-side with Visual Studio 11. You can also install the Windows 7.1 SDK side-by-side and use the Platform Toolset setting of "Windows 7.1 SDK" which uses the VS 2010 RTM compiler toolset and headers that were included with the Windows 7.1 SDK.

Note: you can select a Platform Toolset of "v100-sdk80" with the Windows 8.0 SDK and Visual Studio 2010 installed to get the VS 2010 compiler toolset but using the newer Windows 8.0 SDK header set, but remember that version of D3DCompiler_*.DLL does not support runtime use or deployment on Windows XP.

For Shader Model 5 shaders, some HLSL language features require the DirectX 11.1 runtime. This uses the existing mechanism that indicates a shader requires the hardware support double-precision shaders for DirectX 11.0. This includes use of Feature Level 11.1 features (UAVs at every stage, 64 UAV slots), DirectX 11.1 runtime features (minimum-precision data-types), and new DirectX 11.1 optional hardware features (extended double-precision instructions, SAD4). A shader blob that indicates one of these requirements will fail to bind at runtime if the system doesn't support them. This information is included in the HLSL disassembly output, and all require some explicit feature usage in the HLSL source.

Porting Notes

Here's a handy table of equivalents for replacing legacy D3DX HLSL compiler related functions.

Presentations

High Level Shader Language (HLSL) Update—Introducing Version 5.0 (Gamefest 2008)

Symbolic Differentiation in GPU Shaders

Related: Getting Started with Direct3D 11, What's up with D3DCompiler_xx.DLL