Microsoft DirectX 8.0

デバッグ出力関数

Microsoft® DirectShow® 基底クラスはデバッグ情報表示用のいくつかのマクロを提供する。

宣言 : Wxdebug.h

DirectShow のデバッグ環境は特定のタイプのデバッグ情報を、他の者を無視して、ファインチューンすることができる。この機能で、コード内の特定の範囲に問題をピンポイントさせることができる。DirectShow は以下の表に示されるいくつかのメッセージタイプを定義する。

LOG_ERRORエラー通知。
LOG_LOCKINGクリティカル セクションのロックとアンロック。
LOG_MEMORYメモリ割り当てと、オブジェクトの作成および破棄。
LOG_TIMINGタイミングとパフォーマンスの測定。
LOG_TRACE一般的な呼び出しトレース。

すべてのモジュールは各メッセージタイプに対し自身のデバッグレベルを設定することができる。(モジュール は DLL もしくは実行モジュールであり、Microsoft® Win32® LoadLibrary 関数を使ってロードされる。) モジュールの与えられたメッセージタイプに対するロギング レベルはレジストリ内の次のキーで見ることができる :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\<Message Type>

<Message Type> はメッセージ タイプ から頭の "LOG_" を取ったものである。たとえば、LOCKING は LOG_LOCKING メッセージ。

モジュールがロードされると、デバッグ ライブラリはモジュールのロギング レベルをレジストリから読み込む。レジストリ キーがないと、デバッグ ライブラリはそれを作成する。メッセージタイプのグローバル ロギング レベルは次のキーで指定される :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\GLOBAL\<Message Type>

デバッグ ライブラリは大きい方のレベルを使用する。モジュールは DbgSetModuleLevel 関数を使って、自身のレベルをランタイム時に設定することもできる。デバッグ出力にメッセージを送るには、DbgLog マクロを呼び出すこと。次の例はタイプ LOG_TRACE のレベル 3 メッセージを作成している :

DbgLog((LOG_TRACE, 3, "This is a debug message."));

デバッグ ビルドでは、現在のLOG_TRACE メッセージのロギング レベルが 3 あるいはそれ以上なら、メッセージはデバッグ出力を送る。それ以外なら無視される。デバッグ ビルドはストリームクラス ヘッダー ファイル Streams.h に含まれているプリプロセッサ シンボル DEBUG を定義しなければならない。

デバッグ出力位置は別のレジストリキーによって定義されている :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\LogToFile

この値が Console なら、出力はコンソール ウィンドウになる。この値が DebDebugDebugger あるいは空白文字列なら、出力はデバッガ ウィンドウになる。それ以外なら、出力はレジストリ キーで指定されたファイルに書き込まれる。

実行モジュールが DirectShow デバッグ ライブラリを使う前に、DbgInitialise 関数を呼び出さなければならない。最後に、DbgTerminate 関数呼び出さなければならない。これらの関数を呼び出すのに DLL は必要ない。

関数説明
DbgCheckModuleLevel与えられたメッセージ タイプとレベルでロギングが可能かどうかをチェックする。
DbgDumpObjectRegisterアクティブなオブジェクトについての情報を表示する。
DbgInitialiseデバッグ ライブラリを初期化する。
DbgLog指定したタイプとレベルでロギング可能なら、デバッグ出力位置に文字列を送る。
DbgOutStringデバッグ出力位置に文字列を送る。
DbgSetModuleLevel1 つ以上のメッセージ タイプのロギング レベルを設定する。
DbgTerminateデバッグ ライブラリをクリーン アップする。
DisplayTypeメディア タイプについての情報をデバッグ出力位置に送る。
DumpGraphフィルタ グラフについての情報をデバッグ出力位置に送る。
NAMEデバッグ専用文字列を生成する。
NOTEデバッグ出力位置に文字列を送る。
REMINDコンパイル時に注意を生成する。

DbgCheckModuleLevel

デバッグ出力関数

与えられたメッセージ タイプとレベルでロギングが可能かどうかをチェックする。リテール ビルドでは無視される。

構文

BOOL DbgCheckModuleLevel(
    DWORD Types,
    DWORD Level
);

パラメータ

Types
1 つ以上のメッセージ タイプのビットの組み合わせ。
Level
ロギング レベル

戻り値

もし指定したメッセージタイプに対するロギングが指定したレベルあるいはそれ以上にセットされていると、TRUE を返す。それ以外なら、FALSE を返す。

DbgDumpObjectRegister

デバッグ出力関数

アクティブなオブジェクトについての情報を表示する。リテール ビルドでは無視される。

構文

void DbgDumpObjectRegister(void);

注意

デバッグ ビルドでは、デバッグ ライブラリはアクティブなオブジェクトのリストを保持する。CBaseObjectから派生したすべてのオブジェクトを含むリストは、現在のモジュールによって作成され、削除されない。CBaseObject コンストラクタとデストラクタ メソッドがこのリストをアップデートする。

この関数はいくつかの LOG_MEMORY メッセージを生成する。ロギング レベル 1 では、この関数はオブジェクトの全数だけを表示する。ロギング レベル 2 以上では、オブジェクトのリストを表示する。

DbgInitialise

デバッグ出力関数

デバッグ ライブラリを初期化する。リテール ビルドでは無視される。

構文

void DbgInitialise(
    HINSTANCE hInst
);

パラメータ

hInst
モジュール インスタンスへのハンドル。

注意

実行モジュールでは、DirectShow デバッグ環境を使う前にこのメソッドを呼び出すこと。実行モジュールが終了する前に、DbgTerminate 関数を呼び出し、デバッグ ライブラリをクリーン アップすること。

基底クラス ライブラリ (Strmbase.lib) にリンクしている DLL では、この関数を呼び出す必要はない。この関数は DLL がロードされるとき、自動的に呼び出される。

DbgLog

デバッグ出力関数

指定したタイプとレベルでロギング可能なら、デバッグ出力位置に文字列を送る。リテール ビルドでは無視される。

構文

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

パラメータ

Types
1 つ以上のメッセージ タイプのビットの組み合わせ。
Level
このメッセージのロギング レベル
pFormat
printfスタイルのフォーマット文字列。
...
フォーマット文字列の追加引数。

注意

任意のメッセージタイプのデバッグ ロギングが指定したレベル以上に設定されていれば、デバッグ出力位置に文字列を送る

DbgLog((LOG_TRACE, 3, TEXT("Connected input pin %d"), nPinNumber));

カッコを追加するときはマクロ パラメータで包まなければならないことに注意。

DbgOutString

デバッグ出力関数

デバッグ出力位置に文字列を送る。リテール ビルドでは無視される。

構文

void DbgOutString(
    LPCTSTR psz
);

パラメータ

psz
出力する文字列。

注意

デバッグ ビルドでは、現在のデバッグ出力レベルと関係なく、この関数は必ず文字列を出力する。出力に関してより細かなコントロールをするには、DbgLog マクロを使うこと。

DbgOutString("Creating the filter graph...\n"); 

DbgSetModuleLevel

デバッグ出力関数

1 つ以上のメッセージ タイプのロギング レベルを設定する。リテール ビルドでは無視される。

構文

void DbgSetModuleLevel(
    DWORD Types,
    DWORD Level
);

パラメータ

Types
1 つ以上のメッセージ タイプのビットの組み合わせ。
Level
指定したメッセージタイプのロギング レベル

DbgTerminate

デバッグ出力関数

デバッグ ライブラリをクリーン アップする。リテール ビルドでは無視される。

構文

void DbgTerminate(void);

注意

DbgInitialise 関数を呼び出したなら、この関数を呼び出すこと。

DisplayType

デバッグ出力関数

メディア タイプについての情報をデバッグ出力位置に送る。リテール ビルドでは無視される。

構文

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

パラメータ

label
メディア タイプ情報を表示するメッセージが入る文字列。
pmtIn
メディア タイプが入る AM_MEDIA_TYPE 構造体へのポインタ。

注意

この関数はいくつかの LOG_TRACE メッセージを生成する。ロギング レベル 2 以上では、この関数はメジャー タイプ、マイナー タイプ、フォーマット タイプ、フォーマット ブロックからのデータを表示する。ロギング レベル 5 以上では、この関数はビデオ タイプの転送元矩形やターゲット矩形のような追加情報を表示する。

DumpGraph

デバッグ出力関数

フィルタ グラフについての情報をデバッグ出力位置に送る。リテール ビルドでは無視される。

構文

void DumpGraph(
    IFilterGraph *pGraph,
    DWORD dwLevel
)

パラメータ

pGraph
フィルタ グラフ マネージャの IFilterGraph インターフェイスへのポインタ。
dwLevel
ロギング レベル。関数は指定したロギング レベルで LOG_TRACE メッセージを生成する。

NAME

デバッグ出力関数

デバッグ専用文字列を生成する。

構文

NAME(
    strLiteral
);

パラメータ

strLiteral
テキスト 文字列。

注意

デバッグ ビルドでは、このマクロは TEXT マクロと同じである。リテール ビルドでは、(TCHAR*) NULL を解決する。このマクロは CBaseObject クラスから派生したオブジェクトの名前を宣言するとき便利である。

pObject = new CBaseObject(NAME("My Object"));

NOTE, NOTE1, NOTE2, NOTE3, NOTE4, NOTE5

デバッグ出力関数

デバッグ出力位置に文字列を送る。リテール ビルドでは無視される。

構文

NOTE(
    pFormat
);

NOTEn(
    pFormat,
    arg1 ... arg5    
);

パラメータ

pFormat
printfスタイルのフォーマット文字列。
arg1arg5
フォーマット文字列の追加引数。引数の数はマクロの名前と一致しなければならない。たとえば、NOTE1 は 1 つの引数を持ち、NOTE5 は 5 つの引数を持つ。

注意

これらのマクロは DbgLog マクロの変形である。それらはレベル 5 LOG_TRACE メッセージを生成する。

NOTE("Warning, failed to created graph.");

NOTE2("Width: %d, Height: %d", width, height);

REMIND

デバッグ出力関数

コンパイル時に注意を生成する。このマクロはパラメータ文字列、ソース ファイル名、ライン ナンバーを含む文字列を生成する。

構文

REMIND(
    strLiteral
);

パラメータ

strLiteral
テキスト文字列。

このマクロはコンパイル時のワーニングを生成する際に便利である :

#pragma message (REMIND("TO DO: Add support for IDispatch."))