ホーム › Graphics.Direct3D11 › ID3D11ShaderTrace

ID3D11ShaderTrace

COM

IID36b013e6-2811-4845-baa7-d623fe0df104継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ID3D11ShaderTrace インターフェイスは、シェーダー実行のトレースを取得するためのメソッドを実装します。

解説(Remarks)

ID3D11ShaderTrace のインスタンスを取得するには、ID3D11ShaderTraceFactory::CreateShaderTrace メソッドを呼び出します。ID3D11ShaderTraceFactory のインスタンスを取得するには、D3D11_CREATE_DEVICE_DEBUGGABLE を指定して作成した ID3D11Device に対して IUnknown::QueryInterface を呼び出します。シェーダートレースは D3D11_CREATE_DEVICE_DEBUGGABLE を設定しなくても動作しますが、シェーダーデバッグ用のデバイスを作成することをお勧めします。一部のデバイス (たとえば WARP デバイス) は内部でシェーダーの最適化を行うことがあり、D3D11_CREATE_DEVICE_DEBUGGABLE が設定されていない場合、シェーダートレースがわずかに不正確になる可能性があるためです。

ID3D11ShaderTrace のすべてのメソッドはスレッドセーフです。

ID3D11ShaderTrace のすべてのメソッドは、リファレンスデバイスに対してレンダリングコマンドのフラッシュを直ちに強制します。そのため、リファレンスデバイス上では常に最新のトレース状態が利用できます。つまり、描画操作の後にトレースが準備できていることを期待している場合、実際に準備が完了しています。

注意この API には Windows 8 用の Windows Software Development Kit (SDK) が必要です。

メソッド 8

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

vtbl 3 HRESULT TraceReady(ULONGLONG* pTestCount)

シェーダートレースが記録され、使用可能であるかどうかを示します。

pTestCount

ULONGLONG*

outoptional

トレースに一致する呼び出し (invocation) が発生した回数を受け取る変数への省略可能なポインター。使用しない場合は NULL を設定します。この数値の詳細については、「解説」を参照してください。

戻り値

TraceReady は次の値を返します。

トレースが準備できている場合は S_OK。
トレースが準備できていない場合は S_FALSE。
トレースの記録処理中にメモリが不足した場合は E_OUTOFMEMORY。ID3D11ShaderTrace::ResetTrace を呼び出して再描画することで、トレースの記録を再試行できます。トレースを再記録しない場合は、ID3D11ShaderTrace インターフェイスを解放してください。
Direct3D 11 のリターンコードに記載されているその他のエラーコードが返される場合もあります。

解説(Remarks)

トレースが 3 回目の呼び出しを記録する設定になっているが、これまでに 2 回しか呼び出しが発生していない場合、TraceReady は pTestCount が指す変数に 2 を設定します。この値により、トレースがまだ準備できていない理由を把握できます。逆に、準備が完了しているトレースでは、pTestCount が指す変数が要求した呼び出し回数より大きくなる場合があります。この値を使用すると、必要なトレース呼び出し回数を超えて実行された呼び出しの数を判断できます。たとえば、ある描画呼び出しで特定のシェーダーがピクセルに対して何回オーバードローするかが分からないことがあります。同じシーンを再描画できるのであれば、1 回目のパスで TraceReady が pTestCount に返した値に基づいて、次回のトレースを設定できます。

シェーダートレースが記録されていれば、ID3D11ShaderTrace::GetTraceStats、ID3D11ShaderTrace::GetInitialRegisterContents、ID3D11ShaderTrace::GetStep の各メソッドを正常に呼び出せます。ID3D11ShaderTrace::ResetTrace と ID3D11ShaderTrace::PSSelectStamp の各メソッドは、シェーダートレースが記録されているかどうかにかかわらず呼び出せます。

注意この API には Windows 8 用の Windows Software Development Kit (SDK) が必要です。

vtbl 4 void ResetTrace()

シェーダートレースオブジェクトをリセットします。

解説(Remarks)

ResetTrace を呼び出すと、ID3D11ShaderTrace オブジェクトは作成直後と同じ状態になります。その後、トレースに対するシェーダーの呼び出しは再び 0 から始まり、選択したシェーダー呼び出し回数に達するまで ID3D11ShaderTrace::TraceReady は S_FALSE を返します。到達すると TraceReady は新しいトレースを記録します。

注意この API には Windows 8 用の Windows Software Development Kit (SDK) が必要です。

vtbl 5 HRESULT GetTraceStats(D3D11_TRACE_STATS* pTraceStats)

トレースに関する統計情報を返します。

pTraceStats

D3D11_TRACE_STATS*

out

D3D11_TRACE_STATS 構造体へのポインター。GetTraceStats は、この構造体のメンバーにトレースに関する統計情報を格納します。

戻り値

GetTraceStats は次の値を返します。

トレースの統計情報が正常に取得された場合は S_OK。
トレースの統計情報がまだ利用できない場合は E_FAIL。GetTraceStats が成功するには、ID3D11ShaderTrace::TraceReady が事前に S_OK を返している必要があります。
pTraceStats が NULL の場合は E_INVALIDARG。
Direct3D 11 のリターンコードに記載されているその他のエラーコードが返される場合もあります。

解説(Remarks)

この API には Windows 8 用の Windows Software Development Kit (SDK) が必要です。

vtbl 6 HRESULT PSSelectStamp(DWORD stampIndex)

指定したピクセルシェーダーのスタンプを設定します。

stampIndex

DWORD

選択するスタンプのインデックス。

戻り値

PSSelectStamp は次の値を返します。

ピクセルシェーダーのスタンプを設定し、かつプリミティブがそのスタンプのピクセルとサンプルを覆っている場合は S_OK。
ピクセルシェーダーのスタンプを設定したが、選択したスタンプの呼び出しがプリミティブの範囲外になる場合は S_FALSE。
頂点シェーダーまたはジオメトリシェーダーに対してこのメソッドを呼び出した場合は E_FAIL。PSSelectStamp はピクセルシェーダーに対してのみ意味を持ちます。
stampIndex が範囲 [0..3] の外にある場合は E_INVALIDARG。
Direct3D 11 のリターンコードに記載されているその他のエラーコードが返される場合もあります。

解説(Remarks)

PSSelectStamp を呼び出してピクセルシェーダーのスタンプを設定した後は、ID3D11ShaderTrace::GetInitialRegisterContents、ID3D11ShaderTrace::GetStep、ID3D11ShaderTrace::GetWrittenRegister、ID3D11ShaderTrace::GetReadRegister の各メソッドを呼び出して、そのスタンプのトレースデータを取得できます。

注意この API には Windows 8 用の Windows Software Development Kit (SDK) が必要です。

vtbl 7 HRESULT GetInitialRegisterContents(D3D11_TRACE_REGISTER* pRegister, D3D11_TRACE_VALUE* pValue)

指定した入力レジスタの初期内容を取得します。

pRegister

D3D11_TRACE_REGISTER*

初期内容を取得する入力レジスタを記述する D3D11_TRACE_REGISTER 構造体へのポインター。有効な初期データを取得できるのは、次の入力レジスタ型のみです。つまり、有効なデータを取得するには、D3D11_TRACE_REGISTER の RegType メンバーが次のいずれかの値である必要があります。

データが有効かどうかは、pValue が指す D3D11_TRACE_VALUE 構造体の ValidMask メンバーで示されます。

pValue

D3D11_TRACE_VALUE*

out

D3D11_TRACE_VALUE 構造体へのポインター。GetInitialRegisterContents は、この構造体のメンバーに初期内容に関する情報を格納します。

戻り値

GetInitialRegisterContents は次の値を返します。

レジスタの初期内容を取得できた場合は S_OK。
トレースが利用できない場合は E_FAIL。
pRegister が無効または NULL の場合、あるいは pValue が NULL の場合は E_INVALIDARG。
Direct3D 11 のリターンコードに記載されているその他のエラーコードが返される場合もあります。

解説(Remarks)

pRegister パラメーターの説明で指定した入力レジスタ型以外のレジスタに対しても GetInitialRegisterContents を呼び出すことはできます。ただしその場合、GetInitialRegisterContents は pValue が指す D3D11_TRACE_VALUE 構造体の ValidMask メンバーを空 (すべて 0、0000) に設定し、D3D11_TRACE_VALUE の Bits メンバーが示すレジスタ値は無意味になります。GetInitialRegisterContents が返すデータは、トレース内のステップ実行の影響を受けませんが、ID3D11ShaderTrace::PSSelectStamp の呼び出しによってスタンプインデックスを変更した場合は影響を受けます。

注意この API には Windows 8 用の Windows Software Development Kit (SDK) が必要です。

vtbl 8 HRESULT GetStep(DWORD stepIndex, D3D11_TRACE_STEP* pTraceStep)

トレース内の指定したステップに関する情報を取得します。

stepIndex	DWORD	in	トレース内のステップのインデックス。インデックスの範囲は [0...NumTraceSteps-1] です。NumTraceSteps は D3D11_TRACE_STATS 構造体のメンバーです。ステップの情報は任意の順序で取得できます。
pTraceStep	D3D11_TRACE_STEP*	out	D3D11_TRACE_STEP 構造体へのポインター。GetStep は、この構造体のメンバーに stepIndex パラメーターで指定したトレースステップに関する情報を格納します。

戻り値

GetStep は次の値を返します。

ステップ情報を取得できた場合は S_OK。
トレースが利用できない場合は E_FAIL。
stepIndex が範囲外の場合、または pTraceStep が NULL の場合は E_INVALIDARG。
Direct3D 11 のリターンコードに記載されているその他のエラーコードが返される場合もあります。

解説(Remarks)

この API には Windows 8 用の Windows Software Development Kit (SDK) が必要です。

vtbl 9 HRESULT GetWrittenRegister(DWORD stepIndex, DWORD writtenRegisterIndex, D3D11_TRACE_REGISTER* pRegister, D3D11_TRACE_VALUE* pValue)

トレース内のステップによって書き込まれたレジスタに関する情報を取得します。

stepIndex	DWORD	in	トレース内のステップのインデックス。インデックスの範囲は [0...NumTraceSteps-1] です。NumTraceSteps は D3D11_TRACE_STATS 構造体のメンバーです。情報は任意のステップ順で取得できます。
writtenRegisterIndex	DWORD	in	トレースステップ内のレジスタのインデックス。インデックスの範囲は [0...NumRegistersWritten-1] です。NumRegistersWritten は D3D11_TRACE_STEP 構造体のメンバーです。
pRegister	D3D11_TRACE_REGISTER*	out	D3D11_TRACE_REGISTER 構造体へのポインター。GetWrittenRegister は、この構造体のメンバーに、トレース内のステップによって書き込まれたレジスタに関する情報を格納します。
pValue	D3D11_TRACE_VALUE*	out	D3D11_TRACE_VALUE 構造体へのポインター。GetWrittenRegister は、この構造体のメンバーに、レジスタに書き込まれた値に関する情報を格納します。

戻り値

GetWrittenRegister は次の値を返します。

レジスタ情報を取得できた場合は S_OK。
トレースが利用できない場合、またはトレースが D3D11_SHADER_TRACE_FLAG_RECORD_REGISTER_WRITES フラグを指定して作成されていない場合は E_FAIL。
stepIndex または writtenRegisterIndex が範囲外の場合、あるいは pRegister または pValue が NULL の場合は E_INVALIDARG。
Direct3D 11 のリターンコードに記載されているその他のエラーコードが返される場合もあります。

解説(Remarks)

この API には Windows 8 用の Windows Software Development Kit (SDK) が必要です。

vtbl 10 HRESULT GetReadRegister(DWORD stepIndex, DWORD readRegisterIndex, D3D11_TRACE_REGISTER* pRegister, D3D11_TRACE_VALUE* pValue)

トレース内のステップによって読み取られたレジスタに関する情報を取得します。

stepIndex	DWORD	in	トレース内のステップのインデックス。インデックスの範囲は [0...NumTraceSteps-1] です。NumTraceSteps は D3D11_TRACE_STATS 構造体のメンバーです。情報は任意のステップ順で取得できます。
readRegisterIndex	DWORD	in	トレースステップ内のレジスタのインデックス。インデックスの範囲は [0...NumRegistersRead-1] です。NumRegistersRead は D3D11_TRACE_STEP 構造体のメンバーです。
pRegister	D3D11_TRACE_REGISTER*	out	D3D11_TRACE_REGISTER 構造体へのポインター。GetReadRegister は、この構造体のメンバーに、トレース内のステップによって読み取られたレジスタに関する情報を格納します。
pValue	D3D11_TRACE_VALUE*	out	D3D11_TRACE_VALUE 構造体へのポインター。GetReadRegister は、この構造体のメンバーに、レジスタから読み取られた値に関する情報を格納します。

戻り値

GetReadRegister は次の値を返します。

レジスタ情報を取得できた場合は S_OK。
トレースが利用できない場合、またはトレースが D3D11_SHADER_TRACE_FLAG_RECORD_REGISTER_READS フラグを指定して作成されていない場合は E_FAIL。
stepIndex または readRegisterIndex が範囲外の場合、あるいは pRegister または pValue が NULL の場合は E_INVALIDARG。
Direct3D 11 のリターンコードに記載されているその他のエラーコードが返される場合もあります。

解説(Remarks)

この API には Windows 8 用の Windows Software Development Kit (SDK) が必要です。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ID3D11ShaderTrace "{36B013E6-2811-4845-BAA7-D623FE0DF104}"
#usecom global ID3D11ShaderTrace IID_ID3D11ShaderTrace "{}"
#comfunc global ID3D11ShaderTrace_TraceReady                  3 var
#comfunc global ID3D11ShaderTrace_ResetTrace                  4
#comfunc global ID3D11ShaderTrace_GetTraceStats               5 var
#comfunc global ID3D11ShaderTrace_PSSelectStamp               6 int
#comfunc global ID3D11ShaderTrace_GetInitialRegisterContents  7 var,var
#comfunc global ID3D11ShaderTrace_GetStep                     8 int,var
#comfunc global ID3D11ShaderTrace_GetWrittenRegister          9 int,int,var,var
#comfunc global ID3D11ShaderTrace_GetReadRegister             10 int,int,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_ID3D11ShaderTrace "{36B013E6-2811-4845-BAA7-D623FE0DF104}"
#usecom global ID3D11ShaderTrace IID_ID3D11ShaderTrace "{}"
#comfunc global ID3D11ShaderTrace_TraceReady                  3 sptr
#comfunc global ID3D11ShaderTrace_ResetTrace                  4
#comfunc global ID3D11ShaderTrace_GetTraceStats               5 sptr
#comfunc global ID3D11ShaderTrace_PSSelectStamp               6 int
#comfunc global ID3D11ShaderTrace_GetInitialRegisterContents  7 sptr,sptr
#comfunc global ID3D11ShaderTrace_GetStep                     8 int,sptr
#comfunc global ID3D11ShaderTrace_GetWrittenRegister          9 int,int,sptr,sptr
#comfunc global ID3D11ShaderTrace_GetReadRegister             10 int,int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。