Ogre::Profiler Class Reference
[General]

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

#include <OgreProfiler.h>

Inheritance diagram for Ogre::Profiler:

Classes
struct	ProfileFrame
	Represents the total timing information of a profile since profiles can be called more than once each frame. More...
struct	ProfileHistory
	Represents a history of each profile during the duration of the app. More...
struct	ProfileInstance
	Represents an individual profile call. More...
Public Types
enum	DisplayMode { DISPLAY_PERCENTAGE, DISPLAY_MILLISECONDS }
Public Member Functions
	Profiler ()
	~Profiler ()
void	setTimer (Timer *t)
	Sets the timer for the profiler.
Timer *	getTimer ()
	Retrieves the timer for the profiler.
void	beginProfile (const String &profileName, uint32 groupID=(uint32) OGREPROF_USER_DEFAULT)
	Begins a profile.
void	endProfile (const String &profileName, uint32 groupID=(uint32) OGREPROF_USER_DEFAULT)
	Ends a profile.
void	setEnabled (bool enabled)
	Sets whether this profiler is enabled.
bool	getEnabled () const
	Gets whether this profiler is enabled.
void	enableProfile (const String &profileName)
	Enables a previously disabled profile.
void	disableProfile (const String &profileName)
	Disables a profile.
void	setProfileGroupMask (uint32 mask)
	Set the mask which all profiles must pass to be enabled.
uint32	getProfileGroupMask () const
	Get the mask which all profiles must pass to be enabled.
bool	watchForMax (const String &profileName)
	Returns true if the specified profile reaches a new frame time maximum.
bool	watchForMin (const String &profileName)
	Returns true if the specified profile reaches a new frame time minimum.
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.
void	logResults ()
	Outputs current profile statistics to the log.
void	reset ()
	Clears the profiler statistics.
void	setDisplayMode (DisplayMode d)
	Set the display mode for the overlay.
DisplayMode	getDisplayMode () const
	Get the display mode for the overlay.
void	setUpdateDisplayFrequency (uint freq)
	Sets the Profiler so the display of results are updated every n frames.
uint	getUpdateDisplayFrequency () const
	Gets the frequency that the Profiler display is updated.
void	setOverlayDimensions (Real width, Real height)
	Set the size of the profiler overlay, in pixels.
void	setOverlayPosition (Real left, Real top)
	Set the position of the profiler overlay, in pixels.
Real	getOverlayWidth () const
Real	getOverlayHeight () const
Real	getOverlayLeft () const
Real	getOverlayTop () const
void *	operator new (size_t sz, const char file, int line, const char func)
	operator new, with debug line info
void *	operator new (size_t sz)
void *	operator new (size_t sz, void *ptr)
	placement operator new
void *	operator new[] (size_t sz, const char file, int line, const char func)
	array operator new, with debug line info
void *	operator new[] (size_t sz)
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 *)
Static Public Member Functions
static Profiler &	getSingleton (void)
	Override standard Singleton retrieval.
static Profiler *	getSingletonPtr (void)
	Override standard Singleton retrieval.
Protected Types
typedef list< ProfileInstance > ::type	ProfileStack
typedef list< ProfileFrame >::type	ProfileFrameList
typedef list< ProfileHistory > ::type	ProfileHistoryList
typedef map< String, ProfileHistoryList::iterator > ::type	ProfileHistoryMap
typedef map< String, bool >::type	DisabledProfileMap
typedef list< OverlayElement * > ::type	ProfileBarList
Protected Member Functions
void	initialize ()
	Initializes the profiler's GUI elements.
void	displayResults ()
	Prints the profiling results of each frame.
void	processFrameStats ()
	Processes the profiler data after each frame.
void	changeEnableState ()
	Handles a change of the profiler's enabled state.
OverlayContainer *	createContainer ()
	An internal function to create the container which will hold our display elements.
OverlayElement *	createTextArea (const String &name, Real width, Real height, Real top, Real left, uint fontSize, const String &caption, bool show=true)
	An internal function to create a text area.
OverlayElement *	createPanel (const String &name, Real width, Real height, Real top, Real left, const String &materialName, bool show=true)
	An internal function to create a panel.
Protected Attributes
ProfileStack	mProfiles
	A stack for each individual profile per frame.
ProfileFrameList	mProfileFrame
	Accumulates the results of each profile per frame (since a profile can be called more than once a frame).
ProfileHistoryList	mProfileHistory
	Keeps track of the statistics of each profile.
ProfileHistoryMap	mProfileHistoryMap
	We use this for quick look-ups of profiles in the history list.
DisabledProfileMap	mDisabledProfiles
	Holds the names of disabled profiles.
ProfileBarList	mProfileBars
	Holds the display bars for each profile results.
bool	mInitialized
	Whether the GUI elements have been initialized.
uint	mMaxDisplayProfiles
	The max number of profiles we can display.
Overlay *	mOverlay
	The overlay which contains our profiler results display.
OverlayContainer *	mProfileGui
	The window that displays the profiler results.
Real	mBarHeight
	The height of each bar.
Real	mGuiHeight
	The height of the stats window.
Real	mGuiWidth
	The width of the stats window.
Real	mGuiLeft
	The horz position of the stats window.
Real	mGuiTop
	The vertical position of the stats window.
Real	mBarIndent
	The size of the indent for each profile display bar.
Real	mGuiBorderWidth
	The width of the border between the profile window and each bar.
Real	mBarLineWidth
	The width of the min, avg, and max lines in a profile display.
Real	mBarSpacing
	The distance between bars.
uint	mUpdateDisplayFrequency
	The number of frames that must elapse before the current frame display is updated.
uint	mCurrentFrame
	The number of elapsed frame, used with mUpdateDisplayFrequency.
Timer *	mTimer
	The timer used for profiling.
ulong	mTotalFrameTime
	The total time each frame takes.
bool	mEnabled
	Whether this profiler is enabled.
bool	mEnableStateChangePending
	Keeps track of whether this profiler has received a request to be enabled/disabled.
bool	mNewEnableState
	Keeps track of the new enabled/disabled state that the user has requested which will be applied after the frame ends.
uint32	mProfileMask
	Mask to decide whether a type of profile is enabled or not.
DisplayMode	mDisplayMode
	How to display the overlay.
ulong	mMaxTotalFrameTime
	The max frame time recorded.
Real	mAverageFrameTime
	Rolling average of millisecs.
bool	mResetExtents
Static Protected Attributes
static Profiler *	msSingleton

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 126 of file OgreProfiler.h.

Member Typedef Documentation

typedef map<String, bool>::type Ogre::Profiler::DisabledProfileMap [protected]

Definition at line 400 of file OgreProfiler.h.

typedef list<OverlayElement*>::type Ogre::Profiler::ProfileBarList [protected]

Definition at line 402 of file OgreProfiler.h.

typedef list<ProfileFrame>::type Ogre::Profiler::ProfileFrameList [protected]

Definition at line 397 of file OgreProfiler.h.

typedef list<ProfileHistory>::type Ogre::Profiler::ProfileHistoryList [protected]

Definition at line 398 of file OgreProfiler.h.

typedef map<String, ProfileHistoryList::iterator>::type Ogre::Profiler::ProfileHistoryMap [protected]

Definition at line 399 of file OgreProfiler.h.

typedef list<ProfileInstance>::type Ogre::Profiler::ProfileStack [protected]

Definition at line 396 of file OgreProfiler.h.

Member Enumeration Documentation

enum Ogre::Profiler::DisplayMode

Enumerator:

DISPLAY_PERCENTAGE	Display % frame usage on the overlay.
DISPLAY_MILLISECONDS	Display milliseconds on the overlay.

Definition at line 229 of file OgreProfiler.h.

Constructor & Destructor Documentation

Ogre::Profiler::Profiler ( )

Ogre::Profiler::~Profiler ( )

Member Function Documentation

void Ogre::Profiler::beginProfile	(	const String &	profileName,
		uint32	groupID = `(uint32) OGREPROF_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:

	profileName	Must be unique and must not be an empty string
	groupID	A profile group identifier, which can allow you to mask profiles

void Ogre::Profiler::changeEnableState ( ) [protected]

Handles a change of the profiler's enabled state.

OverlayContainer* Ogre::Profiler::createContainer ( ) [protected]

An internal function to create the container which will hold our display elements.

OverlayElement* Ogre::Profiler::createPanel	(	const String &	name,
		Real	width,
		Real	height,
		Real	top,
		Real	left,
		const String &	materialName,
		bool	show = `true`
	)			`[protected]`

An internal function to create a panel.

OverlayElement* Ogre::Profiler::createTextArea	(	const String &	name,
		Real	width,
		Real	height,
		Real	top,
		Real	left,
		uint	fontSize,
		const String &	caption,
		bool	show = `true`
	)			`[protected]`

An internal function to create a text area.

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

Disables a profile.

Remarks:: Only disables the profile if this function is not called during the profile it is trying to disable.

void Ogre::Profiler::displayResults ( ) [protected]

Prints the profiling results of each frame.

void Ogre::Profiler::enableProfile ( const String & profileName )

Enables a previously disabled profile.

Remarks:: Only enables the profile if this function is not called during the profile it is trying to enable.

void Ogre::Profiler::endProfile	(	const String &	profileName,
		uint32	groupID = `(uint32) OGREPROF_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:

	profileName	Must be unique and must not be an empty string
	groupID	A profile group identifier, which can allow you to mask profiles

DisplayMode Ogre::Profiler::getDisplayMode ( ) const

Get the display mode for the overlay.

Definition at line 242 of file OgreProfiler.h.

bool Ogre::Profiler::getEnabled ( ) const

Gets whether this profiler is enabled.

Real Ogre::Profiler::getOverlayHeight ( ) const

Real Ogre::Profiler::getOverlayLeft ( ) const

Real Ogre::Profiler::getOverlayTop ( ) const

Real Ogre::Profiler::getOverlayWidth ( ) const

uint32 Ogre::Profiler::getProfileGroupMask ( ) const

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

Definition at line 196 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.

Reimplemented from Ogre::Singleton< Profiler >.

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.

Reimplemented from Ogre::Singleton< Profiler >.

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.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)			`[inherited]`

Definition at line 107 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		void *
	)			`[inherited]`

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void * ptr ) [inherited]

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[]	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)			`[inherited]`

Definition at line 118 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] ( void * ptr ) [inherited]

Definition at line 112 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		void *	ptr
	)			`[inherited]`

placement operator new

Definition at line 78 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 72 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

operator new, with debug line info

Definition at line 67 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 90 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

array operator new, with debug line info

Definition at line 85 of file OgreMemoryAllocatedObject.h.

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

Processes the profiler data after each frame.

void Ogre::Profiler::reset ( )

Clears the profiler statistics.

void Ogre::Profiler::setDisplayMode ( DisplayMode d )

Set the display mode for the overlay.

Definition at line 239 of file OgreProfiler.h.

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::setOverlayDimensions	(	Real	width,
		Real	height
	)

Set the size of the profiler overlay, in pixels.

void Ogre::Profiler::setOverlayPosition	(	Real	left,
		Real	top
	)

Set the position of the profiler overlay, in pixels.

void Ogre::Profiler::setProfileGroupMask ( uint32 mask )

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

Definition at line 193 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:

	limit	A number between 0 and 1 representing the percentage of frame time
	greaterThan	If 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.