Edit

Customize Debug Output with ID3D10InfoQueue (Direct3D 10)

  • Article

The information queue is managed by an interface (see ID3D10InfoQueue Interface) that stores, retrieves, and filters debug messages. The queue consists of: a message queue, an optional storage filter stack, and a optional retrieval filter stack. The storage-filter stack can be used to filter the messages you want stored; the retrieval-filter stack can be used to filter the messages you want stored. Once you have filtered a message, the message will be printed out to the debug window and stored in the appropriate stack.

In general:

Registry Controls

Use registry keys to adjust filter settings, adjust break points, and to mute the debug output. The debug layer will check these paths for registry keys; the first path found will be used.

  1. HKCU\Software\Microsoft\Direct3D\<user-defined subkey>
  2. HKLM\Software\Microsoft\Direct3D\<user-defined subkey>
  3. HKCU\Software\Microsoft\Direct3D

Where:

  • HKCU stand for HKEY_CURRENT_USER, and HKLM stand for HKEY_LOCAL_MACHINE.
  • <user-defined subkey> is an arbitrary name to store debug settings for an application

Filtering Debug Messages using Registry Keys

If the registry contains an InfoQueueStorageFilterOverride key (and is non-zero), then messages (and debug output) can be filtered by adding the following registry controls.

  • DWORD Mute_CATEGORY_* - Debug output if this key is non-zero.
  • DWORD Mute_SEVERITY_* - Debug output is disabled if this key is non-zero.
  • DWORD Mute_ID_* - Message name or number can be used for * (just like for BreakOn_ID_* described earlier). Debug output is disabled if this key is non-zero.
  • DWORD Unmute_SEVERITY_INFO - Debug output is ENABLED if this key is non-zero. By default when InfoQueueStorageFilterOverride is enabled, debug messages with severity INFO are muted - therefore for this key allows INFO to be turned back on.

These controls change whether a message is recorded or displayed; they do not affect whether an API passes or fails.

Setting Break Conditions using Registry Keys

Applications can be forced to break on a message using the following registry keys.

EnableBreakOnMessage - This key enables breaking on messages (and causes i's SetBreakOnCategory()/SetBreakOnSeverity()/SetBreakOnID() settings to be ignored). The actual messages to break on are defined using one or more BreakOn_* values defined below.

  • BreakOn_CATEGORY_* - Break on any message passing through the storage filters. * is one of the D3D10_MESSAGE_CATEGORY messages.
  • BreakOn_SEVERITY_* - Break on any message passing through the storage filters. * is one of the D3D10_MESSAGE_SEVERITY_ messages.
  • BreakOn_ID_* - Break on any message passing through the storage filters. * is one of the D3D10_MESSAGE_ID_ messages or can be the numerical value of the error enumeration. For example, Suppose the message with ID "D3D10_MESSAGE_ID_HYPOTHETICAL" had the value 123 in the D3D10_MESSAGE_ID enumeration. In this case, creating the value BreakOn_ID_HYPOTHETICAL=1 or BreakOn_ID_123=1 would both accomplish the same thing - break when a message having ID D3D10_MESSAGE_ID_HYPOTHETICAL is encountered.

Muting Debug Output using Registry Keys

Debug output can be muted using a MuteDebugOutput key. The presence of this value in the registry forces override of the InfoQueue's ID3D10InfoQueue::SetMuteDebugOutput method. MuteDebugOutput stops messages that pass the storage filter from being sent to debug output.

Disabling Debug Layer Messages

Debug layer messages can be disabled individualy or as a group at runtime by specifying filters using ID3D10InfoQueue::AddStorageFilterEntries. The pFilter argument to ID3D10InfoQueue::AddStorageFilterEntries takes a D3D10_INFO_QUEUE_FILTER structure that contains an allow list and a deny list. The allow and deny lists are described by D3D10_INFO_QUEUE_FILTER_DESC structures that allow filtering to be specified by catergory, severity and individual message ID.

The following code is an example of setting up the ID3D10InfoQueue Interface to deny the D3D10_MESSAGE_ID_DEVICE_DRAW_INDEX_BUFFER_TOO_SMALL message.

  //retrieve the ID3D10InfoQueue from a Direct3D device created with the D3D10_CREATE_DEVICE_DEBUG flag
  ID3D10InfoQueue * pInfoQueue;
    g_pd3dDevice->QueryInterface( __uuidof(ID3D10InfoQueue),  (void **)&pInfoQueue );
    
  //set up the list of messages to filter
    D3D10_MESSAGE_ID messageIDs [] = { D3D10_MESSAGE_ID_DEVICE_DRAW_INDEX_BUFFER_TOO_SMALL };
    
  //set the DenyList to use the list of messages
    D3D10_INFO_QUEUE_FILTER filter = { 0 };
    filter.DenyList.NumIDs = 1;
    filter.DenyList.pIDList = messageIDs;
    
  //apply the filter to the info queue
    pInfoQueue->AddStorageFilterEntries( &filter );

API Layers

API Features (Direct3D 10)