Sending a Custom Counter

A counter is an accumulator that is used by PVRTune to only display the per-frame and per-second rates of that accumulator, in other words the rate of change of values.

A counter should only increment, meaning it must never reset or decrease, but it may wrap. Furthermore, a counter cannot display absolute values.

The following are examples of counter usage in PVRTune:

• Cars being rendered: Increments a counter every time a car is rendered. Alternatively, increment once per frame for the number of cards that will be rendered. PVRTune will then calculate the “cars rendered per frame” and “cars rendered per second”.

• Healing (health restored): Every time a character receives health, increment the counter by the quantity. PVRTune will calculate the “healing per frame” and “healing per second”.

Additional Initialisation Steps

To send a custom counter in PVRScope, there a few additional initialisation steps which must be performed:

1. Set up an enumerator of possible custom counters. This contains one entry per counter and an entry containing the total number of counters.

enum PVRScopeCustomCounters {
    eARBITRARY_COUNTER,
    eNUM_CUSTOM_COUNTERS
};

2. Define a custom counter array.

SSPSCommsCounterDef PVRScopeCustomCounterArray[eNUM_CUSTOM_COUNTERS];

3. Set the name of each counter.

std::string customCounterName[eNUM_CUSTOM_COUNTERS]="";
for(unsigned int i = 0; i < (unsigned int)eNUM_CUSTOM_COUNTERS; ++i)     {
    switch(i)         {
        case eARBITRARY_COUNTER:
            customCounterName[i] = "Arbitrary Counter";
            break;
        default:
            customCounterName[i] = "Unnamed counter";
            break;
    }
    PVRScopeCustomCounterArray[i].pszName = customCounterName[i].c_str();
    PVRScopeCustomCounterArray[i].nNameLength = customCounterName[i].length();
}

4. Define an array of integers to hold the values as they are updated for each frame.

unsigned int newValueArray[eNUM_CUSTOM_COUNTERS] = {0};

5. Submit the array of counters.

pplCountersCreate(PVRScopeComms, PVRScopeCustomCounterArray, eNUM_CUSTOM_COUNTERS);

Updating and Sending the Counter Value

After initialisation, it is now possible to update and send the counter value. To do so, perform the following:

1. Set a new value for any counter that needs updating. For example, updating eARBITRARY_COUNTER to increment by a value of 2:

int newCounterValue = 2;
newValueArray[eARBITRARY_COUNTER] += newCounterValue;

2. Send the list of updated values to PVRTune.

pplCountersUpdate(PVRScopeComms, newValueArray);

Full Source Code

/*********************************************************************************************
*
* This example code consists of six steps:
*
* 1. Setup PVRScopeComms
* 2. Create a Custom Counter
* 3. Submit the Custom Counter to PVRTune
* 4. Send an initial value for that counter to PVRTune
* 5. Update the counter once and send the updated counter to PVRTune
* 6. Shutdown PVRScopeComms
*
*********************************************************************************************/

#include "PVRScopeComms.h"

// Setup an enum of custom counters to make life easier later
enum PVRScopeCustomCounters
{
    eARBITRARY_COUNTER,
    eNUM_CUSTOM_COUNTERS
};

// Step 1. Setup PVRScopeComms
SSPSCommsData* PVRScopeComms;
std::string timelineTitle = "Example";
PVRScopeComms = pplInitialise(timelineTitle,
                              (unsigned int)timelineTitle.length());

// Step 2. Create a Custom Counter
std::string customCounterName = "";
SSPSCommsCounterDef PVRScopeCustomCounterArray[eNUM_CUSTOM_COUNTERS];
for(unsigned int i = 0; i < (unsigned int)eNUM_CUSTOM_COUNTERS; ++i)
{
    switch (i)
    {
    case eARBITRARY_COUNTER:
        customCounterName = "Arbitrary Counter";
        break;
    default:
        customCounterName = "Unnamed counter";
        break;
    }
    PVRScopeCustomCounterArray[eARBITRARY_COUNTER].pszName = customCounterName.c_str();
    PVRScopeCustomCounterArray[eARBITRARY_COUNTER].nNameLength = customCounterName.length();
}

// Step 3. Submit the Custom Counter to PVRTune
if(!pplCountersCreate(PVRScopeComms, PVRScopeCustomCounterArray, eNUM_CUSTOM_COUNTERS))
{
    // Error handling goes here
}

// Step 4. Send an initial value for that counter to PVRTune
int newCounterValue = 0;
unsigned int newValueArray[eNUM_CUSTOM_COUNTERS];
for(unsigned int i = 0; i < (unsigned int)eNUM_CUSTOM_COUNTERS; ++i)
{
    newValueArray[eARBITRARY_COUNTER] = newCounterValue;
}
// Submit counters for transmission
pplCountersUpdate(PVRScopeComms, newValueArray);

// Step 5. Update the counter once and send the updated counter to PVRTune
newCounterValue = 100;
for(unsigned int i = 0; i < (unsigned int)eNUM_CUSTOM_COUNTERS; ++i)
{
    newValueArray[eARBITRARY_COUNTER] = newCounterValue;
}
// Submit counters for transmission
pplCountersUpdate(PVRScopeComms, newValueArray);

// Step 6. Shutdown PVRScopeComms
pplShutdown(PVRScopeComms);