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.
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:
- 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.lib
- 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.
API Reference
PIXBeginEvent
PIXBeginEvent marks the start of a user-defined region of CPU or GPU work. There are overloads of PIXBeginEvent that support different types of strings and CPU and GPU events. Use PIXEndEvent to mark the end of the region.
1 2 3 4 5 6 7 8 9 | // CPU only void PIXBeginEvent(UINT64 color, char const* formatString, ...) void PIXBeginEvent(UINT64 color, wchar_t const* formatString, ...) // GPU and CPU void PIXBeginEvent(ID3D12CommandList* commandList, UINT64 color, char const* formatString, ...) void PIXBeginEvent(ID3D12CommandList* commandList, UINT64 color, wchar_t const* formatString, ...) void PIXBeginEvent(ID3D12CommandQueue* commandQueue, UINT64 color, char const* formatString, ...) void PIXBeginEvent(ID3D12CommandQueue* commandQueue, UINT64 color, wchar_t const* formatString, ...) |
The GPU overloads also start an implicit CPU region.
PIXEndEvent
PIXEndEvent marks the end of a user-defined region of CPU or GPU work. There are overloads of PIXEndEvent that support different types of CPU and GPU events. Note that a GPU region that was started on a command list may be ended on a command list or a command queue, and vice versa.
1 2 3 4 5 6 | // CPU only void PIXEndEvent() // GPU and CPU void PIXEndEvent(ID3D12CommandList* commandList) void PIXEndEvent(ID3D12CommandQueue* commandQueue) |
The GPU overloads also end an implicit CPU region.
PIXSetMarker
PIXSetMarker inserts a user-defined marker into the CPU or GPU timeline:
1 2 3 4 5 6 7 8 9 | // CPU void PIXSetMarker(UINT64 color, char const* formatString, ...) void PIXSetMarker(UINT64 color, wchar_t const* formatString, ...) // GPU and CPU void PIXSetMarker(ID3D12GraphicsCommandList* commandList, UINT64 color, char const* formatString, ...) void PIXSetMarker(ID3D12GraphicsCommandList* commandList, UINT64 color, wchar_t const* formatString, ...) void PIXSetMarker(ID3D12CommandQueue* commandQueue, UINT64 color, char const* formatString, ...) void PIXSetMarker(ID3D12CommandQueue* commandQueue, UINT64 color, wchar_t const* formatString, ...) |
PIXScopedEvent
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, ...) |
PIXReportCounter
PIXReportCounter allows a custom value to be graphed in System Monitor or timing captures.
1 | void PIXReportCounter(wchar_t const* name, float value) |
Note that PIXReportCounter does not has a char const* overload.
PIXNotifyWakeFromFenceSignal
Timing captures can show when a thread wakes up as the result of a fence being signaled. This needs some help from the application in the form of PIXNotifyWakeFromFenceSignal. This 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.
1 | void PIXNotifyWakeFromFenceSignal(HANDLE event) |
Color
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 2 3 4 5 6 | // Returns a color for a PIX event or marker from the specified red, green and blue values INT PIX_COLOR(BYTE r, BYTE g, BYTE b) // Returns an arbitrary color value for the given index. // PIX allocates a unique color for each index. UINT PIX_COLOR_INDEX(BYTE i) |
Formatted Strings
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.
Unsupported functions
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() |
ABI Usage
Most of the implementation of PIX markers is in the header file with the DLL providing support functionality. The stable interface though is in the header file. If for some reason it is necessary to use a stable ABI then these entry points are available. These have a stronger compatability guarantee than the other WinPixEventRuntime.dll exports.
Most users should continue to use pix3.h. This will provide richer and more optimized functionality.
The source snippet below is subject to the MIT license
Use LoadLibrary to load the dll and GetProcAddress to access the exports:
1 2 3 4 5 6 7 8 9 | typedef HRESULT(WINAPI* BeginEventOnCommandList)(ID3D12GraphicsCommandList* commandList, UINT64 color, _In_ PCSTR formatString); typedef HRESULT(WINAPI* EndEventOnCommandList)(ID3D12GraphicsCommandList* commandList); typedef HRESULT(WINAPI* SetMarkerOnCommandList)(ID3D12GraphicsCommandList* commandList, UINT64 color, _In_ PCSTR formatString); HMODULE module = LoadLibrary(L"WinPixEventRuntime.dll"); BeginEventOnCommandList pixBeginEventOnCommandList = (BeginEventOnCommandList)GetProcAddress(module, "PIXBeginEventOnCommandList"); EndEventOnCommandList pixEndEventOnCommandList = (EndEventOnCommandList)GetProcAddress(module, "PIXEndEventOnCommandList"); SetMarkerOnCommandList pixSetMarkerOnCommandList = (SetMarkerOnCommandList)GetProcAddress(module, "PIXSetMarkerOnCommandList"); |
Error handling and more careful resource management is left as an exercise for the reader.
Release History
- 1.0.190604001 – Fix compatability with old versions of PIX and the debug layer, fix building with /permissive-
- 1.0.190510001 – Add ABI exports to DLL
- 1.0.190425002 – ARM64 support
- 1.0.181206001 – Add PIXNotifyWakeFromFenceSignal
