PIX events are used to instrument your game, labeling regions of CPU or GPU work and marking important occurrences.\u00a0 Including this instrumentation while developing the game can make PIX captures far nicer to work with.<\/p>\n
An “event” represents a region of time – so an event has a begin and an end.\u00a0 A “marker” is used to represent a single point in time.<\/p>\n
The PIX event runtime is distributed as a NuGet package<\/a>.\u00a0 If your project builds in Visual Studio, you can use Visual Studio to add this package:<\/p>\n If your project uses some other build technology than Visual Studio, you can manually consume the NuGet package contents:<\/p>\n PIX instrumentation is only enabled if one of the preprocessor symbols USE_PIX, DBG, _DEBUG, PROFILE, or PROFILE_BUILD is defined.\u00a0 Otherwise the marker APIs compile out to nothing, which is typically what you want for final release builds of the game.\u00a0 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.\u00a0 To do this, define one of the symbols USE_PIX or PROFILE before including pix3.h.<\/p>\n Note that the Windows SDK provides an older header named pix.h.\u00a0 This defines similar functions to pix3.h, but is obsolete and not compatible with PIX.<\/p>\n PIXBeginEvent marks the start of a user-defined region of CPU or GPU work.\u00a0 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. The paired calls to PIXBeginEvent and PIXEndEvent must be made from the same thread.<\/p>\n The GPU overloads also start an implicit CPU region.<\/p>\n 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.<\/p>\n The GPU overloads also end an implicit CPU region.<\/p>\n PIXSetMarker inserts a user-defined marker into the CPU or GPU timeline:<\/p>\n 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:<\/p>\n PIXReportCounter allows a custom value to be graphed in System Monitor or timing captures.<\/p>\n Note that PIXReportCounter does not has a char const*<\/tt> overload.<\/p>\n Timing captures<\/a> 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<\/tt>.<\/p>\n The color parameter controls how the event will be displayed in timeline lanes when it appears in the PIX timing capture user interface.\u00a0 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:<\/p>\n 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.<\/p>\n PIX on Windows supports programmatic capture APIs (such as PIXBeginCapture) for GPU Captures. Please see this page <\/a>for more details.<\/p>\n 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.<\/p>\n Most users should continue to use pix3.h. This will provide richer and more optimized functionality.<\/em><\/p>\n The source snippet below is subject to the MIT license<\/a><\/p>\n Use LoadLibrary to load the dll and GetProcAddress to access the exports:<\/p>\n Error handling and more careful resource management is left as an exercise for the reader.<\/p>\n\n
\n
\n
API Reference<\/h2>\n
PIXBeginEvent<\/h2>\n
\/\/ CPU only\r\nvoid PIXBeginEvent(UINT64 color, char const* formatString, ...)\r\nvoid PIXBeginEvent(UINT64 color, wchar_t const* formatString, ...)\r\n\r\n\/\/ GPU and CPU\r\nvoid PIXBeginEvent(ID3D12CommandList* commandList, UINT64 color, char const* formatString, ...)\r\nvoid PIXBeginEvent(ID3D12CommandList* commandList, UINT64 color, wchar_t const* formatString, ...)\r\nvoid PIXBeginEvent(ID3D12CommandQueue* commandQueue, UINT64 color, char const* formatString, ...)\r\nvoid PIXBeginEvent(ID3D12CommandQueue* commandQueue, UINT64 color, wchar_t const* formatString, ...)\r\n<\/pre>\n
PIXEndEvent<\/h2>\n
\/\/ CPU only\r\nvoid PIXEndEvent()\r\n \r\n\/\/ GPU and CPU\r\nvoid PIXEndEvent(ID3D12CommandList* commandList)\r\nvoid PIXEndEvent(ID3D12CommandQueue* commandQueue)<\/pre>\n
PIXSetMarker<\/h2>\n
\/\/ CPU\r\nvoid PIXSetMarker(UINT64 color, char const* formatString, ...)\r\nvoid PIXSetMarker(UINT64 color, wchar_t const* formatString, ...)\r\n\r\n\/\/ GPU and CPU\r\nvoid PIXSetMarker(ID3D12GraphicsCommandList* commandList, UINT64 color, char const* formatString, ...)\r\nvoid PIXSetMarker(ID3D12GraphicsCommandList* commandList, UINT64 color, wchar_t const* formatString, ...)\r\nvoid PIXSetMarker(ID3D12CommandQueue* commandQueue, UINT64 color, char const* formatString, ...)\r\nvoid PIXSetMarker(ID3D12CommandQueue* commandQueue, UINT64 color, wchar_t const* formatString, ...)<\/pre>\n
PIXScopedEvent<\/h2>\n
PIXScopedEvent(UINT64 color, char const* formatString, ...)\r\nPIXScopedEvent(UINT64 color, wchar_t const* formatString, ...)\r\nPIXScopedEvent(ID3D12GraphicsCommandList* commandList, UINT64 color, char const* formatString, ...)\r\nPIXScopedEvent(ID3D12GraphicsCommandList* commandList, UINT64 color, wchar_t const* formatString, ...)\r\nPIXScopedEvent(ID3D12CommandQueue* commandQueue, UINT64 color, char const* formatString, ...)\r\nPIXScopedEvent(ID3D12CommandQueue* commandQueue, UINT64 color, wchar_t const* formatString, ...)<\/pre>\n
PIXReportCounter<\/h2>\n
void PIXReportCounter(wchar_t const* name, float value)<\/pre>\n
PIXNotifyWakeFromFenceSignal<\/h2>\n
void PIXNotifyWakeFromFenceSignal(HANDLE event)<\/pre>\n
Color<\/h2>\n
\/\/ Returns a color for a PIX event or marker from the specified red, green and blue values\r\n INT PIX_COLOR(BYTE r, BYTE g, BYTE b)\r\n\r\n\/\/ Returns an arbitrary color value for the given index.\r\n\/\/ PIX allocates a unique color for each index.\r\nUINT PIX_COLOR_INDEX(BYTE i)<\/pre>\n
Formatted Strings<\/h2>\n
Other functions<\/h2>\n
<\/a>ABI Usage<\/h2>\n
typedef void(WINAPI* BeginEventOnCommandList)(ID3D12GraphicsCommandList* commandList, UINT64 color, _In_ PCSTR formatString);\r\ntypedef void(WINAPI* EndEventOnCommandList)(ID3D12GraphicsCommandList* commandList);\r\ntypedef void(WINAPI* SetMarkerOnCommandList)(ID3D12GraphicsCommandList* commandList, UINT64 color, _In_ PCSTR formatString);\r\n\r\nHMODULE module = LoadLibrary(L\"WinPixEventRuntime.dll\");\r\n\r\nBeginEventOnCommandList pixBeginEventOnCommandList = (BeginEventOnCommandList)GetProcAddress(module, \"PIXBeginEventOnCommandList\");\r\nEndEventOnCommandList pixEndEventOnCommandList = (EndEventOnCommandList)GetProcAddress(module, \"PIXEndEventOnCommandList\");\r\nSetMarkerOnCommandList pixSetMarkerOnCommandList = (SetMarkerOnCommandList)GetProcAddress(module, \"PIXSetMarkerOnCommandList\");\r\n<\/pre>\n
Release History<\/h2>\n
\n
Further Reading<\/h2>\n