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.
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:
- Right-click on the project in Solution Explorer.
- Manage NuGet Packages.
- Select the Browse tab.
- Type “WinPixEventRuntime” into the search box.
- Select the package and click Install.
- 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:
- Click the Download link on https://www.nuget.org/packages/WinPixEventRuntime
- Rename the .nupkg file to a .zip extension, then extract its contents.
- Include the header file: Include\WinPixEventRuntime\pix3.h
- Link with the library:
- For desktop apps: bin\WinPixEventRuntime.dll
- For Universal Windows Platform (UWP) apps: bin\WinPixEventRuntime_UAP.lib
- 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 is 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 that 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.
pix3.h provides the following instrumentation functions:
1 2 | void PIXBeginEvent(UINT64 color, char const* formatString, ...) void PIXBeginEvent(UINT64 color, wchar_t const* formatString, ...) |
Marks the start of a user-defined region of CPU work.
1 2 | void PIXBeginEvent(ID3D12GraphicsCommandList* commandList, UINT64 color, wchar_t const* formatString, ...) void PIXBeginEvent(ID3D12GraphicsCommandList* commandList, UINT64 color, char const* formatString, ...) |
Marks the start of a user-defined region of GPU work on the specified command list.
1 2 | void PIXBeginEvent(ID3D12CommandQueue* commandQueue, UINT64 color, char const* formatString, ...) void PIXBeginEvent(ID3D12CommandQueue* commandQueue, UINT64 color, wchar_t const* formatString, ...) |
Marks the start of a user-defined region of GPU work on the specified command queue.
1 2 3 | void PIXEndEvent() void PIXEndEvent(ID3D12GraphicsCommandList* commandList) void PIXEndEvent(ID3D12CommandQueue* commandQueue) |
Marks the end of a user-defined region of CPU or GPU work.
1 2 | void PIXSetMarker(UINT64 color, char const* formatString, ...) void PIXSetMarker(UINT64 color, wchar_t const* formatString, ...) |
Inserts a user-defined marker into the CPU timeline.
1 2 | void PIXSetMarker(ID3D12GraphicsCommandList* commandList, UINT64 color, char const* formatString, ...) void PIXSetMarker(ID3D12GraphicsCommandList* commandList, UINT64 color, wchar_t const* formatString, ...) |
Inserts a user-defined marker into the GPU timeline of the specified command list.
1 2 | void PIXSetMarker(ID3D12CommandQueue* commandQueue, UINT64 color, char const* formatString, ...) void PIXSetMarker(ID3D12CommandQueue* commandQueue, UINT64 color, wchar_t const* formatString, ...) |
Inserts a user-defined marker into the GPU timeline of the specified command queue.
1 | void PIXReportCounter(wchar_t const* name, float value) |
Allows a custom value to be graphed in System Monitor as counter “name”.
1 | void PIXNotifyWakeFromFenceSignal(HANDLE event) |
Notifies PIX that an event handle was set as a result of a D3D12 fence being signaled. The event specified must have the same handle value as the handle used in ID3D12Fence::SetEventOnCompletion. PIX will use these events in Timing Captures to visualize fence/signal dependencies.
The PIXScopedEvent macro has the same overloads as PixBeginEvent, but will automatically issue a matching PixEndEvent call at the end of the C++ code scope where it is used:
1 2 3 4 5 6 | PIXScopedEvent(UINT64 color, char const* formatString, ...) PIXScopedEvent(UINT64 color, wchar_t const* formatString, ...) PIXScopedEvent(ID3D12GraphicsCommandList* commandList, UINT64 color, char const* formatString, ...) PIXScopedEvent(ID3D12GraphicsCommandList* commandList, UINT64 color, wchar_t const* formatString, ...) PIXScopedEvent(ID3D12CommandQueue* commandQueue, UINT64 color, char const* formatString, ...) PIXScopedEvent(ID3D12CommandQueue* commandQueue, UINT64 color, wchar_t const* formatString, ...) |
These functions are defined in pix3.h, but not currently supported by PIX on Windows:
1 2 3 | HRESULT PIXBeginCapture(DWORD captureFlags, const PPIXCaptureParameters captureParameters) HRESULT PIXEndCapture(BOOL discard) DWORD PIXGetCaptureState() |
The color parameter controls how the event will be displayed in timeline lanes when it appears in the PIX timing capture user interface. Suitable values can be obtained from one of these helpers, or you can pass in a raw DWORD noting that the format is ARGB and the alpha channel value must be 0xff:
1 | UINT PIX_COLOR(BYTE r, BYTE g, BYTE b) |
Specifies a color for a PIX event or marker, from red, green and blue values.
1 | UINT PIX_COLOR_INDEX(BYTE i) |
Specifies an arbitrary color index. PIX allocates a unique color for each index number.
In order to minimize instrumentation overhead, the PIXBeginEvent and PIXSetMarker functions directly save their format string and format parameters instead of formatting the string at runtime. Formatting is then done when reading the capture file in PIX. Use 16-byte aligned strings (preferable) or 8-byte aligned strings to get the best performance. To print a char* or wchar_t* as a pointer using %p format specifier, cast the pointer to void* when passing it to these functions.
