Untitled

Direct3D 11 Programming Tip #7: Using FXC

This tip is actually one that I use frequently during my shader development, and is actually applicable to D3D9 and D3D10 as well as D3D11. For those of you who haven't heard of it before, FXC is a command line tool that comes with the DXSDK. It can be found in the following directory if you use the standard install directory for the SDK (and use the C drive for development...):

C:\Program Files\Microsoft DirectX SDK (March 2009)\Utilities\bin\x86

This is the shader compiler tool that can be used to compile a shader (or effect for D3D9/10, and later D3D11) into a bytecode form similar to what you can do with the built in shader compilation functions of the D3D runtime. This is fine if you want to pre-compile your shaders to speed up the loading of your game, but it is also handy if you want to test if a shader is compileable or if there are errors that need to be taken care of first. In addition, you can also output a color coded html file of the assembly output of your shader to help you understand what pains the GPU is going through to implement your HLSL code! This also let's you check the shader without starting up your application, which can save you lots of time...

Let's take a look at a typical command sequence and see what options we need to do the following:

- Test compilation
- Get an error message if compilation failed (so you know what to fix!)
- Produce the color coded HTML file to check out your good work

Normally I take a copy of the FXC.exe file and put it into a directory with my shaders. Then I get to the command line, and move to the same directory. If we use the shader from last time as an example, then we would call FXC like so:

fxc InvertColorCS.hlsl /T cs_5_0 /E CSMAIN /Zi /Cc /Fc InvertColorCS.html

We'll run through each parameter one at a time. First is the call to FXC, followed by the source file to be operated on. Next is /T which represents the target shader model that you are compiling against. After that is /E which declares the shader's main function name (E is for entry point). The last three parameters are all related to the output file: /Zi turns on the debugging information, /Cc produces color coded output, and /Fc let's you specify the output file name for the HTML file.

Running this will either dump an error message to the command line output, or tell you that it compiled and create your output listing. The sample output from last time would look something like this (I had to monkey with the colors to get them to look right on a light colored background, so the color scheme is actually a bit nicer in the real output...):

//
// Generated by Microsoft (R) HLSL Shader Compiler 9.26.952.2844
//
//
// fxc InvertColorCS.hlsl /T cs_5_0 /E CSMAIN /Zi /Cc /Fc InvertColorCS.html
//
//
// Resource Bindings:
//
// Name Type Format Dim Slot Elements
// ---------------- ---------- ------- ----------- ---- --------
// InputMap texture float3 2d 0 1
// OutputMap UAV float3 2d 0 1
//
//
//
// Input signature:
//
// Name Index Mask Register SysValue Format Used
// -------------------- ----- ------ -------- -------- ------ ------
// no Input
//
// Output signature:
//
// Name Index Mask Register SysValue Format Used
// -------------------- ----- ------ -------- -------- ------ ------
// no Output
cs_5_0
dcl_globalFlags refactoringAllowed
dcl_resource_texture2d (float,float,float,float) t0
dcl_uav_typed_texture2d (float,float,float,float) u0
dcl_input vThreadGroupID.xy
dcl_input vThreadIDInGroup.xy
dcl_temps 2
dcl_thread_group 20, 20, 1

#line 18 "C:\Users\Jason\Documents\FXC\InvertColorCS.hlsl"
mov r0.zw, l(0,0,0,0)
imad r0.xy, vThreadGroupID.xyxx, l(20, 20, 0, 0), vThreadIDInGroup.xyxx // texturelocation<0,1>
ld_indexable(texture2d)(float,float,float,float) r1.xyz, r0.xyzw, t0.xyzw // Color<0,1,2>
add r1.xyzw, -r1.xyzx, l(1.000000, 1.000000, 1.000000, 1.000000)
store_uav_typed u0.xyz, r0.xyyy, r1.xyzw // OutputMap<0>

#line 12
ret
// Approximately 6 instruction slots used


There are quite a few more options that you could take a look at by running 'fxc /?' if you are interested in seeing what else it can do. The output gives you all kinds of good detail about the shader itself, as well as the resources that you are required to bind to it. Personally, I have learned quite a bit from looking around in this output file and I would recommend you do the same!

Since this is a command line tool, it can be somewhat tedious to type in all of the commands in an iterative manner. Instead of typing it all in every time I want to check my shader, I just throw the whole thing into a batch file instead. Then you just edit the shader, run the batch file and repeat as necessary until you get what you want.