> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PIXBeginCapture

> PIXBeginCapture

# PIXBeginCapture

Starts a programmatically controlled PIX timing capture.

## Syntax

```cpp theme={null}
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.

*captureParameters*   \_In\_opt\_\
Type: PPIXCaptureParameters

For timing captures, pass a pointer to the `TimingCaptureParameters` structure, or pass a pointer to the [PIXCaptureParameters](/reference/tools/pix3/structs/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.

#### Flags

| Flag | Value | Description |
| - | - | - |
| PIX\_CAPTURE\_TIMING | (1 \<\< 0) | System timing. |
| PIX\_CAPTURE\_GPU | (1 \<\< 1) | Captures all commands and their inputs sent to the GPU so that it can be replayed and analyzed. |
| PIX\_CAPTURE\_FUNCTION\_SUMMARY | (1 \<\< 2) | A function summary capture was initiated from the **Home** tab. |
| PIX\_CAPTURE\_FUNCTION\_DETAILS | (1 \<\< 3) | A request for additional function details was initiated using the **Capture Additional Calls** button from either a function summary or callgraph capture. |
| PIX\_CAPTURE\_CALLGRAPH | (1 \<\< 4) | A callgraph capture was initiated either from PIX or programmatically by calling `PIXBeginCapture`. |
| PIX\_CAPTURE\_INSTRUCTION\_TRACE | (1 \<\< 5) | A CPU instruction trace capture is in progress. |
| PIX\_CAPTURE\_SYSTEM\_MONITOR\_COUNTERS | (1 \<\< 6) | System monitor counters. |
| PIX\_CAPTURE\_VIDEO | (1 \<\< 7) | Video playback. |
| PIX\_CAPTURE\_AUDIO | (1 \<\< 8) | Audio playback. |
| PIX\_CAPTURE\_GPU\_TRACE | (1 \<\< 9) | Captures GPU Streaming Performance Monitor (SPM) counters and Shader Queue Thread Tracing (SQTT) data from nearly all GPU blocks. |
| PIX\_CAPTURE\_RESERVED | (1 \<\< 15) | Placeholder flag used internally by PIX for future or specialized capture scenarios. |

## Remarks

This function initiates a PIX capture from title code. `PIXBeginCapture` can currently only be used to take a [timing capture (NDA topic)](/tools/tools-console/pix/new-timing-captures).

`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](/reference/tools/pix3/structs/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](/reference/tools/pix3/structs/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)](/tools/tools-console/pix/open-offline-timing-captures) for a description of the steps required to view a programmatic capture in PIX.

Use [PIXEndCapture](/reference/tools/pix3/functions/pixendcapture) to stop a PIX capture from title code.

```cpp theme={null}
//
//  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

## Conceptual documentation

* [Analyzing CPU performance (contents)](/tools/tools-console/pix/cpu-performance)

## See also

[PIXEndCapture](/reference/tools/pix3/functions/pixendcapture)\
[PIXCaptureParameters](/reference/tools/pix3/structs/pixcaptureparameters)\
[PIX3](/reference/tools/pix3/pix3_members)\
[PIX (NDA topic)](/tools/tools-console/pix/pix)


## Related topics

- [PIXEndCapture](/reference/tools/pix3/functions/pixendcapture.md)
- [PIXCaptureParameters](/reference/tools/pix3/structs/pixcaptureparameters.md)
- [PIXGetCaptureState](/reference/tools/pix3/functions/pixgetcapturestate.md)
- [PIX3 (API contents)](/reference/tools/pix3/pix3_members.md)
- [PIX on XBOX and Windows for GDK titles](/tools/tools-console/pix/index.md)