Microsoft DirectX 8.0

Debug Output Functions

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_ERRORError notification.
LOG_LOCKINGLocking and unlocking of critical sections.
LOG_MEMORYMemory allocation, and object creation and destruction.
LOG_TIMINGTiming and performance measurements.
LOG_TRACEGeneral 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.

FunctionDescription
DbgCheckModuleLevelChecks whether logging is enabled for the given message types and level.
DbgDumpObjectRegisterDisplays information about active objects.
DbgInitialiseInitializes the debug library.
DbgLogSends a string to the debug output location, if logging is enabled for the specified type and level.
DbgOutStringSends a string to the debug output location.
DbgSetModuleLevelSets the logging level for one or more message types.
DbgTerminateCleans up the debug library.
DisplayTypeSends information about a media type to the debug output location.
DumpGraphSends information about a filter graph to the debug output location.
NAMEGenerates a debug-only string.
NOTESends a string to the debug output location.
REMINDGenerates a reminder at compile time.

DbgCheckModuleLevel

Debug Output Functions

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.

DbgDumpObjectRegister

Debug Output Functions

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.

DbgInitialise

Debug Output Functions

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.

DbgLog

Debug Output Functions

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.

DbgOutString

Debug Output Functions

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"); 

DbgSetModuleLevel

Debug Output Functions

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.

DbgTerminate

Debug Output Functions

Cleans up the debug library. Ignored in retail builds.

Syntax

void DbgTerminate(void);

Remarks

Call this function if you call the DbgInitialise function.

DisplayType

Debug Output Functions

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.

DumpGraph

Debug Output Functions

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.

NAME

Debug Output Functions

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"));

NOTE, NOTE1, NOTE2, NOTE3, NOTE4, NOTE5

Debug Output Functions

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.
arg1arg5
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);

REMIND

Debug Output Functions

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."))