Markers and Ranges

Marker
NVTX_DECLSPEC void NVTX_API	nvtxDomainMarkEx (nvtxDomainHandle_t domain, const nvtxEventAttributes_t *eventAttrib)
	Marks an instantaneous event in the application.
NVTX_DECLSPEC void NVTX_API	nvtxMarkEx (const nvtxEventAttributes_t *eventAttrib)
	Marks an instantaneous event in the application.
NVTX_DECLSPEC void NVTX_API	nvtxMarkA (const char *message)
	Marks an instantaneous event in the application.
NVTX_DECLSPEC void NVTX_API	nvtxMarkW (const wchar_t *message)

Process Ranges
NVTX_DECLSPEC nvtxRangeId_t NVTX_API	nvtxDomainRangeStartEx (nvtxDomainHandle_t domain, const nvtxEventAttributes_t *eventAttrib)
	Starts a process range in a domain.
NVTX_DECLSPEC nvtxRangeId_t NVTX_API	nvtxRangeStartEx (const nvtxEventAttributes_t *eventAttrib)
	Starts a process range.
NVTX_DECLSPEC nvtxRangeId_t NVTX_API	nvtxRangeStartA (const char *message)
	Starts a process range.
NVTX_DECLSPEC nvtxRangeId_t NVTX_API	nvtxRangeStartW (const wchar_t *message)
NVTX_DECLSPEC void NVTX_API	nvtxDomainRangeEnd (nvtxDomainHandle_t domain, nvtxRangeId_t id)
	Ends a process range.
NVTX_DECLSPEC void NVTX_API	nvtxRangeEnd (nvtxRangeId_t id)
	Ends a process range.

Thread Ranges
NVTX_DECLSPEC int NVTX_API	nvtxDomainRangePushEx (nvtxDomainHandle_t domain, const nvtxEventAttributes_t *eventAttrib)
	Starts a nested thread range.
NVTX_DECLSPEC int NVTX_API	nvtxRangePushEx (const nvtxEventAttributes_t *eventAttrib)
	Starts a nested thread range.
NVTX_DECLSPEC int NVTX_API	nvtxRangePushA (const char *message)
	Starts a nested thread range.
NVTX_DECLSPEC int NVTX_API	nvtxRangePushW (const wchar_t *message)
NVTX_DECLSPEC int NVTX_API	nvtxDomainRangePop (nvtxDomainHandle_t domain)
	Ends a nested thread range.
NVTX_DECLSPEC int NVTX_API	nvtxRangePop (void)
	Ends a nested thread range.

Detailed Description

See Markers and Ranges for more details

Function Documentation

nvtxDomainMarkEx()

NVTX_DECLSPEC void NVTX_API nvtxDomainMarkEx	(	nvtxDomainHandle_t	domain,
		const nvtxEventAttributes_t *	eventAttrib
	)

Marks an instantaneous event in the application.

A marker can contain a text message or specify additional information using the event attributes structure. These attributes include a text message, color, category, and a payload. Each of the attributes is optional and can only be sent out using the nvtxDomainMarkEx function.

nvtxDomainMarkEx(NULL, event) is equivalent to calling nvtxMarkEx(event).

Parameters

domain	- The domain of scoping the category.
eventAttrib	- The event attribute structure defining the marker's attribute types and attribute values.

See also

nvtxMarkEx

Version

NVTX_VERSION_2

nvtxDomainRangeEnd()

NVTX_DECLSPEC void NVTX_API nvtxDomainRangeEnd	(	nvtxDomainHandle_t	domain,
		nvtxRangeId_t	id
	)

Ends a process range.

Parameters

domain	- The domain
id	- The correlation ID returned from a nvtxRangeStart call.

Remarks

This function is offered completeness but is an alias for nvtxRangeEnd. It does not need a domain param since that is associated with the range ID at nvtxDomainRangeStartEx

Example

End a range for a domain:

nvtxDomainHandle_t domain = nvtxDomainCreateA("my domain");
nvtxEventAttributes_t eventAttrib = {0};
eventAttrib.version = NVTX_VERSION;
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
eventAttrib.message.ascii = "my range";
nvtxRangeId_t rangeId = nvtxDomainRangeStartEx(domain, &eventAttrib);
// ...
nvtxDomainRangeEnd(domain, rangeId);

See also

nvtxDomainRangeStartEx

Version

NVTX_VERSION_2

nvtxDomainRangePop()

NVTX_DECLSPEC int NVTX_API nvtxDomainRangePop

(

nvtxDomainHandle_t

domain

)

Ends a nested thread range.

Returns

The level of the range being ended. If an error occurs a negative value is returned on the current thread.

Example

Pop a range for a domain:

nvtxDomainHandle_t domain = nvtxDomainCreateA("example domain");
nvtxEventAttributes_t eventAttrib = {0};
eventAttrib.version = NVTX_VERSION;
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
eventAttrib.colorType = NVTX_COLOR_ARGB;
eventAttrib.color = 0xFFFF0000;
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
eventAttrib.message.ascii = "Level 0";
nvtxDomainRangePushEx(domain, &eventAttrib);
 
// Re-use eventAttrib
eventAttrib.messageType = NVTX_MESSAGE_TYPE_UNICODE;
eventAttrib.message.unicode = L"Level 1";
nvtxDomainRangePushEx(domain, &eventAttrib);
 
nvtxDomainRangePop(domain); // Level 1
nvtxDomainRangePop(domain); // Level 0

See also

nvtxRangePushEx nvtxRangePushA nvtxRangePushW

Version

NVTX_VERSION_2

nvtxDomainRangePushEx()

NVTX_DECLSPEC int NVTX_API nvtxDomainRangePushEx	(	nvtxDomainHandle_t	domain,
		const nvtxEventAttributes_t *	eventAttrib
	)

Starts a nested thread range.

Parameters

domain	- The domain of scoping.
eventAttrib	- The event attribute structure defining the range's attribute types and attribute values.

Returns

The 0 based level of range being started. This value is scoped to the domain. If an error occurs, a negative value is returned.

Example

Push a range with attributes for a domain:

nvtxDomainHandle_t domain = nvtxDomainCreateA("example domain");
nvtxEventAttributes_t eventAttrib = {0};
eventAttrib.version = NVTX_VERSION;
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
eventAttrib.colorType = NVTX_COLOR_ARGB;
eventAttrib.color = 0xFFFF0000;
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
eventAttrib.message.ascii = "Level 0";
nvtxDomainRangePushEx(domain, &eventAttrib);
 
// Re-use eventAttrib
eventAttrib.messageType = NVTX_MESSAGE_TYPE_UNICODE;
eventAttrib.message.unicode = L"Level 1";
nvtxDomainRangePushEx(domain, &eventAttrib);
 
nvtxDomainRangePop(domain); // Level 1
nvtxDomainRangePop(domain); // Level 0

See also

nvtxDomainRangePop

Version

NVTX_VERSION_2

nvtxDomainRangeStartEx()

NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxDomainRangeStartEx	(	nvtxDomainHandle_t	domain,
		const nvtxEventAttributes_t *	eventAttrib
	)

Starts a process range in a domain.

Parameters

domain	- The domain of scoping the category.
eventAttrib	- The event attribute structure defining the range's attribute types and attribute values.

Returns

The unique ID used to correlate a pair of Start and End events.

Remarks

Ranges defined by Start/End can overlap.

Example

Start a range with attributes for a domain:

nvtxDomainHandle_t domain = nvtxDomainCreateA("my domain");
nvtxEventAttributes_t eventAttrib = {0};
eventAttrib.version = NVTX_VERSION;
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
eventAttrib.message.ascii = "my range";
nvtxRangeId_t rangeId = nvtxDomainRangeStartEx(domain, &eventAttrib);
// ...
nvtxDomainRangeEnd(domain, rangeId);

See also

nvtxDomainRangeEnd

Version

NVTX_VERSION_2

nvtxMarkA()

NVTX_DECLSPEC void NVTX_API nvtxMarkA

(

const char *

message

)

Marks an instantaneous event in the application.

A marker created using nvtxMarkA or nvtxMarkW contains only a text message.

Parameters

message

- The message associated to this marker event.

Example

Place a mark:

nvtxMarkA("Example nvtxMarkA");
nvtxMarkW(L"Example nvtxMarkW");

See also

nvtxDomainMarkEx nvtxMarkEx

Version

NVTX_VERSION_0

nvtxMarkEx()

NVTX_DECLSPEC void NVTX_API nvtxMarkEx

(

const nvtxEventAttributes_t *

eventAttrib

)

Marks an instantaneous event in the application.

A marker can contain a text message or specify additional information using the event attributes structure. These attributes include a text message, color, category, and a payload. Each of the attributes is optional and can only be sent out using the nvtxMarkEx function. If nvtxMarkA or nvtxMarkW are used to specify the marker or if an attribute is unspecified then a default value will be used.

Parameters

eventAttrib

- The event attribute structure defining the marker's attribute types and attribute values.

Example

Place a mark with attributes:

// zero the structure
nvtxEventAttributes_t eventAttrib = {0};
// set the version and the size information
eventAttrib.version = NVTX_VERSION;
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
// configure the attributes.  0 is the default for all attributes.
eventAttrib.colorType = NVTX_COLOR_ARGB;
eventAttrib.color = 0xFF880000;
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
eventAttrib.message.ascii = "Example nvtxMarkEx";
nvtxMarkEx(&eventAttrib);

See also

nvtxDomainMarkEx

Version

NVTX_VERSION_1

nvtxRangeEnd()

NVTX_DECLSPEC void NVTX_API nvtxRangeEnd

(

nvtxRangeId_t

id

)

Ends a process range.

Parameters

id	- The correlation ID returned from an nvtxRangeStart call.

See also

nvtxDomainRangeStartEx nvtxRangeStartEx nvtxRangeStartA nvtxRangeStartW

Version

NVTX_VERSION_0

nvtxRangePop()

NVTX_DECLSPEC int NVTX_API nvtxRangePop

(

void

)

Ends a nested thread range.

Returns

The level of the range being ended. If an error occurs a negative value is returned on the current thread.

Example

Pop a range:

nvtxRangePushA("Level 0");
nvtxRangePushW(L"Level 1");
nvtxRangePop(); // Level 1
nvtxRangePop(); // Level 0

See also

nvtxRangePushEx nvtxRangePushA nvtxRangePushW

Version

NVTX_VERSION_0

nvtxRangePushA()

NVTX_DECLSPEC int NVTX_API nvtxRangePushA

(

const char *

message

)

Starts a nested thread range.

Parameters

message

- The event message associated to this range event.

Returns

The 0 based level of range being started. If an error occurs a negative value is returned.

Example

Push a range:

nvtxRangePushA("Level 0");
nvtxRangePushW(L"Level 1");
nvtxRangePop(); // Level 1
nvtxRangePop(); // Level 0

See also

nvtxDomainRangePushEx nvtxRangePop

Version

NVTX_VERSION_0

nvtxRangePushEx()

NVTX_DECLSPEC int NVTX_API nvtxRangePushEx

(

const nvtxEventAttributes_t *

eventAttrib

)

Starts a nested thread range.

Parameters

eventAttrib

- The event attribute structure defining the range's attribute types and attribute values.

Returns

The 0 based level of range being started. This level is per domain. If an error occurs a negative value is returned.

Example

Push a range with attributes:

nvtxEventAttributes_t eventAttrib = {0};
eventAttrib.version = NVTX_VERSION;
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
eventAttrib.colorType = NVTX_COLOR_ARGB;
eventAttrib.color = 0xFFFF0000;
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
eventAttrib.message.ascii = "Level 0";
nvtxRangePushEx(&eventAttrib);
 
// Re-use eventAttrib
eventAttrib.messageType = NVTX_MESSAGE_TYPE_UNICODE;
eventAttrib.message.unicode = L"Level 1";
nvtxRangePushEx(&eventAttrib);
 
nvtxRangePop(); // Level 1
nvtxRangePop(); // Level 0

See also

nvtxDomainRangePushEx nvtxRangePop

Version

NVTX_VERSION_1

nvtxRangeStartA()

NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartA

(

const char *

message

)

Starts a process range.

Parameters

message

- The event message associated to this range event.

Returns

The unique ID used to correlate a pair of Start and End events.

Remarks

Ranges defined by Start/End can overlap.

Example

Start a range:

nvtxRangeId_t r1 = nvtxRangeStartA("Range 1");
nvtxRangeId_t r2 = nvtxRangeStartW(L"Range 2");
nvtxRangeEnd(r1);
nvtxRangeEnd(r2);

See also

nvtxRangeEnd nvtxRangeStartEx nvtxDomainRangeStartEx

Version

NVTX_VERSION_0

nvtxRangeStartEx()

NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartEx

(

const nvtxEventAttributes_t *

eventAttrib

)

Starts a process range.

Parameters

eventAttrib

- The event attribute structure defining the range's attribute types and attribute values.

Returns

The unique ID used to correlate a pair of Start and End events.

Remarks

Ranges defined by Start/End can overlap.

Example

Start a range with attributes:

nvtxEventAttributes_t eventAttrib = {0};
eventAttrib.version = NVTX_VERSION;
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
eventAttrib.category = 3;
eventAttrib.colorType = NVTX_COLOR_ARGB;
eventAttrib.color = 0xFF0088FF;
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
eventAttrib.message.ascii = "Example Range";
nvtxRangeId_t rangeId = nvtxRangeStartEx(&eventAttrib);
// ...
nvtxRangeEnd(rangeId);

See also

nvtxRangeEnd nvtxDomainRangeStartEx

Version

NVTX_VERSION_1