PIXBeginCapture

Article
11/09/2023

Starts a programmatically controlled PIX timing capture.

Syntax

HRESULT PIXBeginCapture(  
         DWORD captureFlags,  
         const PPIXCaptureParameters captureParameters  
)

Parameters

captureFlags
Type: DWORD

A flag indicating the type of capture to perform. Only one capture flag can be passed to PIXBeginCapture at a time. Currently, the only valid value is PIX_CAPTURE_TIMING defined in pix3.h:

#define PIX_CAPTURE_TIMING                  (1 << 0)

captureParameters _In_opt_
Type: PPIXCaptureParameters

For timing captures, pass a pointer to the TimingCaptureParameters structure, or pass a pointer to the PIXCaptureParameters union, which contains the TimingCaptureParameters structure.

Return value

Type: HRESULT

Indicates whether the capture was successfully initiated. S_FALSE is returned on success. Only one capture may be running at a time. If PIXBeginCapture is called when another capture is currently running, E_PENDING will be returned and the call will have no effect.

Remarks

This function initiates a PIX capture from title code. PIXBeginCapture can currently only be used to take a timing capture (NDA topic)Authorization required.

PIXBeginCapture stores the capture data in tooling memory on the console. The amount of tooling memory made available to the capture is specified by setting the MaximumToolingMemorySizeMb field in the PIXCaptureParameters structure.

Programmatic Timing Captures can be taken in one of two modes, as defined by the value of the PIXCaptureStorage enum in the PIXCaptureParameters structure. When PIXCaptureStorage is set to Memory PIXBeginCapture will fill up the tooling memory made available, then will discard any new data that comes in. When PIXCaptureStorage is set to MemoryCircular, PIXBeginCapture will use the tooling memory as a ring buffer. The capture will run until tooling memory is full, but instead of stopping the capture, the oldest data will be aged out to make room for new data. The capture will continue to run. MemoryCircular captures are designed to run for extended periods of time, while not exhausting the available tooling memory on the console.

Timing captures taken using PIXBeginCapture must be copied back to the PC and converted into an .xpix file before they can be viewed in PIX. See Opening Programmatic Timing Captures (NDA topic)Authorization required for a description of the steps required to view a programmatic capture in PIX.

Use PIXEndCapture to stop a PIX capture from title code.

//
//  timing capture
//
PIXCaptureParameters captureParams = {};

captureParams.TimingCaptureParameters.CaptureGpuTiming = TRUE;
captureParams.TimingCaptureParameters.CaptureCallstacks = TRUE;
captureParams.TimingCaptureParameters.CaptureCpuSamples = TRUE;
captureParams.TimingCaptureParameters.CpuSamplesPerSecond = 4000;

captureParams.TimingCaptureParameters.CaptureStorage = PIXCaptureParameters::Memory;
captureParams.TimingCaptureParameters.FileName = wstrFilename;
captureParams.TimingCaptureParameters.MaximumToolingMemorySizeMb = 4096;

XSF_ERROR_IF_FAILED(PIXBeginCapture(PIX_CAPTURE_TIMING, &captureParams));

Requirements

Header: pix3.h

Library: pixevt.lib

Supported platforms: Xbox One family consoles and Xbox Series consoles

Share via