Some of the more conventional debug logging techniques provided by Microsoft® DirectShow™ (like DbgOutString) are monolithic. That is, they are either all on (in a debug build) or all off (in other builds). DirectShow provides other debug logging techniques that give much finer control in turning logging on and off. These pinpoint techniques make it easy to isolate and debug individual modules without seeing other people's extraneous debug output, or suffering the possible performance hit when too much information is logged. You can control the pinpoint DirectShow debug routines by module, by type, and by level, as defined in the following list.
You can set the initial debug levels for a given test run. For each module you want to control, you can store a debugging level for each of the types in the registry. For a list of the registry names to use, see Registry Setting of Debug Levels by Type.
You call the DbgLog macro to attempt to log some piece of data, which might or might not actually be logged, depending on the current debug levels. When you call DbgLog, you supply one or more type flags (possibly combined by bitwise-OR), the debug level, and the data to be logged in the form of a printf-style format string, which can refer to optional parameters. (By definition, C/C++ macros allow only a fixed number of parameters. In your call to DbgLog, you enclose all parameters in an extra set of parentheses. This is a common C/C++ idiom.)
Following are some examples of calling DbgLog. The first example is a simple call with one type and no optional parameters; the second call gives two types and no optional parameters; the third call has two types and includes an optional parameter.
DbgLog((LOG_TRACE, 1, TEXT("CVidCap created"))); DbgLog((LOG_ERROR|LOG_TRACE, 1, TEXT("Driver failed to connect") ) ); DbgLog(( LOG_ERROR|LOG_TRACE, 2 , TEXT("Driver disconnect: %x"), bDriverDisconnected) );
Each module has its own current debug level for each type. These current levels are initialized from the registry by DbgInitialise. For dynamic-link libraries (DLLs) linking to strmbase.lib, the DbgInitialise function is called automatically when the DLL is loaded. Executables must call DbgInitialise explicitly, with the module instance handle given to them through the WinMain entry point. An executable must also call DbgTerminate when finished to clean up the resources the debug library uses. This cleanup is also done automatically for DLLs.
For more information about how the debug output location is chosen, see Debug Output Location.
Types of Logging Information
A DWORD value is used to indicate types of information to be logged, as indicated by the following bitmasks. Some operations can be performed on multiple types simultaneously, by using bitwise-OR to combine the bitmasks; for example, (LOG_TRACE | LOG_ERROR).
LOG_TIMING | Timing and performance measurements. |
LOG_TRACE | General step and call tracing. |
LOG_MEMORY | Memory and object allocation/destruction. |
LOG_LOCKING | Locking/unlocking of critical sections. |
LOG_ERROR | Debug error notification. |
Registry Setting of Debug Levels by Type
For every module and executable, Microsoft DirectShow will load a debugging level key for each of the five types. The level keys are stored in the registry under the HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\<KeyName> key values. The allowable values for <KeyName> in the registry are: "TIMING", "TRACE", "MEMORY", "LOCKING", and "ERROR". Note that the values read from the registry are all read during initialization; DirectShow does not look for update notifications while it runs. If the values change, you must restart the application to pick them up.
Name | Description |
DbgCheckModuleLevel | Checks if given types and level are being logged. |
DbgInitialise | Initializes the debug library with the module handle and sets the current logging levels accordingly. |
DbgLog | Logs a message for given types and level. (Ignored except in debug builds.) |
DbgLogInfo | Logs a message for given types and level. (Provided only in debug builds.) |
DbgSetModuleLevel | Changes the logging level for given types. |
DbgTerminate | Cleans up the debug library. |
DisplayType | Displays the given media type. |
Checks whether logging is enabled for the given message types and level. If logging is enabled for any of the given types at the level given, DbgCheckModuleLevel indicates that the message should be logged.
BOOL WINAPI DbgCheckModuleLevel(
DWORD Types,
DWORD Level
);
Returns TRUE if these module types and level are to be logged; otherwise, returns FALSE.
DbgCheckModuleLevel is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.
Initializes the debug library. Among other things, it sets the current logging levels to correspond to the levels that are appropriate for the indicated module.
void WINAPI DbgInitialise(
HINSTANCE hInst
);
DbgInitialise is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included. DbgInitialise also opens the debug output location, as described in Debug Output Location.
Invokes the DbgLogInfo function.
void WINAPI DbgLog(
DWORD Types,
DWORD Level,
const TCHAR *pFormat,
...
);
DbgLog is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.
Formats and sends a message to the debugger, if debug logging is enabled for the given message type and level.
void WINAPI DbgLogInfo(
DWORD Types,
DWORD Level,
const TCHAR *pFormat,
...
);
DbgLogInfo exists only in debug builds.
Changes the current logging level for message types whose bits are set in the Types parameter to Level. Other logging levels are unchanged.
void WINAPI DbgSetModuleLevel(
DWORD Types,
DWORD Level
);
The DirectShow debug routines ignore DbgSetModuleLevel unless DEBUG is defined when the Microsoft DirectShow headers are included.
Cleans the debug library.
void WINAPI DbgTerminate( );
This is called to clean up the resources the debug library uses. If you called DbgInitialise, then you should call DbgTerminate. For example, DbgTerminate deletes the object register list. (For more information about using that aspect of debugging, see Object Register Debugging.) DbgTerminate also closes the debug output location, as described in Debug Output Location. DbgTerminate is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.
Displays the media type details on the debug log.
void WINAPI DisplayType(
LPSTR label,
const AM_MEDIA_TYPE *pmtIn
);
The major types and subtypes are converted into strings for display. DisplayType also asks the base classes for a string description of the subtype, so MEDIASUBTYPE_RGB565 becomes RGB 565 16-bit. In addition, it displays the fields in the BITMAPINFOHEADER structure; this should succeed because input types are not accepted unless the format is big enough.
DisplayType is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.