Frame API

Use the frame API to insert calls to the desired places in your code and analyze performance per frame. A frame is defined as the time period between the frame begin and frame end points. Frames display in Intel® VTune™ Profiler as a separate track, so they provide a way to visually separate this data from typical task data.

The frame API is a per-process function that works in the resumed state. This function does not work in the paused state.

Run the frame analysis to:

Analyze Windows OS game applications that use DirectX* rendering.
Analyze graphical applications that perform repeated calculations.
Analyze transaction processing on a per-transaction basis to discover input cases that cause bad performance.

Frames represent a series of non-overlapping regions of Elapsed time. Frames are global in nature and not connected with any specific thread. ITT APIs that enable analyzing code frames and presenting the analysis data.

Include Frame API to Your Code

Create a domain instance with the __itt_domain_create() function:

__itt_domain *ITTAPI__itt_domain_create ( const char *name );

Follow the URI naming style to create domain names. For example, “com.my_company.my_application” is an acceptable format. The set of domains is expected to be static over the execution time of the application. Therefore, there is no mechanism to destroy a domain.

Any thread in the process can access any domain, irrespective of the thread that created the domain. This call is thread-safe.

Define the beginning of the frame instance. An __itt_frame_begin_v3 call must be paired with an __itt_frame_end_v3 call:

void __itt_frame_begin_v3(const __itt_domain *domain, __itt_id *id);

Successive calls to __itt_frame_begin_v3 with the same ID are ignored until a call to __itt_frame_end_v3 with the same ID.

Type	Parameter	Description
[in]	domain	The domain for this frame instance
[in]	id	The instance ID for this frame instance. Can be NULL, in which case the next call to `__itt_frame_end_v3` with NULL as the id parameter designates the end of the frame.

Define the end of the frame instance. A __itt_frame_end_v3 call must be paired with a __itt_frame_begin_v3 call. The first call to __itt_frame_end_v3 with a given ID ends the frame. Successive calls with the same ID are ignored, as are calls that do not have a matching __itt_frame_begin_v3 call:

void __itt_frame_end_v3(const __itt_domain *domain, __itt_id *id);

Type	Parameter	Description
[in]	domain	The domain for this frame instance
[in]	id	The instance ID for this frame instance, or NULL for the current instance

Note

The analysis types based on the hardware event-based sampling collection are limited to 64 distinct frame domains.

Usage Guidelines

Use the frame API to denote the frame begin point and end point. Consider a frame as the time period between frame begin and end points.
VTune Profiler does not attribute the time/samples between __itt_frame_end_v3() and __itt_frame_begin_v3() to any program unit. In the viewpoint for the analysis, this information displays as [Unknown].
If there are consecutive __itt_frame_begin_v3 calls in the same domain, treat it as a __itt_frame_end_v3/__itt_frame_begin_v3 pair.
Recursive/nested/overlapping frames for the same domain are not allowed.
The __itt_frame_begin_v3() and __itt_frame_end_v3() calls can be made from different threads.
The recommended maximum rate for calling the frame API is 1000 frames per second. A higher rate may result in large product memory consumption and slow finalization.

Usage Example

The following example uses the frame API to capture the Elapsed times for the specified code sections.

#include "ittnotify.h"

__itt_domain* pD = __itt_domain_create( L"My Domain" );

pD->flags = 1; /* enable domain */

for (int i = 0; i < getItemCount(); ++i)
{
  __itt_frame_begin_v3(pD, NULL);
  do_foo();
  __itt_frame_end_v3(pD, NULL);
}

//...

__itt_frame_begin_v3(pD, NULL);
do_foo_1();
__itt_frame_end_v3(pD, NULL);

//...

__itt_frame_begin_v3(pD, NULL);
do_foo_2();
__itt_frame_end_v3(pD, NULL);