Intel® Graphics Performance Analyzers User Guide

Download PDF
ID 767266
Date 3/15/2023
Public

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

Document Table of Contents
Document Table of Contents x
Intel® Graphics Performance Analyzers User Guide
Intel® Graphics Performance Analyzers User Guide x
Introduction to Intel® Graphics Performance Analyzers Get Help Game Optimization Methodology Install and Launch Intel® GPA Enable System-wide Time-based GPU Metrics and Enable Query-based Metrics for OpenGL* in Graphics Frame Analyzer for Ubuntu* Launch Application for Analysis Configure Analysis Settings Quick Start with Profiling Unreal Engine* Games Analyze Desktop Graphics Applications Instrumentation and Tracing Technology API Support Intel® GPA Reference Notices and Disclaimers
Launch Application for Analysis x
Start a Desktop Application with Graphics Monitor Start a Windows* Mixed Reality Application Connect to a Running Application (Windows* only) Analyze Applications in the Network Mode
Configure Analysis Settings x
Configure a Metric Set Customize Keyboard Shortcuts Set Up a Trigger Set Up Tracing Options Set Up Stream Options Set Frame Delimiters
Analyze Desktop Graphics Applications x
Manage Analysis with Graphics Monitor Monitor Real-Time Performance with System Analyzer Identify Issues in Graphics Application Execution with Trace Analyzer Analyze GPU-bound Applications with Graphics Frame Analyzer Optimize Specific Domains
Monitor Real-Time Performance with System Analyzer x
Pause and Resume a Running Application Export Metrics Data with System Analyzer
Analyze GPU-bound Applications with Graphics Frame Analyzer x
Run Render State Experiments with Frame Analyzer Use Advanced Profiling Mode Graphics Frame Analyzer Plugins
Graphics Frame Analyzer Plugins x
Create a Custom Plugin for Graphics Frame Analyzer
Optimize Specific Domains x
Optimize Shaders Analyze Textures Minimize Overdraw Optimize Graphic API States Identify Graphics Elements with Complex Geometry Visualize Color Distribution
Instrumentation and Tracing Technology API Support x
Compile and Link with ITT API Instrument Your Application Minimize ITT API Overhead Clock Domain API Counter API Domain API Marker API Metadata API Relation API String Handle API Thread Naming API Task API Task API Functions ITTAPI__itt_task_* Function Parameters Usage Example
Intel® GPA Reference x
Performance Metrics Reference User Interface Reference
Performance Metrics Reference x
CPU Metrics Device I/O Metrics GPU Metrics Graphics API Metrics Memory Metrics
User Interface Reference x
Graphics Monitor UI Reference Heads-Up Display (HUD) UI Reference System Analyzer UI Reference Graphics Frame Analyzer UI Reference Graphics Trace Analyzer UI Reference
Graphics Monitor UI Reference x
Graphics Monitor Context Menu Graphics Monitor Configuration Window Graphics Monitor Control Panel Graphics Monitor Window: Desktop Applications Tab Graphics Monitor Window: Universal Windows Applications Tab (Windows* only) Graphics Monitor Window: Options Dialog Box
Graphics Frame Analyzer UI Reference x
Graphics Frame Analyzer Window: Open Frame Capture Graphics Frame Analyzer Window: Multiframe View Graphics Frame Analyzer Window: Profiling View Graphics Frame Analyzer Window: Dependency Viewer
Graphics Frame Analyzer Window: Profiling View x
Main Toolbar Visualization Pane API Log Pane Resources Pane Metrics Pane Experiments Pane
Graphics Trace Analyzer UI Reference x
Graphics Trace Analyzer Window: Open Trace Capture Graphics Trace Analyzer Window: Platform View
Intel® Graphics Performance Analyzers User Guide

Task API

A task is a logical unit of work performed by a particular thread. Tasks can nest; thus, tasks typically correspond to functions, scopes, or a case block in a switch statement. You can use the Task API to assign tasks to threads.

The Task API does not enable a thread to suspend the current task and switch to a different task (task switching), or move a task to a different thread (task stealing).

A task instance represents a piece of work performed by a particular thread for a period of time. The task is defined by the bracketing of __itt_task_begin() and __itt_task_end() on the same thread.

Tasks can be of two types: simple or overlapped.

Simple tasks implicitly support a concept of embedded execution. This means that the call __itt_task_end() finalizes the most recent __itt_task_begin() call. For example, the following metacode is a valid sequence, and execution time of "a" tasks incorporates the execution time of "b" tasks:

__itt_task_begin(a)

__itt_task_begin(b)

__itt_task_end(b)

__itt_task_end(a)

Execution regions of overlapped tasks may intercept. For example, the following metacode is a valid sequence, and a "b" task started after an "a" task can finish upon completion of the "a" task:

__itt_task_begin_overlapped(a)

__itt_task_begin_overlapped(b)

__itt_task_end_overlapped(a)

__itt_task_end_overlapped(b)

Task API Functions

To create a simple task instance on a thread, use the following functions:

void ITTAPI __itt_task_begin (const __itt_domain *domain,__itt_id taskid, __itt_id parentid, __itt_string_handle *name)

void ITTAPI __itt_task_begin_fn (const __itt_domain *domain,__itt_id taskid, __itt_id parentid, void* address)

void ITTAPI __itt_task_end (const __itt_domain *domain)

To create a simple task instance in a different clock domain, use the following functions:

void ITTAPI __itt_task_begin_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name)

void ITTAPI __itt_task_begin_fn_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, void* fn)

void ITTAPI _itt_task_end_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp)

To create an overlapped task instance on a thread, use the following functions:

void ITTAPI __itt_task_begin_overlapped(const __itt_domain* domain, __itt_id taskid, __itt_id parentid, __itt_string_handle* name)

void ITTAPI __itt_task_end_overlapped(const __itt_domain *domain, __itt_id taskid)

The argument taskid is mandatory for these functions.

To create an overlapped task instance in a different clock domain, use the following functions:

void ITTAPI __itt_task_begin_overlapped_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name)

void ITTAPI __itt_task_end_overlapped_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid)

The argument taskid is mandatory for these functions.

ITTAPI__itt_task_* Function Parameters

The following table defines the parameters used in the Task API primitives.

Type

Parameter

Description

[in]

__itt_domain

The domain of the task.

[in]

__itt_id taskid

User-defined ID optional for all task instances, except for overlapped task instances.

__itt_null can be used as default for undefined task instances. Task ID is used to define relations between task instances.

NOTE:

Tasks with different domains cannot have same IDs.

[in]

__itt_id parentid

Optional parameter. Parent instance ID, to which the task belongs, or __itt_null.

NOTE:

Parents with different domains cannot have same IDs.

[in]

__itt_string_handle

The task string handle.

[in] void* fn

Function address that can be used instead of the name. For example, the function address can be resolved into the function name by using debug symbol information.

Usage Example

The following code snippet creates a domain and a couple of tasks at global scope. 


#include "ittnotify.h"

void do_foo(double seconds);

__itt_domain* domain = __itt_domain_create(__TEXT("MyTraces.MyDomain"));
__itt_string_handle* shMyTask = __itt_string_handle_create(__TEXT("My Task"));
__itt_string_handle* shMySubtask = __itt_string_handle_create(__TEXT("My SubTask"));

void BeginFrame() {
     __itt_task_begin(domain, __itt_null, __itt_null, shMyTask);
     do_foo(1);
}

void DoWork() {
     __itt_task_begin(domain, __itt_null, __itt_null, shMySubtask);
     do_foo(1);
     __itt_task_end(domain);
}
void EndFrame() {
     do_foo(1);
     __itt_task_end(domain);
}

int main() {
    BeginFrame();
    DoWork();
    EndFrame();
    return 0;
}
Parent topic: Instrumentation and Tracing Technology API Support

See Also

Level Two Title