> ## 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,  
         PCWSTR 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\_\
类型：PCWSTR

用于描述事件的名称，作为指向以 null 结尾 Unicode 字符串的指针。该字符串可以指定零个或多个可选的字符串格式占位符，非常类似于 `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](/reference/tools/pix3/pix3_members#pixgpucaptureapis) 部分。

每次调用 `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 主机

## 另请参阅

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


## Related topics

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