PIX API overview

The PIX API lets you programmatically control PIX functionality—taking GPU captures, opening timing captures, analyzing rendering performance, and more—without the PIX UI. The API is COM-based: you include PixApi.h, link against PixApi.lib, and work through a set of COM interfaces rooted at IPixFactory.

This section documents the C++ API surface. The reference pages are generated from the PIX API headers, so they track the shipping API.

Prerequisites

The PIX API ships with the PIX installer. Install PIX on a Windows 10 or later machine to get it. The remaining prerequisites depend on the language you use - you only need the toolchain for your chosen language:

  • C++ - MSVC (cl.exe or clang-cl). The API is COM-based; consumers include PixApi.h and link against PixApi.lib. The headers use __uuidof and the MSVC C++ ABI, so they require Microsoft C++ extensions, which are enabled by default in cl.exe and clang-cl.
  • D3D12 headers - Windows SDK 10.0.26100 or later, or the DirectX Agility SDK.
  • C# - .NET 10 or later. The C# projections are generated with CsWin32.
  • Python - Python 3.9 or later with the pythonnet package.

Find your PIX installation

PIX is usually installed under %ProgramFiles%\Microsoft PIX\<version>\, or Microsoft PIX Preview\<version>\ for preview builds. The install directory contains these PIX API components:

Path Contents
include\ C++ header files (PixApi.h and the interface headers)
lib\ Import library (PixApi.lib)
(install root) Runtime DLL (pixapi.dll) and its native dependencies

Set up your project

To use the PIX API in a C++ project:

  1. Add the PIX install include\ directory to your project's Additional Include Directories.
  2. Add PixApi.lib from the lib\ directory to your linker's Additional Dependencies. This library provides the PixCreateFactory entry point.
  3. Ensure pixapi.dll from the install root is discoverable at runtime. The simplest approach is to add the PIX install directory to your PATH, or copy pixapi.dll next to your executable.

Get started

The PIX API uses a factory pattern. All interaction begins with PixCreateFactory, which returns an IPixFactory interface:

ComPtr<IPixFactory> factory;
HRESULT hr = PixCreateFactory(IID_PPV_ARGS(factory.GetAddressOf()));

From the factory, you can open captures, connect to devices, and reach the rest of the PIX API:

// Open an existing GPU capture.
ComPtr<IPixGpuCaptureDocument> gpuDoc;
hr = factory->OpenGpuCaptureDocument(
    L"C:\\path\\to\\capture.wpix",
    IID_PPV_ARGS(gpuDoc.GetAddressOf()));

// Or connect to a device for live capture and timing.
PIX_CONNECTION_DESC_LOCAL local = {};
PIX_CONNECTION_DESC desc = {};
desc.Type = PIX_CONNECTION_TYPE_LOCAL;
desc.pLocal = &local;
ComPtr<IPixConnectionDocument> connection;
hr = factory->OpenConnectionDocument(
    &desc, nullptr,
    IID_PPV_ARGS(connection.GetAddressOf()));

Key interfaces

Interface Purpose
IPixFactory Entry point that opens captures and creates connections and tokens.
IPixConnectionDocument Manages device connections for live capture and timing.
IPixGpuCaptureDocument Opens and inspects GPU capture files (.wpix).
IPixGpuCaptureAnalysis Runs GPU capture analysis for timing, resources, and counters.
IPixTimingCaptureDocument Opens timing capture files for inspection and symbol resolution.
IPixGpuCaptureDrPix Runs Dr. PIX automated experiments on GPU captures.

For the complete list of interfaces, structures, enumerations, and functions, see the reference pages in this section.

C# and Python support

The PIX API also ships C# bindings, generated as CsWin32 projections, and can be used from Python through the .NET interop layer. See the samples repository for working examples in all three languages.

  • Last updated on