X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=simgear%2Ftiming%2Fsg_time.hxx;h=ba058f4a864b8f600532655ac34db493f1046452;hb=423eba373389684061fc0a8c7b78292f10011ed7;hp=3712928da5ed201af12868a0fe63c66b46f685c5;hpb=f0081c769716eb9bbb27c8ccef109a0aac2ad118;p=simgear.git diff --git a/simgear/timing/sg_time.hxx b/simgear/timing/sg_time.hxx index 3712928d..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,41 +28,52 @@ #define _SG_TIME_HXX -#ifndef __cplusplus +#ifndef __cplusplus # error This library requires C++ -#endif - - -#ifdef HAVE_CONFIG_H -# include #endif + #include -#ifdef FG_HAVE_STD_INCLUDES -# include -#else -# include -#endif +#include + +#include + + +/** + * 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. -#include "timezone.h" + * 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; // Points to the current local timezone name; - char *zonename; + std::string zonename; // Unix "calendar" time in seconds time_t cur_time; // Break down of equivalent GMT time - struct tm *gmt; + struct tm m_gmt; // copy of system gmtime(&time_t) structure // offset of local time relative to GMT time_t local_offset; @@ -81,36 +95,120 @@ private: // gst_diff has pretty good accuracy over the span of a couple hours double gst_diff; + /** init common constructor code */ + void init( double lon_rad, double lat_rad, const std::string& root, + time_t init_time ); + public: - SGTime( double lon, double lat, const string& root ); - 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 - void update( double lon, double lat, long int warp = 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_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(); } - // Given lon/lat, update timezone information and local_offset - void updateLocal( double lon, double lat, const string& root ); + /** @return GMT in a "brokent down" tm structure */ + inline struct tm* getGmt()const { return (struct tm *)&m_gmt; }; - inline time_t get_cur_time() const { return cur_time; }; - inline char* get_zonename() const { return zonename; } - inline struct tm* getGmt()const { return 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; }; + + /** @return offset in seconds to local timezone time */ + inline time_t get_local_offset() const { return local_offset; }; }; // 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 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); -// 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, @@ -121,15 +219,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 );