Debug Output Functions

Microsoft DirectShow 9.0

Debug Output Functions

The Microsoft® DirectShow® base classes provide several macros for displaying debugging information.


**  Header:** Declared in Wxdebug.h; include Streams.h.

**  Library:** Use Strmbase.lib (retail builds) or Strmbasd.lib (debug builds).

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.


The debugging facilities in DirectShow can be fine-tuned to display specific types of debug information, while ignoring others. With this feature, you can pinpoint problems in particular areas of your code.

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:


In Windows Vista or later, they are located under the following path:


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>\<Module Name>\<Message Type>

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>\<Module 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.