TimeSource.h

00001 /***************************************************************************
00002  *                                                                         *
00003  *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
00004  *       mailto: <tevs@mpi-sb.mpg.de>                                      *
00005  *                                                                         *
00006  *   This program is free software; you can redistribute it and/or modify  *
00007  *   it under the terms of the GNU General Public License as published by  *
00008  *   the Free Software Foundation; either version 2 of the License, or     *
00009  *   (at your option) any later version.                                   *
00010  *                                                                         *
00011  ***************************************************************************/
00012 
00013 
00014 #ifndef _NR_I_TIMESOURCE_H_
00015 #define _NR_I_TIMESOURCE_H_
00016 
00017 /*!
00018 * \defgroup time Clock and Timers
00019 *
00020 * This groups contains all classes and interfaces you will need by working with the time.
00021 * Time is relative like Einstein said. So this part of the engine allows you to use
00022 * this aspect in your applications.
00023 * To use this you have to derive a time source class and bind it to any clock. Then
00024 * the clock should ticks and will give you always right time. Now you create any timer
00025 * from the clock. The timer has its own speed relative to the clock. This allows you
00026 * to use one timer for GUI and one for your game. If you pause the game timer gui
00027 * is still working. Also some nice effects are possible by using more than one
00028 * timer in you rapplication.
00029 **/
00030 
00031 //----------------------------------------------------------------------------------
00032 // Includes
00033 //----------------------------------------------------------------------------------
00034 #include "Prerequisities.h"
00035 
00036 namespace nrEngine{
00037                 
00038         
00039         //! Interface for time source give clock a current time
00040         /**
00041         * \par
00042         * TimeSource is an interface for each time emitter. You have to bind any time source to
00043         * the clock to have possibility to know the current time. You can think on time source
00044         * as on tick mechanism in every clock.<br>
00045         * In our default imlementation of the time source, we use a high performance tick counter
00046         * provided by the cpu if such one exists. So you will be able to get more precise time
00047         * results as usual.
00048         *
00049         * \par
00050         * Each time source should be able to provide real system time (real does not mean absolute).
00051         * The provided time has to be computed through system clock or similar techniques
00052         * without using of high performance tick counters (e.g. rdtsc). We need this to be able
00053         * to sync nrEngine's Clock-System for the current CPU-Speed. Because today's CPU does
00054         * support frequency scaling, so we need somewhere to sync the time.
00055         *
00056         * \ingroup time
00057         **/
00058         class _NRExport TimeSource {
00059         public:
00060                 
00061                 /**
00062                 * Create an instance of the time source object.
00063                 **/
00064                 TimeSource();
00065 
00066                 /**
00067                 * Release used memory
00068                 **/
00069                 virtual ~TimeSource();
00070                 
00071                 /**
00072                 * Get the current time in seconds. Returned time is not the same as system time.
00073                 * @return current time in seconds
00074                 **/
00075                 virtual float64 getTime();
00076 
00077                 /**
00078                 * Get current system time as it is provided through system functions without
00079                 * using of high performance tick counter (like rdtsc).
00080                 **/
00081                 virtual float64 getSystemTime();
00082                 
00083                 /**
00084                 * Reset the time source, so it can start reading the time from the beginning.
00085                 * You do not have to call this method, clock will do it automaticaly, if
00086                 * it is needed.
00087                 * @param startValue This value will be added to the default start value, which is normally
00088                 *  0. So specifying the startValue parameter modifies the time to which the source should reset.
00089                 **/
00090                 virtual void reset(float64 startValue = 0.0);
00091 
00092                 /**
00093                 * Syncing the time source means we get the current time store it as sync time point
00094                 * caluclate the new start point do all calculations again.
00095                 * This syncing can help us to sync clock for example if the cpu speed changes.
00096                 * If no new calculation about the cpu speed is done and we use rdtsc to compute
00097                 * the current time, so we will get wrong time steps. Syncing should prevent this.<br>
00098                 * Clock-Engine will decide by itself when to sync, so time source shouldn't do it.
00099                 **/
00100                 virtual void sync();
00101 
00102                 /**
00103                 * Call this method to notify the time source, that new frame beginns.
00104                 * This method is usefull if we are using non-time based time sources.
00105                 * So the time source could read time from some file, which is based
00106                 * on frames.
00107                 **/
00108                 virtual void notifyNextFrame();
00109                 
00110         protected:
00111 
00112                 //! Store here time value given by gettimeofday - function
00113                 struct timeval _startTime;
00114 
00115                 //! Store the current time in seconds, since the source was resetted
00116                 float64 _currentTime;
00117 
00118                 //! Here we store the sncying time point. This will help us to sync the source
00119                 float64 _syncTime;
00120                 
00121                 //! This is the reset value. The value is used to store time of reset point 
00122                 float64 _resetTime;
00123         };
00124         
00125 }; // end namespace
00126 
00127 #endif

Generated on Wed Sep 12 23:19:42 2007 for nrEngine by  doxygen 1.5.1