Microsoft DirectX 8.0 |
The Microsoft® DirectShow® base classes provide several macros for displaying debugging information.
Declaration: Wxdebug.h
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. DirectShow defines several message types, shown in the following table.
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. |
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 Microsoft® Win32® LoadLibrary function.) A module's logging level for a given message type appears in the registry under the following key:
\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\<Message Type>
<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 looks up the module's logging levels in the registry. If the registry keys do not exist, the debug library creates them. Global logging levels for a message type can be specified in the following key:
\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\GLOBAL\<Message Type>
The debug library uses whichever level is greater. 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:
DbgLog((LOG_TRACE, 3, "This is a debug message."));
In debug builds, if the current logging level for LOG_TRACE messages is 3 or higher, the message is sent to the debug output. Otherwise, it is ignored. Debug builds must define the preprocessor symbol DEBUG before including the base-class header file, Streams.h.
The debug output location is determined by another registry key:
\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\LogToFile
If the value 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.
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. |
NAME | Generates a debug-only string. |
NOTE | Sends a string to the debug output location. |
REMIND | Generates a reminder at compile time. |
Checks whether logging is enabled for the given message types and level. Ignored in retail builds.
Syntax
BOOL DbgCheckModuleLevel( DWORD Types, DWORD Level );
Parameters
- Types
- Bitwise combination of one or more message types.
- Level
- Logging level
Return Value
Returns TRUE if logging for any of the specified message types is set to the specified level or higher. Otherwise, returns FALSE.
Displays information about active objects. Ignored in retail builds.
Syntax
void DbgDumpObjectRegister(void);
Remarks
In debug builds, the debug library maintains a list of active objects. The list includes any objects that derive from CBaseObject, were created by the current module, and have not been destroyed. The CBaseObject constructor and destructor methods update the list.
This function generates several LOG_MEMORY messages. At logging level 1, the function displays only the total number of objects. At logging level 2 or higher, it displays a list of the objects.
Initializes the debug library. Ignored in retail builds.
Syntax
void DbgInitialise( HINSTANCE hInst );
Parameters
- hInst
- Handle to the module instance.
Remarks
In an executable, call this method before using the DirectShow debug facilities. Before the executable quits, call the DbgTerminate function to clean up the debug library.
In a DLL that links to the base-class library (Strmbase.lib), it is not necessary to call this function. The function is called automatically when the DLL is loaded.
Sends a string to the debug output location, if logging is enabled for the specified type and level. Ignored in retail builds.
Syntax
void DbgLog(( DWORD Types, DWORD Level, const TCHAR *pFormat, ... ));
Parameters
- Types
- Bitwise combination of one or more message types.
- Level
- Logging level for this message.
- pFormat
- A printf-style format string.
- ...
- Additional arguments for the format string.
Remarks
If debug logging for any of the message types is set to the specified level or higher, this macro sends the formatted string to the debug output location.
Example
DbgLog((LOG_TRACE, 3, TEXT("Connected input pin %d"), nPinNumber));Note that an additional set of parentheses must enclose the macro parameters.
Sends a string to the debug output location. Ignored in retail builds.
Syntax
void DbgOutString( LPCTSTR psz );
Parameters
- psz
- String to output.
Remarks
In debug builds, this function always outputs the string, regardless of the current debug output levels. For finer control over the output, use the DbgLog macro.
Example
DbgOutString("Creating the filter graph...\n");
Sets the logging level for one or more message types. Ignored in retail builds.
Syntax
void DbgSetModuleLevel( DWORD Types, DWORD Level );
Parameters
- Types
- Bitwise combination of one or more message types.
- Level
- Logging level for the specified message types.
Cleans up the debug library. Ignored in retail builds.
Syntax
void DbgTerminate(void);
Remarks
Call this function if you call the DbgInitialise function.
Sends information about a media type to the debug output location. Ignored in retail builds.
Syntax
void DisplayType( LPSTR label, const AM_MEDIA_TYPE *pmtIn );
Parameters
- label
- String that contains a message to display with the media type information.
- pmtIn
- Pointer to the AM_MEDIA_TYPE structure that contains the media type.
Remarks
This function generates several LOG_TRACE messages. At logging level 2 or higher, the function displays the major type, subtype, and format type, and data from the format block. At logging level 5 or higher, the function displays additional information, such as the source and target rectangles for video types.
Sends information about a filter graph to the debug output location. Ignored in retail builds.
Syntax
void DumpGraph( IFilterGraph *pGraph, DWORD dwLevel )
Parameters
- pGraph
- Pointer to the IFilterGraph interface on the filter graph manager.
- dwLevel
- Logging level. The function generates a LOG_TRACE message with the specified logging level.
Generates a debug-only string.
Syntax
NAME( strLiteral );
Parameters
- strLiteral
- Text string.
Remarks
In debug builds, this macro is equivalent to the TEXT macro. In retail builds, it resolves to (TCHAR*) NULL. This macro is useful when declaring the name of an object that derives from the CBaseObject class.
Example
pObject = new CBaseObject(NAME("My Object"));
Sends a string to the debug output location. Ignored in retail builds.
Syntax
NOTE( pFormat ); NOTEn( pFormat, arg1 ... arg5 );
Parameters
- pFormat
- A printf-style format string.
- arg1 arg5
- Additional arguments for the format string. The number of arguments must match the macro name. For example, NOTE1 takes one argument, and NOTE5 takes five arguments.
Remarks
These macros are variants of the DbgLog macro. They generate level 5 LOG_TRACE messages.
Example
NOTE("Warning, failed to created graph."); NOTE2("Width: %d, Height: %d", width, height);
Generates a reminder at compile time. This macro generates a string that includes the parameter string, the name of the source file, and the line number.
Syntax
REMIND( strLiteral );
Parameters
- strLiteral
- Text string.
Example
This macro is useful for generating compile-time warnings:
#pragma message (REMIND("TO DO: Add support for IDispatch."))