PIXBeginEvent function

Article
06/22/2023

Starts a user-defined event for a timing capture of CPU activity, to be displayed in the System Timing Capture feature of PIX.

Syntax

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

Parameters

color
Type: UINT64

The event color to use in the system timing chart. Use PIX_COLOR to specify a color, PIX_COLOR_INDEX to specify a color index, or pass in a raw DWORD noting that the format is ARGB and the alpha channel value must be 0xff.

formatString _In_
Type: PCSTR

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

If placeholders are used in formatString, there must be a corresponding number of parameters whose types depend on the placeholders. This method supports up to a maximum of 16 format parameters.

Return value

Type: void

Remarks

The PIXBeginEvent function saves format string and format parameters instead of formatting the string at runtime. Formatting is then done when reading capture files in PIX. Use 16-byte aligned strings (preferable) or 8-byte aligned strings with PIXBeginEvent to get the best performance. To print a char* or wchar_t* as a pointer using %p format specifier, cast the pointer to void* or a pointer to an integral or a floating point type when passing it to PIXBeginEvent. For the best performance, use a statically allocated string.

Calls to PIXBeginEvent 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.

This method is used to time CPU events. To time GPU events, refer to PIX GPU Capture APIs on the PIX3 page.

Each call to PIXBeginEvent must have a matching call to PIXEndEvent. The timing interval is about 200ns, and there is a low overhead to using this function, so up to several hundred thousand calls to PIXBeginEvent can be made per second.

PIXBeginEvent and PIXEndEvent pairs can be nested to any depth.

Requirements

Header: pix3.h

Library: pixevt.lib

Supported platforms: Xbox One family consoles and Xbox Series consoles

Share via