Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
When a device error such as a GPU timeout occurs, the DirectX runtime writes a DirectX Dump File for the application. This article covers the requirements for generating dump files, and the APIs and settings you can use to control what they contain. For an introduction to dump files, see DirectX Dump Files.
Requirements
To generate DirectX Dump Files, you need:
- Agility SDK 1.620 or later. For more information, see DirectX 12 Agility SDK.
- An up-to-date version of Windows. To get the latest updates, go to Settings > Windows Update and select Check for updates.
- A graphics driver that supports DirectX Dump Files, for full dump files. Without driver support, the runtime still creates partial dump files that don't include hardware state or driver data. Contact your GPU vendor about driver support.
Check for support
To check whether the OS and driver support DirectX Dump Files, call ID3D12Device::CheckFeatureSupport with D3D12_FEATURE_DUMP_FILE. The returned D3D12_FEATURE_DATA_DUMP_FILE structure reports:
SupportedByOS: whether the OS creates a dump file when a device error occurs.DumpFileDriverTier: the level of dump file support in the driver.DumpFileDriverOptionsMask: which driver options the driver supports.
Configure dump files in your application
Configure dump files in your application through the ID3D12DeviceDumpFile interface. Get it by calling QueryInterface on your ID3D12Device. For details about each method, see the D3D12: DirectX Dump Files specification.
To test different settings without changing your code, you can also override them in PIX or D3DConfig. For more information, see Override dump file settings without changing code.
Choose which driver data to collect
Drivers that support DirectX Dump Files can track additional data while your application runs. More data makes dumps more useful, but it can lower the frame rate or increase the dump file size. To choose which data to collect, call ConfigureDumpFile with a combination of D3D12_DUMP_FILE_DRIVER_OPTIONS flags.
The overhead level sets the overall tradeoff:
| Option | Description |
|---|---|
D3D12_DUMP_FILE_DRIVER_OPTION_NO_OVERHEAD |
Collects driver data with no runtime cost. Suitable for broad use. |
D3D12_DUMP_FILE_DRIVER_OPTION_MEDIUM_OVERHEAD |
Collects additional diagnostic data with a moderate performance impact. |
D3D12_DUMP_FILE_DRIVER_OPTION_HIGH_OVERHEAD |
Collects the most detailed GPU and driver state, at the cost of higher runtime overhead. |
You can also turn on these options individually:
| Option | Description |
|---|---|
D3D12_DUMP_FILE_DRIVER_OPTION_SHADER_REGISTERS |
Collects shader vector general-purpose registers. |
D3D12_DUMP_FILE_DRIVER_OPTION_RESOURCES |
Tracks resources and collects existing and recently deleted resources when a crash occurs. |
D3D12_DUMP_FILE_DRIVER_OPTION_EVENT_MARKERS |
Tracks application and driver event markers as the application runs. |
D3D12_DUMP_FILE_DRIVER_OPTION_NO_DATA |
Collects no data from the driver. Turns off the other options. |
Which options are available depends on the driver. To check, use DumpFileDriverOptionsMask as described in Check for support.
Add application data and get the file path
Call SetDumpFileCallbacks to register two callbacks:
- D3D12_DUMPFILEBEGINCALLBACK runs when the runtime starts writing the dump file. In this callback, call AddBlobToDumpFile to add up to 2 MB of your own data and metadata, such as the game state or the current level. PIX shows this data in the Application Blobs view.
- D3D12_DUMPFILEENDCALLBACK runs after the dump file is written, and receives its path. Use it to send the file to your crash collection pipeline. The file is available until the callback returns, even if you don't retain it.
Keep dump files on disk
By default, the runtime deletes the dump file after it finishes processing the device error. To keep it on disk, for example so you can open it in PIX on your development machine, call RetainDumpFile. This setting lasts until you turn it off, the device is re-created, or the application closes.
Retained dump files are saved in %LOCALAPPDATA%\CrashDumps, using this file name format:
<ExecutableNameWithoutExtension>-yyyy-mm-dd-hh-mm-ss.dxdmp
Include PIX markers in dump files
PIX uses PIX markers to rebuild the frame and to fill the Event List view, so markers make it much easier to find where the GPU was when it crashed. By default, the runtime doesn't pass PIX markers to the driver. To include them in dump files, turn on retail annotation mode:
- Check for support by calling
CheckFeatureSupportwithD3D12_FEATURE_USER_DEFINED_ANNOTATION. For more information, see D3D12_FEATURE_DATA_USER_DEFINED_ANNOTATION. - If the driver supports it, call
SetUserDefinedAnnotationModeon ID3D12DeviceTools2 withD3D12_USER_DEFINED_ANNOTATION_MODE_DRIVER_RETAIL.
For more information, see D3D12: PIX Markers. To turn on retail annotations without changing your code, see Configure dump file settings in PIX. To add PIX markers to your application, see WinPixEventRuntime.
Override dump file settings without changing code
PIX and D3DConfig can override the dump file settings for an application without changing its code. Use them to try different settings while you investigate a crash. The runtime reads these settings only when the device is created, so restart your application after you change them.
Configure dump file settings in PIX
- In PIX, connect to the machine that runs your application.
- On the connection toolbar, select Connection Settings.
- On the DirectX Options tab, optionally select your application's executable to apply the settings to only that application.
- Under Device Options, set Retain Dump File and Force Driver Retail Annotations as needed. Force Driver Retail Annotations passes PIX markers to the driver, like retail annotation mode.
- Under Dump File Driver Options, choose the Overhead Level and the data collection options.
- Under DRED Options, turn on Auto Breadcrumbs and Page Faults to include DRED breadcrumbs and page fault data in the dump file.
- Restart your application.
Configure dump file settings with D3DConfig
D3DConfig settings apply only to applications in its app list. To add your application and set dump file options, run:
d3dconfig apps --add MyGame.exe
d3dconfig device retain-dump-file=true
d3dconfig device dump-file-driver-options=65
The value of dump-file-driver-options combines D3D12_DUMP_FILE_DRIVER_OPTIONS flags. For example, 65 (0x41) is D3D12_DUMP_FILE_DRIVER_OPTION_NO_OVERHEAD | D3D12_DUMP_FILE_DRIVER_OPTION_EVENT_MARKERS. Restart your application after you change these settings.
For more information about D3DConfig, see D3DConfig: A new tool to manage DirectX Control Panel settings.
Trigger a dump file from a shader
To capture GPU state when a shader hits an unexpected condition, call the HLSL DebugBreak() intrinsic. When a pipeline state or state object is created with the D3D12_PIPELINE_STATE_FLAG_DEBUG_BREAK_ALWAYS_BREAK or D3D12_STATE_OBJECT_FLAG_DEBUG_BREAK_ALWAYS_BREAK flag, DebugBreak() halts the shader and triggers the same TDR flow as a real GPU crash, so the runtime creates a dump file.
Note
DebugBreak() requires Shader Model 6.10. As of October 2026, Shader Model 6.10 is available only in preview versions of the Agility SDK. To check for support, call CheckFeatureSupport with D3D12_FEATURE_DEBUG_BREAK.
For more information, see D3D12: Debug Break.