PIXBeginCapture

Starts a programmatically controlled PIX capture.

Syntax

HRESULT PIXBeginCapture(
         DWORD captureFlags,
         const PPIXCaptureParameters pCaptureParameters
)

Parameters

captureFlags
Type: DWORD

[in] Uses the PIX_CAPTURE_* family of flags to specify the type of capture to take. 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 values are one of the following from pix.h:pix.h:

#define PIX_CAPTURE_TIMING                  (1 << 0)
#define PIX_CAPTURE_CALLGRAPH               (1 << 4)
#define PIX_CAPTURE_INSTRUCTION_TRACE       (1 << 5)

pCaptureParameters
Type: PPIXCaptureParameters

[in, optional] For callgraph and instruction trace captures, pass nullptr.

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_OK is returned on success. Only one capture may be running at a time. If PIXBeginCapture is called when another capture is currently running, S_OK will be returned but the call will have no effect.

Remarks

This function initiates a PIX capture from title code. PIXBeginCapture can currently only be used to take CPU callgraph, instruction trace and timing captures.

Before PIXBeginCapture can be used to take a callgraph or instruction trace capture, PIX must be placed in a mode where a capture can be taken. This mode is necessary because PIX must insert profiling hooks and its tracing runtime into your title in order to take a capture. These profiling hooks are the same technology that is used to enable function summary, callgraph and instruction trace captures taken from PIX.

To place PIX into the mode that is required for PIXBeginCapture to take a callgraph or instruction trace capture:

Go to the Home tab, then under the Callgraph or Instruction Tracebuttons, in the Options pane, select the option Next call to PIXBeginCapture(…).

When PIX is put into capture mode, a callgraph or instruction trace capture will be taken the next time PIXBeginCapture is called. If PIXBeginCapture is not called within 30 seconds, PIX will revert to its previous state.

Calls to PIXBeginCapture are a no-op if PIX is not in the mode required for a capture to be taken. PIXBeginCapture returns S_OK in this case.

Example

//
//  callgraph capture
//
HRESULT hr = PIXBeginCapture(PIX_CAPTURE_CALLGRAPH, nullptr);
if (SUCCEEDED(hr))
{
  // capture started successfully or was a no-op
}
  
//
//  instruction trace capture
//
HRESULT hr = PIXBeginCapture(PIX_CAPTURE_INSTRUCTION_TRACE, nullptr);
if (SUCCEEDED(hr))
{
  // capture started successfully or was a no-op
}

//
//  timing capture
//
TimingCaptureParameters captureParams;
captureParams.CaptureCallstacks = TRUE;
captureParams.FileName = “D:\\ProgrammaticTimingCapture.pix3”;
HRESULT hr = PIXBeginCapture(PIX_CAPTURE_TIMING, &captureParams);
if (SUCCEEDED(hr))
{
  // capture started successfully or was a no-op
}

Requirements

Header: Declared in pix.h.

Library: Use PIXEvt.lib.