Custom Activity Map annotations

This topic describes the Custom Activity Map (CAM) annotations supported by Streamline.

CAM annotations allow you to define and visualize the execution of a complex dependency chain of jobs. Each CAM view contains one or more tracks and each track contains one or more jobs. Tracks can also be nested hierarchically.

Jobs might have dependencies on other jobs. Dependencies between jobs are shown using connecting lines with circles at each end to indicate the direction of the dependency. A job with a closed circle depends on a job with an open circle.

Custom Activity Maps

Annotation macros

CAM_VIEW_NAME(view_uid, name)

Create a named CAM view. view_uid must be unique in the application process.

CAM_TRACK(view_uid, track_uid, parent_track, name)

Add a track to a CAM view. To make the track a child of another track, specify the parent track ID in parent_track. To make it a root track, set parent_track to -1. track_uid must be unique within the view.

CAM_JOB(view_uid, job_uid, name, track, start_time, duration,  color)

Add a job with a start time and duration to a CAM track. job_uid must be unique within the view. The job is displayed in the Timeline view as a colored bar representing its duration. The job name is displayed inside the bar. The start time and duration of the job are specified in nanoseconds. To get the current timestamp in nanoseconds, use gator_get_time(), which is declared in streamline_annotate.h.

CAM_JOB_DEPS(view_uid, job_uid, name, track, start_time, duration, color,  dependency_count, dependencies)

Add a job with dependencies on other jobs to a CAM track. track is the track to add this job to, dependencies are the jobs that this job depends on, and dependency_count is the number of dependencies.

CAM_JOB_DEP(view_uid, job_uid, name, track, start_time, duration, color,  dependency)

The single-dependency version of CAM_JOB_DEPS.

CAM_JOB_SET_DEPS(view_uid, job_uid, time, dependency_count, dependencies)

Set the dependencies of a job that was previously started using CAM_JOB_START. If you call this macro multiple times, Streamline uses the dependencies with the latest timestamp.

CAM_JOB_SET_DEP(view_uid, job_uid, time, dependency)

The single-dependency version of CAM_JOB_SET_DEPS.

CAM_JOB_START(view_uid, job_uid, name, track, time, color)

Add a job with a start time to a CAM track. End the job using CAM_JOB_STOP.

CAM_JOB_STOP(view_uid, job_uid, time)

End a CAM job that was previously started using CAM_JOB_START.

Example

The following code is an example that uses the CAM_VIEW_NAME, CAM_TRACK, CAM_JOB, CAM_START, and CAM_STOP annotations:

// Setup
cam_view = cam_next_id++;
CAM_VIEW_NAME(cam_view, "Graphics Analyzer");

cam_track_thread_context = cam_next_id++;
CAM_TRACK(cam_view, cam_track_thread_context, -1, "Active Context");

cam_thread_track = cam_next_id++;
CAM_TRACK(cam_view, cam_track, cam_track_thread_context, thread_label);

// Per frame
if (last_job)
{
        CAM_JOB_STOP(cam_view, last_job, gator_get_time());
}

last_job++
CAM_JOB_START(cam_view, last_job, job_name, cam_thread_track, gator_get_time(), ANNOTATE_LTGRAY);

The example code enables the "Graphics Analyzer" CAM view to be available as a details panel mode:

Example CAM annotations mode

To view the tracks, select the "Graphics Analyzer" CAM view, and select a high zoom:

Example CAM annotations tracks view at high zoom