Win32 API 日本語リファレンス
ホーム › Graphics.Direct3D11 › ID3DUserDefinedAnnotation

ID3DUserDefinedAnnotation

COM
📘 Microsoft Learn (日本語) · English
IIDb2daad8b-03d4-4dbf-95eb-32ab4b63d0ab継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ID3DUserDefinedAnnotation インターフェイスを使用すると、アプリケーションのコードフロー内の概念的なセクションやマーカーを記述できます。

解説(Remarks)

呼び出し元のアプリケーションが Visual Studio Ultimate 2012 などの Direct3D 専用プロファイリングツールの下で実行されていない場合、ID3DUserDefinedAnnotation の各メソッドは効果を持ちません。

ID3DUserDefinedAnnotation インターフェイスは、Microsoft Direct3D 11 のデバイスコンテキストによって公開されます。したがって ID3DUserDefinedAnnotation は、ID3D11DeviceContext インターフェイスやその他のコンテキストインターフェイスと同じスレッド規則に従います。Direct3D のスレッド処理の詳細については、MultiThreading を参照してください。 コンテキストの ID3DUserDefinedAnnotation インターフェイスを取得するには、コンテキストの QueryInterface メソッド (例: ID3D11DeviceContext::QueryInterface) を呼び出します。この呼び出しでは、ID3DUserDefinedAnnotation の識別子を渡す必要があります。

ID3DUserDefinedAnnotation インターフェイスは、Direct3D 9 の PIX 関数 (D3DPERF_* 関数) に相当する Microsoft Direct3D 10 以降の機能です。

メモ アプリで D3D11_CREATE_DEVICE_PREVENT_ALTERING_LAYER_SETTINGS_FROM_REGISTRY フラグを設定することは、D3DPerf_SetOptions(1) の呼び出しに代わるものです。ただし、Direct3D デバッグツールがアプリにフックするのを防ぐために、アプリから ID3DUserDefinedAnnotation::GetStatus を呼び出して Direct3D デバッグツールの下で実行されているかどうかを判定し、必要に応じて終了することもできます。
BeginEvent メソッドと EndEvent メソッドは必ず対で呼び出す必要があります。これらのメソッドの呼び出しの対は、アプリケーションの呼び出し履歴のより上位にある同メソッドの呼び出しの対の内側に入れ子にできます。言い換えると、「Draw World」というセクションが「Draw Trees」という別のセクションを完全に含み、さらにその中に「Draw Oaks」というセクションを完全に含めることができます。EndEvent メソッドは、直近の BeginEvent メソッドとのみ対応付けることができます。つまり、対が重なり合うことはできません。直近の BeginEvent より前の BeginEvent に対して EndEvent を呼び出すことはできません。実際、ランタイムは最初の EndEvent を 2 番目の BeginEvent の終了として解釈します。

メソッド 4

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 INT BeginEvent(LPWSTR Name)

イベントコードのセクションの開始を示します。

NameLPWSTRinイベントの名前を格納する NULL 終端の UNICODE 文字列です。この名前はオペレーティングシステムにとっては意味を持ちません。呼び出し元のアプリケーションが Direct3D プロファイリングツールの下で実行されているときに意味のある名前を選択できます。 NULL ポインターを渡した場合の結果は未定義です。

戻り値

ID3DUserDefinedAnnotation::EndEvent メソッドの呼び出しによってまだ確定されていない、これまでの BeginEvent の呼び出し回数を返します。

呼び出し元のアプリケーションが Direct3D プロファイリングツールの下で実行されていない場合、戻り値は –1 になります。

解説(Remarks)

イベントコードのセクションの終了を示すには、EndEvent メソッドを呼び出します。

呼び出し元のアプリケーションが Microsoft Visual Studio Ultimate 2012 などの有効な Direct3D プロファイリングツールの下で実行されている場合、ユーザーはイベントを可視化できます。

呼び出し元のアプリケーションが有効な Direct3D プロファイリングツールの下で実行されていない場合、BeginEvent は効果を持ちません。

例

次のコードは、BeginEvent メソッドと EndEvent メソッドを対で呼び出す方法を示しています。 また、CComPtr スマートポインター型も使用しています。


CComPtr< ID3D11DeviceContext > pContext;

HRESULT hrCreateDevice = (*pfnD3D11CreateDevice)( 
        0,
        D3D_DRIVER_TYPE_NULL,
        0,
        0,
        NULL,
        0,
        D3D11_SDK_VERSION,
        NULL,
        0,
        & pContext );
VERIFY_SUCCEEDED(hrCreateDevice);
CComPtr<ID3DUserDefinedAnnotation> pPerf;
HRESULT hr = pContext->QueryInterface( __uuidof(pPerf), reinterpret_cast<void**>(&pPerf) );
if ( FAILED( hr ) ) 
    return;
pPerf->BeginEvent( L”Now entering ocean rendering code” );
MyDrawOceanRoutine( );
pPerf->EndEvent( );
vtbl 4 INT EndEvent()

イベントコードのセクションの終了を示します。

戻り値

EndEvent の呼び出しによってまだ確定されていない、これまでの ID3DUserDefinedAnnotation::BeginEvent メソッドの呼び出し回数を返します。

呼び出し元のアプリケーションが Direct3D プロファイリングツールの下で実行されていない場合、戻り値は –1 になります。

解説(Remarks)

イベントコードのセクションの開始を示すには、BeginEvent メソッドを呼び出します。

呼び出し元のアプリケーションが Microsoft Visual Studio Ultimate 2012 などの有効な Direct3D プロファイリングツールの下で実行されている場合、ユーザーはイベントを可視化できます。

呼び出し元のアプリケーションが有効な Direct3D プロファイリングツールの下で実行されていない場合、EndEvent は効果を持ちません。

vtbl 5 void SetMarker(LPWSTR Name)

コード内の単一の実行ポイントを示します。

NameLPWSTRinマーカーの名前を格納する NULL 終端の UNICODE 文字列です。この名前はオペレーティングシステムにとっては意味を持ちません。呼び出し元のアプリケーションが Direct3D プロファイリングツールの下で実行されているときに意味のある名前を選択できます。 NULL ポインターを渡した場合の結果は未定義です。

解説(Remarks)

呼び出し元のアプリケーションが Microsoft Visual Studio Ultimate 2012 などの有効な Direct3D プロファイリングツールの下で実行されている場合、ユーザーはマーカーを可視化できます。

呼び出し元のアプリケーションが有効な Direct3D プロファイリングツールの下で実行されていない場合、SetMarker は効果を持ちません。

例

次のコードは、SetMarker の使用方法を示しています。 また、CComPtr スマートポインター型も使用しています。


CComPtr< ID3D11DeviceContext > pID3D11DeviceContext;

HRESULT hrCreateDevice = (*pfnD3D11CreateDevice)( 
        0,
        D3D_DRIVER_TYPE_NULL,
        0,
        0,
        NULL,
        0,
        D3D11_SDK_VERSION,
        NULL,
        0,
        & pID3D11DeviceContext );
VERIFY_SUCCEEDED(hrCreateDevice);

CComPtr<ID3DUserDefinedAnnotation> pPerf;
HRESULT hr = pID3D11DeviceContext->QueryInterface( __uuidof(pPerf), reinterpret_cast<void**>(&pPerf) );
if ( FAILED( hr ) ) 
    return;
pPerf->SetMarker( L”Occlusion test failed- not drawing sun flare” );
vtbl 6 BOOL GetStatus()

呼び出し元のアプリケーションが Microsoft Direct3D プロファイリングツールの下で実行されているかどうかを判定します。

戻り値

呼び出し元のアプリケーションが Visual Studio Ultimate 2012 などの Direct3D プロファイリングツールの下で実行されている場合は 0 以外の値、それ以外の場合は 0 を返します。

解説(Remarks)

ID3DUserDefinedAnnotation インターフェイスの他のメソッドを呼び出す前に、GetStatus を呼び出してアプリケーションが Direct3D プロファイリングツールの下で実行されているかどうかを判定できます。たとえば、ID3DUserDefinedAnnotation::BeginEvent メソッドと ID3DUserDefinedAnnotation::EndEvent メソッドは、呼び出し元のアプリケーションが有効な Direct3D プロファイリングツールの下で実行されていない場合には効果を持ちません。したがって、アプリケーションが Direct3D プロファイリングツールの下で実行されていない限り、これらのメソッドを呼び出す必要はありません。

例

次のコードは、GetStatus の使用方法を示しています。


#ifdef DEVELOPMENT_BUILD
    if ( pPerf->GetStatus() )
        m_MakeD3DAnnotationCalls = true;
#endif

…

   if ( m_ MakeD3DAnnotationCalls )
        pPerf->BeginEvent(L“Drawing Ocean”);
   MyDrawOceanRoutine();
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

#define global IID_ID3DUserDefinedAnnotation "{B2DAAD8B-03D4-4DBF-95EB-32AB4B63D0AB}"
#usecom global ID3DUserDefinedAnnotation IID_ID3DUserDefinedAnnotation "{}"
#comfunc global ID3DUserDefinedAnnotation_BeginEvent  3 wstr
#comfunc global ID3DUserDefinedAnnotation_EndEvent    4
#comfunc global ID3DUserDefinedAnnotation_SetMarker   5 wstr
#comfunc global ID3DUserDefinedAnnotation_GetStatus   6
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。