3 * Data structures and routines for managing time related values.
6 // Written by Curtis Olson, started August 1997.
8 // Copyright (C) 1997 Curtis L. Olson - http://www.flightgear.org/~curt
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.
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.
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.
32 # error This library requires C++
36 #include <simgear/compiler.h>
40 #include <simgear/timing/timezone.h>
44 * A class to calculate and manage a variety of time parameters.
45 * The SGTime class provides many real-world time values. It
46 * calculates current time in seconds, GMT time, local time zone,
47 * local offset in seconds from GMT, Julian date, and sidereal
48 * time. All of these operate with seconds as their granularity so
49 * this class is not intended for timing sub-second events. These
50 * values are intended as input to things like real world lighting
51 * calculations and real astronomical object placement.
53 * To properly use the SGTime class there are a couple of things to be
54 * aware of. After creating an instance of the class, you will need to
55 * periodically (i.e. before every frame) call the update()
56 * method. Optionally, if you care about updating time zone
57 * information based on your latitude and longitude, you can call the
58 * updateLocal() method periodically as your position changes by
59 * significant amounts.
66 // tzContainer stores all the current Timezone control points/
67 SGTimeZoneContainer* tzContainer;
69 // Points to the current local timezone name;
72 // Unix "calendar" time in seconds
75 // Break down of equivalent GMT time
76 #if defined(_MSC_VER) || defined(__MINGW32__)
77 struct tm m_gmt; // copy of system gmtime(&time_t) structure
82 // offset of local time relative to GMT
88 // modified Julian date
91 // side real time at prime meridian
94 // local sidereal time
97 // the difference between the precise / expensive sidereal time
98 // algorithm result and the quick course result. course_gst +
99 // gst_diff has pretty good accuracy over the span of a couple hours
102 /** init common constructor code */
103 void init( double lon_rad, double lat_rad, const std::string& root,
108 /** Default constructor */
112 * Create an instance based on a specified position and data file path.
113 * This creates an instance of the SGTime object. When calling the
114 * constructor you need to provide a root path pointing to your
115 * time zone definition tree. Optionally, you can call a form of
116 * the constructor that accepts your current longitude and
117 * latitude in radians.
119 * If you don't know your position when you call the SGTime
120 * constructor, you can just use the first form (which assumes 0,
122 * @param lon_rad current longitude (radians)
123 * @param lat_rad current latitude (radians)
124 * @param root root path point to data file location (timezone, etc.)
125 * @param init_time provide an initialization time, 0 means use
126 current clock time */
127 SGTime( double lon_rad, double lat_rad, const std::string& root,
131 * Create an instance given a data file path.
132 * @param root root path point to data file location (timezone, etc.)
134 SGTime( const std::string& root );
140 * Update the time related variables.
141 * The update() method requires you to pass in your position and
142 * an optional time offset in seconds. The offset (or warp) allows
143 * you to offset "sim" time relative to "real" time. The update()
144 * method is designed to be called by the host application before
146 * @param lon_rad current longitude (radians)
147 * @param lat_rad current latitude (radians)
148 * @param ct specify a unix time, otherwise specify 0 to use current
150 * @param warp an optional time offset specified in seconds. This
151 * allows us to advance or rewind "time" if we choose to. */
152 void update( double lon_rad, double lat_rad, time_t ct, long int warp );
155 * Given lon/lat, update timezone information and local_offset
156 * The updateLocal() method is intended to be called less
157 * frequently - only when your position is likely to be changed
158 * enough that your timezone may have changed as well. In the
159 * FlightGear project we call updateLocal() every few minutes from
160 * our periodic event manager.
161 * @param lon_rad current longitude (radians)
162 * @param lat_rad current latitude (radians)
163 * @param root base path containing time zone directory */
164 void updateLocal( double lon_rad, double lat_rad, const std::string& root );
166 /** @return current system/unix time in seconds */
167 inline time_t get_cur_time() const { return cur_time; };
169 /** @return time zone name for your current position*/
170 inline const char * get_zonename() const { return zonename.c_str(); }
172 /** @return GMT in a "brokent down" tm structure */
173 #if defined(_MSC_VER) || defined(__MINGW32__)
174 inline struct tm* getGmt()const { return (struct tm *)&m_gmt; };
176 inline struct tm* getGmt()const { return gmt; };
179 /** @return julian date */
180 inline double getJD() const { return jd; };
182 /** @return modified julian date */
183 inline double getMjd() const { return mjd; };
185 /** @return local side real time */
186 inline double getLst() const { return lst; };
188 /** @return grenich side real time (lst when longitude == 0) */
189 inline double getGst() const { return gst; };
191 /** @return offset in seconds to local timezone time */
192 inline time_t get_local_offset() const { return local_offset; };
196 // Some useful utility functions that don't make sense to be part of
201 * Return unix time in seconds for the given date (relative to GMT)
202 * @param year current GMT year
203 * @param month current GMT month
204 * @param day current GMT day
205 * @param hour current GMT hour
206 * @param minute current minute
207 * @param second current second
208 * @return unix/system time in seconds
210 time_t sgTimeGetGMT(int year, int month, int day,
211 int hour, int minute, int second);
215 * this is just a wrapper for sgTimeGetGMT that allows an alternate
216 * form of input parameters.
217 * @param the_time the current GMT time in the tm structure
218 * @return unix/system time in seconds
220 inline time_t sgTimeGetGMT(struct tm* the_time) {
221 // printf("Using: %24s as input\n", asctime(the_time));
222 return sgTimeGetGMT(the_time->tm_year,
232 * Given a date in our form, return the equivalent modified Julian
233 * date (number of days elapsed since 1900 jan 0.5), mjd. Adapted
238 * @return modified julian date */
239 double sgTimeCalcMJD(int mn, double dy, int yr);
243 * Given an optional offset from current time calculate the current
244 * modified julian date.
245 * @param ct specify a unix time, otherwise specify 0 to use current
247 * @param warp number of seconds to offset from current time (0 if no offset)
248 * @return current modified Julian date (number of days elapsed
249 * since 1900 jan 0.5), mjd. */
250 double sgTimeCurrentMJD( time_t ct /* = 0 */, long int warp /* = 0 */ );
254 * Given an mjd, calculate greenwich mean sidereal time, gst
255 * @param mjd modified julian date
256 * @return greenwich mean sidereal time (gst) */
257 double sgTimeCalcGST( double mjd );
261 * Format time in a pretty form
262 * @param p time specified in a tm struct
263 * @param buf buffer space to contain the result
264 * @return pointer to character array containt the result
266 char* sgTimeFormatTime( const struct tm* p, char* buf );
269 #endif // _SG_TIME_HXX