Shaders and the FXC Shader Compiler

There are several shaders in Direct3D and in the Xbox One GPU. The FXC shader compiler has options for HLSL tools and for PIX.

To see an alphabetical list of these Xbox extension compiler flags, in the Index, see “compiler flags”.

• Types of Shaders
• Compiling Shaders Using FXC
• Disabling Pre-compilation
• Shader Registers
• Additional Shader Objects
• Read-only Shader defines
• Miscellaneous Shader Options

Types of Shaders

Types of Shaders in Direct3D

There are six types of shaders implemented in DirectX 11.1 and supported by the Xbox One XDK. The six shader types are the logical components used in Direct3D.

Types of Shaders on the GPU

There are seven shader types on the Xbox One GPU:

There is no Domain shader on the GPU.

Compiling Shaders Using FXC

Shaders are pre-compiled by default by the Xbox One XDK tools that add to Visual Studio on the Development PC. The pre-compiled shaders are loaded by the Xbox One User Mode graphics driver on the Xbox One hardware when the title is being instantiated. Pre-compiling avoids the one-time runtime cost of compiling the shaders to GPU instructions.

With each XDK release, shader code should be re-compiled, because all precompiled shaders from previous releases become obsolete. If the shaders are not re-compiled an error will not occur but this will provoke the run-time cost of compilation. The fxc/dumpbin utility has been updated to print out disassembled pre-compiled shaders that may be embedded in the output of d3dcompiler.

The tool for pre-compiling shaders is FXC, which is the Microsoft Direct3D Shader Compiler. FXC for Xbox One provides similar functionality to the tool with the same name for Direct3D on Windows, but the tools are not the same and cannot be used interchangeably. FXC for Windows is described in Effect-Compiler Tool.

By default, FXC.exe is installed to the following folder:

C:\Program Files (x86)\Microsoft Durango XDK\[release]\xdk\FXC\amd64  

Note [release] is the release number (e.g. 161002 for October 2016 QFE 2).

FXC for Xbox One has the same options as the tool for Windows, with the addition of the following switches:

The following table gives examples of the use of FXC to set an internal flag.

Fxc cs.hlsl –T cs_5_0 –D__XBOX_CONTROL_NONIEEE=0

Fxc cs.hlsl –T cs_5_0 –D__XBOX_CONTROL_NONIEEE=1

Fxc cs.hlsl –T cs_5_0 –D__XBOX_CONTROL_NONIEEE

Fxc cs.hlsl –T cs_5_0 –D__XBOX_CONTROL_NONIEEE=999

Within an HLSL source file, set flags using the following syntax:

#define __XBOX_CONTROL_NONIEEE 0    // sets internal flag to 0
#define __XBOX_CONTROL_NONIEEE 1    // sets internal flag to 1
#define __XBOX_CONTROL_NONIEEE      // sets internal flag to 1
#define __XBOX_CONTROL_NONIEEE 9999 // setting is IGNORED since this flag requires value of 0 or 1  

The code module defined by d3dcompiler.h is used both by running titles to compile shaders to GPU instructions, and by the FXC tool to precompile the shaders. There are significant code changes to d3dcompiler between the Windows and Xbox One version of d3dcompiler. In particular, FXC takes a number of parameters specified in defines, which are often passed through to d3dcompiler.

For reference, the Windows version of d3dcompiler is documented here D3DCompile function.

Disabling Pre-compilation

There are a range of flags that can be used to disable the pre-compilation of a shader stage. The Direct3D software shaders listed above often map to a single hardware shader stage, though the following table shows some of the more complex mappings.

This means that if, for example, the LS stage of tessellation is disabled, then pre-compilation of the other hardware stages will still be generated.

Disabling pre-compilation reduces the size of the code generated and could potentially increase efficiency. For example, if a Vertex shader will never be used with tessellation, then pre-compiling the LS is inefficient because the LS code will never be used. Set the following flags to 1 to disable the various shader stages, for example, to disable the LS stage in the game.hlsl shader:

Fxc game.hlsl –T cs_5_0 –D __XBOX_DISABLE_PRECOMPILE_LS=1  

Alternatively, provide these flags to the d3dcompilers definearray. Do not set the flags in source code.

Shader Registers

The following flags define control behavior of the shader compiler by lowering the number of estimated lifetimes that will be tolerated by the shader compiler’s pre-allocation instruction scheduler. These limits are not a hard rule and merely guide the scheduler’s heuristics, the shader compiler will use more registers if necessary.

By restricting the instruction scheduler you can prevent extra overlapping lifetimes from being created, which can help reduce the number of registers that are needed to execute the shader. By lowering the number of registers that are required by a shader, the shader’s occupancy can be increased (that is, more copies of the same shader can run at the same time).

These flags are used internally by both __XBOX_ATTEMPT_WAVE_WIDENING and __XBOX_WAVESIM_ITERATION (see below). Both of these flags evaluate a range of settings to find a likely improvement.

To set a shader flag, enter it when running the Fxc compiler. For example, to set the VGPR limit to 64:

Fxc game.hlsl –T cs_5_0 –D __XBOX_REGALLOC_VGPR_LIMIT=64  

Note Register thresholds are also used by the scheduler, so sometimes the compiler will not use all the registers when the threshold is lowered.

Additional Shader Objects

If any of the following flags are set, additional shader objects will be produced. For example, if a vertex shader is compiled with the __XBOX_ENABLE_PSPRIMID define, the HLSL tools will produce both a VS and a VS_PSPRIMID shader object. If it is known that the non-psprimid shader object is not needed, its production can be disabled by defining __XBOX_DISABLE_PRECOMPILE_VS.

All produced shader objects and their types can be seen in the disassembly listing using the FXC tool (for example: fxc /dumpbin).

Read-only Shader defines

The following defines are made inside the D3DCompiler and are there for the developer to rely on. They should never be set by a developer.

Miscellaneous Shader Options

The following miscellaneous flags are available. Long flag names are wrapped into two lines.

RWTexture2D <uint2> uav;
[numthreads(8,8,1)]
void main(uint3 invoc : SV_GroupThreadID)
{
  uav[invoc.xy] = uav[invoc.xy] + uint2(1,2);
}

-D__XBOX_PDBFILENAME="\"foo bar\""

See also

D3DCOMPILE Constants

D3Dcompiler Intrinsics

GPU and Shader Acronyms