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  - curt@flightgear.org
   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 Library General Public
  21 // License along with this library; if not, write to the
  22 // Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  23 // Boston, MA  02111-1307, USA.
  24 //
  25 // $Id$
  26
  27
  28 #ifndef _SG_TIME_HXX
  29 #define _SG_TIME_HXX
  30
  31
  32 #ifndef __cplusplus
  33 # error This library requires C++
  34 #endif
  35
  36
  37 #include <simgear/compiler.h>
  38
  39 #ifdef SG_HAVE_STD_INCLUDES
  40 #  include <ctime>
  41 #else
  42 #  include <time.h>
  43 #endif
  44
  45 #include <simgear/timing/timezone.h>
  46
  47
  48 /**
  49  * A class to calculate and manage a variety of time parameters.
  50  * The SGTime class provides many real-world time values. It
  51  * calculates current time in seconds, GMT time, local time zone,
  52  * local offset in seconds from GMT, Julian date, and sidereal
  53  * time. All of these operate with seconds as their granularity so
  54  * this class is not intended for timing sub-second events. These
  55  * values are intended as input to things like real world lighting
  56  * calculations and real astronomical object placement.
  57
  58  * To properly use the SGTime class there are a couple of things to be
  59  * aware of. After creating an instance of the class, you will need to
  60  * periodically (i.e. before every frame) call the update()
  61  * method. Optionally, if you care about updating time zone
  62  * information based on your latitude and longitude, you can call the
  63  * updateLocal() method periodically as your position changes by
  64  * significant amounts.
  65
  66  */
  67
  68 class SGTime {
  69
  70 private:
  71     // tzContainer stores all the current Timezone control points/
  72     TimezoneContainer* tzContainer;
  73
  74     // Points to the current local timezone name;
  75     char *zonename;
  76
  77     // Unix "calendar" time in seconds
  78     time_t cur_time;
  79
  80     // Break down of equivalent GMT time
  81     struct tm *gmt;
  82
  83     // offset of local time relative to GMT
  84     time_t local_offset;
  85
  86     // Julian date
  87     double jd;
  88
  89     // modified Julian date
  90     double mjd;
  91
  92     // side real time at prime meridian
  93     double gst;
  94
  95     // local sidereal time
  96     double lst;
  97
  98     // the difference between the precise / expensive sidereal time
  99     // algorithm result and the quick course result.  course_gst +
 100     // gst_diff has pretty good accuracy over the span of a couple hours
 101     double gst_diff;
 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 current longitude
 120      * @param lat current latitude
 121      * @param root root path point to data file location (timezone, etc.)  */
 122     SGTime( double lon, double lat, const string& root );
 123
 124     /**
 125      * Create an instance given a data file path.
 126      * @param root root path point to data file location (timezone, etc.)
 127      */
 128     SGTime( const string& root );
 129
 130     /** Destructor */
 131     ~SGTime();
 132
 133     /**
 134      * Update the time related variables.
 135      * The update() method requires you to pass in your position and
 136      * an optional time offset in seconds. The offset (or warp) allows
 137      * you to offset "sim" time relative to "real" time. The update()
 138      * method is designed to be called by the host application before
 139      * every frame.
 140      * @param lon current longitude
 141      * @param lat current latitude
 142      * @param warp an optional time offset specified in seconds.  This
 143      *        allows us to advance or rewind "time" if we choose to.  */
 144     void update( double lon, double lat, long int warp = 0 );
 145
 146     /**
 147      * Given lon/lat, update timezone information and local_offset
 148      * The updateLocal() method is intended to be called less
 149      * frequently - only when your position is likely to be changed
 150      * enough that your timezone may have changed as well. In the
 151      * FlightGear project we call updateLocal() every few minutes from
 152      * our periodic event manager.
 153      * @param lon current longitude
 154      * @param lat current latitude
 155      * @param root base path containing time zone directory */
 156     void updateLocal( double lon, double lat, const string& root );
 157
 158     /** @return current system/unix time in seconds */
 159     inline time_t get_cur_time() const { return cur_time; };
 160
 161     /** @return time zone name for your current position*/
 162     inline char* get_zonename() const { return zonename; }
 163
 164     /** @return GMT in a "brokent down" tm structure */
 165     inline struct tm* getGmt()const { return gmt; };
 166
 167     /** @return julian date */
 168     inline double getJD() const { return jd; };
 169
 170     /** @return modified julian date */
 171     inline double getMjd() const { return mjd; };
 172
 173     /** @return local side real time */
 174     inline double getLst() const { return lst; };
 175
 176     /** @return grenich side real time (lst when longitude == 0) */
 177     inline double getGst() const { return gst; };
 178 };
 179
 180
 181 // Some useful utility functions that don't make sense to be part of
 182 // the SGTime class
 183
 184 /**
 185  * \relates SGTime
 186  * Return unix time in seconds for the given data (relative to GMT)
 187  * @param year current GMT year
 188  * @param month current GMT month
 189  * @param day current GMT day
 190  * @param hour current GMT hour
 191  * @param minute current minute
 192  * @param second current second
 193  * @return unix/system time in seconds
 194  */
 195 time_t sgTimeGetGMT(int year, int month, int day,
 196                     int hour, int minute, int second);
 197
 198 /**
 199  * \relates SGTime
 200  * this is just a wrapper for sgTimeGetGMT that allows an alternate
 201  * form of input parameters.
 202  * @param the_time the current GMT time in the tm structure
 203  * @return unix/system time in seconds
 204  */
 205 inline time_t sgTimeGetGMT(struct tm* the_time) {
 206     // printf("Using: %24s as input\n", asctime(the_time));
 207     return sgTimeGetGMT(the_time->tm_year,
 208                         the_time->tm_mon,
 209                         the_time->tm_mday,
 210                         the_time->tm_hour,
 211                         the_time->tm_min,
 212                         the_time->tm_sec);
 213 }
 214
 215 /**
 216  * \relates SGTime
 217  * Given a date in our form, return the equivalent modified Julian
 218  * date (number of days elapsed since 1900 jan 0.5), mjd.  Adapted
 219  * from Xephem.
 220  * @param mn month
 221  * @param dy day
 222  * @param yr year
 223  * @return modified julian date */
 224 double sgTimeCalcMJD(int mn, double dy, int yr);
 225
 226 /**
 227  * \relates SGTime
 228  * Given an mjd, calculate greenwich mean sidereal time, gst
 229  * @param mjd modified julian date
 230  * @return greenwich mean sidereal time (gst)
 231  */
 232 double sgTimeCalcGST( double mjd );
 233
 234 /**
 235  * \relates SGTime
 236  * Format time in a pretty form
 237  * @param p time specified in a tm struct
 238  * @param buf buffer space to contain the result
 239  * @return pointer to character array containt the result
 240  */
 241 char* sgTimeFormatTime( const struct tm* p, char* buf );
 242
 243
 244 #endif // _SG_TIME_HXX