WinPixEventRuntime API reference

Include pix3.h to use the WinPixEventRuntime APIs described in this reference. Use this page with the WinPixEventRuntime overview and Programmatic capture. The WinPixEventRuntime source code is available in the PixEvents GitHub repository.

Configuration macros

Define one of these macros before you include pix3.h only when you need to override the default instrumentation configuration. The WinPixEventRuntime NuGet package supports x64 and ARM64 Windows builds.

// Enable the full PIX API in a custom profiling configuration.
#if defined(_M_X64) || defined(_M_ARM64)
#define USE_PIX
#endif

// Keep retail GPU-context events and markers enabled in a retail build.
#if defined(_M_X64) || defined(_M_ARM64)
#define USE_PIX_RETAIL
#endif

// Disable the optimized string-copy path when you need conservative argument copying.
#define PIX_ENABLE_BLOCK_ARGUMENT_COPY 0

Macro	Description
`USE_PIX_SUPPORTED_ARCHITECTURE`	Enables WinPixEventRuntime on supported architectures. `pix3.h` defines it automatically on x64 and ARM64, or when `USE_PIX_ON_ALL_ARCHITECTURES` is defined.
`USE_PIX`	Enables the full debug/profile instrumentation API. `pix3.h` defines it automatically on supported architectures for `_DEBUG`, `DBG`, `PROFILE`, or `PROFILE_BUILD` builds, unless `_PREFAST_` is defined.
`USE_PIX_RETAIL`	Enables the retail marker API without enabling the full debug/profile API. Use it for markers that must remain active in retail builds.
`USE_PIX_ON_ALL_ARCHITECTURES`	Forces `USE_PIX_SUPPORTED_ARCHITECTURE` even when the compiler target isn't x64 or ARM64. This overrides the header guard, but it doesn't change the NuGet package's supported platforms.
`PIX_ENABLE_BLOCK_ARGUMENT_COPY`	Controls the optimized string-copy path used when events record formatted string arguments on x64 and x86. It defaults to `1`, but the header disables it when Address Sanitizer is detected. Define it as `0` to opt out.

When USE_PIX isn't active, the debug/profile APIs compile to no-op inline functions or harmless return values. When only USE_PIX_RETAIL is active, the retail event APIs stay active, and the debug/profile event APIs compile out.

Event and marker signatures

The event and marker APIs have overloads for ANSI and wide format strings, for several color parameter types, and for CPU-only or GPU-context instrumentation.

// ColorType is UINT64, UINT32, INT32, DWORD, or UINT8.
// FormatString is PCSTR or PCWSTR.
// Context is one of the supported Direct3D context types listed below.

Context type	Required Direct3D header	Applies to
No context parameter.	None.	CPU events and markers.
`ID3D12GraphicsCommandList*`.	`d3d12.h`.	Graphics command-list events and markers.
`ID3D12CommandQueue*`.	`d3d12.h`.	Command-queue events and markers.
`ID3D12VideoDecodeCommandList*`.	`d3d12video.h`.	Video decode command-list events and markers.
`ID3D12VideoProcessCommandList*`.	`d3d12video.h`.	Video process command-list events and markers.
`ID3D12VideoEncodeCommandList*`.	`d3d12video.h`.	Video encode command-list events and markers.

Include the Direct3D header before pix3.h when you use a GPU-context overload. Use ID3D12GraphicsCommandList*, not the ID3D12CommandList* base type. On Windows, GPU-context calls emit D3D12 event metadata for GPU work and CPU timing markers that PIX links to the GPU event in captures. The begin and end calls for a GPU-context event (a PIX GPU event) can run on different CPU threads; CPU-only events without a context (PIX CPU events) must begin and end on the same CPU thread. Keep the corresponding GPU-context begin and end calls balanced. For how timing captures display these calls, and when PIX shows a $END GPU EVENT marker, see CPU and GPU-context events.

`PIXBeginEvent`

template<typename... ARGS>
void PIXBeginEvent(ColorType color, FormatString formatString, ARGS... args);

template<typename Context, typename... ARGS>
void PIXBeginEvent(Context* context, ColorType color, FormatString formatString, ARGS... args);

Starts a CPU event or a GPU-context event. The GPU-context overload records the CPU call site as a linked timing marker in Windows captures. It is active in debug/profile builds when USE_PIX is active.

`PIXEndEvent`

void PIXEndEvent();

template<typename Context>
void PIXEndEvent(Context* context);

Ends the current CPU event or GPU-context event. The GPU-context overload records the CPU call site as a linked timing marker in Windows captures. It is active in debug/profile builds when USE_PIX is active.

`PIXSetMarker`

template<typename... ARGS>
void PIXSetMarker(ColorType color, FormatString formatString, ARGS... args);

template<typename Context, typename... ARGS>
void PIXSetMarker(Context* context, ColorType color, FormatString formatString, ARGS... args);

Inserts a point marker into the CPU or GPU-context timeline. The GPU-context overload records the CPU call site as a linked timing marker in Windows captures. It is active in debug/profile builds when USE_PIX is active.

`PIXScopedEvent`

PIXScopedEvent is a statement-style macro, not a callable function. It declares a uniquely named RAII local that starts an event and automatically ends it when the C++ scope exits. It is active in debug/profile builds when USE_PIX is active.

PIXScopedEvent(PIX_COLOR(0, 128, 255), "CPU work %u", workIndex);
PIXScopedEvent(commandList, PIX_COLOR(255, 128, 0), "GPU work %u", drawIndex);

Retail event and marker APIs

Retail event APIs are intended for markers that should remain active when you define USE_PIX_RETAIL. They use the same ColorType, FormatString, and Context conventions as the debug/profile APIs, but they require a GPU context parameter.

`PIXBeginRetailEvent`

template<typename Context, typename... ARGS>
void PIXBeginRetailEvent(Context* context, ColorType color, FormatString formatString, ARGS... args);

Starts a GPU-context event that remains available when USE_PIX_RETAIL is active.

`PIXEndRetailEvent`

template<typename Context>
void PIXEndRetailEvent(Context* context);

Ends a GPU-context retail event that was started with PIXBeginRetailEvent.

`PIXSetRetailMarker`

template<typename Context, typename... ARGS>
void PIXSetRetailMarker(Context* context, ColorType color, FormatString formatString, ARGS... args);

Inserts a GPU-context marker that remains available when USE_PIX_RETAIL is active.

`PIXScopedRetailEventObject`

PIXScopedRetailEventObject<ID3D12GraphicsCommandList> eventScope(commandList, PIX_COLOR(255, 128, 0), "Retail GPU work");

Creates an RAII helper that calls PIXBeginRetailEvent in its constructor and PIXEndRetailEvent in its destructor. Use it when only USE_PIX_RETAIL is active and you want a scoped retail GPU-context event.

Formatted strings

PIXBeginEvent, PIXSetMarker, PIXScopedEvent, and the retail marker APIs save the format string and arguments instead of formatting the string at runtime. PIX formats the string when it reads the capture. Use 16-byte aligned strings when possible, or 8-byte aligned strings otherwise. To print a char* or wchar_t* value with %p, cast the pointer to void* before you pass it to the API.

Counters

Use counters to add named numeric values to PIX views that graph timing data.

`PIXReportCounter`

void WINAPI PIXReportCounter(PCWSTR name, float value);

Reports a custom floating-point counter value for timing captures and System Monitor. It is active in debug/profile builds when USE_PIX is active, and it doesn't have a PCSTR overload.

Fence wake notifications

Use fence wake notifications to help timing captures connect a D3D12 fence signal to a thread wake.

`PIXNotifyWakeFromFenceSignal`

void WINAPI PIXNotifyWakeFromFenceSignal(HANDLE event);

Notifies PIX that an event handle was set because a D3D12 fence was signaled. It is active in debug/profile builds when USE_PIX is active, and the handle must match the handle passed to ID3D12Fence::SetEventOnCompletion.

Memory events

Memory event APIs let you add application-defined memory allocation and free records to captures. They are active in debug/profile builds when USE_PIX is active.

`PIXRecordMemoryAllocationEvent`

void WINAPI PIXRecordMemoryAllocationEvent(USHORT allocatorId, void* baseAddress, size_t size, UINT64 metadata);

Records an allocation event for the specified allocator, address, size, and application-defined metadata.

`PIXRecordMemoryFreeEvent`

void WINAPI PIXRecordMemoryFreeEvent(USHORT allocatorId, void* baseAddress, size_t size, UINT64 metadata);

Records a free event for the specified allocator, address, size, and application-defined metadata.

Colors

Color helpers are always available when you include pix3.h.

UINT32 PIX_COLOR(UINT8 r, UINT8 g, UINT8 b);
UINT8 PIX_COLOR_INDEX(UINT8 i);
const UINT8 PIX_COLOR_DEFAULT;

API	Description
`PIX_COLOR`	Returns an ARGB color with an alpha value of `0xff` from the specified red, green, and blue bytes.
`PIX_COLOR_INDEX`	Returns an 8-bit color index. PIX assigns a color to each index.
`PIX_COLOR_DEFAULT`	Uses color index `0`.

Programmatic capture APIs

For full guidance and examples, see Programmatic capture. These APIs are active in debug/profile builds when USE_PIX is active. On Windows, load the appropriate capturer DLL into the process before you call the capture functions; use PIXLoadLatestWinPixGpuCapturerLibrary for GPU captures and PIXLoadLatestWinPixTimingCapturerLibrary for timing captures.

Capture flags

#define PIX_CAPTURE_TIMING                  (1 << 0)
#define PIX_CAPTURE_GPU                     (1 << 1)
#define PIX_CAPTURE_FUNCTION_SUMMARY        (1 << 2)
#define PIX_CAPTURE_FUNCTION_DETAILS        (1 << 3)
#define PIX_CAPTURE_CALLGRAPH               (1 << 4)
#define PIX_CAPTURE_INSTRUCTION_TRACE       (1 << 5)
#define PIX_CAPTURE_SYSTEM_MONITOR_COUNTERS (1 << 6)
#define PIX_CAPTURE_VIDEO                   (1 << 7)
#define PIX_CAPTURE_AUDIO                   (1 << 8)
#define PIX_CAPTURE_GPU_TRACE               (1 << 9)
#define PIX_CAPTURE_RESERVED                (1 << 15)

Use capture flags with PIXBeginCapture, the header implementation of PIXBeginCapture2, and PIXGetCaptureState. On Windows, PIXBeginCapture2 dispatches PIX_CAPTURE_GPU to GPU capture, PIX_CAPTURE_TIMING to timing capture, and returns E_NOTIMPL for other flags.

`PIXCaptureParameters`

union PIXCaptureParameters
{
    enum PIXCaptureStorage
    {
        Memory = 0,
        MemoryCircular = 1,
        FileCircular = 2,
    };

    struct GpuCaptureParameters
    {
        PCWSTR FileName;
    } GpuCaptureParameters;

    struct TimingCaptureParameters
    {
        PCWSTR FileName;
        UINT32 MaximumToolingMemorySizeMb;
        PIXCaptureStorage CaptureStorage;
        BOOL CaptureGpuTiming;
        BOOL CaptureCallstacks;
        BOOL CaptureCpuSamples;
        UINT32 CpuSamplesPerSecond;
        BOOL CaptureFileIO;
        BOOL CaptureVirtualAllocEvents;
        BOOL CaptureHeapAllocEvents;
        BOOL CaptureXMemEvents;
        BOOL CapturePixMemEvents;
        BOOL CapturePageFaultEvents;
        BOOL CaptureVideoFrames;
    } TimingCaptureParameters;

    struct GpuTraceParameters
    {
        PWSTR FileName;
        UINT32 MaximumToolingMemorySizeMb;
        BOOL CaptureGpuOccupancy;
    } GpuTraceParameters;
};

Pass PIXCaptureParameters to PIXBeginCapture or PIXBeginCapture2. MemoryCircular, CaptureXMemEvents, CaptureVideoFrames, and GpuTraceParameters aren't supported on Windows. FileCircular is Windows-only.

Capture functions

API	Signature	Description
`PIXBeginCapture`	`HRESULT PIXBeginCapture(DWORD captureFlags, const PPIXCaptureParameters captureParameters);`	Starts a programmatic capture. `PPIXCaptureParameters` is a typedef for `PIXCaptureParameters*`.
`PIXBeginCapture2`	`HRESULT WINAPI PIXBeginCapture2(DWORD captureFlags, const PPIXCaptureParameters captureParameters);`	Implements the header dispatch used by `PIXBeginCapture`; prefer `PIXBeginCapture` in app code. The desktop DLL export is private.
`PIXEndCapture`	`HRESULT WINAPI PIXEndCapture(BOOL discard);`	Ends the active programmatic capture. The `discard` parameter isn't supported on Windows.
`PIXGetCaptureState`	`DWORD WINAPI PIXGetCaptureState();`	Is declared and exported, but the Windows WinPixEventRuntime implementation currently returns `0`; don't use it to detect active captures on Windows.
`PIXGpuCaptureNextFrames`	`HRESULT WINAPI PIXGpuCaptureNextFrames(PCWSTR fileName, UINT32 numFrames);`	Captures the next GPU frames to the specified file.
`PIXSetTargetWindow`	`HRESULT WINAPI PIXSetTargetWindow(HWND hwnd);`	Sets the target window used by GPU capture HUD behavior.
`PIXForceD3D11On12`	`HRESULT WINAPI PIXForceD3D11On12();`	Forces D3D11 capture through D3D11On12 when the GPU capturer supports it.
`PIXSetHUDOptions`	`HRESULT WINAPI PIXSetHUDOptions(PIXHUDOptions hudOptions);`	Configures GPU capture HUD visibility.
`PIXIsAttachedForGpuCapture`	`bool WINAPI PIXIsAttachedForGpuCapture();`	Returns whether PIX is attached for GPU capture.
`PIXOpenCaptureInUI`	`HINSTANCE WINAPI PIXOpenCaptureInUI(PCWSTR fileName);`	Opens a capture file in PIX.
`PIXLoadLatestWinPixGpuCapturerLibrary`	`HMODULE PIXLoadLatestWinPixGpuCapturerLibrary();`	Loads the latest installed `WinPixGpuCapturer.dll`.
`PIXLoadLatestWinPixTimingCapturerLibrary`	`HMODULE PIXLoadLatestWinPixTimingCapturerLibrary();`	Loads the latest installed `WinPixTimingCapturer.dll`.

`PIXHUDOptions`

enum PIXHUDOptions
{
    PIX_HUD_SHOW_ON_ALL_WINDOWS = 0x1,
    PIX_HUD_SHOW_ON_TARGET_WINDOW_ONLY = 0x2,
    PIX_HUD_SHOW_ON_NO_WINDOWS = 0x4
};

Pass PIXHUDOptions values to PIXSetHUDOptions.

Optional dynamic-loading ABI exports

Most apps should include pix3.h instead of loading WinPixEventRuntime exports directly. The DLL also exports ABI entry points for apps that need to use LoadLibrary and GetProcAddress without depending on the C++ templates in the header. These names aren't declared by pix3.h; declare matching WINAPI function-pointer types before you call them.

using PIXBeginEventOnCommandListFn = void (WINAPI*)(ID3D12GraphicsCommandList* commandList, UINT64 color, PCSTR formatString);

HMODULE module = LoadLibraryW(L"WinPixEventRuntime.dll");
auto beginEventOnCommandList = reinterpret_cast<PIXBeginEventOnCommandListFn>(GetProcAddress(module, "PIXBeginEventOnCommandList"));

void WINAPI PIXBeginEventOnCommandList(ID3D12GraphicsCommandList* commandList, UINT64 color, PCSTR formatString);
void WINAPI PIXEndEventOnCommandList(ID3D12GraphicsCommandList* commandList);
void WINAPI PIXSetMarkerOnCommandList(ID3D12GraphicsCommandList* commandList, UINT64 color, PCSTR formatString);

void WINAPI PIXBeginEventOnCommandQueue(ID3D12CommandQueue* commandQueue, UINT64 color, PCSTR formatString);
void WINAPI PIXEndEventOnCommandQueue(ID3D12CommandQueue* commandQueue);
void WINAPI PIXSetMarkerOnCommandQueue(ID3D12CommandQueue* commandQueue, UINT64 color, PCSTR formatString);

void WINAPI PIXBeginEventOnVideoDecodeCommandList(ID3D12VideoDecodeCommandList* commandList, UINT64 color, PCSTR formatString);
void WINAPI PIXEndEventOnVideoDecodeCommandList(ID3D12VideoDecodeCommandList* commandList);
void WINAPI PIXSetMarkerOnVideoDecodeCommandList(ID3D12VideoDecodeCommandList* commandList, UINT64 color, PCSTR formatString);

void WINAPI PIXBeginEventOnVideoProcessCommandList(ID3D12VideoProcessCommandList* commandList, UINT64 color, PCSTR formatString);
void WINAPI PIXEndEventOnVideoProcessCommandList(ID3D12VideoProcessCommandList* commandList);
void WINAPI PIXSetMarkerOnVideoProcessCommandList(ID3D12VideoProcessCommandList* commandList, UINT64 color, PCSTR formatString);

void WINAPI PIXBeginEventOnVideoEncodeCommandList(ID3D12VideoEncodeCommandList* commandList, UINT64 color, PCSTR formatString);
void WINAPI PIXEndEventOnVideoEncodeCommandList(ID3D12VideoEncodeCommandList* commandList);
void WINAPI PIXSetMarkerOnVideoEncodeCommandList(ID3D12VideoEncodeCommandList* commandList, UINT64 color, PCSTR formatString);

void WINAPI PIXBeginEventOnThread(UINT32 color, PCSTR name);
void WINAPI PIXEndEventOnThread();
void WINAPI PIXSetMarkerOnThread(UINT32 color, PCSTR name);

The ABI exports take ANSI string names and don't expose the full formatted-string template support in pix3.h. Desktop and OneCore DLLs export the thread ABI entry points; the UAP DLL exports the command-list, command-queue, and video command-list ABI entry points but not the thread ABI entry points.

Release history

For published versions and release notes, see the WinPixEventRuntime package on NuGet. For source changes, see the PixEvents repository.

Feedback

Was this page helpful?

Last updated on 2026-10-05

WinPixEventRuntime API reference

Configuration macros

Event and marker signatures

PIXBeginEvent

PIXEndEvent

PIXSetMarker

PIXScopedEvent