D3D12 Debug Object Auto-Naming

Bill Kristiansen

Great. The D3D12 Debug Layer has just helpfully reported, “An ID3D12Resource object (‘Unnamed ID3D12Resource’) referenced in a command list (‘Unnamed ID3D12GraphicsCommandList’) was deleted prior to executing the command list…”. Getting past the fact that the application never called ID3D12Object::SetName to provide useful names for the resource and command list (no judgement, it happens), you are now left to figure out which objects these were with very limited data. If only there was something more to go on than just, “Unnamed ID3D12Resource”.

As of Windows 10 Release Preview 20236 (the latest available Insider Fast build as of this writing), there is now an option to enable automatic naming of D3D12 objects. Debug Object Auto-Names are unique, and descriptive, and are easy to enable programmatically or using d3dconfig. The related API’s also require Windows Insider Preview SDK 20236.

With Debug Object Auto-Naming enabled, the previously mentioned message would be something more like, “An ID3D12Resource object (‘Unnamed Committed ID3D12Resource: Format=R32_FLOAT, Dimension=Texture1D, Width=128, MipLevels=1, ArraySize=1, UniqueId=0x0000000000567231’ ) referenced in a command list (‘Unnamed ID3D12GraphicsCommandList: Type=Direct, UniqueId=0x0000000000566145’) was deleted prior to executing the command list…”. Not only is this telling us more about the offending resource and command list, this is also reporting a ‘UniqueId’.

So, hidden in this new feature is another new feature: D3D12 assigns a locally-unique id (LUID) to every D3D12 DeviceChild object at create time. This id can be retrieved using GetPrivateData with the REFGUID value WKPDID_D3D12UniqueObjectId. Note, these ID’s are going to be unique from one run to the next, even for the exact same object. Still, if you happen to have this ID in your execution log then it can be easily cross-referenced from the auto-name.

Due to memory and performance overhead, Debug Object Auto-Naming is disabled by default. It can be enabled programmatically using the new interface method:

void ID3D12Debug5::SetEnableAutoDebugName(BOOL bEnable)

Alternatively, Debug Object Auto-Naming can be enabled using d3dconfig:

c:\users\bad_with_names>d3dconfig device auto-debug-name=forced-on

To avoid application compatibility issues, Debug Object Auto-Names are not retrievable using public ID3D12Object::GetPrivateData(). Debug Object Auto-names will only appear in DRED output and Debug Layer messages, and only when an object has not been assigned a debug object name. Note that the Debug Object Auto-Name feature is not intended to replace developer-assigned names. In most cases, the app developer can provide a much more meaningful name, and there is nothing in the Auto-Name that cannot be replicated by app developers.

Bill Kristiansen Principal Developer, DirectX

Follow