Adding Custom Metrics

With the System Analyzer, you can view and analyze custom metrics of your profiled graphics application.

Follow the procedure described below to analyze your custom metrics.

Defining Types of Extension Functions

Insert the following function calls into your application code to get custom metrics displayed in the System Analyzer. Using these functions is optional, but this feature may help you identify performance bottlenecks in your application. For example, you might want to display the following:

  • special algorithms within your program are being invoked, such as different types of shades
  • values of game parameters or metrics that may affect performance, such as the number of zombies in the scene

eglCreateMetricGPA

EGLint eglCreateMetricGPA(const char*, const char*, const char*);

Use this function to create a custom metric.
Parameters

  • name – the metric name to be displayed in the System Analyzer Metric Tree Control Panel.

  • units – the metric units to be displayed on a chart along with the metric name.

  • group – the logical group name of your choice to group related custom metrics in the metrics tree. The metric groups appear under the User group in the System Analyzer Metric Tree Control Panel.

Return Values

This function returns handle to a newly created metric, or -1 in case of failure. The returned metric handle can be used to update the value of this metric with other custom metric functions.

eglSetMetricValueGPA

void eglSetMetricValueGPA(EGLint metric, double value);

Use this function to update a metric value. Intel® GPA updates the value of the metric in any chart that includes this custom metric.

Parameters

  • metric – a handle to the metric provided by the eglCreateMetricGPA function

  • value – the metric value to be displayed in the System Analyzer charts

eglRemoveMetricGPA

void eglRemoveMetricGPA(EGLint metric);

Use this function to remove a metric created by eglCreateMetricGPA function. This metric will no longer appear in the list of available metrics, and will be removed from any charts that are using this metric.

Parameters

  • metric – a handle to the metric provided by the eglCreateMetricGPA function

Programming Tips for Using Custom Metric Functions

You can retrieve any of the custom metric functions by calling a standard eglGetProcAddress function with a corresponding function name as a parameter. For example:

void* pfnCreateMetricGPA = eglGetProcAddress(“glCreateMetricGPA”);

If your graphics application is running under Intel® GPA, the eglGetProcAddress function returns the pointer to the requested function; otherwise NULL. The code example below demonstrates how to define types of extension functions:

typedef EGLint(*eglCreateMetricGPA_t)(const char*, const char*, const char*);

typedef GLvoid(*eglSetMetricValueGPA_t)(EGLint, double);

typedef GLvoid(*eglRemoveMetricGPA_t)(EGLint);

Getting Extension Functions

Use the eglGetProcAddress function to get extension functions:

eglCreateMetricGPA_t pfnCreateMetricGPA = (eglCreateMetricGPA_t)eglGetProcAddress("eglCreateMetricGPA");

eglSetMetricValueGPA_t pfnSetMetricValueGPA = (eglSetMetricValueGPA_t)eglGetProcAddress("eglSetMetricValueGPA");

eglRemoveMetricGPA_t pfnRemoveMetricGPA = (eglRemoveMetricGPA_t)eglGetProcAddress("eglRemoveMetricGPA");

Example

The code example below demonstrates how to create a new metric with different attributes:

EGLint hMetric = -1; if (pfnCreateMetricGPA) { hMetric = pfnCreateMetricGPA("Ref Value", "unit", "Synthetic"); }

Each custom metric you define appears in the System Analyzer > Metrics pane > User > <group>. In this example, the group is set to Synthetic.

You can create or remove a metric during your application run.

Setting up Custom Metric Values

Set up values for your custom metric. In the example below the value of the custom metric is set to 42.0:

if (pfnSetMetricValueGPA) { pfnSetMetricValueGPA(hMetric, 42.0); }

System Analyzer shows only the last value of the metric that you have set. If the value changes between frames, update the metric value every time you render a frame, otherwise you will see "old" value(s) for your custom metrics.

System Analyzer does not support negative metric values.

Removing a Custom Metric

Remove a custom metric from your graphics application, if needed, as shown below:

if (pfnRemoveMetricGPA) { pfnRemoveMetricGPA(hMetric); }

For more complete information about compiler optimizations, see our Optimization Notice.