Debug Output Functions
| Microsoft DirectShow 9.0 |
Debug Output Functions
The Microsoft® DirectShow® base classes provide several macros for displaying debugging information.
Requirements
** 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. |
Remarks
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:
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>\<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.