Compilation Flags & Debugging

FXC equivalents: /Od, /O0–/O3, /Zi, /Fd, /Zpr, /WX, /Gfa (avoid flow control), /Gfp (prefer flow control), /Gec (backward compatibility), /Ges (strict mode), /all_resources_bound, /enable_unbounded_descriptor_tables.

38.1 Important DXC flags

-T <profile> / -E <entry> target profile, entry point -O0 … -O3, -Od optimization level; -Od disables optimizations for debugging generate debug info embed debug info (PDB) in the shader blob -Fd <file or dir> write a separate PDB (PIX finds it by shader hash) -Zss / -Zsb compute the shader hash from source+flags / binary only

-Qstrip_debug, -Qstrip_reflect, -Qstrip_rootsignature remove parts from the output blob -Zpr / -Zpc default row-major / column-major matrix packing -HV <2016|2018|2021> HLSL language version native 16-bit types (SM 6.2+) -WX, -Wno-<warning> warnings as errors, disable a warning strict IEEE floating point -denorm <any|preserve|ftz> denormal mode (SM 6.2+) allow optimizations assuming every declared resource is bound resources may alias (disables some optimizations) -D NAME=VALUE, -I dir macros, include paths

-Fo, -Fc, -Fh, -Vn, -Fe, -Fre output object, assembly, C header, header variable name, warnings/errors file, reflection file -rootsig-define NAME take the root signature from a macro -spirv and -fspv-*, -fvk-* SPIR-V generation options compile time breakdown

38.2 Common compiler errors & warnings

Message (abridged) implicit truncation of vector type assigning float4 to float3 swizzle explicitly: v.xyz

use of potentially uninitialized variable some path doesn't assign initialize (= 0 or (T)0)

gradient instruction used in a loop with varying iteration / divergent control flow Sample in a dynamic loop/branch

SampleLevel/SampleGrad, or hoist derivatives cannot map expression to vs_5_0 instruction set unsupported op for the profile raise the profile or rewrite

array dimensions must be literal scalar expressions runtime-sized local array use a constant size 'X': undeclared identifier in a stage missing include / macro mismatch check #if paths and permutations

Semantic 'SV_Target' is invalid as vs output wrong stage semantic

signature mismatch at PSO creation (debug layer) VS output ≠ PS input share one struct definition Root Signature doesn't match shader uses a register not in the root signature update RS or bindings

38.3 Runtime debugging

DRED (Device Removed Extended Data): breadcrumbs and page-fault info after a TDR/device removal (ID3D12DeviceRemovedExtendedDataSettings).

PIX on Windows: take a GPU capture → select a draw/dispatch → *Debug Pixel* / *Debug Vertex* / *Debug Thread* to step through HLSL source with variable values; *Timing captures* and per-event counters for performance; *Shader Edit & Continue* to tweak a shader in the capture. Requires -Zi debug info (embedded or PDB search path) for source-level debugging.

RenderDoc: capture D3D11/D3D12/Vulkan frames; inspect pipeline state, textures, buffers; debug pixels/vertices/compute threads (with source when debug info is present).

Vendor tools: Nsight Graphics (shader profiler, ray tracing inspector), Radeon GPU Profiler/Analyzer (ISA, occupancy, VGPR usage), Intel GPA.

Shader-side techniques: output debug colors; write values to a debug RWStructuredBuffer and read back; draw debug lines from a UAV-appended line buffer; NaN checks (if (any(isnan(v))) return float4(1, 0, 1, 1);).

// D3D12 debug layer + GPU-based validation (debug builds only, before device creation)
ComPtr<ID3D12Debug1> debug;
if (SUCCEEDED(D3D12GetDebugInterface(IID_PPV_ARGS(&debug))))
{
    debug->EnableDebugLayer();
    debug->SetEnableGPUBasedValidation(TRUE);     // catches out-of-bounds descriptor indexing, bad states
}
// After device creation: break on errors
ComPtr<ID3D12InfoQueue> iq;
if (SUCCEEDED(device.As(&iq))) iq->SetBreakOnSeverity(D3D12_MESSAGE_SEVERITY_ERROR, TRUE);