[Orxonox-commit 2626] r7331 - code/branches/doc/src/libraries/util

[rgrieder at orxonox.net]

Author: rgrieder
Date: 2010-09-03 01:06:52 +0200 (Fri, 03 Sep 2010)
New Revision: 7331

Modified:
   code/branches/doc/src/libraries/util/Clock.cc
   code/branches/doc/src/libraries/util/Clock.h
Log:
Added documentation for util/Clock.

Modified: code/branches/doc/src/libraries/util/Clock.cc
===================================================================
--- code/branches/doc/src/libraries/util/Clock.cc	2010-09-02 22:28:21 UTC (rev 7330)
+++ code/branches/doc/src/libraries/util/Clock.cc	2010-09-02 23:06:52 UTC (rev 7331)
@@ -49,7 +49,7 @@
         Mind the types! Ogre::Timer::getMicroseconds() will return an unsigned
         long, which will eventually overflow. But if you use the subtraction of
         the current time minus the last time the timer gave us and sum these up to
-        a 64 bit integer, we get the desired result.
+        a 64 bit integer, we get the desired result. <br>
         Also mind that we don't have to store the last timer's time as unsigned long
         as well because (unsigned long)tickTime_ will do exactly that.
     */

Modified: code/branches/doc/src/libraries/util/Clock.h
===================================================================
--- code/branches/doc/src/libraries/util/Clock.h	2010-09-02 22:28:21 UTC (rev 7330)
+++ code/branches/doc/src/libraries/util/Clock.h	2010-09-02 23:06:52 UTC (rev 7331)
@@ -34,31 +34,66 @@
 
 namespace orxonox
 {
+    /** Simple real time clock based on Ogre::Timer
+    @details
+        The class can be used to both capture the current real time or to
+        incrementally capture the time and then distribute that time information
+        via Clock& references (for instance for the game tick). <br>
+        Precision: <br>
+        The maximum precision is given by the Ogre::Timer and that is somewhere
+        in the microsecond range for both Windows and UNIX. 
+    @remarks
+        For proper functionality this class MUST be used in the same thread! <br>
+        Further more it might be possible that the Ogre::Timer has a performance
+        caveat on Windows because it will only capture the time on the same
+        CPU core. Confining the main thread to one process could speed up the game.
+        See command line argument 'limitToCPU'.
+    */
     class _UtilExport Clock
     {
     public:
+        //! Starts the time at 0
         Clock();
         ~Clock();
 
+        //! Internally captures the time and stays at that particular time
         void capture();
 
-        unsigned long long getMicroseconds()   const { return tickTime_; }
-        unsigned long long getMilliseconds()   const { return tickTime_ / 1000; }
-        unsigned long      getSeconds()        const { return static_cast<long> (tickTime_ / 1000000); }
-        float              getSecondsPrecise() const { return static_cast<float>(tickTime_ / 1000000.0f); }
+        //! Returns the last captured absolute time in microseconds
+        unsigned long long getMicroseconds() const
+            { return tickTime_; }
+        //! Returns the last captured absolute time in milliseconds
+        unsigned long long getMilliseconds() const
+            { return tickTime_ / 1000; }
+        //! Returns the last captured absolute time in seconds
+        unsigned long getSeconds() const
+            { return static_cast<long> (tickTime_ / 1000000); }
+        //! Returns the last captured absolute time in seconds as float
+        float getSecondsPrecise() const
+            { return static_cast<float>(tickTime_ / 1000000.0f); }
 
-        float              getDeltaTime()      const { return tickDtFloat_; }
-        long               getDeltaTimeMicroseconds() const { return tickDt_; }
+        //! Returns the timespan in seconds between the last two calls to capture()
+        float getDeltaTime() const
+            { return tickDtFloat_; }
+        //! Returns the timespan in microseconds between the last two calls to capture()
+        long getDeltaTimeMicroseconds() const
+            { return tickDt_; }
 
+        /** Returns the current real time in microseconds
+        @note
+            This is especially useful to measure execution times because of the
+            high precision.
+        */
         unsigned long long getRealMicroseconds() const;
 
     private:
+        //! Undefined
         Clock(const Clock& instance);
 
-        Ogre::Timer*       timer_;
-        unsigned long long tickTime_;
-        long               tickDt_;
-        float              tickDtFloat_;
+        Ogre::Timer*       timer_;       //!< Ogre timer object
+        unsigned long long tickTime_;    //!< Currently captured time
+        long               tickDt_;      //!< Delta time in microseconds (cache value)
+        float              tickDtFloat_; //!< Delta time in seconds (cache value)
     };
 }