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

# PIXBeginRetailEvent

> PIXBeginRetailEvent

# PIXBeginRetailEvent

啟動使用者定義的零售事件。

## 語法

```cpp theme={null}
void PIXBeginRetailEvent(  
         void* context,  
         UINT64 color,  
         PCWSTR 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\_\
類型：PCWSTR

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

類型：...

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

### 傳回值

類型：void

## 備註

在偵錯或已檢測的裝置上，`PIXBeginRetailEvent` 的行為與 [PIXBeginEvent](/zh-TW/reference/tools/pix3/functions/pixbeginevent) 相同。在零售裝置上，這些事件會包含在 HIX 檔案中，以用於 GPU 停止回應偵錯。

`PIXBeginRetailEvent` 和 `PIXEndRetailEvent` 配對可以巢狀至任何深度。

## 需求

**標頭：** pix3.h

**程式庫：** pixevt.lib
**支援的平台：** XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

[PIX (NDA 主題)](/zh-TW/tools/tools-console/pix/pix)\
[pix3](/zh-TW/reference/tools/pix3/pix3_members)\
[PIXEndRetailEvent](/zh-TW/reference/tools/pix3/functions/pixendretailevent)\
[PIXBeginRetailEvent(void\*, UINT64, PCSTR, ...)](/zh-TW/reference/tools/pix3/functions/pixbeginretailevent)


## Related topics

- [PIXBeginRetailEvent 函式](/zh-TW/reference/tools/pix3/functions/pixbeginretailevent.md)
- [PIXEndRetailEvent](/zh-TW/reference/tools/pix3/functions/pixendretailevent.md)
- [PIXBeginEvent 函式](/zh-TW/reference/tools/pix3/functions/pixbeginevent-overloads.md)
- [PIXSetRetailMarker](/zh-TW/reference/tools/pix3/functions/pixsetretailmarker_2.md)
- [PIXSetRetailMarker 函式](/zh-TW/reference/tools/pix3/functions/pixsetretailmarker.md)