You copied the Doc URL to your clipboard.

Adding images to reports using Visual Annotate

In addition to simple text overlays using Annotate, Streamline supports the annotation of images, providing further application-level context to the timeline view.

Figure 40. Visual Annotation in the Timeline view

Visual Annotation in the Timeline view

Just like textual annotation, the application writes to /dev/gator/annotate virtual file using standard c-library functions. The gator driver outputs this data with a timestamp to Streamline and integrates it with the trace and sample report.

The mechanics of instrumenting your source code to provide visual annotation is similar to the process of adding standard annotation. For more information on text-only annotation, see Customize reports using Annotate.

To include images in the data sent to the host during a capture session, use the ANNOTATE_BLOCK macro in your source code instead of the ANNOTATE and ANNOTATE_COLOR macros used in standard annotation. ANNOTATE_BLOCK provides a parameter for image data.

To use visual annotation, you must:

  1. Create an annotate.h file using the sample code from this topic.

  2. Include the annotate.h header file in your source code using the following line of code:

    #include "annotate.h"

  3. You must call the following before using the ANNOTATE_BLOCK macro:


  4. Insert the ANNOTATE_BLOCK macro into your code:

    ANNOTATE_BLOCK(data, length, str);

    Replace data with your image, length with the size of the data being written to the annotate file, and str with a descriptive string to be included with the image. Including a string is optional.

Figure 41. Visual annotation with optional text ‘

Visual annotation with optional text ‘


Visual Annotation supports images in the following formats: GIF, PNG, JPEG, TIFF, ICO, and BMP +RLE. There is no limit to the image size but the larger the image, the greater impact on the system performance. Increasing the amount of data sent to the host in this way increases the probe effect for the applications you are profiling

You can see the effects of visual annotation in the Timeline and Log views of your Streamline Analysis Reports. With visual annotation, the Timeline view data includes a chart that contains the annotated images. For more information about how visual annotation changes the Timeline view and how to interact with it, see Timeline view charts.

Any annotation event that includes an image has an icon in the message field of the Log view. Hover over the icon to see the image.

Code example: annotate.h

The following example annotate.h header file includes the ANNOTATE_VISUAL macro, used to send image data to the annotate virtual file.

#ifndef __ANNOTATE_H__
#define __ANNOTATE_H__

#include <stdio.h>
extern FILE *gator_annotate;

/* You must put 'ANNOTATE_DEFINE;' one place in your program. */
#define ANNOTATE_DEFINE   FILE *gator_annotate

#define ANNOTATE_SETUP  do { \
	gator_annotate = fopen("/dev/gator/annotate", "wb"); \
	if (gator_annotate) { setvbuf(gator_annotate, (char *)NULL, _IONBF, 0); }} while(0)

#define ANNOTATE(...)   do { if (gator_annotate) { \
	fprintf(gator_annotate, __VA_ARGS__); \
	fputc('\0', gator_annotate); }} while(0)

#define ANNOTATE_COLOR(color, ...) do { if (gator_annotate) { \
	fwrite((char*)&color, 1, sizeof(color), gator_annotate); \
	fprintf(gator_annotate, __VA_ARGS__); \
	fputc('\0', gator_annotate); }} while(0)

#define ANNOTATE_END() do { if (gator_annotate) { \
	fputc('\0', gator_annotate); }} while(0)

#define ANNOTATE_VISUAL(data, length, str) do { if (gator_annotate) { \
	int str_size = strlen(str) & 0xffff; \
	long long visual_annotation = 0x011c | (str_size<<16) | ((long long)length << 32); \
	fwrite((char*)&visual_annotation, 8, 1, gator_annotate); \
	if (str_size > 0) fwrite(str, 1, str_size, gator_annotate); \
	if (length > 0) fwrite((char*)(data), 1, length, gator_annotate); }} while(0)

// ESC character, hex RGB (little endian)
static const int  ANNOTATE_RED = 0x0000ff1b;
static const int  ANNOTATE_BLUE = 0xff00001b;
static const int  ANNOTATE_GREEN = 0x00ff001b;
static const int  ANNOTATE_PURPLE = 0xff00ff1b;
static const int  ANNOTATE_YELLOW = 0x00ffff1b;
static const int  ANNOTATE_CYAN = 0xffff001b;
static const int  ANNOTATE_WHITE = 0xffffff1b;
static const int  ANNOTATE_LTGRAY = 0xbbbbbb1b;
static const int  ANNOTATE_DKGRAY = 0x5555551b;
static const int  ANNOTATE_BLACK = 0x0000001b;

#endif // __ANNOTATE_H__
Was this page helpful? Yes No