pixtool.exe

pixtool.exe は、一般的なキャプチャ ワークフローを自動化するための PIX コマンドライン ツールです。 これを使用して、アプリの起動またはアタッチ、GPU またはタイミング キャプチャの取得、 .wpix キャプチャを開く、キャプチャ データのエクスポート、GPU キャプチャの一部を再キャプチャ、GPU キャプチャのアップグレード、PIX UI を開かないでの再生チェックの実行を行います。

pixtool.exe WinPix.exe と同じバージョン管理されたインストール フォルダーの %ProgramFiles%\Microsoft PIX\<version>\ で PIX を使用してインストールされます。 PIX プレビュー ビルドと試験的ビルドは、一致する %ProgramFiles% 製品フォルダーを使用します。

PIX インストール フォルダーから pixtool を実行し、そのフォルダーを PATH に追加するか、実行可能ファイルへの引用符で囲まれた完全なパスを指定します。

"%ProgramFiles%\Microsoft PIX\<version>\pixtool.exe" --help

pixtool --help を実行してコマンド リストを表示するか、pixtool --help <command> を実行して 1 つのコマンドの詳細なヘルプを表示します。

コマンド チェーン

pixtool コマンド ラインには、任意の数のコマンドを含めることができます。 pixtool 最初にグローバル オプションを解析し、同じセッションで各コマンドを左から右に実行します。 後のコマンドでは、起動されたアプリ、新しく取得したキャプチャ、 open-captureによって開かれたキャプチャなど、以前のコマンドの状態を使用できます。

コマンド プロンプトでキャレット (^) を使用して、長いコマンド ラインを複数の行に分割します。

pixtool ^
  open-capture foo.wpix --remote=192.168.1.1 ^
  save-event-list eventlist.csv --counters=*

グローバル オプション

オプション 説明
--help 全般的なヘルプを表示します。
--help <command> 特定のコマンドのヘルプを表示します。
--output=<level> 本体出力の詳細を quiet、 trace、 engine、または verbose に設定します。 既定値は trace です。
--log=<level> ログ ファイルの詳細度を quiet、 trace、 engine、 verbose、または off に設定します。 既定値は verbose です。
--log-file=<filename> ログ ファイル パスを設定します。 既定値は一時ファイル フォルダーに pixtool.log されます。

コマンド

次の表に、 pixtool --help によって示されるパブリック コマンドを示します。 オプションは、各コマンドのヘルプ テキストから取得されます。

コマンド 説明 オプション
launch <exe> [...] GPU キャプチャ用の実行可能ファイルを起動します。 --command-line=<cl> コマンド ライン パラメーターを実行可能ファイルに渡します。
--working-directory=<dir> 作業ディレクトリを設定します。既定値は、実行可能ファイルを含むディレクトリです。
--setenv="VARNAME=VARVALUE" 環境変数を設定します。複数回指定できます。
--remote=<machine name> リモート キャプチャ マシンを指定します。既定値は localhost です。
--timing タイミング キャプチャ用にアプリを起動します。
--force11on12 PIX で D3D11On12 を使用するように強制します。
--captureFromStart 後続の take-capture が実行の開始時からキャプチャできるように、アプリを一時停止して起動します。
launch-app <package> <application> [...] GPU キャプチャ用の UWP アプリを起動します。 <package> はパッケージの完全な名前です。
<application> はアプリケーション ID です。
--remote=<machine name> リモート キャプチャ マシンを指定します。既定値は localhost です。
--timing タイミング キャプチャ用にアプリを起動します。
--force11on12 PIX に D3D11On12 を強制的に使用させ、 --GpuCapture と相互に排他的です。
--GpuCapture 従来のコマンド ラインの既定の GPU キャプチャ モードを選択し、 --force11on12 と相互に排他的です。
set-gpu-capture-parameters [--frames=<n>] [...] 後続のすべてのキャプチャのパラメーターを設定します。 --frames=<n> キャプチャするフレーム数を設定します。既定値は 1 です。
--capture-key=<F1-F12> 手動キャプチャキーを設定します。既定値は F11 です。
--winml現在から現在への変換ではなく、フレーム区切り記号として Windows ML 動作を使用します。
--remote=<machine name> 構成するリモート キャプチャ マシンを指定します。既定値は localhost です。
take-capture [--open] [...] 現在起動されているアプリの GPU キャプチャを取得します。 --open キャプチャを取得した後、ターゲット マシンでキャプチャを開きます。
--winml現在から現在への変換ではなく、フレーム区切り記号として Windows ML 動作を使用します。
--frames=<n> キャプチャするフレーム数を設定します。既定値は 1、または set-gpu-capture-parameters によって設定される値です。
programmatic-capture [--open] [--until-exit] 現在起動されているアプリによってプログラムによるキャプチャがトリガーされるまで待機します。 --open --until-exit も指定されていない限り、トリガー後にターゲット コンピューターでプログラムによるキャプチャを開きます。
--until-exit save-all-capturesするために、アプリからすべてのプログラムによるキャプチャを複数のキャプチャ ファイルにキャプチャします。
save-capture <filename> 現在開いているキャプチャを指定されたファイル名に保存します。 ありません。
save-all-captures <directory> この GPU キャプチャ起動セッションで最近取得したすべてのキャプチャを、指定されたディレクトリに保存します。 ありません。
open-capture <filename> [...] Windows GPU キャプチャ .wpix ファイルを開きます。 --remote=<machine name> リモート分析マシンを指定します。既定値は localhost です。
--use-replay-time-executeindirect-buffers キャプチャ時バッファーではなく、再生時の ExecuteIndirect 引数バッファーを使用します。
--disable-gpu-plugins キャプチャが開いている間は GPU プラグインは読み込まれません。
--enable-recreate-at-gpuva リプレイ デバイスがサポートしている場合、キャプチャ時の GPU 仮想アドレスでヒープとバッファー リソースを再作成します。
--disable-application-specific-driver-state 再生中に、アプリケーション固有のドライバー回避策を設定しません。
--force-set-application-specific-driver-state デバイスまたはドライバーの不一致に関係なく、再生中にアプリケーション固有のドライバー回避策を強制的に設定します。
list-counters 使用可能なすべてのカウンターを一覧表示します。 ありません。
save-event-list <filename> [...] イベント リストを CSV 形式で保存します。 --counters=<pattern> パターンに一致し、複数回指定できるカウンターを含みます。キュー ID、名前、グローバル ID は常に含まれます。
--counter-groups=<pattern> パターンに一致するカウンター グループ内のすべてのカウンターが含まれます。
--queue-name=<queue name> イベント リストに使用するキューを選択します。
run-debug-layer デバッグ レイヤーを有効にして強制的に再生します。 ありません。
save-high-frequency-counters <filename> [...] 高周波カウンターのデータを収集し、CSV 形式で保存します。 --counters=<pattern> パターンに一致するカウンターを含み、複数回指定できます。
--merge タイムスタンプを 1 つの列にマージし、カウンター データを結合します。
save-screenshot <filename> キャプチャのスクリーンショットを PNG ファイルとして保存します。 ありません。
save-resource <filename> [...] 特定の描画呼び出しからリソースを保存します。 --rtv=<RenderTargetView index> 指定されたレンダー ターゲット ビューを保存します。既定値は 0 です。
--depth 深度バッファーの視覚的表現を保存します。PNG ファイルのみがサポートされています。
--global-id=<Global ID> 指定されたグローバル ID を持つイベントからリソースを保存します。
--marker=<name> リソースのバインドされたインスタンスを持つ PIX マーカーの下の最後の子イベントからリソースを保存します。
begin-recapture pixtool 自体のキャプチャを開始します。 ありません。
end-recapture 再キャプチャを終了します。 ありません。
recapture-single-playback [...] 現在開いているファイルの再生のキャプチャを実行します。 --include-recreation リプレイ レクリエーション イベントをキャプチャします。
--expand-execute 再生中に ExecuteIndirect 引数バッファーを拡張します。
perform-single-playback [...] 現在開いているファイルを 1 回再生します。 --do-not-expand-executeindirect 再生中に ExecuteIndirect 引数バッファーを親コマンド リストに展開しません。
--loop プロセスが終了するまで 1 回の再生を繰り返します。
--loop-count=<n> 再生をループする回数を設定します。既定値は 0 で、無期限を意味し、このオプションは --loop でのみ有効です。
--time-cpu 再生中のコマンド リストの記録時間を測定し、現在の作業ディレクトリに CSV ファイルを書き込みます。
--measure-cycles CPU 時間をミリ秒ではなくサイクルで測定し、 --time-cpuでのみ有効です。
recapture-region <outputFilePath> [...] 現在開いているキャプチャ ファイルの領域を再キャプチャします。 --start=<GlobalID> 再キャプチャされたファイルに含める最初のグローバル ID を設定します。
--end=<GlobalID> 再キャプチャされたファイルに含める最後のグローバル ID を設定します。
take-new-timing-capture <filename> [--duration=<n>] [...] 現在のアプリの新しいタイミング キャプチャを取得して保存します。 <filename> ターゲット キャプチャ ファイルのパスを設定します。ターゲット ディレクトリが存在する必要があります。
--duration=<n> 指定された期間をミリ秒単位でキャプチャします。既定値は 100 です。
--until-exit ターゲット プロセスが終了し、 --duration と組み合わせることができなくなるまでキャプチャします。
--circular キャプチャーはリング バッファーに格納され、 --etlと組み合わせることはできません。
--max-file-size-mb=<n> 循環リング バッファーのメモリ制限を MB 単位で設定します。既定値は 4096、最小値は 256、最大値は 8192 です。
--etl生の ETW トレースを .wpix キャプチャに処理する代わりに、<filename> に書き込みます。
--sample-rate=<n> CPU サンプリング レートを 1 秒あたりのサンプル数で設定します。既定値は 1000、最小値は 1、最大値は 8000 です。
--no-cpu-samples CPU サンプルを除外します。
--no-callstacks コンテキスト スイッチのコール スタックを除外します。
--no-gpu-timings GPU タイミングと GPU メモリ使用量を除外します。
--no-gpu-memory GPU メモリ使用量を除外します。
--no-gpu-only-eventsまた、それらを発生させたスレッドの CPU タイムライン上の GPU コンテキストで発生する PIX イベントも表示されます。
--file-io ファイル I/O イベントをキャプチャします。
--virtual-alloc-events VirtualAlloc イベントと VirtualFree イベントをキャプチャします。
--heap-alloc-events ヒープ割り当てイベントをキャプチャします。
--pix-alloc-events PIX メモリ割り当てイベントをキャプチャします。
--page-faults ページ フォールト イベントをキャプチャします。
--clr-data マネージド アプリケーションの .NET/CLR データをキャプチャします。
--stacks-for-all-processes ターゲットだけでなく、すべてのプロセスのコール スタックをキャプチャします。
--merge-kernel-images カーネル イメージをマージして、カーネル シンボルが解決されるようにします。
--minimal-instrumentation D3D12 ランタイムの最小限の ETW インストルメンテーションを使用し、Agility SDK 1.717 以降が必要です。
レガシ エイリアス --sampleRate、 --noCpuSamples、 --noCallstacks、および --noGpuTimings は引き続き機能します。
attach <targetProcessId> 指定した実行中のプロセスに接続します。 <targetProcessId> はターゲット プロセス ID です。
--remote=<machine name> リモート キャプチャ マシンを指定します。既定値は localhost です。
export-to-cpp <directory> [--force] [--use-winpixeventruntime] [...] PIX でキャプチャされたフレームを C++ プロジェクトとしてエクスポートします。 --force 同じ名前のファイルを上書きします。
--use-winpixeventruntime WinPixEventRuntime ライセンスを確認し、同意します。
--use-agilitySdk DirectX 12 Agility SDK ライセンスを確認し、同意します。
--use-replay-time-executeindirect-buffers キャプチャ時のコピーではなく、再生時引数バッファーを使用して ExecuteIndirect 呼び出しを再生します。
upgrade-gpu-capture <sourceCapturePath> [--dest=<destCapturePath>] GPU キャプチャ ファイルを最新の形式にアップグレードします。 --dest=<destCapturePath> アップグレードされたキャプチャのコピー先パスを設定します。 --dest を指定して出力パスを制御します。省略した場合、現在の実装では現在の作業ディレクトリが宛先ディレクトリとして使用されます。

ワークフローの例

サンプルの実行可能パス、パッケージ名、プロセス ID、グローバル ID、カウンター パターンを、アプリまたはキャプチャの値に置き換えます。

Win32 アプリの GPU キャプチャを取得する

GPU キャプチャ用にアプリを起動し、1 つのキャプチャを取得し、ターゲット マシンで開き、 .wpix ファイルとして保存します。

pixtool launch C:\Apps\D3D12HelloTriangle.exe take-capture --open save-capture C:\Captures\triangle.wpix

既定の 1 フレーム以上が必要な場合は、キャプチャを取得する前にキャプチャ パラメーターを設定します。

pixtool set-gpu-capture-parameters --frames=3 --capture-key=F10 launch C:\Apps\D3D12HelloTriangle.exe take-capture --open save-capture C:\Captures\triangle-3frames.wpix

必要なフレームが起動直後に開始される場合は --captureFromStart を使用します。 起動されたアプリは、take-capture がキャプチャを要求するまで一時停止のままであるため、同じコマンド ラインに take-capture を含めます。

pixtool launch C:\Apps\D3D12HelloTriangle.exe --captureFromStart take-capture --open save-capture C:\Captures\triangle-start.wpix

環境変数の値に等号が含まれているため、 --setenv 値を引用します。

pixtool launch C:\Apps\D3D12HelloTriangle.exe --setenv="PIX_TEST_MODE=1" take-capture --open save-capture C:\Captures\triangle-env.wpix

最初に開かずに、起動された 1 つのアプリから複数のキャプチャを保存します。

pixtool launch C:\Apps\D3D12HelloTriangle.exe take-capture take-capture save-all-captures C:\Captures\TriangleRun

タイミング キャプチャを取得する

タイミング キャプチャ用のアプリを起動し、5 秒 .wpix のタイミング キャプチャを保存します。

pixtool launch C:\Apps\Game.exe --timing take-new-timing-capture C:\Captures\game-timing.wpix --duration=5000

既に実行中のプロセスにアタッチし、プロセスが終了するまでキャプチャします。

pixtool attach 12345 take-new-timing-capture C:\Captures\game-until-exit.wpix --until-exit

イベントとカウンターのデータを CSV にエクスポートする

.wpix GPU キャプチャを開き、使用可能なすべてのイベント カウンターを含むイベント リストをエクスポートします。

pixtool open-capture C:\Captures\frame.wpix save-event-list C:\Exports\eventlist.csv --counters=*

正確なカウンター名またはグループが必要な場合は、最初に list-counters を使用してください。

pixtool open-capture C:\Captures\frame.wpix list-counters

イベント一覧の CSV は、Excel または他のデータ ツールで開くことができます。

Excel で開かれた pixtool イベント一覧の CSV ファイルのスクリーンショット。

キャプチャで GPU プラグインからのストリーミング カウンターがサポートされている場合にのみ、高周波数カウンターをエクスポートします。

pixtool open-capture C:\Captures\frame.wpix save-high-frequency-counters C:\Exports\high-frequency-counters.csv --counters=* --merge

キャプチャから画像とリソースを保存する

GPU キャプチャを開き、キャプチャに保存されているスクリーンショットを保存し、特定のイベントのレンダー ターゲット 0 を保存します。

pixtool open-capture C:\Captures\frame.wpix save-screenshot C:\Exports\capture-screenshot.png save-resource C:\Exports\rtv0.png --global-id=42 --rtv=0

PIX マーカーが必要なイベント範囲を一意に識別する場合は、その深度バッファーを PIX マーカーの下に保存します。

pixtool open-capture C:\Captures\frame.wpix save-resource C:\Exports\terrain-depth.png --marker=Terrain --depth

GPU キャプチャを再キャプチャまたはアップグレードする

選択したグローバル ID 範囲のみを含む小さなキャプチャを作成します。

pixtool open-capture C:\Captures\frame.wpix recapture-region C:\Captures\frame-region.wpix --start=400 --end=520

元のファイルを上書きせずに、古い GPU キャプチャを現在のキャプチャ形式にアップグレードします。

pixtool upgrade-gpu-capture C:\Captures\old-frame.wpix --dest=C:\Captures\upgraded-frame.wpix

begin-recapture、end-recapture、および recapture-single-playback では、PIX または別の pixtool インスタンスからの GPU キャプチャで pixtool 自体を実行する必要があります。

再生チェックを実行する

キャプチャを開き、有限再生ループを実行します。

pixtool open-capture C:\Captures\frame.wpix perform-single-playback --loop --loop-count=10

キャプチャを C++ にエクスポートする

キャプチャを開き、キャプチャしたフレームを C++ プロジェクトとしてエクスポートします。

pixtool open-capture C:\Captures\frame.wpix export-to-cpp C:\Exports\FrameProject --force --use-winpixeventruntime --use-agilitySdk