irrTRACE (graphic debug tool)

[xterminhate]

IrrTrace is a tool for debuging a program based on Irrlicht. IrrTrace has two components : a trace manager and a trace gui. The trace manager can register or unregister (member) data and (member) functions. Once registered, data values and function return values are displayed on the viewport by the trace gui.

Screenshot (See next post / mod of example #11) :



Main features :
* show/hide control key ("d"),
* register/unregister data and function,
* trace a value for a number of frames,
* support of types : bool, u32, s32, f32, vector3df, SColor, string...
* trace the program pointer (kind of simplistic program profiling)


Download irrTRACE example :

>>> Here!


Note :

Trace manager is a singleton and massively uses templates programming. Trace gui requires CGUIStaticText.h/cpp in your project.


Howto :

1) Getting an instance of the Trace Manager :

Code: Select all

CTraceManager * traceMgr = CTraceManager::getInstance();

2) Register a data into the Trace Manager :
'var' is a variable (u32, s32, f32, string, vector3df, SColor...). 'traceId' is an identifier to the traced data.

Code: Select all

u32 var;
[...]
// Start tracing 'var'
std::size_t traceId = traceMgr->traceStaticData( &var, "tracename", "traceunit" );
[...]
// Stop tracing 'var'
traceMgr->erase( traceId );

3) Register a pointed data into the Trace Manager :
'pvar' is a pointer to a variable (*u32, *s32, *f32, *string, *vector3df, *SColor...).

Code: Select all

u32 * pvar;
[...]
// Start tracing 'pvar'
std::size_t traceId = traceMgr->traceStaticData( pvar, "tracename", "traceunit" );
[...]
// Stop tracing 'pvar'
traceMgr->erase( traceId );

4) Register a function (returned value) into the Trace Manager :
'func' is a function that return a 'type' (*u32, *s32, *f32, *string, *vector3df, *SColor...).

Code: Select all

u32 * func();
[...]
// Start tracing 'func'
std::size_t traceId = traceMgr->traceStaticData<u32>( &func, "tracename", "traceunit" );
[...]
// Stop tracing 'func'
traceMgr->erase( traceId );

5) Register a member data into the Trace Manager :
'mvar' is a public member data (*u32, *s32, *f32, *string, *vector3df, *SColor...).

Code: Select all

struct object
{
u32 * mvar;
};
[...]
object o1;
[...]
// Start tracing 'object::mvar'
std::size_t traceId = traceMgr->traceMemberData<object,u32>( &o1, &object::mvar, "tracename", "traceunit" );
[...]
// Stop tracing 'object::mvar'
traceMgr->erase( traceId );

6) Register a member function (returned value) into the Trace Manager :
'mfunc' is a public member function that returns a type (*u32, *s32, *f32, *string, *vector3df, *SColor...).

a) without constness:

Code: Select all

struct object
{
u32 * mfunc();
};
[...]
object o1;
[...]
// Start tracing 'object::mfunc'
std::size_t traceId = traceMgr->traceMemberFunction<object,u32>( &o1, &object::mfunc, "tracename", "traceunit" );
[...]
// Stop tracing 'object::mfunc'
traceMgr->erase( traceId );

b) with constness:

Code: Select all

struct object
{
u32 * mfunc() const;
};
[...]
object o1;
[...]
// Start tracing 'object::mfunc'
std::size_t traceId = traceMgr->traceMemberFunctionConst<object,u32>( &o1, &object::mfunc, "tracename", "traceunit" );
[...]
// Stop tracing 'object::mfunc'
traceMgr->erase( traceId );

7) Display a value for a while:
'var' is a variable (u32, s32, f32, string, vector3df, SColor...). The value will be displayed into the gui manager for N frames. The displayed value do not change even though the content of 'var' is altered.

Code: Select all

u32 var;
[...]
// Display the value of 'var' for 500 frames
traceMgr->traceInstantValue( var, "tracename", "traceunit", 500 );

8) Simplistic profiling:
Trace manager allows tracing the program pointer. A tag will be displayed into the trace gui for N frames.

Code: Select all

[...]
// Trace the program pointer here. Display 'tag' for 500 frames
traceMgr->markProgram( "tag", __FILE__, __LINE__, 500 );
[...]

9) Clean trace manager :
All trace are erased.

Code: Select all

traceMgr->clean();

I will provide source, documentation and support in this thread.

[xterminhate]

Development is in progress. Watches are placed in the top left corner of the viewport :



Using irrTace in the code:

CGUITrace * guiTrace = new CGUITrace( env );
CTraceManager * traceMgr = CTraceManager::getInstance();
traceMgr->traceMemberFunction<IVideoDriver,s32>(driver,&IVideoDriver::getFPS,"Frame rate"," frames per second" );
traceMgr->traceMemberFunction<IVideoDriver,u32>(driver,&IVideoDriver::getPrimitiveCountDrawn,"Primitive count draw","primitives");
traceMgr->traceMemberFunction<IVideoDriver,s32>(driver,&IVideoDriver::getMaterialRendererCount,"Material render count","materials");
traceMgr->traceMemberFunctionConst<ISceneNode,core::vector3df const>(smgr->getActiveCamera(),&ISceneNode::getPosition,"Camera position","unit");
traceMgr->traceMemberFunctionConst<ISceneNode,core::vector3df const>(smgr->getActiveCamera(),&ISceneNode::getRotation, "Camera rotation","degree");
traceMgr->traceMemberFunctionConst<ISceneNode,core::vector3df const>(sphere,&ISceneNode::getPosition,"Sphere position","unit");
traceMgr->traceMemberFunctionConst<ISceneNode,vector3df const>(sphere,&ISceneNode::getRotation,"Sphere rotation","degree");
traceMgr->traceMemberFunctionConst<ISceneNode,vector3df const>(light1, &ISceneNode::getPosition,"Light#1 position","unit");
traceMgr->traceMemberFunctionConst<ISceneNode,vector3df const>(light1, &ISceneNode::getRotation,"Light#1 rotation","degree");
traceMgr->traceMemberFunctionConst<ISceneNode,vector3df const>(light2, &ISceneNode::getPosition,"Light#2 position","unit");
traceMgr->traceMemberFunctionConst<ISceneNode,vector3df const>(light2, &ISceneNode::getRotation,"Light#2 rotation","degree");
traceMgr->traceStaticData(&lastFPS,"FPS","frames per second");

[Midnight]

this is an interesting idea and concept.

very useful in programming... but tools like Guice already do this for you and your tool/gui element serves only to connect parts of the engine that are seperate for a reason.

I say make it.. but don't be offended if you never see this in Guice or if Guice makes it a big waste of your time.

but still I'm with you 90% on this. and I'll most likly use it as visual debug stats within Guice.

[xterminhate]

I agree, such a tool must exist. Well, IrrTrace is intended to ease debugging user apps which are based on irrlicht engine. But, I'm afraid I do not understand the connection between irrTrace and GUICE tool.

Anyway, thanks for your encouragement

[xterminhate]

Added : a screenshot, a clearer explanation, the use-cases with code, a download link.

Let me know if irrTrace helps you to debug your apps (which may be build in release).

Xterm-In'Hate.

[ortsa]

Anyone got a link for this?
It looks quite interesting.