X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=simgear%2Ftiming%2Fsg_time.hxx;h=ba058f4a864b8f600532655ac34db493f1046452;hb=423eba373389684061fc0a8c7b78292f10011ed7;hp=0a1cd0a08d1cb6459e913615eb5e9405bb824770;hpb=8159b749f49be587e794a8438db7a4373d527b1d;p=simgear.git diff --git a/simgear/timing/sg_time.hxx b/simgear/timing/sg_time.hxx index 0a1cd0a0..ba058f4a 100644 --- a/simgear/timing/sg_time.hxx +++ b/simgear/timing/sg_time.hxx @@ -1,22 +1,25 @@ -// 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 +// Copyright (C) 1997 Curtis L. Olson - http://www.flightgear.org/~curt // -// This program is free software; you can redistribute it and/or -// modify it under the terms of the GNU General Public License as -// published by the Free Software Foundation; either version 2 of the -// License, or (at your option) any later version. +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Library General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. // -// This program is distributed in the hope that it will be useful, but -// WITHOUT ANY WARRANTY; without even the implied warranty of +// This library is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -// General Public License for more details. +// Library General Public License for more details. // // You should have received a copy of the GNU General Public License // along with this program; if not, write to the Free Software -// Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. // // $Id$ @@ -25,60 +28,55 @@ #define _SG_TIME_HXX -#ifndef __cplusplus +#ifndef __cplusplus # error This library requires C++ -#endif - - -#ifdef HAVE_CONFIG_H -# include -#endif - -#ifdef HAVE_WINDOWS_H -# include #endif -#include #include -#ifdef FG_HAVE_STD_INCLUDES -# include -#else -# include -#endif +#include -// #include +#include -#include "timezone.h" -// #include "lowleveltime.h" +/** + * 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. -enum sgTimingOffsetType { - SG_TIME_SYS_OFFSET = 0, - SG_TIME_GMT_OFFSET = 1, - SG_TIME_LAT_OFFSET = 2, - SG_TIME_SYS_ABSOLUTE = 3, - SG_TIME_GMT_ABSOLUTE = 4, - SG_TIME_LAT_ABSOLUTE = 5 -}; + * 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. + */ -// Define a structure containing time parameters class SGTime { private: // tzContainer stores all the current Timezone control points/ - TimezoneContainer* tzContainer; + SGTimeZoneContainer* tzContainer; - //Store the current local timezone name; - char *zonename; + // Points to the current local timezone name; + std::string zonename; // Unix "calendar" time in seconds time_t cur_time; - // Break down of GMT time - struct tm *gmt; + // Break down of equivalent GMT time + struct tm m_gmt; // copy of system gmtime(&time_t) structure + + // offset of local time relative to GMT + time_t local_offset; // Julian date double jd; @@ -86,84 +84,178 @@ private: // modified Julian date double mjd; - double last_mjd, last_dy; - int last_mn, last_yr; - // side real time at prime meridian double gst; // local sidereal time double lst; - // local offset to GMT - time_t localOffset; - - // the difference between the precise sidereal time algorithm - // result and the course result. course + diff has good accuracy - // for the short term + // the difference between the precise / expensive sidereal time + // algorithm result and the quick course result. course_gst + + // gst_diff has pretty good accuracy over the span of a couple hours double gst_diff; - // An offset in seconds from the true time. Allows us to adjust - // the effective time of day. - long int warp; - - // How much to change the value of warp each iteration. Allows us - // to make time progress faster than normal. - long int warp_delta; + /** init common constructor code */ + void init( double lon_rad, double lat_rad, const std::string& root, + time_t init_time ); public: - SGTime( const string& root ); + /** Default constructor */ + SGTime(); + + /** + * 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_rad current longitude (radians) + * @param lat_rad current latitude (radians) + * @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_rad, double lat_rad, const std::string& root, + time_t init_time ); + + /** + * Create an instance given a data file path. + * @param root root path point to data file location (timezone, etc.) + */ + SGTime( const std::string& root ); + + /** Destructor */ ~SGTime(); + /** + * 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_rad current longitude (radians) + * @param lat_rad current latitude (radians) + * @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_rad, double lat_rad, time_t ct, long int warp ); + + /** + * 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_rad current longitude (radians) + * @param lat_rad current latitude (radians) + * @param root base path containing time zone directory */ + void updateLocal( double lon_rad, double lat_rad, const std::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 const char * get_zonename() const { return zonename.c_str(); } + + /** @return GMT in a "brokent down" tm structure */ + inline struct tm* getGmt()const { return (struct tm *)&m_gmt; }; + + /** @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; }; - inline time_t get_cur_time() const { return cur_time; }; - inline struct tm* getGmt()const { return gmt; }; - - void adjust_warp(int val) { warp += val; }; - void adjust_warp_delta(int val) { warp_delta += val; }; - - // Initialize the time dependent variables - void init( double lon, double lat, const string& root, - time_t timeOffset, sgTimingOffsetType offsetType ); - - // Update the time dependent variables - void update( double lon, double lat, double alt_m ); - void updateLocal( double lon, double lat, const string& root ); - - void cal_mjd (int mn, double dy, int yr); - void utc_gst(); - double sidereal_precise (double lng); - double sidereal_course(double lng); - static SGTime *cur_time_params; - - // Some other stuff which were changed to SGTime members on - // questionable grounds -:) - // time_t get_start_gmt(int year); - time_t get_gmt(int year, int month, int day, - int hour, int minute, int second); - time_t get_gmt(struct tm* the_time); - - char* format_time( const struct tm* p, char* buf ); - long int fix_up_timezone( long int timezone_orig ); - - inline int get_warp_delta() const { return warp_delta; } + + /** @return offset in seconds to local timezone time */ + inline time_t get_local_offset() const { return local_offset; }; }; -inline time_t SGTime::get_gmt(struct tm* the_time) // this is just a wrapper -{ - //printf("Using: %24s as input\n", asctime(the_time)); - return get_gmt(the_time->tm_year, - the_time->tm_mon, - the_time->tm_mday, - the_time->tm_hour, - the_time->tm_min, - the_time->tm_sec); +// Some useful utility functions that don't make sense to be part of +// the SGTime class + +/** + * \relates SGTime + * Return unix time in seconds for the given date (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); + +/** + * \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, + the_time->tm_mon, + the_time->tm_mday, + the_time->tm_hour, + the_time->tm_min, + the_time->tm_sec); } +/** + * \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); + +/** + * \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 ); + +/** + * \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 ); + #endif // _SG_TIME_HXX