D3DConfig: A new tool to manage DirectX Control Panel settings

Bill Kristiansen

The DirectX Control Panel (DXCpl.exe) has dutifully given developers the ability to configure Direct3D debug settings for nearly two decades.  But what started as a simple utility for controlling D3D debug output and driver type selection has struggled to keep up with modern DX12 debugging options.  In addition, the UI-based DXCpl doesn’t integrate into automation scripts, nor is it useful on scaled-down Windows platforms that do not support Win32-based user interfaces.

What we need is a command line tool

Introducing D3DConfig.exe in, a console app compatible with DXCpl.  The D3DConfig tool can display and modify the DXCpl settings from the comfort of your very own console window or batch script.  D3DConfig.exe is part of the Graphics Tools Feature-on-Demand and is available in the “20H1” Windows 10 Insider Preview (currently build 18970 in fast-ring).  If you already have Graphics Tools installed (you do if you are using D3D debug layers), then updating to 20H1 will automatically add D3DConfig to your system.  If you have been holding off installing Graphics Tools until you could change D3D settings from the command line, then your time has come.  Graphics Tools can be installed by using Windows 10 “Manage Optional Features” settings, or by running the following command:

> DISM /online /add-capability /capabilityname:tools.graphics.directx~~~~0.0.1.0

You can still use the DirectX Control Panel if you like.  D3DConfig recognizes DXCpl settings.  Similarly, the DXCpl reflects most D3DConfig settings.  At this time we have no plans to expand the DXCpl user interface.  This means that new settings are likely to be exposed only in the D3DConfig tool.  For example, DRED settings are only available in D3DConfig.

Examples

Like DXCpl, only registered apps are affected by the D3DConfig settings.  To list the currently registered apps, run:

> d3dconfig apps

apps
--------------------------------
  foo.exe
  bar.exe

To register an app:

> d3dconfig apps --add MyBuggyGame.exe

apps
--------------------------------
  MyBuggyGame.exe
  foo.exe
  bar.exe

Apps can also be registered using directory scope (yes, the terminating ‘\’ character is needed):

> d3dconfig apps --add g:\bin\games\

apps
--------------------------------
  g:\bin\games\
  MyBuggyGame.exe
  foo.exe
  bar.exe

One of the most common tasks done in DXCpl is to force the debug layer on.  The D3DConfig tool can do that too.

> d3dconfig debug-layer debug-layer-mode=force-on

debug-layer
----------------
debug-layer-mode=force-on

Break-on debug messages can also be controlled using D3DConfig.  In order to remain compatible with the DX Control Panel, this is a two-step process:

> d3dconfig message-break allow-debug-breaks=true

message-break
----------------
allow-debug-breaks=true

> d3dconfig message-break --add-id-12 722

message-break
----------------
Break-On D3D11 Message Ids:
  <none>
Break-On D3D12 Message Ids:
  722: D3D12_MESSAGE_ID_CREATERESOURCE_INVALIDMIPLEVELS

Of course, the –help option provides a full list of available options.

Feedback Requested

If you get a chance to try out D3DConfig let us know that you think.  At the moment, D3DConfig has a very simple design.  There certainly are some interesting bells and whistles we would like to add but customer feedback helps us prioritize our work.

Bill Kristiansen Principal Developer, DirectX

Follow