PIXSetMarker overview

Article
06/22/2023

Inserts a marker into the GPU timeline in the PIX System Timing Capture window, when a particular user-defined event occurs.

Syntax

void PIXSetMarker(  
         void* context,  
         UINT64 color,  
         PCWSTR formatString,  
         ...  
)

Parameters

context
Type: void*

Context for the event, accepts ID3D12GraphicsCommandList* , ID3D12CommandQueue* and ID3D12XboxDmaCommandList* (Xbox only).

color
Type: UINT64

The color that will be used in the timing chart when this event occurs in PIX windows.

Use PIX_COLOR to specify a color, use 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 (up to a maximum of 16) whose types match the placeholders.

Return value

Type: void

Remarks

The PIXSetMarker function saves format string and format parameters instead of formatting the string at runtime. Formatting is then done when reading capture file in PIX. Use 16-byte aligned strings (preferable) or 8-byte aligned strings with PIXSetMarker to get the best performance. To print a char* or wchar_t* as a pointer using %p format specifier, cast pointer to void* or a pointer to an integral or a floating point type when passing it to PIXSetMarker. Any call to PIXSetMarker has guaranteed at least 512 bytes of space to save the record data.

The event will be shown as having no duration, and will be represented by a single line (a single vertical bar) in the PIX System Timing Capture window.

This function is used to mark events in the GPU timeline. To mark events in the CPU timeline, call the first overload of the PIXSetMarker function or the second overload of the PIXSetMarker function.

Calls to PIXSetMarker can occur anywhere, and do not have to follow a call to PIXBeginEvent.

Requirements

Header: pix3.h

Library: pixevt.lib

Supported platforms: Xbox One family consoles and Xbox Series consoles

Share via