OGRE  2.0
Object-Oriented Graphics Rendering Engine
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Ogre::Profiler Class Reference

The profiler allows you to measure the performance of your code. More...

#include <OgreProfiler.h>

+ Inheritance diagram for Ogre::Profiler:
+ Collaboration diagram for Ogre::Profiler:

Public Member Functions

 Profiler ()
 
 ~Profiler ()
 
void addListener (ProfileSessionListener *listener)
 
void beginGPUEvent (const String &event)
 Mark the beginning of a GPU event group. More...
 
void beginProfile (const String &profileName, uint32 groupID=(uint32) OGREPROF_USER_DEFAULT)
 Begins a profile. More...
 
void disableProfile (const String &profileName)
 Disables a profile. More...
 
void enableProfile (const String &profileName)
 Enables a previously disabled profile. More...
 
void endGPUEvent (const String &event)
 Mark the end of a GPU event group. More...
 
void endProfile (const String &profileName, uint32 groupID=(uint32) OGREPROF_USER_DEFAULT)
 Ends a profile. More...
 
bool getEnabled () const
 Gets whether this profiler is enabled. More...
 
uint32 getProfileGroupMask () const
 Get the mask which all profiles must pass to be enabled. More...
 
TimergetTimer ()
 Retrieves the timer for the profiler. More...
 
uint getUpdateDisplayFrequency () const
 Gets the frequency that the Profiler display is updated. More...
 
void logResults ()
 Outputs current profile statistics to the log. More...
 
void markGPUEvent (const String &event)
 Mark a specific, ungrouped, GPU event. More...
 
void operator delete (void *ptr)
 
void operator delete (void *ptr, void *)
 
void operator delete (void *ptr, const char *, int, const char *)
 
void operator delete[] (void *ptr)
 
void operator delete[] (void *ptr, const char *, int, const char *)
 
void * operator new (size_t sz, const char *file, int line, const char *func)
 operator new, with debug line info More...
 
void * operator new (size_t sz)
 
void * operator new (size_t sz, void *ptr)
 placement operator new More...
 
void * operator new[] (size_t sz, const char *file, int line, const char *func)
 array operator new, with debug line info More...
 
void * operator new[] (size_t sz)
 
void removeListener (ProfileSessionListener *listener)
 
void reset ()
 Clears the profiler statistics. More...
 
void setEnabled (bool enabled)
 Sets whether this profiler is enabled. More...
 
void setProfileGroupMask (uint32 mask)
 Set the mask which all profiles must pass to be enabled. More...
 
void setTimer (Timer *t)
 Sets the timer for the profiler. More...
 
void setUpdateDisplayFrequency (uint freq)
 Sets the Profiler so the display of results are updated every n frames. More...
 
bool watchForLimit (const String &profileName, Real limit, bool greaterThan=true)
 Returns true if the specified profile goes over or under the given limit frame time. More...
 
bool watchForMax (const String &profileName)
 Returns true if the specified profile reaches a new frame time maximum. More...
 
bool watchForMin (const String &profileName)
 Returns true if the specified profile reaches a new frame time minimum. More...
 

Static Public Member Functions

static ProfilergetSingleton (void)
 Override standard Singleton retrieval. More...
 
static ProfilergetSingletonPtr (void)
 Override standard Singleton retrieval. More...
 

Protected Types

typedef set< String >::type DisabledProfileMap
 
typedef
ProfileInstance::ProfileChildren 
ProfileChildren
 
typedef vector
< ProfileSessionListener * >
::type 
TProfileSessionListener
 

Protected Member Functions

void changeEnableState ()
 Handles a change of the profiler's enabled state. More...
 
void displayResults ()
 
void initialize ()
 Initializes the profiler's GUI elements. More...
 
void processFrameStats (void)
 Processes frame stats for all of the mRoot's children. More...
 
void processFrameStats (ProfileInstance *instance, Real &maxFrameTime)
 Processes specific ProfileInstance and it's children recursively. More...
 

Protected Attributes

Real mAverageFrameTime
 Rolling average of millisecs. More...
 
ProfileInstancemCurrent
 
uint mCurrentFrame
 The number of elapsed frame, used with mUpdateDisplayFrequency. More...
 
DisabledProfileMap mDisabledProfiles
 Holds the names of disabled profiles. More...
 
bool mEnabled
 Whether this profiler is enabled. More...
 
bool mInitialized
 Whether the GUI elements have been initialized. More...
 
ProfileInstancemLast
 
TProfileSessionListener mListeners
 
ulong mMaxTotalFrameTime
 The max frame time recorded. More...
 
bool mNewEnableState
 Keeps track of the new enabled/disabled state that the user has requested which will be applied after the frame ends. More...
 
uint32 mProfileMask
 Mask to decide whether a type of profile is enabled or not. More...
 
bool mResetExtents
 
ProfileInstance mRoot
 
TimermTimer
 The timer used for profiling. More...
 
ulong mTotalFrameTime
 The total time each frame takes. More...
 
uint mUpdateDisplayFrequency
 The number of frames that must elapse before the current frame display is updated. More...
 

Static Protected Attributes

static ProfilermsSingleton
 

Friends

class ProfileInstance
 

Detailed Description

The profiler allows you to measure the performance of your code.

Remarks
Do not create profiles directly from this unless you want a profile to last outside of its scope (i.e. the main game loop). For most cases, use the macro OgreProfile(name) and braces to limit the scope. You must enable the Profile before you can used it with setEnabled(true). If you want to disable profiling in Ogre, simply set the macro OGRE_PROFILING to 0.
Author
Amit Mathew (amitmathew (at) yahoo (dot) com)

Definition at line 279 of file OgreProfiler.h.

Member Typedef Documentation

typedef set<String>::type Ogre::Profiler::DisabledProfileMap
protected

Definition at line 472 of file OgreProfiler.h.

Definition at line 455 of file OgreProfiler.h.

Constructor & Destructor Documentation

Ogre::Profiler::Profiler ( )
Ogre::Profiler::~Profiler ( )

Member Function Documentation

void Ogre::Profiler::addListener ( ProfileSessionListener listener)
Remarks
Register a ProfileSessionListener from the Profiler
Parameters
listenerA valid listener derived class
void Ogre::Profiler::beginGPUEvent ( const String event)

Mark the beginning of a GPU event group.

Remarks
Can be safely called in the middle of the profile.
void Ogre::Profiler::beginProfile ( const String profileName,
uint32  groupID = (uint32OGREPROF_USER_DEFAULT 
)

Begins a profile.

Remarks
Use the macro OgreProfileBegin(name) instead of calling this directly so that profiling can be ignored in the release version of your app.
You only use the macro (or this) if you want a profile to last outside of its scope (i.e. the main game loop). If you use this function, make sure you use a corresponding OgreProfileEnd(name). Usually you would use the macro OgreProfile(name). This function will be ignored for a profile that has been disabled or if the profiler is disabled.
Parameters
profileNameMust be unique and must not be an empty string
groupIDA profile group identifier, which can allow you to mask profiles
void Ogre::Profiler::changeEnableState ( )
protected

Handles a change of the profiler's enabled state.

void Ogre::Profiler::disableProfile ( const String profileName)

Disables a profile.

Remarks
Can be safely called in the middle of the profile.
void Ogre::Profiler::displayResults ( )
protected
void Ogre::Profiler::enableProfile ( const String profileName)

Enables a previously disabled profile.

Remarks
Can be safely called in the middle of the profile.
void Ogre::Profiler::endGPUEvent ( const String event)

Mark the end of a GPU event group.

Remarks
Can be safely called in the middle of the profile.
void Ogre::Profiler::endProfile ( const String profileName,
uint32  groupID = (uint32OGREPROF_USER_DEFAULT 
)

Ends a profile.

Remarks
Use the macro OgreProfileEnd(name) instead of calling this directly so that profiling can be ignored in the release version of your app.
This function is usually not called directly unless you want a profile to last outside of its scope. In most cases, using the macro OgreProfile(name) which will call this function automatically when it goes out of scope. Make sure the name of this profile matches its corresponding beginProfile name. This function will be ignored for a profile that has been disabled or if the profiler is disabled.
Parameters
profileNameMust be unique and must not be an empty string
groupIDA profile group identifier, which can allow you to mask profiles
bool Ogre::Profiler::getEnabled ( ) const

Gets whether this profiler is enabled.

uint32 Ogre::Profiler::getProfileGroupMask ( ) const
inline

Get the mask which all profiles must pass to be enabled.

Definition at line 364 of file OgreProfiler.h.

static Profiler& Ogre::Profiler::getSingleton ( void  )
static

Override standard Singleton retrieval.

Remarks
Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.
This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.
static Profiler* Ogre::Profiler::getSingletonPtr ( void  )
static

Override standard Singleton retrieval.

Remarks
Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.
This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.
Timer* Ogre::Profiler::getTimer ( )

Retrieves the timer for the profiler.

uint Ogre::Profiler::getUpdateDisplayFrequency ( ) const

Gets the frequency that the Profiler display is updated.

void Ogre::Profiler::initialize ( )
protected

Initializes the profiler's GUI elements.

void Ogre::Profiler::logResults ( )

Outputs current profile statistics to the log.

void Ogre::Profiler::markGPUEvent ( const String event)

Mark a specific, ungrouped, GPU event.

Remarks
Can be safely called in the middle of the profile.
template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr)
inlineinherited

Definition at line 96 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
void *   
)
inlineinherited

Definition at line 102 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

Definition at line 108 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr)
inlineinherited

Definition at line 113 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

Definition at line 119 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

operator new, with debug line info

Definition at line 68 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz)
inlineinherited

Definition at line 73 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
void *  ptr 
)
inlineinherited

placement operator new

Definition at line 79 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

array operator new, with debug line info

Definition at line 86 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz)
inlineinherited

Definition at line 91 of file OgreMemoryAllocatedObject.h.

void Ogre::Profiler::processFrameStats ( void  )
protected

Processes frame stats for all of the mRoot's children.

void Ogre::Profiler::processFrameStats ( ProfileInstance instance,
Real maxFrameTime 
)
protected

Processes specific ProfileInstance and it's children recursively.

void Ogre::Profiler::removeListener ( ProfileSessionListener listener)
Remarks
Unregister a ProfileSessionListener from the Profiler
Parameters
listenerA valid listener derived class
void Ogre::Profiler::reset ( )

Clears the profiler statistics.

void Ogre::Profiler::setEnabled ( bool  enabled)

Sets whether this profiler is enabled.

Only takes effect after the the frame has ended.

Remarks
When this is called the first time with the parameter true, it initializes the GUI for the Profiler
void Ogre::Profiler::setProfileGroupMask ( uint32  mask)
inline

Set the mask which all profiles must pass to be enabled.

Definition at line 361 of file OgreProfiler.h.

void Ogre::Profiler::setTimer ( Timer t)

Sets the timer for the profiler.

void Ogre::Profiler::setUpdateDisplayFrequency ( uint  freq)

Sets the Profiler so the display of results are updated every n frames.

bool Ogre::Profiler::watchForLimit ( const String profileName,
Real  limit,
bool  greaterThan = true 
)

Returns true if the specified profile goes over or under the given limit frame time.

Remarks
If this is called during a frame, it will be reading the results from the previous frame. Therefore, it is best to use this after the frame has ended.
Parameters
limitA number between 0 and 1 representing the percentage of frame time
greaterThanIf true, this will return whether the limit is exceeded. Otherwise, it will return if the frame time has gone under this limit.
bool Ogre::Profiler::watchForMax ( const String profileName)

Returns true if the specified profile reaches a new frame time maximum.

Remarks
If this is called during a frame, it will be reading the results from the previous frame. Therefore, it is best to use this after the frame has ended.
bool Ogre::Profiler::watchForMin ( const String profileName)

Returns true if the specified profile reaches a new frame time minimum.

Remarks
If this is called during a frame, it will be reading the results from the previous frame. Therefore, it is best to use this after the frame has ended.

Friends And Related Function Documentation

friend class ProfileInstance
friend

Definition at line 453 of file OgreProfiler.h.

Member Data Documentation

Real Ogre::Profiler::mAverageFrameTime
protected

Rolling average of millisecs.

Definition at line 512 of file OgreProfiler.h.

ProfileInstance* Ogre::Profiler::mCurrent
protected

Definition at line 475 of file OgreProfiler.h.

uint Ogre::Profiler::mCurrentFrame
protected

The number of elapsed frame, used with mUpdateDisplayFrequency.

Definition at line 490 of file OgreProfiler.h.

DisabledProfileMap Ogre::Profiler::mDisabledProfiles
protected

Holds the names of disabled profiles.

Definition at line 480 of file OgreProfiler.h.

bool Ogre::Profiler::mEnabled
protected

Whether this profiler is enabled.

Definition at line 499 of file OgreProfiler.h.

bool Ogre::Profiler::mInitialized
protected

Whether the GUI elements have been initialized.

Definition at line 483 of file OgreProfiler.h.

ProfileInstance* Ogre::Profiler::mLast
protected

Definition at line 476 of file OgreProfiler.h.

TProfileSessionListener Ogre::Profiler::mListeners
protected

Definition at line 456 of file OgreProfiler.h.

ulong Ogre::Profiler::mMaxTotalFrameTime
protected

The max frame time recorded.

Definition at line 509 of file OgreProfiler.h.

bool Ogre::Profiler::mNewEnableState
protected

Keeps track of the new enabled/disabled state that the user has requested which will be applied after the frame ends.

Definition at line 503 of file OgreProfiler.h.

uint32 Ogre::Profiler::mProfileMask
protected

Mask to decide whether a type of profile is enabled or not.

Definition at line 506 of file OgreProfiler.h.

bool Ogre::Profiler::mResetExtents
protected

Definition at line 513 of file OgreProfiler.h.

ProfileInstance Ogre::Profiler::mRoot
protected

Definition at line 477 of file OgreProfiler.h.

Profiler * Ogre::Singleton< Profiler >::msSingleton
staticprotectedinherited

Definition at line 75 of file OgreSingleton.h.

Timer* Ogre::Profiler::mTimer
protected

The timer used for profiling.

Definition at line 493 of file OgreProfiler.h.

ulong Ogre::Profiler::mTotalFrameTime
protected

The total time each frame takes.

Definition at line 496 of file OgreProfiler.h.

uint Ogre::Profiler::mUpdateDisplayFrequency
protected

The number of frames that must elapse before the current frame display is updated.

Definition at line 487 of file OgreProfiler.h.


The documentation for this class was generated from the following file: