イベント API は、アプリケーションで境界設定されたイベントが発生するのを観察したり、境界設定されたコード領域の実行時間の特定に使用されます。アプリケーションにアノテーションを追加して、注目するイベントが発生する領域を区分します。解析の実行後、[タイムライン] ペインでマークしたイベントを観察できます。
イベント API はレジューム状態で動作するスレッド単位の関数です。この関数はポーズ状態では動作しません。
Windows* プラットフォームでは、文字列を渡すワイド文字バージョンの API を使用する Unicode を定義できます。これらの文字列は、内部では ASCII 文字列に変換されます。
Linux* プラットフォームでは、API は 1 つのみです。
使用するプリミティブ |
説明 |
|---|---|
__itt_event __itt_event_create(const __itt_char *name, int namelen ); |
指定する名前と長さでイベントタイプを作成します。この API は、次のイベント開始およびイベント終了 API に引数として渡すイベントタイプのハンドルを返します。namelen パラメーターは、バイト数ではなく文字数で名前の長さを指定します。 |
int __itt_event_start( __itt_event event );
|
以前作成したイベントタイプのハンドルを使用してこの API を呼び出し、イベントのインスタンスを登録します。イベントの開始は、[タイムライン] ペインにティックマークとして表示されます。 |
int __itt_event_end( __itt_event event ); |
__itt_event_start() の呼び出し後にこの API を呼び出して、開始から終了までの期間をティックマークとしてイベントを表示します。この API が呼び出されない場合、イベントは [タイムライン] ペインに単独のティックマークとして表示されます。 |
__itt_event_end() は常に直前の __itt_event_start() とペアになります。それ以外では、__itt_event_end() 呼び出しは先行するペアにならない __itt_event_start() に対応付けられます。干渉するイベントはすべて入れ子にされます。
同一または異なる種類のユーザーイベントを相互に入れ子にできます。イベントが入れ子になる場合、その時間は最も深く入れ子になったユーザーイベント領域でのみ費やされたと見なされます。
異なる ITT API イベントをオーバーラップできます。イベントが重複する場合、時間は __itt_event_start() を持つイベント領域でのみ費やされたと見なされます。一致しない __itt_event_end() 呼び出しは無視されます。
結果にイベントとユーザータスクを表示するには、(注目する事前定義された解析を基に) [カスタム解析] を作成して、解析設定の[ユーザータスク、イベントおよびカウンターを解析] チェックボックスをオンにします。
__itt_event_create API は、__itt_event_start API を使用してユーザーイベントをマークするために使用する新しいイベントハンドラーを返します。この例では、2 つのイベント・タイプ・ハンドラーが作成され、異なるタイプのイベントを追跡する開始点を設定するために使用されます。
#include "ittnotify.h"
__itt_event mark_event = __itt_event_create( "User Mark", 9 );
__itt_event frame_event = __itt_event_create( "Frame Completed", 15 );
...
__itt_event_start( mark_event );
...
for( int f ; f<number_of_frames ; f++ ) {
...
__itt_event_start( markframe_event );
}次の例のように、__itt_event_start API の後に __itt_event_end API を続けてイベント領域を定義します。
#include "ittnotify.h"
__itt_event render_event = __itt_event_create( "Rendering Phase", 15 );
...
for( int f ; f<number_of_frames ; f++ ) {
...
do_stuff_for_frame();
...
__itt_event_start( render_event );
...
do_rendering_for_frame();
...
__itt_event_end( render_event );
...
}