X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=simgear%2Ftiming%2Fsg_time.hxx;h=f2bab45aff35d83e9bae408e5a0b894475a6c0c6;hb=a885314a39890b898ab078b365beaa7e24f4b501;hp=cba4b27f203f9a167387f8834979d91518036b01;hpb=baf25ca7a78bb282569da3404dd5efddd0a7613c;p=simgear.git diff --git a/simgear/timing/sg_time.hxx b/simgear/timing/sg_time.hxx index cba4b27f..f2bab45a 100644 --- a/simgear/timing/sg_time.hxx +++ b/simgear/timing/sg_time.hxx @@ -1,5 +1,8 @@ -// sg_time.hxx -- data structures and routines for managing time related stuff. -// +/** + * \file sg_time.hxx + * Data structures and routines for managing time related values. + */ + // Written by Curtis Olson, started August 1997. // // Copyright (C) 1997 Curtis L. Olson - curt@flightgear.org @@ -31,10 +34,6 @@ #endif -#ifdef HAVE_CONFIG_H -# include -#endif - #include #ifdef SG_HAVE_STD_INCLUDES @@ -46,7 +45,26 @@ #include -// Define a structure containing time parameters +/** + * A class to calculate and manage a variety of time parameters. + * The SGTime class provides many real-world time values. It + * calculates current time in seconds, GMT time, local time zone, + * local offset in seconds from GMT, Julian date, and sidereal + * time. All of these operate with seconds as their granularity so + * this class is not intended for timing sub-second events. These + * values are intended as input to things like real world lighting + * calculations and real astronomical object placement. + + * To properly use the SGTime class there are a couple of things to be + * aware of. After creating an instance of the class, you will need to + * periodically (i.e. before every frame) call the update() + * method. Optionally, if you care about updating time zone + * information based on your latitude and longitude, you can call the + * updateLocal() method periodically as your position changes by + * significant amounts. + + */ + class SGTime { private: @@ -60,7 +78,11 @@ private: time_t cur_time; // Break down of equivalent GMT time +#if defined(_MSC_VER) || defined(__MINGW32__) + struct tm m_gmt; // copy of system gmtime(&time_t) structure +#else struct tm *gmt; +#endif // offset of local time relative to GMT time_t local_offset; @@ -84,23 +106,89 @@ private: public: - SGTime( double lon, double lat, const string& root ); - SGTime( const string& root ); + /** Default constructor */ SGTime(); - ~SGTime(); - // Update the time related variables - void update( double lon, double lat, long int warp = 0 ); + /** + * Create an instance based on a specified position and data file path. + * This creates an instance of the SGTime object. When calling the + * constructor you need to provide a root path pointing to your + * time zone definition tree. Optionally, you can call a form of + * the constructor that accepts your current longitude and + * latitude in radians. + * + * If you don't know your position when you call the SGTime + * constructor, you can just use the first form (which assumes 0, + * 0). + * @param lon current longitude + * @param lat current latitude + * @param root root path point to data file location (timezone, etc.) + * @param init_time provide an initialization time, 0 means use + current clock time */ + SGTime( double lon, double lat, const string& root, time_t init_time /* = 0 */ ); + + /** + * Create an instance given a data file path. + * @param root root path point to data file location (timezone, etc.) + */ + SGTime( const string& root ); + + /** Destructor */ + ~SGTime(); - // Given lon/lat, update timezone information and local_offset + /** init common constructor code */ + void init( double lon, double lat, const string& root, time_t init_time /* = 0 */ ); + + /** + * Update the time related variables. + * The update() method requires you to pass in your position and + * an optional time offset in seconds. The offset (or warp) allows + * you to offset "sim" time relative to "real" time. The update() + * method is designed to be called by the host application before + * every frame. + * @param lon current longitude + * @param lat current latitude + * @param ct specify a unix time, otherwise specify 0 to use current + clock time + * @param warp an optional time offset specified in seconds. This + * allows us to advance or rewind "time" if we choose to. */ + void update( double lon, double lat, time_t ct /* = 0 */, long int warp /* = 0 */ ); + + /** + * Given lon/lat, update timezone information and local_offset + * The updateLocal() method is intended to be called less + * frequently - only when your position is likely to be changed + * enough that your timezone may have changed as well. In the + * FlightGear project we call updateLocal() every few minutes from + * our periodic event manager. + * @param lon current longitude + * @param lat current latitude + * @param root base path containing time zone directory */ void updateLocal( double lon, double lat, const string& root ); + /** @return current system/unix time in seconds */ inline time_t get_cur_time() const { return cur_time; }; + + /** @return time zone name for your current position*/ inline char* get_zonename() const { return zonename; } + + /** @return GMT in a "brokent down" tm structure */ +#if defined(_MSC_VER) || defined(__MINGW32__) + inline struct tm* getGmt()const { return (struct tm *)&m_gmt; }; +#else inline struct tm* getGmt()const { return gmt; }; +#endif + + /** @return julian date */ inline double getJD() const { return jd; }; + + /** @return modified julian date */ inline double getMjd() const { return mjd; }; + + /** @return local side real time */ inline double getLst() const { return lst; }; + + /** @return grenich side real time (lst when longitude == 0) */ inline double getGst() const { return gst; }; }; @@ -108,11 +196,27 @@ public: // Some useful utility functions that don't make sense to be part of // the SGTime class -// Return unix time in seconds for the given data (relative to GMT) +/** + * \relates SGTime + * Return unix time in seconds for the given data (relative to GMT) + * @param year current GMT year + * @param month current GMT month + * @param day current GMT day + * @param hour current GMT hour + * @param minute current minute + * @param second current second + * @return unix/system time in seconds + */ time_t sgTimeGetGMT(int year, int month, int day, int hour, int minute, int second); -// this is just a wrapper +/** + * \relates SGTime + * this is just a wrapper for sgTimeGetGMT that allows an alternate + * form of input parameters. + * @param the_time the current GMT time in the tm structure + * @return unix/system time in seconds + */ inline time_t sgTimeGetGMT(struct tm* the_time) { // printf("Using: %24s as input\n", asctime(the_time)); return sgTimeGetGMT(the_time->tm_year, @@ -123,15 +227,42 @@ inline time_t sgTimeGetGMT(struct tm* the_time) { the_time->tm_sec); } -// given a date in months, mn, days, dy, years, yr, return the -// modified Julian date (number of days elapsed since 1900 jan 0.5), -// mjd. Adapted from Xephem. +/** + * \relates SGTime + * Given a date in our form, return the equivalent modified Julian + * date (number of days elapsed since 1900 jan 0.5), mjd. Adapted + * from Xephem. + * @param mn month + * @param dy day + * @param yr year + * @return modified julian date */ double sgTimeCalcMJD(int mn, double dy, int yr); -// given an mjd, calculate greenwich mean sidereal time, gst +/** + * \relates SGTime + * Given an optional offset from current time calculate the current + * modified julian date. + * @param ct specify a unix time, otherwise specify 0 to use current + clock time + * @param warp number of seconds to offset from current time (0 if no offset) + * @return current modified Julian date (number of days elapsed + * since 1900 jan 0.5), mjd. */ +double sgTimeCurrentMJD( time_t ct /* = 0 */, long int warp /* = 0 */ ); + +/** + * \relates SGTime + * Given an mjd, calculate greenwich mean sidereal time, gst + * @param mjd modified julian date + * @return greenwich mean sidereal time (gst) */ double sgTimeCalcGST( double mjd ); -// format time +/** + * \relates SGTime + * Format time in a pretty form + * @param p time specified in a tm struct + * @param buf buffer space to contain the result + * @return pointer to character array containt the result + */ char* sgTimeFormatTime( const struct tm* p, char* buf );