> ## 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,  
         PCSTR formatString,
         ...  
)  
```

### 参数

*context*   \
类型：void\*

事件的上下文，接受 `ID3D12GraphicsCommandList\*`、`ID3D12GraphicsCommandList\*` 和 `ID3D12XboxDmaCommandList\*`（仅限 XBOX）。

*color*   \
类型：UINT64

在系统计时图表中使用的事件颜色。使用 [PIX\_COLOR](/reference/tools/pix3/functions/pix_color) 指定颜色，使用 [PIX\_COLOR\_INDEX](/reference/tools/pix3/functions/pix_color_index) 指定颜色索引，或传入原始 DWORD，请注意其格式为 ARGB，Alpha 通道值必须为 0xff。\
*formatString*   \_In\_\
类型：PCSTR

用于描述事件的名称，作为指向以 null 结尾字符串的指针。该字符串可以指定零个或多个可选的字符串格式占位符，非常类似于 `sprintf` 格式。

类型：...

如果在 *formatString* 中使用了占位符，则必须有相应数量的参数，其类型取决于占位符。此方法最多支持 16 个格式参数。

### 返回值

类型：void

## 备注

在调试或检测设备上，`PIXBeginRetailEvent` 的行为与 [PIXBeginEvent](/reference/tools/pix3/functions/pixbeginevent) 完全相同。对于零售设备，这些事件将包含在用于 GPU 挂起调试的 HIX 文件中。

`PIXBeginRetailEvent` 和 `PIXEndRetailEvent` 对可以嵌套到任意深度。

## 要求

**头文件：** pix3.h

**库：** pixevt.lib
**支持的平台：** XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[PIXBeginRetailEvent(void\*,UINT64, PCWSTR, ...)](/reference/tools/pix3/functions/pixbeginretailevent_2)\
[PIXEndRetailEvent](/reference/tools/pix3/functions/pixendretailevent)\
[pix3](/reference/tools/pix3/pix3_members)\
[PIX（NDA 主题）](/tools/tools-console/pix/pix)


## Related topics

- [PIXBeginRetailEvent](/zh-CN/reference/tools/pix3/functions/pixbeginretailevent_2.md)
- [PIXBeginEvent 函数](/zh-CN/reference/tools/pix3/functions/pixbeginevent-overloads.md)
- [PIXBeginEvent 函数参考](/zh-CN/reference/tools/pix3/functions/pixbeginevent_2.md)
- [PIXEndRetailEvent](/zh-CN/reference/tools/pix3/functions/pixendretailevent.md)
- [PIXSetRetailMarker](/zh-CN/reference/tools/pix3/functions/pixsetretailmarker_2.md)