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

> PIXSetRetailMarker function

# PIXSetRetailMarker function

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

## 语法

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

### 参数

*context*   \
类型：void\*

事件的上下文，接受 1ID3D12GraphicsCommandList\*` 、`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\_\
类型：PCSTR

用于描述事件的名称。该字符串可以指定零个或多个可选的字符串格式占位符，与 **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 主机

## 另请参阅

[PIXSetRetailMarker(void\*, UINT64, PCWSTR, ...)](/reference/tools/pix3/functions/pixsetretailmarker_2)\
[pix3](/reference/tools/pix3/pix3_members)\
[PIX (NDA 主题)](/tools/tools-console/pix/pix)


## Related topics

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