-// 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$
#define _SG_TIME_HXX
-#ifndef __cplusplus
+#ifndef __cplusplus
# error This library requires C++
-#endif
-
-
-#ifdef HAVE_CONFIG_H
-# include <config.h>
-#endif
-
-#ifdef HAVE_WINDOWS_H
-# include <windows.h>
#endif
-#include <GL/glut.h>
#include <simgear/compiler.h>
-#ifdef FG_HAVE_STD_INCLUDES
-# include <ctime>
-#else
-# include <time.h>
-#endif
+#include <ctime>
-// #include <FDM/flight.hxx>
+#include <simgear/timing/timezone.h>
-#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;
// 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
projects / simgear.git / blobdiff