OGRE  1.9.0
OgreProfiler.h
Go to the documentation of this file.
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4 (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2014 Torus Knot Software Ltd
8
9Permission is hereby granted, free of charge, to any person obtaining a copy
10of this software and associated documentation files (the "Software"), to deal
11in the Software without restriction, including without limitation the rights
12to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13copies of the Software, and to permit persons to whom the Software is
14furnished to do so, subject to the following conditions:
15
16The above copyright notice and this permission notice shall be included in
17all copies or substantial portions of the Software.
18
19THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25THE SOFTWARE.
26-----------------------------------------------------------------------------
27*/
28/*
29
30 Although the code is original, many of the ideas for the profiler were borrowed from
31"Real-Time In-Game Profiling" by Steve Rabin which can be found in Game Programming
32Gems 1.
33
34 This code can easily be adapted to your own non-Ogre project. The only code that is
35Ogre-dependent is in the visualization/logging routines and the use of the Timer class.
36
37 Enjoy!
38
39*/
40
41#ifndef __Profiler_H__
42#define __Profiler_H__
43
44#include "OgrePrerequisites.h"
45#include "OgreSingleton.h"
46#include "OgreString.h"
47#include "OgreHeaderPrefix.h"
48
49#if OGRE_PROFILING == 1
50# define OgreProfile( a ) Ogre::Profile _OgreProfileInstance( (a) )
51# define OgreProfileBegin( a ) Ogre::Profiler::getSingleton().beginProfile( (a) )
52# define OgreProfileEnd( a ) Ogre::Profiler::getSingleton().endProfile( (a) )
53# define OgreProfileGroup( a, g ) Ogre::Profile _OgreProfileInstance( (a), (g) )
54# define OgreProfileBeginGroup( a, g ) Ogre::Profiler::getSingleton().beginProfile( (a), (g) )
55# define OgreProfileEndGroup( a, g ) Ogre::Profiler::getSingleton().endProfile( (a), (g) )
56# define OgreProfileBeginGPUEvent( g ) Ogre::Profiler::getSingleton().beginGPUEvent(g)
57# define OgreProfileEndGPUEvent( g ) Ogre::Profiler::getSingleton().endGPUEvent(g)
58# define OgreProfileMarkGPUEvent( e ) Ogre::Profiler::getSingleton().markGPUEvent(e)
59#else
60# define OgreProfile( a )
61# define OgreProfileBegin( a )
62# define OgreProfileEnd( a )
63# define OgreProfileGroup( a, g )
64# define OgreProfileBeginGroup( a, g )
65# define OgreProfileEndGroup( a, g )
66# define OgreProfileBeginGPUEvent( e )
67# define OgreProfileEndGPUEvent( e )
68# define OgreProfileMarkGPUEvent( e )
69#endif
70
71namespace Ogre {
81 {
85 OGREPROF_ALL = 0xFF000000,
87 OGREPROF_GENERAL = 0x80000000,
89 OGREPROF_CULLING = 0x40000000,
91 OGREPROF_RENDERING = 0x20000000
92 };
93
105 public ProfilerAlloc
106 {
107
108 public:
109 Profile(const String& profileName, uint32 groupID = (uint32)OGREPROF_USER_DEFAULT);
111
112 protected:
113
118
119 };
120
125 {
126
129
132
135
136 };
137
140 {
145
150
155
158
163
167
170
171 };
172
175 {
176 friend class Profiler;
177 public:
179 virtual ~ProfileInstance(void);
180
182
184 void reset();
185
188 inline bool watchForLimit(Real limit, bool greaterThan = true)
189 {
190 if (greaterThan)
191 return history.currentTimePercent > limit;
192 else
193 return history.currentTimePercent < limit;
194 }
195
196 bool watchForMax(const String& profileName);
197 bool watchForMin(const String& profileName);
198 bool watchForLimit(const String& profileName, Real limit, bool greaterThan = true);
199
202
205
207
210
212
215
219
222 };
223
230 {
231 public:
233 {
237 DISPLAY_MILLISECONDS
238 };
239
240 ProfileSessionListener() : mDisplayMode(DISPLAY_MILLISECONDS) {}
242
244 virtual void initializeSession() = 0;
245
247 virtual void finializeSession() = 0;
248
253 virtual void changeEnableState(bool enabled) {};
254
256 virtual void displayResults(const ProfileInstance& instance, ulong maxTotalFrameTime) {};
257
259 void setDisplayMode(DisplayMode d) { mDisplayMode = d; }
260
262 DisplayMode getDisplayMode() const { return mDisplayMode; }
263
264 protected:
267 };
268
281 public Singleton<Profiler>,
282 public ProfilerAlloc
283 {
284 public:
287
289 void setTimer(Timer* t);
290
293
307 void beginProfile(const String& profileName, uint32 groupID = (uint32)OGREPROF_USER_DEFAULT);
308
323 void endProfile(const String& profileName, uint32 groupID = (uint32)OGREPROF_USER_DEFAULT);
324
328 void beginGPUEvent(const String& event);
329
333 void endGPUEvent(const String& event);
334
338 void markGPUEvent(const String& event);
339
345 void setEnabled(bool enabled);
346
348 bool getEnabled() const;
349
353 void enableProfile(const String& profileName);
354
358 void disableProfile(const String& profileName);
359
362 void setProfileGroupMask(uint32 mask) { mProfileMask = mask; }
365 uint32 getProfileGroupMask() const { return mProfileMask; }
366
372 bool watchForMax(const String& profileName);
373
379 bool watchForMin(const String& profileName);
380
390 bool watchForLimit(const String& profileName, Real limit, bool greaterThan = true);
391
394
396 void reset();
397
400
403
411
419
435 static Profiler& getSingleton(void);
452
453 protected:
454 friend class ProfileInstance;
455
458
461
463
467 void processFrameStats(ProfileInstance* instance, Real& maxFrameTime);
468
471
472 // lol. Uses typedef; put's original container type in name.
475
479
482
485
489
492
495
498
501
505
508
511
515
516
517 }; // end class
521} // end namespace
522
523#include "OgreHeaderSuffix.h"
524
525#endif
#define _OgreExport
Superclass for all objects that wish to use custom memory allocators when their new / delete operator...
Represents an individual profile call.
bool watchForMax(const String &profileName)
Ogre::map< String, ProfileInstance * >::type ProfileChildren
ProfileChildren children
bool watchForLimit(const String &profileName, Real limit, bool greaterThan=true)
ProfileHistory history
uint hierarchicalLvl
The hierarchical level of this profile, 0 being the root profile.
String name
The name of the profile.
bool watchForMin(const String &profileName)
ProfileInstance * parent
The name of the parent, null if root.
ulong currTime
The time this profile was started.
ulong accum
Represents the total time of all child profiles to subtract from this profile.
virtual ~ProfileInstance(void)
bool watchForLimit(Real limit, bool greaterThan=true)
ProfileSessionListener should be used to visualize profile results.
void setDisplayMode(DisplayMode d)
Set the display mode for the overlay.
virtual void displayResults(const ProfileInstance &instance, ulong maxTotalFrameTime)
Here we get the real profiling information which we can use.
virtual void initializeSession()=0
Create the internal resources.
virtual void finializeSession()=0
All internal resources should be deleted here.
@ DISPLAY_PERCENTAGE
Display % frame usage on the overlay.
DisplayMode mDisplayMode
How to display the overlay.
virtual void changeEnableState(bool enabled)
If the profiler disables this listener then it should hide its panels (if any exists) or stop sending...
DisplayMode getDisplayMode() const
Get the display mode for the overlay.
An individual profile that will be processed by the Profiler.
String mName
The name of this profile.
uint32 mGroupID
The group ID.
Profile(const String &profileName, uint32 groupID=(uint32) OGREPROF_USER_DEFAULT)
The profiler allows you to measure the performance of your code.
void addListener(ProfileSessionListener *listener)
ulong mTotalFrameTime
The total time each frame takes.
bool mEnabled
Whether this profiler is enabled.
void disableProfile(const String &profileName)
Disables a profile.
static Profiler * getSingletonPtr(void)
Override standard Singleton retrieval.
bool mNewEnableState
Keeps track of the new enabled/disabled state that the user has requested which will be applied after...
void markGPUEvent(const String &event)
Mark a specific, ungrouped, GPU event.
ProfileInstance::ProfileChildren ProfileChildren
void processFrameStats(void)
Processes frame stats for all of the mRoot's children.
void changeEnableState()
Handles a change of the profiler's enabled state.
set< String >::type DisabledProfileMap
uint mCurrentFrame
The number of elapsed frame, used with mUpdateDisplayFrequency.
Timer * mTimer
The timer used for profiling.
DisabledProfileMap mDisabledProfiles
Holds the names of disabled profiles.
Real mAverageFrameTime
Rolling average of millisecs.
bool getEnabled() const
Gets whether this profiler is enabled.
void logResults()
Outputs current profile statistics to the log.
void initialize()
Initializes the profiler's GUI elements.
void enableProfile(const String &profileName)
Enables a previously disabled profile.
void setTimer(Timer *t)
Sets the timer for the profiler.
void beginGPUEvent(const String &event)
Mark the beginning of a GPU event group.
TProfileSessionListener mListeners
uint mUpdateDisplayFrequency
The number of frames that must elapse before the current frame display is updated.
Timer * getTimer()
Retrieves the timer for the profiler.
uint32 mProfileMask
Mask to decide whether a type of profile is enabled or not.
void removeListener(ProfileSessionListener *listener)
void displayResults()
static Profiler & getSingleton(void)
Override standard Singleton retrieval.
bool mInitialized
Whether the GUI elements have been initialized.
void processFrameStats(ProfileInstance *instance, Real &maxFrameTime)
Processes specific ProfileInstance and it's children recursively.
uint32 getProfileGroupMask() const
Get the mask which all profiles must pass to be enabled.
void setEnabled(bool enabled)
Sets whether this profiler is enabled.
void beginProfile(const String &profileName, uint32 groupID=(uint32) OGREPROF_USER_DEFAULT)
Begins a profile.
ulong mMaxTotalFrameTime
The max frame time recorded.
void endProfile(const String &profileName, uint32 groupID=(uint32) OGREPROF_USER_DEFAULT)
Ends a profile.
ProfileInstance * mCurrent
ProfileInstance mRoot
void setUpdateDisplayFrequency(uint freq)
Sets the Profiler so the display of results are updated every n frames.
void endGPUEvent(const String &event)
Mark the end of a GPU event group.
void setProfileGroupMask(uint32 mask)
Set the mask which all profiles must pass to be enabled.
bool watchForMin(const String &profileName)
Returns true if the specified profile reaches a new frame time minimum.
void reset()
Clears the profiler statistics.
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.
vector< ProfileSessionListener * >::type TProfileSessionListener
uint getUpdateDisplayFrequency() const
Gets the frequency that the Profiler display is updated.
bool watchForMax(const String &profileName)
Returns true if the specified profile reaches a new frame time maximum.
ProfileInstance * mLast
Template class for creating single-instance global classes.
ProfileGroupMask
List of reserved profiling masks.
@ OGREPROF_CULLING
Culling.
@ OGREPROF_RENDERING
Rendering.
@ OGREPROF_USER_DEFAULT
User default profile.
@ OGREPROF_GENERAL
General processing.
@ OGREPROF_ALL
All in-built Ogre profiling will match this mask.
unsigned long ulong
float Real
Software floating point type.
unsigned int uint
unsigned int uint32
_StringBase String
Represents the total timing information of a profile since profiles can be called more than once each...
uint calls
The number of times this profile was called this frame.
ulong frameTime
The total time this profile has taken this frame.
uint hierarchicalLvl
The hierarchical level of this profile, 0 being the main loop.
Represents a history of each profile during the duration of the app.
uint numCallsThisFrame
The number of times this profile has been called each frame.
Real currentTimePercent
The current percentage of frame time this profile has taken.
Real maxTimeMillisecs
The maximum frame time this profile has taken in milliseconds.
Real minTimeMillisecs
The minimum frame time this profile has taken in milliseconds.
ulong totalCalls
The total number of times this profile was called (used to calculate average)
Real totalTimePercent
The total percentage of frame time this profile has taken.
Real maxTimePercent
The maximum percentage of frame time this profile has taken.
Real minTimePercent
The minimum percentage of frame time this profile has taken.
uint hierarchicalLvl
The hierarchical level of this profile, 0 being the root profile.
Real currentTimeMillisecs
The current frame time this profile has taken in milliseconds.
Real totalTimeMillisecs
The total frame time this profile has taken in milliseconds.
std::map< K, V, P, A > type
std::set< T, P, A > type
std::vector< T, A > type