nvtxEventAttributes_t Struct Reference

Event Attribute Structure. . More...

#include <nvToolsExt.h>

Data Structures
union	payload_t
	Payload assigned to this event.. More...

Data Fields
uint16_t	version
	Version flag of the structure.
uint16_t	size
	Size of the structure.
uint32_t	category
	ID of the category the event is assigned to.
int32_t	colorType
	Color type specified in this attribute structure.
uint32_t	color
	Color assigned to this event..
int32_t	payloadType
	Payload type specified in this attribute structure.
int32_t	reserved0
union nvtxEventAttributes_v2::payload_t	payload
int32_t	messageType
	Message type specified in this attribute structure.
nvtxMessageValue_t	message
	Message assigned to this attribute structure..

Detailed Description

Event Attribute Structure. .

This structure is used to describe the attributes of an event. The layout of the structure is defined by a specific version of the tools extension library and can change between different versions of the Tools Extension library.

Initializing the Attributes

The caller should always perform the following three tasks when using attributes:

• Zero the structure
• Set the version field
• Set the size field

Zeroing the structure sets all the event attributes types and values to the default value.

The version and size field are used by the Tools Extension implementation to handle multiple versions of the attributes structure.

It is recommended that the caller use one of the following to methods to initialize the event attributes structure:

Method 1: Initializing nvtxEventAttributes for future compatibility

nvtxEventAttributes_t eventAttrib = {0};
eventAttrib.version = NVTX_VERSION;
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;

Method 2: Initializing nvtxEventAttributes for a specific version

nvtxEventAttributes_t eventAttrib = {0};
eventAttrib.version = 1;
eventAttrib.size = (uint16_t)(sizeof(nvtxEventAttributes_v1));

If the caller uses Method 1 it is critical that the entire binary layout of the structure be configured to 0 so that all fields are initialized to the default value.

The caller should either use both NVTX_VERSION and NVTX_EVENT_ATTRIB_STRUCT_SIZE (Method 1) or use explicit values and a versioned type (Method 2). Using a mix of the two methods will likely cause either source level incompatibility or binary incompatibility in the future.

Settings Attribute Types and Values

Example:

// Initialize
nvtxEventAttributes_t eventAttrib = {0};
eventAttrib.version = NVTX_VERSION;
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
 
// Configure the Attributes
eventAttrib.colorType = NVTX_COLOR_ARGB;
eventAttrib.color = 0xFF880000;
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
eventAttrib.message.ascii = "Example";

In the example the caller does not have to set the value of nvtxEventAttributes_v2::category or ::nvtxEventAttributes_v2::payload as these fields were set to the default value by {0}.

See also

nvtxDomainMarkEx nvtxDomainRangeStartEx nvtxDomainRangePushEx

Definition at line 444 of file nvToolsExt.h.

Field Documentation

category

uint32_t nvtxEventAttributes_t::category

ID of the category the event is assigned to.

A category is a user-controlled ID that can be used to group events. The tool may use category IDs to improve filtering or enable grouping of events in the same category. The functions nvtxNameCategoryA or ::nvtxNameCategoryW can be used to name a category.

Default Value is 0

Definition at line 474 of file nvToolsExt.h.

color

uint32_t nvtxEventAttributes_t::color

Color assigned to this event..

The color that the tool should use to visualize the event.

Definition at line 489 of file nvToolsExt.h.

colorType

int32_t nvtxEventAttributes_t::colorType

Color type specified in this attribute structure.

Defines the color format of the attribute structure's color field.

Default Value is NVTX_COLOR_UNKNOWN

Definition at line 483 of file nvToolsExt.h.

message

nvtxMessageValue_t nvtxEventAttributes_t::message

Message assigned to this attribute structure..

The text message that is attached to an event.

Definition at line 533 of file nvToolsExt.h.

messageType

int32_t nvtxEventAttributes_t::messageType

Message type specified in this attribute structure.

Defines the message format of the attribute structure's message field.

Default Value is NVTX_MESSAGE_UNKNOWN

Definition at line 527 of file nvToolsExt.h.

payloadType

int32_t nvtxEventAttributes_t::payloadType

Payload type specified in this attribute structure.

Defines the payload format of the attribute structure's payload field.

Default Value is NVTX_PAYLOAD_UNKNOWN

Definition at line 499 of file nvToolsExt.h.

reserved0

int32_t nvtxEventAttributes_t::reserved0

Definition at line 501 of file nvToolsExt.h.

size

uint16_t nvtxEventAttributes_t::size

Size of the structure.

Needs to be set to the size in bytes of the event attribute structure used to specify the event.

Definition at line 461 of file nvToolsExt.h.

version

uint16_t nvtxEventAttributes_t::version

Version flag of the structure.

Needs to be set to NVTX_VERSION to indicate the version of NVTX APIs supported in this header file. This can optionally be overridden to another version of the tools extension library.

Definition at line 453 of file nvToolsExt.h.

---

The documentation for this struct was generated from the following file:

• nvToolsExt.h