Frame API

User Guide

Intel® VTune™ Profiler User Guide

Download PDF

ID 766319

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-6E323493-FF06-4B96-B8E3-FDB8B8E2E00B

View Details

Frame API

Use the frame API to insert calls to the desired places in your code and analyze performance per frame, where frame is the time period between frame begin and end points. When frames are displayed in Intel® VTune™ Profiler, they are displayed in a separate track, so they provide a way to visually separate this data from normal task data.

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

You can run the frame analysis to:

Analyze Windows OS game applications that use DirectX* rendering.
Analyze graphical applications performing 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.

Adding Frame API to Your Code

Use This Primitive

To Do This

__itt_domain *ITTAPI__itt_domain_create ( const char *name)

For a domain name, the URI naming style is recommended, for example, com.my_company.my_application. The set of domains is expected to be static over the application's execution time, therefore, there is no mechanism to destroy a domain.

Any domain can be accessed by any thread in the process, regardless of which thread created the domain. This call is thread-safe.

[in]

name

Name of domain

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

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

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.

`[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_htm">__itt_frame_end_v3 with NULL as the id parameter designates the end of the frame.

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

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.

`[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.

Guidelines for Frame API Usage

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 and displays it as [Unknown] in the viewpoint.
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);

Parent topic: Instrumentation and Tracing Technology API Reference

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® VTune™ Profiler User Guide

Frame API

Adding Frame API to Your Code

Guidelines for Frame API Usage

Usage Example

See Also