Debugging
`
`Page 15 of31
`
`the correct kind of memory, although possibly with a significant performance hit for each test.
`Name
`Description
`CheckPointer
`Checks whether or not a given pointer is NULL.
`ValidateReadPtr
`Validates a read pointer.
`ValidateReadWritePtr Validates a read/write pointer.
`ValidateStringPtr
`Validates a string pointer.
`ValidateStringPtrA
`Validates an ANSI string pointer.
`ValidateStringPtrW Validates a wide (Unicode) string pointer.
`Va I idateWritePtr
`Validates a write pointer.
`
`© 1997 Microsoft Corooratjon . All rights reserved. Terms of Use.
`
`MQ<§i[.jjj,M MB.HS Topic Contents
`
`i@faiilMM
`
`CheckPointer
`
`Pointer Validation Macros
`
`Determines if a given pointer is NULL. If the pointer is NULL, CheckPointer returns a user(cid:173)
`defined value.
`
`CheckPointer(
`p,
`ret
`);
`
`Parameters
`
`p
`
`ret
`
`Pointer to check.
`
`Value your function will return if p is NULL.
`
`Remarks
`
`The following examples illustrate how to call this macro.
`
`HRESULT OneFunction (VOID *pSomeParameter)
`{
`
`CheckPointer(pSomeParameter, E_INVALIDARG )
`
`}
`
`BOOL AnotherFunction(VOID *pSomeParameter)
`{
`
`CheckPointer(pSomeParameter, FALSE )
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`1906
`
`

`
`Debugging
`
`Page 16 of31
`
`+Qi§1[.]++ 1 !!·HM Topic Contents
`
`i@l§ii!MM
`
`ValidateReadPtr
`
`Pointer Validation Macros
`
`Checks a read pointer. If the pointer is not valid, this macro calls DbgBreak.
`
`ValidateReadPtr(
`const void * p,
`UINT cb
`);
`
`Parameters
`
`p
`
`cb
`
`Pointer value (of any type).
`
`Byte count to be checked.
`
`Remarks
`
`This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow
`headers are included.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qij[.jjj,M 11!.l:.!9 Topic Contents
`
`i@l§ii!MM
`
`ValidateReadWritePtr
`
`Pointer Validation Macros
`
`Checks a read/write pointer. If the pointer is not valid, this macro calls DbgBreak.
`
`ValidateReadWritePtr(
`const void * p,
`UINT cb
`);
`
`Parameters
`
`1907
`
`

`
`Debugging
`
`Page 17of31
`
`p
`
`cb
`
`Pointer value (of any type).
`
`Byte count to be checked.
`
`Remarks
`
`This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow
`headers are included.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`w Q<M [.] 11,1 Mii.HM Topic Contents
`
`•@M* 1gnw
`
`ValidateStringPtr
`
`Pointer Validation Macros
`
`Checks a string pointer and calls DbgBreak if the pointer is not valid.
`
`ValidateStringPtr(
`LPCTSTRp
`);
`
`Parameters
`
`p
`
`TCHAR string pointer value.
`
`Remarks
`
`This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow
`headers are included.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`M Q '41 [.] lj,M I !1.],,[9 Topic Contents
`
`i@faii!MM
`
`ValidateStringPtrA
`
`Pointer Validation Macros
`
`1908
`
`

`
`Debugging
`
`Page 18 of31
`
`Checks an ANSI string pointer and calls DbqBreak if the pointer is not valid.
`
`ValidateStringPtrA(
`LPCSTRp
`);
`
`Parameters
`
`p
`
`ANSI string pointer value.
`
`Remarks
`
`This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow
`headers are included.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`MQi§i[.]jj,M '!!·HM Topic Contents
`
`lmll§I 11¥8
`
`ValidateStringPtrW
`
`Pointer Validation Macros
`
`Checks a wide (Unicode) string pointer and calls DbgBreak if the pointer is not valid.
`
`ValidateStringPtrW(
`LPCWSTRp
`);
`
`Parameters
`
`p
`
`Wide string pointer value.
`
`Remarks
`
`This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow
`headers are included.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`• QIM [.] +• I !!·HM Topic Contents
`
`lfflj[§ill¥M
`
`1909
`
`

`
`Debugging
`
`Page 19of31
`
`ValidateWritePtr
`
`Pointer Validation Macros
`
`Checks a write pointer and calls DbqBreak if the pointer is not valid.
`
`ValidateWritePtr(
`const void * p,
`UINT cb
`);
`
`Parameters
`
`p
`
`cb
`
`Pointer value (of any type).
`
`Byte count to be checked.
`
`Remarks
`
`This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow
`headers are included.
`
`© 1997 Microsoft Corooratjon. All rights reserved. Terms of Use.
`
`MQ<§i[.jjj,M lh.l:.!5 Topic Contents
`
`i@faii!MM
`
`Miscellaneous Macros
`
`Some miscellaneous macros are provided, mainly for debug string processing. In particular,
`the NAME macro is used with many class constructors that support debug names. The REMIND
`macro is less useful; it just builds a reminder string (including the source file name and line
`number), which can be displayed at compile time.
`Macro Description
`NAME Generates a debug-only name.
`REMIND Generates a compile-time string.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`MQ<§i[.jjj,M lh.l:.!5
`
`Topic Contents
`
`i@faii!MM
`
`NAME
`
`1910
`
`

`
`Debugging
`
`Page 20 of 31
`
`Generates a debug-only string.
`
`NAME(
`strliteral
`);
`
`Parameters
`
`strliteral
`Text string, which must be in quotation marks.
`
`Remarks
`
`This macro is helpful for generating the debug name passed to many Microsoft® DirectShow™
`class constructors. (See Object Register Debugging for more information about using that
`aspect of debugging.) For example:
`
`x =new CVideoRenderer(NAME("Sample Video Renderer"),pUnk,phr);
`
`The NAME macro generates NULL unless DEBUG is defined when the Microsoft DirectShow
`headers are included.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qi§1H++ 1 !!·HM
`
`Topic Contents
`
`ifflj[§ii!¥M
`
`REMIND
`
`Generates a compile-time string.
`
`REMIND(
`strliteral
`);
`
`Parameters
`
`strliteral
`Text string, which must be in quotation marks.
`
`Remarks
`
`This generated string includes the parameter string, the source file name, and the line
`number.
`
`For example, to generate a compile-time warning, use the following syntax.
`
`1911
`
`

`
`Debugging
`
`Page 21 of31
`
`#pragma message (REMIND ( "Add automation support" ))
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`8 4'MM+1 111·!:.!¥ Topic Contents
`
`lmll§lllMM
`
`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 I 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 CIC++ 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.
`
`1912
`
`

`
`Debugging
`
`Page 22 of 31
`
`DbgLog (( LOG TRACE, 1, TEXT ("CVidCap created" ))) ;
`DbgLog (( LOG=ERRORILOG_TRACE, 1, TEXT ("Driver failed to connect" )
`DbgLog (( LOG_ERRORILOG_TRACE, 2
`, TEXT ( "Driver disconnec t: %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
`Dbglnitialise function is called automatically when the DLL is loaded. Executables must call
`Dbglnitialise 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 I 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.
`Logs a message for given types and level. (Ignored except in debug
`builds.)
`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.
`Displays the given media type.
`DisplayType
`
`DbgLoginfo
`
`DbgLog
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qi§1H+* 1 11·!:.!M Topic Contents
`
`ifflj(§i 11¥+
`
`1913
`
`

`
`Debugging
`
`Page 23 of 31
`
`+Qi§1[.]++ 1 !!·HM Topic Contents
`
`i@l§ii!MM
`
`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.
`
`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 Values
`
`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 Microsoft DirectShow
`headers are included.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qi§1[.]++ 111.J,,[9 Topic Contents
`
`i@l§ii!MM
`
`Dbglnitialise
`
`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.
`
`1914
`
`

`
`Debugging
`
`Page 24 of 31
`
`void WINAPI Dbglnitialise(
`HINSTANCE h!nst
`);
`
`Parameters
`
`h!nst
`Module instance handle.
`
`Remarks
`
`Dbglnitialise is ignored unless DEBUG is defined when the Microsoft DirectShow headers are
`included. Dbglnitialise also opens the debug output location, as described in Debug Output
`Location.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQl@[.jlj,M l!i.! 111j Topic Contents
`
`l@i§lllMM
`
`Dbglog
`
`Debug Logging by Module Level
`
`Invokes the DbgLoginfo function.
`
`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 orintf-style format string, which must be in quotation marks.
`
`Remarks
`
`Dbglog is ignored unless DEBUG is defined when the Microsoft DirectShow headers are
`included.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`1915
`
`

`
`Debugging
`
`Page 25of31
`
`+Qi§1[.]++ 1 !!·HM Topic Contents
`
`i@l§ii!MM
`
`Dbgloglnfo
`
`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.
`
`void WINAPI Dbgloglnfo(
`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
`
`Dbgloglnfo exists only in debug builds.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qij[.jjj,M 11!.l:.!9 Topic Contents
`
`i@l§ii!MM
`
`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.
`
`void WINAPI DbgSetModulelevel (
`DWORD Types,
`DWORD Level
`
`1916
`
`

`
`Debugging
`
`);
`
`Parameters
`
`Page 26 of 31
`
`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 Microsoft DirectShow headers are included.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qi§1H++ 1 !!·HM Topic Contents
`
`ifflj[§ii!¥M
`
`DbgTerminate
`
`Debug Logging by Module Level
`
`Cleans the debug library.
`
`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 Microsoft DirectShow headers are
`included.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`+;<§1[.]jj,+ 111.],.[9 Topic Contents i@l§ii!¥M
`
`DisplayType
`
`Debug Logging by Module Level
`
`1917
`
`

`
`Debugging
`
`Page 27 of 31
`
`Displays the media type details on the debug log.
`
`void WINAPI DisplayType(
`LPSTR label,
`const AM_MEDIA_ TYPE *pmtln
`);
`
`Parameters
`
`label
`
`Short message to be logged with the media type.
`pmtln
`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 Microsoft DirectShow headers are
`included.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Q'41!.!+• 111.q9 Topic Contents
`
`l@!§il!MM
`
`Object Register Debugging
`
`The CBaseObject class is at the root of all Microsoft® DirectShow™ base classes. It maintains
`the object register, which is the list of objects (in those classes) that have been created but
`not yet destroyed. It exists primarily to provide debugging assistance by keeping a count of all
`active DirectShow objects. All base class constructors in derived base classes provide a
`debugging object name as the first parameter and call the CBaseObject constructor. You can
`view the debugging object name sent to this base class on a debugging monitor.
`
`For more information about how the debug output location is chosen, see Debug Output
`Location.
`Description
`Name
`DbgDumpObjectRegister Displays details about all objects in the object register.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qij[.jlj,M 111.11119 Topic Contents
`
`l@!§il!MM
`
`1918
`
`

`
`Debugging
`
`Page 28 of 31
`
`Dbg Du m pObjectReg ister
`
`Object Register Debugging
`
`Displays details about all objects in the object register.
`
`void WINAPI DbgDumpObjectRegister( );
`
`Remarks
`
`The DirectShow debug routines ignore DbgDumpObjectRegister unless DEBUG is defined
`when the Microsoft DirectShow headers are included.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`• QIM [.] "'' I![.],.[. Topic Contents •@M* 1gnw
`
`Wait Debugging
`
`DirectShow provides facilities for wait debugging. These facilities build on the Microsoft®
`Win32® HANDLE-based wait facilities, but you can expand them to debug specific wait
`conditions.
`
`In the debug build, you can update the global current time-out with calls to
`DbqSetWaitTimeout. Updating the current time-out does not affect debug wait calls that are
`already waiting. If this is a debug build and a value named TIMEOUT exists in the registry
`under the HKEY _LOCAL_MACHINE\SOFTWARE\Debug\GLOBAL key, the TIMEOUT value is used
`as the initial current time-out. TIMEOUT must be a REG_DWORD value and is measured in
`milliseconds. If not, the initial time-out defaults to INFINITE.
`
`Call the following functions to perform debuggable waiting.
`Name
`Description
`DbgSetWaitTimeout
`Updates the current time-out value.
`DbgWaitForMultipleObjects Waits for an array of handles to be signaled, or for the current
`time-out to expire.
`DbgWaitForSingleObject Waits for a handle to be signaled, or for the current time-out to
`expire.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQl@[.jjj,M l!l.! 1119 Topic Contents
`
`i@faii!MM
`
`1919
`
`

`
`Debugging
`
`Page 29 of 31
`
`DbgSetWaitTimeout
`
`Wait Debugging
`
`Updates the global current time-out value. (This update does not apply to debug wait calls that
`are already waiting.)
`
`void WINAPI DbgSetWaitTimeout(
`DWORD dwTimeout
`);
`
`Parameters
`
`dwTimeout
`New time-out value in milliseconds, or INFINITE.
`
`Remarks
`
`DbgSetWaitTimeout is ignored unless DEBUG is defined when the Microsoft® DirectShow™
`headers are included.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`•;<MM+' •11·!:.!¥ Topic Contents
`
`lmli§lllMM
`
`DbgWaitForMultipleObjects
`
`Wait Debugging
`
`In a debug build, waits for the current time-out, or the array of handles to become signaled,
`whichever comes first. In other builds, this is treated as a call to the Microsoft Win32®
`WaitForMultipleObjects function, with an INFINITE time-out.
`
`DWORD WINAPI DbgWaitForMultipleObjects(
`DWORD nCount,
`CONST HANDLE *lpHandles,
`BOOL bWaitAll
`);
`
`Parameters
`
`nCount
`Number of entries in the lpHandles array.
`lpHandles
`Array of HANDLE values.
`bWaitAll
`TRUE if all handles in the array must become signaled to satisfy the wait. FALSE if any
`
`1920
`
`

`
`Debugging
`
`Page 30 of 31
`
`one handle can satisfy the wait.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`8 4'MM+1 111·!:.!¥ Topic Contents
`
`lmll§lllMM
`
`DbgWaitForSingleObject
`
`Wait Debugging
`
`In a debug build, waits for the current time-out, or the given handle to become signaled. In
`other builds, this is treated as a call to the Microsoft Win32 WaitForSingleObject function, with
`an INFINITE time-out.
`
`DWORD WINAPI DbgWaitForSingleObject(
`HANDLE h
`);
`
`Parameters
`
`h
`
`HANDLE value.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQij[.jjj,M 111.11119
`
`Topic Contents
`
`l@i§il!MM
`
`Debug Output Location
`
`Microsoft® DirectShow™ provides facilities for debug output, with a wide variety of options for
`the debug output location. Possible output locations include using the normal debugger output
`(the default), recording to a file with a given name, or using the Win32 ® standard output
`handle (creating a console if this handle is not already open). After the debug output location
`is specified, each of the following debug facilities uses the same location.
`Debug Output
`Debug NOTE (Message) Macros
`Debug Logging by Module Level
`Object Register Debugging
`
`The debug output location is chosen (based on the registry) when Dbginitialise is called.
`DbgTerminate must be called when this process finishes using the debug output location.
`These macros are generally called automatically by other debug routines.
`
`1921
`
`

`
`Debugging
`
`Page 31of31
`
`To specify the debug output location, set the LogToFile value in the registry (under the
`HKEY _LOCAL_MACHINE\SOFTWARE\Debug\GLOBAL key) to one of the following (case(cid:173)
`insensitive) values.
`LogToFile Value
`"Console"
`
`Results
`Use the Microsoft Win32 standard output handle if it exists. If no
`standard output handle exists, allocate a console and use it for
`output.
`Use the Win32 OutoutDebuqStrinq function.
`
`"Deb", "Debug", or
`"Debugger"
`Any nonempty string other Write to file of that name.
`than the preceding
`An empty string (or the
`registry key does not exist)
`
`Use the Win32 OutoutDebuqStrinq function.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Q'41!.!+• +11.q9 Topic Contents
`
`l@!§il!MM
`
`1922
`
`

`
`Structures
`
`Page 1of35
`
`MQi@[.jjj,M M!i.!111j Topic Contents
`
`l@i§il!MM
`
`Structures
`
`This section describes the Microsoft® DirectShow™ structures.
`Structure
`Description
`ALLOCATOR PROPERTIES Contains the allocator's count, size, alignment, and prefix
`properties.
`AM DVD RENDERSTATUS Provides status (failure) codes for
`IDvdGraphBuilder:: RenderDvdVideoVolume.
`Describes a media sample type.
`AM MEDIA TYPE
`AM SAMPLE2 PROPERTIES Describes the properties of a generic media sample.
`AMOVIESETUP FILTER
`Contains filter information for registering a filter.
`AMOVIESETUP MEDIATYPE Contains media type information for registering a filter.
`Contains pin information for registering a filter.
`AMOVIESETUP PIN
`AM STREAM INFO
`Contains start and stop information given to a pin.
`AMVPDATAINFO
`Specifies the data-specific characteristics of the VP input stream.
`AMVPDIMINFO
`Specifies the dimensional characteristics of the VP input stream.
`AMVPSIZE
`Specifies the width and height for a VP image.
`DVD ATR
`Specifies DVD attributes.
`DVD TIMECODE
`Contains DVD timecode in hours, minutes, seconds, and frames.
`FILTER INFO
`Contains information about a filter.
`PIN INFO
`Contains information about a pin.
`POSITION
`Placeholder for linked lists.
`Quality
`Describes a quality message by indicating Flood or Famine in the
`renderer and specifying the percentage of frames to drop or add to
`optimize the renderer's performa nee.
`Describes a filter in the registry.
`Describes a filter for registration through the IFilterMapper2
`interface.
`Contains information for registering a filter through the
`IFilterMapper2 interface.
`Describes a pin medium (as defined in the Windows NT DDK) for
`registration through the IFilterMapper2 interface.
`Contains pin information for registering a filter.
`Contains media type information for registering a filter.
`
`REGFILTER
`REGFILTER2
`
`REGFILTERPINS2
`
`REGPINMEDIUM
`
`REGFILTERPINS
`REGPINTYPES
`
`The following structure maintains information about graphics device interface (GDI) bitmaps
`and device-independent bitmaps (DIBs). This is used solely by the ClmageAllocator,
`ClmageSample, and CDrawlmage window utility classes.
`Structure Description
`DIBDATA Contains information about each DIB.
`
`1923
`
`

`
`Structures
`
`Page 2of35
`
`The following structures maintain information about video, as well as video capture and
`compression.
`Structure
`TRU ECO LORIN FO
`ANALOGVIDEOINFO
`
`Description
`Maintains color information.
`Maintains information about the format of the analog video
`signal.
`AUDIO STREAM CON FIG CAPS Contains information about all possible audio formats
`supported.
`Communicates color key information between the renderer
`and another filter.
`Contains additional MPEG-1 video system information.
`MPEG1 VIDEOINFO
`Contains additional MPEG-2 video system information.
`MPEG2VIDEOINFO
`Contains basic timecode frame count information.
`TIMECODE
`TIMECODE SAMPLE
`Contains complete timecode information.
`VIDEO STREAM CONFIG CAPS Contains information about possible connections.
`VIDEOINFO
`Contains information that specifies a video image and its color
`palette and bitmasks.
`Describes the bitmap and color information for a video image.
`Describes the bitmap and color information for a video image,
`including interlace, copy protection, and pixel aspect ratio
`information.
`
`COLORKEY
`
`VIDEO IN FOH EADER
`VIDEO IN FOH EADER2
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Q'41!.l+' 111.q9 Topic Contents
`
`l@!§il!MM
`
`+Qij[.jlj,M 111.11119 Topic Contents
`
`1@!§111¥+
`
`ALLOCATOR_PROPERTIES
`
`Structures
`
`Contains the allocator's count, size, alignment, and prefix properties.
`
`typedef struct _Allo catorProperties
`long cBuffers;
`l ong cbBuffer;
`long cbAlign;
`long cbPrefix;
`ALLOCATOR_PROPERTIES;
`
`Members
`
`cBuffers
`Count of buffers at this allocator.
`
`1924
`
`

`
`Structures
`
`Page 3of35
`
`cbBuffer
`Size of each buffer in bytes, excluding any prefix.
`cbAlign
`Alignment of the buffer; buffer start will be aligned on a multiple of this value.
`cbPrefix
`Each buffer is preceded by a prefix of this many bytes.
`
`Remarks
`
`The CMediaSample: :GetPointer member function points to the beginning of the buffer, not
`including the prefix bytes designated by cbPrefix.
`
`The alignment is applied to the prefix data, if any. If a nonzero prefix is used, the beginning of
`the prefix is aligned according to cbAlign. Since the buffer pointer returned by
`IMediaSample: :GetPointer points to the area immediately following the prefix, the cbPrefix
`address (the value returned by IMediaSample::GetPointer minus cbPrefix) should be
`aligned on an address that is a multiple of cbAlign bytes.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`•;<MM+' 111.],.[9 Topic Contents
`
`lmli§lllMM
`
`8 4'41M+• 111.q9 Topic Contents
`
`1@!§111$8
`
`AM_DVD_RENDERSTATUS
`
`Structures
`
`Provides status (failure) codes for IDvdGraphBuilder:: RenderDvdVideoVolume.
`
`typedef struct {
`HRESULT hrVPEStatus;
`BOOL
`bVPEFailed;
`BOOL
`bDVDVolinvalid;
`BOOL
`bDVDVolUnknown;
`BOOL
`bNoLine21In;
`BOOL
`bNoLine210ut;
`int
`iNumStreams;
`int
`iNumstreamsFailed;
`DWORD
`dwFailedstreamsFlag;
`} AM_DVD_RENDERSTATUS;
`
`Members
`
`hrVPEStatus
`Video port extension (VPE) error code. Zero indicates success; any other value is failure.
`bVPEFailed
`TRUE if the caller didn't set the AM DVD NOVPE flag in the RenderDvdVideoVolume call
`and VPE mixing failed; FALSE otherwise.
`
`1925
`
`

`
`Structures
`
`Page 4of35
`
`bDVDVollnvalid
`TRUE if the specified DVD volume to be played does not exist; FALSE otherwise.
`bDVDVolUnknown
`TRUE if no DVD volume is specified or if it isn't found; FALSE otherwise.
`bNoline211n
`TRUE if the video decoder doesn't produce Line 21 (closed captioning) data; FALSE
`otherwise.
`bNoline210ut
`TRUE if the video decoder can't show decoded Line 21 data as CC on video; FALSE
`otherwise.
`iNumStreams
`Number of DVD streams to render.
`iNumStreamsFailed
`Number of streams that failed to render.
`dwFailedStreamsFlag
`Combination of AM DVD STREAM FLAGS flags indicating which streams failed.
`
`See Also
`
`IDvdGraphBuilder:: RenderDvdVideoVolume
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQij[.jjj,M l!i.! 111j
`
`Topic Contents
`
`l@i§il!MM
`
`MQ<§i[.jjj,M lh.l:.!j
`
`Topic Contents
`
`i@faii!MM
`
`AM_MEDIA_TYPE
`
`Structures
`
`Describes a media sample type.
`
`typedef struct _MediaType
`{
`majortype;
`GUID
`subtype;
`GUID
`bFixedsizesamples;
`BOOL
`bTemporalcompression;
`BOOL
`lSampleSize;
`ULONG
`format type;
`GUID
`!Unknown *pUnk;
`ULONG
`cbFormat;
`/ * [size is] */ BYTE
`} AM_MEDIA_TYPE;
`
`RPC FAR *pbFormat;
`
`Members
`
`majortype
`Major type of the media sample.
`
`1926
`
`

`
`Structures
`
`Page 5of35
`
`subtype
`Subtype of the media sample.
`bFixedSizeSamples
`If TRUE, samples are of a fixed size.
`bTemporalCompression
`If TRUE, samples are compressed.
`ISampleSize
`Size of the sample in bytes.
`formattype
`Registered (GUID) format type.
`pUnk
`Pointer to the !Unknown interface.
`cbFormat
`Size of the format section of the media type.
`pbFormat
`Pointer to the format section of the media type. The layout of this is determined by the
`format type GUID. Format types include the following:
`Format type
`Structure pointed to
`FORMAT_ MPEGVideo
`MPEG1 VIDEOINFO
`FORMAT_ Videolnfo
`VI D EOI N FOH EADER
`FORMAT_ WaveFormatEx WAVEFORMATEX
`FORMAT _ M PEG2Video MPEG2VID EOI NFO
`FORMAT_ Videolnfo2
`VI D EOI N FOH EADER2
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`•;<MM+' 111.],.[9
`
`Topic Contents
`
`lmli§lllMM
`
`8 4'41M+• 111.q9
`
`Topic Contents 1@!§111$8
`
`AM_SAMPLE2_PROPERTIES
`
`Structures
`
`Describes the properties of a generic media sample.
`
`typedef struct tagAM_SAMPLE2 PROPERTIES
`DWORD
`cbData;
`DWORD
`dwTypeSpecificFlags;
`DWORD
`dwsampleFlags;
`LONG
`lActual;
`REFERENCE_TIME tstart;
`REFERENCE_TIME tstop;
`DWORD
`dwstreamid;
`AM_MEDIA_TYPE *pMediaType;
`BYTE
`*pbBuffer;
`LONG
`cbBuffer;
`AM_SAMPLE2_PROPERTIES;
`
`1927
`
`

`
`Structures
`
`Members
`
`Page 6of35
`
`cbData
`Length of property data for extensibility; number of bytes including this field.
`dwTypeSpecificFlags
`Type-specific flag data. These flags are defined separately for each media type. Default is
`zero.
`dwSampleFlags
`Flags bits defined by the AM SAMPLE PROPERTY FLAGS enumerated data type. All
`undefined bits are reserved (set them to zero, and do not copy them).
`!Actual
`Length of data in the buffer pointed to by the pbBuffer member.
`tStart
`Start time if valid.
`tStop
`Stop time if valid.
`dwStreamid
`Stream identifier. Stream 0 is the normal media transport. Stream 1 is control.
`Currently, only Stream 0 is used. Filters should pass any other stream ID directly to their
`output pins without processing.
`pMediaType
`Copy of the media type. It becomes invalid after the sample has been released.
`pbBuffer
`Pointer to the buffer. The pointer becomes invalid after the sample is released.
`cbBuffer
`Total length of the buffer pointed to by pbBuffer, in bytes.
`
`Remarks
`
`The IMediaSample2 interface uses this structure.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+;<§1[.]lj,i 111.],.[9 Topic Contents
`
`ifflj(§il!MM
`
`+Qij[.jlj,M 111.l:.!9 Topic Contents
`
`l@i§il!MM
`
`AMOVIESETUP _FILTER
`
`Structures
`
`Contains filter information for registering a filter.
`
`typedef struct AMOVIESETUP FILTER
`{
`
`const CLSID * clsID;
`LPWSTR
`strName;
`DWORD
`dwMerit;
`
`1928
`
`

`
`Structures
`
`Page 7of35
`
`nPins;
`UINT
`LPAMOVIESETUP PIN lpPin;
`
`AMOVIESETUP FILTER
`
`Members
`
`clsID
`Class identifier of the filter.
`strName
`Name of the filter.
`dwMerit
`Merit used by the GraphBuilder