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

# PIXSetMarker overview

> PIXSetMarker overview

# PIXSetMarker overview

当特定的用户自定义事件发生时，向 **PIX System Timing Capture** 窗口的 GPU 时间线插入一个标记。

## 语法

```cpp theme={null}
void PIXSetMarker(  
         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

## 备注

`PIXSetMarker` 函数会保存格式字符串和格式参数，而不是在运行时格式化字符串。格式化操作会在 PIX 中读取捕获文件时完成。使用 `PIXSetMarker` 时，请使用 16 字节对齐的字符串（首选）或 8 字节对齐的字符串以获得最佳性能。若要使用 %p 格式说明符将 char\* 或 wchar\_t\* 打印为指针，请在将其传递给 `PIXSetMarker` 时，将该指针强制转换为 void\* 或指向整数或浮点类型的指针。对 `PIXSetMarker` 的任何调用都至少保证 512 字节的空间用于保存记录数据。

该事件将显示为无持续时间，并在 **PIX System Timing Capture** 窗口中以一条竖线（单个竖条）表示。

此函数用于在 GPU 时间线中标记事件。若要在 CPU 时间线中标记事件，请调用 [PIXSetMarker 函数的第一个重载](/reference/tools/pix3/functions/pixsetmarker) 或 [PIXSetMarker 函数的第二个重载](/reference/tools/pix3/functions/pixsetmarker_2)。

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

## 要求

**头文件：** pix3.h

**库：** pixevt.lib

**支持的平台：** XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[PIX 概述 (NDA 主题)](/tools/tools-console/pix/pix)\
[pix3](/reference/tools/pix3/pix3_members)\
[PIXSetMarker](/reference/tools/pix3/functions/pixsetmarker)\
[PIXSetMarker\_2](/reference/tools/pix3/functions/pixsetmarker_2)\
[PIXSetMarker\_3](/reference/tools/pix3/functions/pixsetmarker_3)\
[PIXBeginEvent](/reference/tools/pix3/functions/pixbeginevent)


## Related topics

- [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 function reference](/zh-CN/reference/tools/pix3/functions/pixsetmarker_3.md)
- [PIXSetRetailMarker](/zh-CN/reference/tools/pix3/functions/pixsetretailmarker_2.md)