Changeset 7331 for code/branches/doc/src

Timestamp:

Sep 3, 2010, 1:06:52 AM (14 years ago)

Author:

rgrieder

Message:

Added documentation for util/Clock.

Location:

code/branches/doc/src/libraries/util

Files:

• Clock.cc (modified) (1 diff)
• Clock.h (modified) (1 diff)

code/branches/doc/src/libraries/util/Clock.cc

@@ -50 +50 @@
         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.

code/branches/doc/src/libraries/util/Clock.h

@@ -35 +35 @@
 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)
     };
 }