PIXBeginEvent overview
Starts a user-defined event for a timing capture of CPU activity, to be displayed in the System Timing Capture feature of PIX.Syntax
Parameters
contextType: void* Context for the event, accepts
ID3D12GraphicsCommandList\*, ID3D12GraphicsCommandList\* and ID3D12XboxDmaCommandList\* (XBOX only).
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: 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.
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
Type: voidRemarks
ThePIXBeginEvent 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. For more information about timing GPU events, see the PIX GPU Capture APIs section of PIX3.
Each call to PIXBeginEvent must have a matching call to PIXEndEvent. The paired calls to PIXBeginEvent and PIXEndEvent must occur on the same thread. 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 consolesSee also
PIX (NDA topic)pix3
PIXEndEvent
PIXBeginEvent
PIXBeginEvent_2
PIXBeginEvent_3