PIXScopedEvent

Creates a user-defined event for a timing capture of CPU activity, to be displayed in the System Timing Capture feature of PIX. Events defined by calling PIXScopedEvent begin when the API is called and end when the enclosing scope exits.

Syntax

void PIXScopedEvent(
         DWORD Metadata,
         const WCHAR *formatString,
         va_list arglist
)

Parameters

Metadata
Type: DWORD

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
Type: WCHAR *

The name to use to describe the event, as a pointer to a Unicode null-terminated string.

The string may specify zero or more optional string format placeholders, very similar to sprintf formatting.

arglist
Type: va_list

If placeholders are used in formatString, there must be a corresponding number of parameters (up to a maximum of 16) whose types match the placeholders.

Return value

None.

Remarks

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.

C is no longer supported; functions turn into no-ops if __cplusplus is not defined. The PIXScopedEvent 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 PIXScopedEvent 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 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.

This method is used to time CPU events. To time GPU events, call the methods ID3D11DeviceContextX::PIXBeginEvent or ID3D11ComputeContextX::PIXBeginEvent.

Requirements

Header: Declared in pix.h.