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

# PIXScopedEvent function reference

> PIXScopedEvent function reference

# PIXScopedEvent function reference

为特定上下文的 CPU 活动时序捕获（在 XBOX 上还可用于 GPU 活动）创建一个用户自定义事件，用于显示在 Performance Investigator for XBOX (PIX) 的 **Timing Capture** 功能中。

<a id="syntaxSection" />

## 语法

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

<a id="parametersSection" />

### 参数

*context*   \
类型：void\*

事件的上下文。仅在 XBOX 上，该参数还接受 `ID3D12GraphicsCommandList*`、`ID3D12GraphicsCommandList*` 和 `ID3D12XboxDmaCommandList*` 指针，以便对 GPU 活动进行时序捕获。

*color*   \
类型：UINT64

用于时间线图表中的事件颜色。可指定 [PIX\_COLOR](/reference/tools/pix3/functions/pix_color) 常量以使用预定义颜色，指定 [PIX\_COLOR\_INDEX](/reference/tools/pix3/functions/pix_color_index) 常量以使用颜色索引，或指定 ARGB 格式的 DWORD 值以使用自定义颜色。如果指定 ARGB 格式的 DWORD 值，则该值的 alpha 通道必须设置为 `0xff`。

*formatString*   \_In\_\
类型：PCSTR

用于描述事件的名称，作为指向以 null 结尾的 Unicode 字符串的指针。该字符串可以指定零个或多个可选的字符串格式占位符，与 `sprintf` 的格式化方式非常相似。此方法最多支持 16 个占位符。

类型：...

如果在 *formatString* 中指定了占位符，则必须在此参数中提供相应数量的值。此参数中所指定值的类型取决于对应占位符所指示的类型。

<a id="retvalSection" />

### 返回值

类型：void

无。

<a id="remarksSection" />

## 备注

此函数为 CPU 活动的时序捕获创建一个用户自定义事件，用于显示在 PIX 的 **Timing Capture** 功能中。使用 `PIXScopedEvent` 创建的事件会在调用该 API 的作用域退出时自动结束，因此事件的起止匹配是自动完成的。

`PIXScopedEvent` 函数会保存格式字符串和格式参数，而不是在运行时格式化字符串。格式化操作会在 PIX 中读取捕获文件时完成。使用 `PIXScopedEvent` 时，请使用 8 字节对齐的字符串，最好是 16 字节对齐的字符串以获得最佳性能。若要使用 `%p` 格式说明符将 `char\*` 或 `wchar_t\*` 格式化为指针，请在将该指针传递给 `PIXScopedEvent` 时，将其强制转换为 `void\*` 或任意整数或浮点类型。

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

此方法通常用于对 CPU 事件计时。但通过在 `context` 参数中传入 `ID3D12GraphicsCommandList*`、`ID3D12CommandQueue*` 或 `ID3D12XboxDmaCommandList*` 指针，也可以对 GPU 事件进行计时。

<a id="remarksSection" />

## 要求

**头文件：** pix3.h

**库：** pixevt.lib

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

<a id="seealsoSection" />

## 另请参阅

[PIXScopedEvent](/reference/tools/pix3/functions/pixscopedevent-overloads)\
[PIX3](/reference/tools/pix3/pix3_members)\
[PIX (NDA 主题)](/tools/tools-console/pix/pix)


## Related topics

- [PIXScopedEvent](/zh-CN/reference/tools/pix3/functions/pixscopedevent-overloads.md)
- [PIXScopedEvent function](/zh-CN/reference/tools/pix3/functions/pixscopedevent.md)
- [PIXScopedEvent reference](/zh-CN/reference/tools/pix3/functions/pixscopedevent_2.md)
- [PIXScopedEvent overview](/zh-CN/reference/tools/pix3/functions/pixscopedevent_4.md)
- [PIX_COLOR](/zh-CN/reference/tools/pix3/functions/pix_color.md)