WinPixEventRuntime

PIX events are used to instrument your game, labeling regions of CPU or GPU work and marking important occurrences. Including this instrumentation while developing the game can make PIX captures far nicer to work with.

An event represents a region of time, so an event has a begin and an end. A marker is used to represent a single point in time.

The source code for the WinPixEventRuntime is available in the GitHub repository PixEvents. For the full list of instrumentation APIs, see the WinPixEventRuntime API reference.

CPU and GPU-context events

PIXBeginEvent and PIXEndEvent calls without a Direct3D context define a PIX CPU event on the current thread. The begin and end calls must run on the same CPU thread so PIX can close the event on that thread's timeline.

The overloads with a Direct3D context parameter define a PIX GPU event that labels GPU work on that context. Use these overloads with a supported D3D12 command list or command queue. The begin and end calls for a PIX GPU event can run on different CPU threads; keep them balanced for the D3D12 context work. The ability to begin and end an event on different threads applies only to PIX GPU events.

Because the begin and end of a PIX GPU event can run on different CPU threads, a single event on one CPU thread can't accurately represent how the CPU work relates to the GPU work. Instead, in timing captures, PIX shows the CPU-side begin and end of a PIX GPU event as PIX CPU markers on the threads that made the calls, and draws arrows between those markers and the corresponding GPU event.

$END GPU EVENT markers

If PIX can't associate an end call with a PIX GPU event, the CPU timeline shows a marker named $END GPU EVENT. This can happen when:

• Command lists or command queues are created on the CPU but never submitted to the GPU.
• The D3D debug layer is enabled. Events with a short duration might not be logged to PIX.
• The capture stops after the CPU work for an event is done but before the corresponding GPU work completes.

Installation

The PIX event runtime is distributed as a NuGet package. If your project builds in Visual Studio, you can use Visual Studio to add this package:

1. Right-click on the project in Solution Explorer.
2. Select Manage NuGet Packages.
3. Select the Browse tab.
4. Type "WinPixEventRuntime" into the search box.
5. Select the package and select Install.
6. You can now #include "pix3.h" to access the PIX event APIs.

If your project uses some other build technology than Visual Studio, you can manually consume the NuGet package contents:

1. Select the Download link on https://www.nuget.org/packages/WinPixEventRuntime.
2. Rename the .nupkg file to a .zip extension, then extract its contents.
3. Include the header file: Include\WinPixEventRuntime\pix3.h.
4. Link with the library:
   • For desktop apps: bin\WinPixEventRuntime.lib
   • For Universal Windows Platform (UWP) apps: bin\WinPixEventRuntime_UAP.lib
5. Place the corresponding .dll next to your game.

PIX instrumentation is only enabled if one of the preprocessor symbols USE_PIX, DBG, _DEBUG, PROFILE, or PROFILE_BUILD is defined. Otherwise the marker APIs compile out to nothing, which is typically what you want for final release builds of the game. It's often useful to maintain an intermediate build flavor for profiling purposes, which is fully optimized and leaves out self-checks such as ASSERT, but does include the PIX marker instrumentation. To do this, define one of the symbols USE_PIX or PROFILE before including pix3.h.

Note

The Windows SDK provides an older header named pix.h. This defines similar functions to pix3.h, but is obsolete and not compatible with PIX.