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

# PIXBeginEvent 參考

> PIXBeginEvent 參考

# PIXBeginEvent 參考

為 CPU 或 GPU 活動的計時擷取啟動使用者定義的事件，以顯示在 PIX 的 **系統計時擷取** 功能中。

## 語法

```cpp theme={null}
void PIXBeginEvent(  
         void* context,  
         UINT64 color,  
         PCSTR formatString,
         ...  
)  
```

### 參數

*context*   \
類型：void\*

事件的內容，接受 `ID3D12GraphicsCommandList\*`、`ID3D12GraphicsCommandList\*` 和 `ID3D12XboxDmaCommandList\*` (僅限 XBOX)。

*color*   \
類型：UINT64

要在系統計時圖表中使用的事件色彩。使用 [PIX\_COLOR](/zh-TW/reference/tools/pix3/functions/pix_color) 指定色彩、使用 [PIX\_COLOR\_INDEX](/zh-TW/reference/tools/pix3/functions/pix_color_index) 指定色彩索引，或傳入原始 DWORD (請注意格式為 ARGB，且 Alpha 通道值必須為 0xff)。

*formatString*   \_In\_\
類型：PCSTR

用來描述事件的名稱，以指向以 Null 結束之字串的指標表示。此字串可以指定零或多個選擇性的字串格式預留位置，與 `sprintf` 格式化非常相似。

類型：...

如果在 *formatString* 中使用預留位置，則必須有對應數目的參數，其類型取決於預留位置。此方法最多支援 16 個格式參數。

### 傳回值

類型：void

## 備註

`PIXBeginEvent` 函式會儲存格式字串和格式參數，而不是在執行階段格式化字串。格式化會在 PIX 中讀取擷取檔案時進行。搭配 PIXBeginEvent 使用 16 位元組對齊的字串 (建議) 或 8 位元組對齊的字串，以獲得最佳效能。若要使用 %p 格式規範將 char\* 或 wchar\_t\* 列印為指標，請在將指標傳遞給 `PIXBeginEvent` 時，將其轉換為 void\* 或整數或浮點類型的指標。若要獲得最佳效能，請使用靜態配置的字串。

`PIXBeginEvent` 呼叫保證至少有 512 位元組的空間來儲存記錄資料，其中包括格式字串和所有變數的完整大小和對齊。一般而言，PIX 事件適用於與遊戲主要元件、系統或內容對齊的簡短高效能標記。

此方法用於計時 CPU 事件。如需計時 GPU 事件的詳細資訊，請參閱 [PIX3](/zh-TW/reference/tools/pix3/pix3_members) 的 [PIX GPU 擷取 API](/zh-TW/reference/tools/pix3/pix3_members#pixgpucaptureapis) 一節。

每個 `PIXBeginEvent` 呼叫都必須有相符的 [PIXEndEvent](/zh-TW/reference/tools/pix3/functions/pixendevent) 呼叫。成對的 `PIXBeginEvent` 和 [PIXEndEvent](/zh-TW/reference/tools/pix3/functions/pixendevent) 呼叫必須在同一個執行緒上進行。計時間隔約為 200ns，且使用此函式的額外負荷很低，因此每秒最多可以進行數十萬次 `PIXBeginEvent` 呼叫。

`PIXBeginEvent` 和 `PIXEndEvent` 配對可以巢狀至任何深度。

## 需求

**標頭：** pix3.h

**程式庫：** pixevt.lib

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

## 另請參閱

[PIXBeginEvent](/zh-TW/reference/tools/pix3/functions/pixbeginevent)\
[PIXBeginEvent\_2](/zh-TW/reference/tools/pix3/functions/pixbeginevent_2)\
[PIXBeginEvent\_4](/zh-TW/reference/tools/pix3/functions/pixbeginevent_4)\
[PIXEndEvent](/zh-TW/reference/tools/pix3/functions/pixendevent)\
[PIX3](/zh-TW/reference/tools/pix3/pix3_members)\
[PIX (NDA 主題)](/zh-TW/tools/tools-console/pix/pix)


## Related topics

- [PIXBeginEvent 函式參考](/zh-TW/reference/tools/pix3/functions/pixbeginevent_2.md)
- [PIXBeginEvent 概觀](/zh-TW/reference/tools/pix3/functions/pixbeginevent_4.md)
- [PIXBeginEvent 函式](/zh-TW/reference/tools/pix3/functions/pixbeginevent.md)
- [PIXEndEvent 參考](/zh-TW/reference/tools/pix3/functions/pixendevent.md)
- [PIXBeginRetailEvent](/zh-TW/reference/tools/pix3/functions/pixbeginretailevent_2.md)