通过

PIXBeginEvent 函数

  • 项目

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

语法

void PIXBeginEvent(  
         UINT64 color,  
         PCSTR formatString,  
         ...  
)

参数

color   
类型：UINT64

要在系统计时图表中使用的事件颜色。 使用 PIX_COLOR 指定颜色，使用 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 页上的“PIX GPU 捕获 API”。

对 PIXBeginEvent 的每个调用都必须具有匹配的 PIXEndEvent 调用。 对 PIXBeginEvent 和 PIXEndEvent 的配对调用必须在同一线程上发生。 时间间隔大约为 200 纳秒，并且由于使用此函数的开销很低，因此每秒可对 PIXBeginEvent 进行多达数十万次调用。

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

要求

头文件：pix3.h

库：pixevt.lib

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

另请参阅

PIX 概述（NDA 主题）
pix3
PIXEndEvent
PIXBeginEvent_2
PIXBeginEvent_3
PIXBeginEvent_4