Debug Output Functions
[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]
The DirectShow Base Classes provide several macros for displaying debugging information.
| Function | Description |
|---|---|
| DbgCheckModuleLevel | Checks whether logging is enabled for the given message types and level. |
| DbgDumpObjectRegister | Displays information about active objects. |
| DbgInitialise | Initializes the debug library. |
| DbgLog | Sends a string to the debug output location, if logging is enabled for the specified type and level. |
| DbgOutString | Sends a string to the debug output location. |
| DbgSetModuleLevel | Sets the logging level for one or more message types. |
| DbgTerminate | Cleans up the debug library. |
| DisplayType | Sends information about a media type to the debug output location. |
| DumpGraph | Sends information about a filter graph to the debug output location. |
| GuidNames | Global array that contains strings representing the GUIDs defined in Uuids.h. |
| NAME | Generates a debug-only string. |
| NOTE | Sends a string to the debug output location. |
| REMIND | Generates a reminder at compile time. |
Registry Keys
The debug output function in DirectShow use a set of registry keys. The location of these registry keys depends on the version of Windows.
Prior to Windows Vista, the debugging keys are located under the following path:
HKEY_LOCAL_MACHINE\SOFTWARE\Debug
In Windows Vista or later, they are located under the following path:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DirectShow\Debug
For third-party filters, the location depends on which version of the DirectShow Base Classes was used to build the filter. The version included in the Windows SDK for Windows Vista uses the newer path. Previous versions used the older path.
In the remarks that follow, the label <DebugRoot> is used to indicate these two paths. Substitute the correct path, depending on the version of Windows or the version of the base classes.
Debug Logging
DirectShow defines several message types, shown in the following table.
| Value | Description |
|---|---|
| LOG_ERROR | Error notification. |
| LOG_LOCKING | Locking and unlocking of critical sections. |
| LOG_MEMORY | Memory allocation, and object creation and destruction. |
| LOG_TIMING | Timing and performance measurements. |
| LOG_TRACE | General call tracing. |
| CUSTOM1 through CUSTOM5 | Available for custom debug messages |
Each of the DirectShow debug logging functions specifies a message type and a log level. The debug message is displayed only when the current debugging level for that message type is equal to or greater than the level specified in the logging function. Otherwise, the message is ignored.
For example, the following code outputs the string "This is a debug message" if the LOG_TRACE level is 3 or higher:
DbgLog((LOG_TRACE, 3, TEXT("This is a debug message")));
Every module can set its own debugging level for each message type. (A module is a DLL or executable that can be loaded using the LoadLibrary function.) A module's debugging levels appear in the registry under the following key:
HKEY_LOCAL_MACHINE\<DebugRoot>\<ModuleName>\<MessageType>
where <Message Type> is the message type minus the initial "LOG_"; for example, LOCKING for LOG_LOCKING messages. When a module is loaded, the debug library finds the module's logging levels in the registry. If the registry keys do not exist, the debug library creates them.
A module can also set its own levels at run time, using the DbgSetModuleLevel function. To send a message to the debug output, call the DbgLog macro. The following example creates a level 3 message of type LOG_TRACE:
You can also specify global logging levels, with the following registry key:
\HKEY_LOCAL_MACHINE\<DebugRoot>\GLOBAL\<Message Type>
The debug library uses whichever level is greater, the global level or the module level.
Debug Output Location
The debug output location is determined by another registry key:
HKEY_LOCAL_MACHINE\<DebugRoot>\<Modile Name>\LogToFile
If the value of this key is Console, the output goes to the console window. If the value is Deb, Debug, Debugger, or an empty string, the output goes to the debugger window. Otherwise, the output is written to a file specified by the registry key.
Before an executable uses the DirectShow debug library, it must call the DbgInitialise function. Afterward, it must call the DbgTerminate function. DLLs do not need to call these functions, because the DLL entry point (defined in the base class library) calls them automatically.
Related topics