iProgressCallBack

previous: iSolidObjects::numberOfConvexSolids()

next: iProgressCallBack::updateProgress()

Contents, API Reference, Interfaces, iProgressCallBack

Interface iProgressCallBack

Description

An interface class which can be used to obtain progress updates and display a progress bar during potentially time consuming operations.

This interface is defined in SDKRoot/code/externalAPI/i_pathengine.h.

Methods:

updateProgress

This method is called by PathEngine to report progress.

Handling frequent updates

In some situations, a straightforward implementation of a progress bar might be to trigger a render update each time a progress update is received.

Be careful with this kind of straightforward implementation.
In general, processes calling back to progress callbacks assume that it is ok to make very frequent progress reports.
So triggering a render update for each report can potentially add significant overhead the process being watched.

The progress bar used by the testbed solves this problem by checking the time elapsed since the last render update, as follows:

class cTestBedProgressCallBack : public iProgressCallBack
{
    cTimerValue _lastUpdate;
    const char* _lastDescription;

    bool enoughTimePassed() const
    {
        cTimerValue expired;
        expired.read();
        expired -= _lastUpdate;
        return expired.asSeconds() > 0.2;
    }

public:

    cTestBedProgressCallBack()
    {
        _lastUpdate.read();
        _lastDescription = 0;
    }
    void updateProgress(const char* description, float percent)
    {
        if(description != _lastDescription || enoughTimePassed())
        {
            DrawProgressBar(nSingletons::testBed().getGIP(), description, percent, 10);
            nSingletons::testBed().update();
            _lastUpdate.read();
            _lastDescription = description;
        }
    }
};

Using progress call-backs to examine performance or memory issues

The following is an example of how a progress call-back might be set up to report on how memory allocation progresses during a process.

#include <string>
#include <sstream>
#include <windows.h>
#include "i_pathengine.h"

class cMemoryInstrumentedProgressCallBack : public iProgressCallBack
{
    iPathEngine* _pathEngine;
    std::string _lastOperationDescription;
    float _lastPercent;
public:
    cMemoryInstrumentedProgressCallBack(iPathEngine* pathEngine)
    {
        _pathEngine = pathEngine;
        _lastPercent = 0.f;
    }
    void updateProgress(const char* operationDescription, float percent)
    {
        if(operationDescription == _lastOperationDescription && percent < _lastPercent + 0.1f)
        {
            return;
        }
        std::ostringstream oss;
        oss << operationDescription;
        oss << ": percent=" << percent << " total=" << _pathEngine->totalMemoryAllocated() << ", max=" << _pathEngine->maximumMemoryAllocated();
        oss << "\n";
        OutputDebugString(oss.str().c_str());
        _lastOperationDescription = operationDescription;
        _lastPercent = percent;
    }
};

(A similar technique can be used, with suitable timer calls and output, to track time taken.)

next: iProgressCallBack::updateProgress()