Compiling HLSL

<stage>_<major>_<minor>: vs_5_0, ps_6_6, cs_6_0, ms_6_5, lib_6_3.

6.1 Target profiles & entry points

<stage>_<major>_<minor>: vs_5_0, ps_6_6, cs_6_0, ms_6_5, lib_6_3. Entry points can have any name (-E VSMain). Library targets (lib_6_x) contain many entry points identified by [shader("...")] attributes.

6.2 DXC command line

:: Basic
dxc -T ps_6_6 -E main shader.hlsl -Fo shader.cso

:: Debug build: no optimization, embedded debug info, PDB alongside
dxc -T ps_6_6 -E main -Zi -Qembed_debug -Od shader.hlsl -Fo shader.cso

:: Release with separate PDB (for PIX) and reflection stripped
dxc -T ps_6_6 -E main -O3 -Zi -Fd shader.pdb -Qstrip_reflect shader.hlsl -Fo shader.cso

:: Macros, include dirs, HLSL version, 16-bit types, warnings as errors
dxc -T cs_6_6 -E CSMain -D USE_SHADOWS=1 -I include -HV 2021 -enable-16bit-types -WX blur.hlsl -Fo blur.cso

:: Emit a C header with the bytecode array, or disassembly
dxc -T vs_6_0 -E main shader.hlsl -Fh shader_vs.h -Vn g_VS
dxc -T vs_6_0 -E main shader.hlsl -Fc shader_vs.asm

:: Vulkan SPIR-V
dxc -spirv -T ps_6_0 -E main -fspv-target-env=vulkan1.3 shader.hlsl -Fo shader.spv

6.3 FXC command line

fxc /T ps_5_0 /E main /O3 shader.hlsl /Fo shader.cso
fxc /T vs_5_0 /E main /Zi /Od /Fd shader.pdb shader.hlsl /Fo shader.cso
fxc /T ps_5_0 /E main shader.hlsl /Fc shader.asm     :: DXBC disassembly

6.4 Runtime compilation with the DXC API

#include <dxcapi.h>     // link dxcompiler.lib; ship dxcompiler.dll + dxil.dll
ComPtr<IDxcUtils> utils;       DxcCreateInstance(CLSID_DxcUtils, IID_PPV_ARGS(&utils));
ComPtr<IDxcCompiler3> compiler; DxcCreateInstance(CLSID_DxcCompiler, IID_PPV_ARGS(&compiler));
ComPtr<IDxcIncludeHandler> includes; utils->CreateDefaultIncludeHandler(&includes);

ComPtr<IDxcBlobEncoding> source;
utils->LoadFile(L"shader.hlsl", nullptr, &source);
DxcBuffer buf = { source->GetBufferPointer(), source->GetBufferSize(), DXC_CP_ACP };

LPCWSTR args[] = { L"shader.hlsl", L"-E", L"main", L"-T", L"ps_6_6", L"-Zi", L"-Qembed_debug" };
ComPtr<IDxcResult> result;
compiler->Compile(&buf, args, _countof(args), includes.Get(), IID_PPV_ARGS(&result));

ComPtr<IDxcBlobUtf8> errors;
result->GetOutput(DXC_OUT_ERRORS, IID_PPV_ARGS(&errors), nullptr);
if (errors && errors->GetStringLength()) OutputDebugStringA(errors->GetStringPointer());

ComPtr<IDxcBlob> dxil;
result->GetOutput(DXC_OUT_OBJECT, IID_PPV_ARGS(&dxil), nullptr);   // pass to the PSO

6.5 Preprocessor

HLSL uses a C preprocessor:

Useful predefined macros: __SHADER_TARGET_STAGE, __SHADER_TARGET_MAJOR, __SHADER_TARGET_MINOR, __HLSL_VERSION (e.g. 2021), __DXC_VERSION_MAJOR, __spirv__.

#include "common.hlsli"          // relative to file or -I directories
#define PI 3.14159265
#define SQR(x) ((x) * (x))

#if defined(USE_NORMAL_MAP) && USE_NORMAL_MAP
    float3 N = SampleNormalMap(uv);
#else
    float3 N = normalize(input.normal);
#endif

#ifdef __SHADER_TARGET_MAJOR       // predefined by DXC/FXC
#if __SHADER_TARGET_MAJOR >= 6
    // wave intrinsics allowed
#endif
#endif

#ifdef __spirv__                    // defined by DXC when compiling with -spirv
    [[vk::binding(0, 0)]]
#endif
Texture2D gTex : register(t0);

#pragma once                        // include guard (supported by DXC)
#pragma pack_matrix(row_major)      // default matrix packing for following declarations

6.6 Comments

// single line
/* multi
   line */