> ## 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

啟動以程式設計方式控制的 PIX 計時擷取。

## 語法

```cpp theme={null}
HRESULT PIXBeginCapture(  
         DWORD captureFlags,  
         const PPIXCaptureParameters captureParameters  
)  
```

### 參數

*captureFlags*   \
類型：DWORD

指出要執行之擷取類型的旗標。一次只能將一個擷取旗標傳遞給 `PIXBeginCapture`。

*captureParameters*   \_In\_opt\_\
類型：PPIXCaptureParameters

若為計時擷取，請傳遞 `TimingCaptureParameters` 結構的指標，或傳遞包含 `TimingCaptureParameters` 結構之 [PIXCaptureParameters](/zh-TW/reference/tools/pix3/structs/pixcaptureparameters) 等位的指標。

### 傳回值

類型：HRESULT

指出是否已成功起始擷取。成功時會傳回 S\_FALSE。一次只能執行一個擷取。如果在另一個擷取正在執行時呼叫 `PIXBeginCapture`，將會傳回 E\_PENDING，且呼叫不會有任何作用。

#### 旗標

| 旗標 | 值 | 描述 |
| - | - | - |
| PIX\_CAPTURE\_TIMING | (1 \<\< 0) | 系統計時。 |
| PIX\_CAPTURE\_GPU | (1 \<\< 1) | 擷取傳送至 GPU 的所有命令及其輸入，以便重新執行和分析。 |
| PIX\_CAPTURE\_FUNCTION\_SUMMARY | (1 \<\< 2) | 已從 \[首頁] 索引標籤起始函式摘要擷取。 |
| PIX\_CAPTURE\_FUNCTION\_DETAILS | (1 \<\< 3) | 已使用函式摘要或呼叫圖擷取中的 \[擷取其他呼叫] 按鈕，起始其他函式詳細資料的要求。 |
| PIX\_CAPTURE\_CALLGRAPH | (1 \<\< 4) | 已從 PIX 或以程式設計方式呼叫 `PIXBeginCapture` 起始呼叫圖擷取。 |
| PIX\_CAPTURE\_INSTRUCTION\_TRACE | (1 \<\< 5) | CPU 指令追蹤擷取正在進行中。 |
| PIX\_CAPTURE\_SYSTEM\_MONITOR\_COUNTERS | (1 \<\< 6) | 系統監視器計數器。 |
| PIX\_CAPTURE\_VIDEO | (1 \<\< 7) | 視訊播放。 |
| PIX\_CAPTURE\_AUDIO | (1 \<\< 8) | 音訊播放。 |
| PIX\_CAPTURE\_GPU\_TRACE | (1 \<\< 9) | 從幾乎所有 GPU 區塊擷取 GPU 串流效能監視器 (SPM) 計數器和著色器佇列執行緒追蹤 (SQTT) 資料。 |
| PIX\_CAPTURE\_RESERVED | (1 \<\< 15) | PIX 內部用於未來或特殊擷取案例的預留位置旗標。 |

<a id="remarksSection" />

## 備註

此函式會從遊戲程式碼起始 PIX 擷取。`PIXBeginCapture` 目前只能用來進行[計時擷取 (NDA 主題)](/zh-TW/tools/tools-console/pix/new-timing-captures)。

`PIXBeginCapture` 會將擷取資料儲存在主機上的工具記憶體中。可供擷取使用的工具記憶體數量，是透過設定 [PIXCaptureParameters](/zh-TW/reference/tools/pix3/structs/pixcaptureparameters) 結構中的 `MaximumToolingMemorySizeMb` 欄位來指定。

以程式設計方式進行的計時擷取可以使用兩種模式之一，由 [PIXCaptureParameters](/zh-TW/reference/tools/pix3/structs/pixcaptureparameters) 結構中 `PIXCaptureStorage` 列舉的值定義。當 `PIXCaptureStorage` 設定為 *Memory* 時，`PIXBeginCapture` 會填滿可用的工具記憶體，然後捨棄任何傳入的新資料。當 `PIXCaptureStorage` 設定為 *MemoryCircular* 時，`PIXBeginCapture` 會將工具記憶體當作環形緩衝區使用。擷取會執行到工具記憶體已滿為止，但不會停止擷取，而是將最舊的資料淘汰，以騰出空間給新資料。擷取會繼續執行。*MemoryCircular* 擷取的設計是長時間執行，同時不會耗盡主機上可用的工具記憶體。

使用 `PIXBeginCapture` 進行的計時擷取必須複製回 PC 並轉換為 .xpix 檔案，才能在 PIX 中檢視。如需在 PIX 中檢視程式設計擷取所需步驟的說明，請參閱[開啟以程式設計方式進行的計時擷取 (NDA 主題)](/zh-TW/tools/tools-console/pix/open-offline-timing-captures)。

使用 [PIXEndCapture](/zh-TW/reference/tools/pix3/functions/pixendcapture) 從遊戲程式碼停止 PIX 擷取。

```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));

```

## 需求

**標頭：** pix3.h

**程式庫：** pixevt.lib

**支援的平台：** XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [分析 CPU 效能 (內容)](/zh-TW/tools/tools-console/pix/cpu-performance)

## 另請參閱

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


## Related topics

- [PIXCaptureParameters](/zh-TW/reference/tools/pix3/structs/pixcaptureparameters.md)
- [PIXEndCapture](/zh-TW/reference/tools/pix3/functions/pixendcapture.md)
- [PIXGetCaptureState](/zh-TW/reference/tools/pix3/functions/pixgetcapturestate.md)
- [PIX3](/zh-TW/reference/tools/pix3/pix3_members.md)
- [XtfCaptureOutputBegin](/zh-TW/reference/tools/xtf/xtfapi/functions/xtfcaptureoutputbegin-xtfapi-xbox-windows-m.md)