simgear/timing/sg_time.hxx

   1 /**
   2  * \file sg_time.hxx
   3  * Data structures and routines for managing time related values.
   4  */
   5
   6 // Written by Curtis Olson, started August 1997.
   7 //
   8 // Copyright (C) 1997  Curtis L. Olson  - http://www.flightgear.org/~curt
   9 //
  10 // This library is free software; you can redistribute it and/or
  11 // modify it under the terms of the GNU Library General Public
  12 // License as published by the Free Software Foundation; either
  13 // version 2 of the License, or (at your option) any later version.
  14 //
  15 // This library is distributed in the hope that it will be useful,
  16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18 // Library General Public License for more details.
  19 //
  20 // You should have received a copy of the GNU General Public License
  21 // along with this program; if not, write to the Free Software
  22 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  23 //
  24 // $Id$
  25
  26
  27 #ifndef _SG_TIME_HXX
  28 #define _SG_TIME_HXX
  29
  30
  31 #ifndef __cplusplus
  32 # error This library requires C++
  33 #endif
  34
  35
  36 #include <simgear/compiler.h>
  37
  38 #include <ctime>
  39 #include <memory> // for std::auto_ptr
  40 #include <string>
  41
  42 // forward decls
  43 class SGPath;
  44 class SGGeod;
  45
  46 /**
  47  * A class to calculate and manage a variety of time parameters.
  48  * The SGTime class provides many real-world time values. It
  49  * calculates current time in seconds, GMT time, local time zone,
  50  * local offset in seconds from GMT, Julian date, and sidereal
  51  * time. All of these operate with seconds as their granularity so
  52  * this class is not intended for timing sub-second events. These
  53  * values are intended as input to things like real world lighting
  54  * calculations and real astronomical object placement.
  55
  56  * To properly use the SGTime class there are a couple of things to be
  57  * aware of. After creating an instance of the class, you will need to
  58  * periodically (i.e. before every frame) call the update()
  59  * method. Optionally, if you care about updating time zone
  60  * information based on your latitude and longitude, you can call the
  61  * updateLocal() method periodically as your position changes by
  62  * significant amounts.
  63
  64  */
  65
  66 class SGTime {
  67
  68 private:
  69
  70     // Points to the current local timezone name;
  71     std::string zonename;
  72
  73     // Unix "calendar" time in seconds
  74     time_t cur_time;
  75
  76     // Break down of equivalent GMT time
  77     struct tm m_gmt;    // copy of system gmtime(&time_t) structure
  78
  79     // offset of local time relative to GMT
  80     time_t local_offset;
  81
  82     // Julian date
  83     double jd;
  84
  85     // modified Julian date
  86     double mjd;
  87
  88     // side real time at prime meridian
  89     double gst;
  90
  91     // local sidereal time
  92     double lst;
  93
  94     // the difference between the precise / expensive sidereal time
  95     // algorithm result and the quick course result.  course_gst +
  96     // gst_diff has pretty good accuracy over the span of a couple hours
  97     double gst_diff;
  98
  99     /** init common constructor code */
 100     void init( const SGGeod& location, const SGPath& root,
 101                time_t init_time );
 102
 103 public:
 104
 105     /** Default constructor */
 106     SGTime();
 107
 108     /**
 109      * Create an instance based on a specified position and data file path.
 110      * This creates an instance of the SGTime object. When calling the
 111      * constructor you need to provide a root path pointing to your
 112      * time zone definition tree. Optionally, you can call a form of
 113      * the constructor that accepts your current longitude and
 114      * latitude in radians.
 115      *
 116      * If you don't know your position when you call the SGTime
 117      * constructor, you can just use the first form (which assumes 0,
 118      * 0).
 119      * @param lon_rad current longitude (radians)
 120      * @param lat_rad current latitude (radians)
 121      * @param root root path point to data file location (timezone, etc.)
 122      * @param init_time provide an initialization time, 0 means use
 123               current clock time */
 124     SGTime( const SGGeod& location, const SGPath& root,
 125                time_t init_time );
 126
 127     /**
 128      * Create an instance given a data file path.
 129      * @param root root path point to data file location (timezone, etc.)
 130      */
 131     SGTime( const SGPath& root );
 132
 133     /** Destructor */
 134     ~SGTime();
 135
 136     /**
 137      * Update the time related variables.
 138      * The update() method requires you to pass in your position and
 139      * an optional time offset in seconds. The offset (or warp) allows
 140      * you to offset "sim" time relative to "real" time. The update()
 141      * method is designed to be called by the host application before
 142      * every frame.
 143      * @param lon_rad current longitude (radians)
 144      * @param lat_rad current latitude (radians)
 145      * @param ct specify a unix time, otherwise specify 0 to use current
 146               clock time
 147      * @param warp an optional time offset specified in seconds.  This
 148      *        allows us to advance or rewind "time" if we choose to.  */
 149     void update( const SGGeod& location, time_t ct, long int warp );
 150
 151     /**
 152      * Given lon/lat, update timezone information and local_offset
 153      * The updateLocal() method is intended to be called less
 154      * frequently - only when your position is likely to be changed
 155      * enough that your timezone may have changed as well. In the
 156      * FlightGear project we call updateLocal() every few minutes from
 157      * our periodic event manager.
 158      * @param lon_rad current longitude (radians)
 159      * @param lat_rad current latitude (radians)
 160      * @param root base path containing time zone directory */
 161     void updateLocal( const SGGeod& location, const std::string& root );
 162
 163     /** @return current system/unix time in seconds */
 164     inline time_t get_cur_time() const { return cur_time; };
 165
 166     /** @return time zone name for your current position*/
 167     inline const char * get_zonename() const { return zonename.c_str(); }
 168
 169     /** @return GMT in a "brokent down" tm structure */
 170     inline struct tm* getGmt()const { return (struct tm *)&m_gmt; };
 171
 172     /** @return julian date */
 173     inline double getJD() const { return jd; };
 174
 175     /** @return modified julian date */
 176     inline double getMjd() const { return mjd; };
 177
 178     /** @return local side real time */
 179     inline double getLst() const { return lst; };
 180
 181     /** @return grenich side real time (lst when longitude == 0) */
 182     inline double getGst() const { return gst; };
 183
 184     /** @return offset in seconds to local timezone time */
 185     inline time_t get_local_offset() const { return local_offset; };
 186 };
 187
 188
 189 // Some useful utility functions that don't make sense to be part of
 190 // the SGTime class
 191
 192 /**
 193  * \relates SGTime
 194  * Return unix time in seconds for the given date (relative to GMT)
 195  * @param year current GMT year
 196  * @param month current GMT month
 197  * @param day current GMT day
 198  * @param hour current GMT hour
 199  * @param minute current minute
 200  * @param second current second
 201  * @return unix/system time in seconds
 202  */
 203 time_t sgTimeGetGMT(int year, int month, int day,
 204                     int hour, int minute, int second);
 205
 206 /**
 207  * \relates SGTime
 208  * this is just a wrapper for sgTimeGetGMT that allows an alternate
 209  * form of input parameters.
 210  * @param the_time the current GMT time in the tm structure
 211  * @return unix/system time in seconds
 212  */
 213 inline time_t sgTimeGetGMT(struct tm* the_time) {
 214     // printf("Using: %24s as input\n", asctime(the_time));
 215     return sgTimeGetGMT(the_time->tm_year,
 216                         the_time->tm_mon,
 217                         the_time->tm_mday,
 218                         the_time->tm_hour,
 219                         the_time->tm_min,
 220                         the_time->tm_sec);
 221 }
 222
 223 /**
 224  * \relates SGTime
 225  * Given a date in our form, return the equivalent modified Julian
 226  * date (number of days elapsed since 1900 jan 0.5), mjd.  Adapted
 227  * from Xephem.
 228  * @param mn month
 229  * @param dy day
 230  * @param yr year
 231  * @return modified julian date */
 232 double sgTimeCalcMJD(int mn, double dy, int yr);
 233
 234 /**
 235  * \relates SGTime
 236  * Given an optional offset from current time calculate the current
 237  * modified julian date.
 238  * @param ct specify a unix time, otherwise specify 0 to use current
 239           clock time
 240  * @param warp number of seconds to offset from current time (0 if no offset)
 241  * @return current modified Julian date (number of days elapsed
 242  * since 1900 jan 0.5), mjd. */
 243 double sgTimeCurrentMJD( time_t ct /* = 0 */, long int warp /* = 0 */ );
 244
 245 /**
 246  * \relates SGTime
 247  * Given an mjd, calculate greenwich mean sidereal time, gst
 248  * @param mjd modified julian date
 249  * @return greenwich mean sidereal time (gst) */
 250 double sgTimeCalcGST( double mjd );
 251
 252 /**
 253  * \relates SGTime
 254  * Format time in a pretty form
 255  * @param p time specified in a tm struct
 256  * @param buf buffer space to contain the result
 257  * @return pointer to character array containt the result
 258  */
 259 char* sgTimeFormatTime( const struct tm* p, char* buf );
 260
 261
 262 #endif // _SG_TIME_HXX