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

> PIXScopedEvent reference

# PIXScopedEvent reference

Creates a user-defined event for a timing capture of CPU activity, to be displayed in the **Timing Capture** feature of Performance Investigator for XBOX (PIX).

<a id="syntaxSection" />

## Syntax

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

<a id="parametersSection" />

### Parameters

*color*   \
Type: UINT64

The event color to use in the timeline chart. Specify a [PIX\_COLOR](/reference/tools/pix3/functions/pix_color) constant to use a pre-defined color, a [PIX\_COLOR\_INDEX](/reference/tools/pix3/functions/pix_color_index) constant to use a color index, or a DWORD value in ARGB format to use a custom color. If an ARGB-formatted DWORD value is specified, the alpha channel for that value must be set to `0xff`.

*formatString*   \_In\_\
Type: PCWSTR

The name to use to describe the event, as a pointer to a null-terminated Unicode string. The string may specify zero or more optional string format placeholders, very similar to `sprintf` formatting. This method supports up to 16 placeholders.

Type: ...

If placeholders are specified in *formatString*, you must specify a corresponding number of values in this parameter. The types of the values specified in this parameter depend on the types identified by their corresponding placeholders.

<a id="retvalSection" />

### Return value

Type: void

<a id="remarksSection" />

## Remarks

This function creates a user-defined event for a timing capture of CPU activity, to be displayed in the **Timing Capture** feature of PIX. Events created with `PIXScopedEvent` automatically end when the scope the API is called in is exited, thus making the matching of the event's start and its end automatic.

The `PIXScopedEvent` function saves the format string and format parameters instead of formatting the string at runtime. Formatting is then done when reading capture files in PIX. Use 8-byte aligned strings or, preferably, 16-byte aligned strings with `PIXScopedEvent` to get the best performance. To format a `char\*` or `wchar_t\*` as a pointer using the `%p` format specifier, cast the pointer to either a `void\*` or to any integral or floating point type when passing the pointer to `PIXScopedEvent`.

Calls to `PIXScopedEvent` are guaranteed at least 512 bytes of space to save the record data, which includes the full size and alignment of the format string and all variables. In general, PIX events are intended for short high-performance markers that align to your game's major components, systems, or content.

<a id="requirementsSection" />

## Requirements

**Header:** pix3.h

**Library:** pixevt.lib

**Supported platforms:** XBOX One family consoles and XBOX Series consoles

<a id="seealsoSection" />

## See also

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


## Related topics

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