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

# PIXBeginEvent 函数

> PIXBeginEvent 函数

# PIXBeginEvent 函数

启动一个用户定义事件，用于 CPU 活动的计时捕获，将显示在 PIX 的系统计时捕获功能中。

## 语法

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

### 参数

*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

## 备注

`PIXBeginEvent` 函数保存格式字符串和格式参数，而不是在运行时格式化字符串。然后在 PIX 中读取捕获文件时进行格式化。使用与 16 字节对齐的字符串（首选）或与 8 字节对齐的字符串来配合 `PIXBeginEvent` 以获得最佳性能。要使用 %p 格式说明符将 char\* 或 wchar\_t\* 作为指针打印，在将其传递给 `PIXBeginEvent` 时，将指针强制转换为 void\* 或指向整型或浮点类型的指针。为获得最佳性能，请使用静态分配的字符串。

对 `PIXBeginEvent` 的调用可保证至少有 512 字节的空间来保存记录数据，其中包括格式字符串和所有变量的完整大小和对齐方式。一般情况下，PIX 事件旨在用作与游戏主要组件、系统或内容对齐的简短高性能标记。

此方法用于对 CPU 事件计时。要对 GPU 事件计时，请参阅 [PIX3](/reference/tools/pix3/pix3_members) 页面上的 PIX GPU 捕获 API。

每次调用 `PIXBeginEvent` 都必须有相匹配的对 [PIXEndEvent](/reference/tools/pix3/functions/pixendevent) 的调用。配对的 `PIXBeginEvent` 和 [PIXEndEvent](/reference/tools/pix3/functions/pixendevent) 调用必须在同一线程上发生。计时间隔约为 200ns，使用此函数的开销很低，因此每秒可以进行多达数十万次的 `PIXBeginEvent` 调用。

`PIXBeginEvent` 和 `PIXEndEvent` 对可以嵌套到任意深度。

## 要求

**头文件：** pix3.h

**库：** pixevt.lib

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

## 另请参阅

[PIX 概览（NDA 主题）](/tools/tools-console/pix/pix)\
[pix3](/reference/tools/pix3/pix3_members)\
[PIXEndEvent](/reference/tools/pix3/functions/pixendevent)\
[PIXBeginEvent\_2](/reference/tools/pix3/functions/pixbeginevent_2)\
[PIXBeginEvent\_3](/reference/tools/pix3/functions/pixbeginevent_3)\
[PIXBeginEvent\_4](/reference/tools/pix3/functions/pixbeginevent_4)


## Related topics

- [PIXBeginEvent 函数](/zh-CN/reference/tools/pix3/functions/pixbeginevent-overloads.md)
- [PIXBeginEvent 函数参考](/zh-CN/reference/tools/pix3/functions/pixbeginevent_2.md)
- [PIXBeginEvent 参考](/zh-CN/reference/tools/pix3/functions/pixbeginevent_3.md)
- [PIXBeginEvent 概览](/zh-CN/reference/tools/pix3/functions/pixbeginevent_4.md)
- [PIXBeginRetailEvent 函数](/zh-CN/reference/tools/pix3/functions/pixbeginretailevent.md)