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 - curt@flightgear.org
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 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.
33 # error This library requires C++
37 #include <simgear/compiler.h>
39 #ifdef SG_HAVE_STD_INCLUDES
45 #include <simgear/timing/timezone.h>
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.
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.
71 // tzContainer stores all the current Timezone control points/
72 TimezoneContainer* tzContainer;
74 // Points to the current local timezone name;
77 // Unix "calendar" time in seconds
80 // Break down of equivalent GMT time
83 // offset of local time relative to GMT
89 // modified Julian date
92 // side real time at prime meridian
95 // local sidereal time
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
105 /** Default constructor */
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.
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,
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 );
125 * Create an instance given a data file path.
126 * @param root root path point to data file location (timezone, etc.)
128 SGTime( const string& root );
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
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 );
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 );
158 /** @return current system/unix time in seconds */
159 inline time_t get_cur_time() const { return cur_time; };
161 /** @return time zone name for your current position*/
162 inline char* get_zonename() const { return zonename; }
164 /** @return GMT in a "brokent down" tm structure */
165 inline struct tm* getGmt()const { return gmt; };
167 /** @return julian date */
168 inline double getJD() const { return jd; };
170 /** @return modified julian date */
171 inline double getMjd() const { return mjd; };
173 /** @return local side real time */
174 inline double getLst() const { return lst; };
176 /** @return grenich side real time (lst when longitude == 0) */
177 inline double getGst() const { return gst; };
181 // Some useful utility functions that don't make sense to be part of
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
195 time_t sgTimeGetGMT(int year, int month, int day,
196 int hour, int minute, int second);
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
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,
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
223 * @return modified julian date */
224 double sgTimeCalcMJD(int mn, double dy, int yr);
228 * Given an mjd, calculate greenwich mean sidereal time, gst
229 * @param mjd modified julian date
230 * @return greenwich mean sidereal time (gst)
232 double sgTimeCalcGST( double mjd );
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
241 char* sgTimeFormatTime( const struct tm* p, char* buf );
244 #endif // _SG_TIME_HXX