User Guide (Version 1.17)

Creating Data Groups

When adding a new data group to Statoscope, do not choose a letter that's already in use.

Statoscope doesn't need updating when new data groups are added. You simply create an implementation of IStatoscopeDataGroup and register it with CStatoscope::RegisterDataGroup(). Here's an example of the simplest data group:

struct SFrameLengthDG : public IStatoscopeDataGroup { virtual SDescription GetDescription() const { return SDescription('f', "frame lengths", "['/' (float frameLengthInMS)]"); } virtual void Write(IStatoscopeFrameRecord& fr) { fr.AddValue(gEnv->pTimer->GetRealFrameTime() * 1000.0f); } }; ... RegisterDataGroup(new SFrameLengthDG()); ...

When this data group is enabled by adding f to e_StatoscopeDataGroups, frame lengths will appear in the e_StatoscopeDataGroups help string and for every frame it will output a single float value that appears as /frameLengthInMS in the Overview tree view.

Below is an example frame profilers data group, which shows how to record bar data:

struct SFrameProfilersDG : public IStatoscopeDataGroup { virtual SDescription GetDescription() const { return SDescription('r', "frame profilers", "['/Threads/$' (int count) (float selfTimeInMS)]"); } virtual void Enable() { IStatoscopeDataGroup::Enable(); ICVar *pCV_profile = gEnv->pConsole->GetCVar("profile"); if (pCV_profile) pCV_profile->Set(-1); } virtual void Disable() { IStatoscopeDataGroup::Disable(); ICVar *pCV_profile = gEnv->pConsole->GetCVar("profile"); if (pCV_profile) pCV_profile->Set(0); } virtual void Write(IStatoscopeFrameRecord &fr) { for (uint32 i=0; i<m_frameProfilerRecords.size(); i++) { SPerfStatFrameProfilerRecord &fpr = m_frameProfilerRecords[i]; string fpPath = GetFrameProfilerPath(fpr.m_pProfiler); fr.AddValue(fpPath.c_str()); fr.AddValue(fpr.m_count); fr.AddValue(fpr.m_selfTime); } m_frameProfilerRecords.clear(); } virtual uint32 PrepareToWrite() { return m_frameProfilerRecords.size(); } std::vector<SPerfStatFrameProfilerRecord> m_frameProfilerRecords; // the most recent frame's profiler data - filled out externally };

With bar data as shown, the same format is output many times per frame, in this case count and selfTimeInMS for each named profiler. The number of items needs to be returned by PrepareToWrite(). To specify the name of each item, place a $ in the appropriate location in the format string of GetDescription() and the first value output will be used to replace it. For this example, if fpPath is Main/Action/CFlowSystem::Update(), the values output will be attributed to /Threads/Main/Action/CFlowSystem::Update() and hierarchied accordingly

Values can either be float or integer, but are stored as floats.