Custom counter annotations

Application software can use counter annotations to generate custom data series that are displayed as charts in the Timeline view. Streamline automatically displays a chart for each custom counter that an application creates.

Each custom counter is presented as a single data series. For each counter, the implementation tracks an independent value for each application thread. The per-thread values are accumulated into a single series value, which is displayed in the Timeline view. Like hardware counters, you can filter custom counters using the Details panel to select which threads to include in the accumulated value.

Annotation macros

The following macros define integer counters, where the numeric value is in the range 0...1<<63-1:

ANNOTATE_DELTA_COUNTER(uid, title, name)

Define a custom delta counter. Specify:

uid

An integer that uniquely identifies the counter in the application process.

title

A string for the chart title.

name

A string for the series name.

ANNOTATE_ABSOLUTE_COUNTER(uid, title, name)

Define a custom absolute counter. The parameters are the same as for ANNOTATE_DELTA_COUNTER.

ANNOTATE_COUNTER_VALUE(uid, value)

Emit an integer value for a custom delta or absolute counter. uid identifies the counter.

The following macros define fractional (float or double) counters:

Note

The float value is converted to an integer value in the above range using some fixed multiplier, so for example to send a float value in the range 0.000...1.000, with 3-decimal places accuracy, use a modifier value of 1000.

ANNOTATE_DELTA_COUNTER_SCALE(uid, title, name, modifier)

Define a custom fixed-point delta counter with a scaling modifier. Specify:

uid

An integer that uniquely identifies the counter.

title

A string for the chart title.

name

A string for the series name.

modifier

An integer scaling factor.

Floating point counter samples reported through ANNOTATE_COUNTER_VALUE_SCALE are encoded as (int)(sample * modifier) for transport, and converted back to unscaled float for presentation. For example, to present a float with two decimal places of precision, set modifier to 100.

ANNOTATE_ABSOLUTE_COUNTER_SCALE(uid, title, name, modifier)

Define a custom absolute counter with a scaling modifier. The parameters are the same as for ANNOTATE_DELTA_COUNTER_SCALE.

ANNOTATE_COUNTER_VALUE_SCALE(uid, value, modifier)

Emit a value for a custom scaled delta or absolute counter. uid identifies the counter and value specifies a float value. The scaling value modifier must be an integer with the same value as the modifier that was used when the scaled counter was declared.

Example

The following example uses the ANNOTATE_ABSOLUTE_COUNTER and ANNOTATE_COUNTER_VALUE custom counter annotations to create a custom "Draw Calls / Frame" chart:

// Setup code
ANNOTATE_ABSOLUTE_COUNTER(draw_chart_id, "Draw Calls / Frame", context_label);

// Counter generation code
ANNOTATE_COUNTER_VALUE(draw_chart_id, draw_call_count);

Which enables the custom "Draw Calls / Frame" graph to be displayed in your capture timeline:

Custom counter annotation example capture

Note

To view a list of the graphs available, including custom graphs created using the custom counter annotations, select the Add charts with default settings... button. The available graphs are listed in the drop-down.