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

# PIXSetRetailMarker

> PIXSetRetailMarker

# PIXSetRetailMarker

当特定的用户自定义事件发生时，插入一个零售标记。

## 语法

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

### 参数

*context*   \
类型：void\*

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

*color*   \
类型：UINT64

在 PIX 窗口中该事件发生时，用于时序图表的颜色。\
使用 [PIX\_COLOR](/reference/tools/pix3/functions/pix_color) 指定颜色，使用 [PIX\_COLOR\_INDEX](/reference/tools/pix3/functions/pix_color_index) 指定颜色索引，或者传入一个原始 DWORD，注意其格式为 ARGB 且 alpha 通道值必须为 0xff。

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

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

类型：...

如果在 **formatString** 中使用了占位符，则必须提供相应数量（最多 16 个）的参数，且其类型与占位符匹配。

### 返回值

类型：void

## 备注

在调试或检测（instrumented）设备上，`PIXSetRetailMarker` 的行为与 [PIXSetMarker](/reference/tools/pix3/functions/pixsetmarker) 完全相同。对于零售设备，这些标记会包含在用于 GPU 挂起调试的 HIX 文件中。

对 `PIXSetRetailMarker` 的调用可以出现在任何位置，无需在 [PIXBeginRetailEvent](/reference/tools/pix3/functions/pixbeginretailevent) 调用之后。

## 要求

**头文件：** pix3.h

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

## 另请参阅

[PIX 概述 (NDA 主题)](/tools/tools-console/pix/pix)\
[pix3](/reference/tools/pix3/pix3_members)\
[PIXSetRetailMarker(void\*, UINT64, PCSTR, ...)](/reference/tools/pix3/functions/pixsetretailmarker)\
[PIXBeginRetailEvent](/reference/tools/pix3/functions/pixbeginretailevent)


## Related topics

- [PIXSetRetailMarker function](/zh-CN/reference/tools/pix3/functions/pixsetretailmarker.md)
- [PIXSetMarker](/zh-CN/reference/tools/pix3/functions/pixsetmarker-overloads.md)
- [PIXSetMarker function](/zh-CN/reference/tools/pix3/functions/pixsetmarker.md)
- [PIXSetMarker reference](/zh-CN/reference/tools/pix3/functions/pixsetmarker_2.md)
- [PIXSetMarker overview](/zh-CN/reference/tools/pix3/functions/pixsetmarker_4.md)