PIXBeginEvent

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(
         DWORD Metadata,
         const WCHAR *formatString,
         ...
)

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 null-terminated Unicode string. The string may specify zero or more optional string format placeholders, very similar to sprintf formatting.

Type: …

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

None.

Remarks

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

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, call the methods ID3D11DeviceContextX::PIXBeginEvent or ID3D11ComputeContextX::PIXBeginEvent.

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.

If you are still using, or have strings setup for, the deprecated function PIXBeginNamedEvent (which uses CHAR and not WCHAR) consider using the following code to keep using CHAR strings, but with the PixBeginEvent method.

// PIXBeginNamedEvent( Metadata, oldCharName );
PIXBeginEvent( Metadata, L"%hs", oldCharName );

Requirements

Header: Declared in pix.h.