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

# PIXScopedEvent 參考

> PIXScopedEvent 參考

# PIXScopedEvent 參考

為 CPU 活動的計時擷取建立使用者定義的事件，以顯示在 Performance Investigator for XBOX (PIX) 的 **Timing Capture** 功能中。

<a id="syntaxSection" />

## 語法

```cpp theme={null}
void PIXScopedEvent(
         UINT64 color,
         _In_ PCWSTR formatString,
         ...
)
```

<a id="parametersSection" />

### 參數

*color*   \
類型：UINT64

要在時間軸圖表中使用的事件色彩。指定 [PIX\_COLOR](/zh-TW/reference/tools/pix3/functions/pix_color) 常數以使用預先定義的色彩、指定 [PIX\_COLOR\_INDEX](/zh-TW/reference/tools/pix3/functions/pix_color_index) 常數以使用色彩索引，或指定 ARGB 格式的 DWORD 值以使用自訂色彩。如果指定 ARGB 格式的 DWORD 值，則該值的 Alpha 色板必須設定為 `0xff`。

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

用來描述事件的名稱，為以 Null 結束之 Unicode 字串的指標。此字串可以指定零個或多個選擇性的字串格式預留位置，與 `sprintf` 格式非常類似。此方法最多支援 16 個預留位置。

類型：...

如果在 *formatString* 中指定了預留位置，您必須在此參數中指定對應數目的值。此參數中指定之值的類型，取決於其對應預留位置所識別的類型。

<a id="retvalSection" />

### 傳回值

類型：void

<a id="remarksSection" />

## 備註

此函式會為 CPU 活動的計時擷取建立使用者定義的事件，以顯示在 PIX 的 **Timing Capture** 功能中。使用 `PIXScopedEvent` 建立的事件，會在呼叫 API 的範圍結束時自動結束，因此事件開始與結束的配對是自動的。

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

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

<a id="requirementsSection" />

## 需求

**標頭：** pix3.h

**程式庫：** pixevt.lib

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

<a id="seealsoSection" />

## 另請參閱

[PIXScopedEvent](/zh-TW/reference/tools/pix3/functions/pixscopedevent-overloads)\
[PIX3](/zh-TW/reference/tools/pix3/pix3_members)\
[PIX (NDA 主題)](/zh-TW/tools/tools-console/pix/pix)


## Related topics

- [PIXScopedEvent 函式參考](/zh-TW/reference/tools/pix3/functions/pixscopedevent_3.md)
- [PIXScopedEvent](/zh-TW/reference/tools/pix3/functions/pixscopedevent-overloads.md)
- [PIXScopedEvent 函式](/zh-TW/reference/tools/pix3/functions/pixscopedevent.md)
- [PIXScopedEvent 概觀](/zh-TW/reference/tools/pix3/functions/pixscopedevent_4.md)
- [PIX_COLOR](/zh-TW/reference/tools/pix3/functions/pix_color.md)