Debug Logging by Module Level

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.

A module is used in the Win32 sense, as in a .dll or .exe file that the Win32 LoadLibrary API can read. Thus, you can specify that you want debug output from your filter (for example, NewFilter.ax) and not any other.
A type is a bitmask that defines the kind(s) of informational string being presented. For example, timing information, errors, and memory allocations are some of the types of logging that can be individually controlled. For the complete list of types, see Types of Logging Information. You can combine types by using a bitwise-OR of their bitmasks; for example, (LOG_TRACE | LOG_ERROR).
A level is a DWORD value indicating the relative importance of this output, where zero is the most important level. A debug level of zero means that output is always sent to the debugger. Using zero as the debug logging level is encouraged only for major errors or events; otherwise, the logging of too much information might slow down the system. A request to log at a nonzero logging level is checked with the current debug level for this module; if it is less than or equal to the current level, it will be logged.

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, DirectShow loads 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.

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.

DbgCheckModuleLevel

Debug Logging by Module Level

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.

Syntax

BOOL WINAPI DbgCheckModuleLevel(
  DWORD Types,
  DWORD Level
  );

Parameters

Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level for this message, where zero means always log.

Return Value

Returns TRUE if these module types and level are to be logged; otherwise, returns FALSE.

Remarks

DbgCheckModuleLevel is ignored unless DEBUG is defined when the DirectShow headers are included.

DbgInitialise

Debug Logging by Module Level

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.

Syntax

void WINAPI DbgInitialise(
  HINSTANCE hInst
  );

Parameters

hInst
Module instance handle.

Remarks

DbgInitialise is ignored unless DEBUG is defined when the DirectShow headers are included. DbgInitialise also opens the debug output location, as described in Debug Output Location.

DbgLog

Debug Logging by Module Level

Invokes the DbgLogInfo function.

Syntax

void WINAPI DbgLog(
  DWORD Types,
  DWORD Level,
  const TCHAR *pFormat,
  ...
  );

Parameters

Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level for this message, where zero means always log.
pFormat
A printf-style format string, which must be in quotation marks.

Remarks

DbgLog is ignored unless DEBUG is defined when the DirectShow headers are included.

DbgLogInfo

Debug Logging by Module Level

Formats and sends a message to the debugger, if debug logging is enabled for the given message type and level.

Syntax

void WINAPI DbgLogInfo(
  DWORD Types,
  DWORD Level,
  const TCHAR *pFormat,
  ...
  );

Parameters

Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level for this message, where zero means always log.
pFormat
A printf-style format string, which must be in quotation marks.

Remarks

DbgLogInfo exists only in debug builds.

DbgSetModuleLevel

Debug Logging by Module Level

Changes the current logging level for message types whose bits are set in the Types parameter to Level. Other logging levels are unchanged.

Syntax

void WINAPI DbgSetModuleLevel(
  DWORD Types,
  DWORD Level
  );

Parameters

Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level that will be set for future messages. That is, future messages must have a level less than or equal to this value in order for the debug routines to log them.

Remarks

The DirectShow debug routines ignore DbgSetModuleLevel unless DEBUG is defined when the DirectShow headers are included.

DbgTerminate

Debug Logging by Module Level

Cleans the debug library.

Syntax

void WINAPI DbgTerminate( );

Remarks

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 DirectShow headers are included.

DisplayType

Debug Logging by Module Level

Displays the media type details on the debug log.

Syntax

void WINAPI DisplayType(
  LPSTR label,
  const AM_MEDIA_TYPE *pmtIn
  );

Parameters

label
Short message to be logged with the media type.
pmtIn
Pointer to the media type to be displayed.

Remarks

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 DirectShow headers are included.

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.

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.