head 1.4; access; symbols; locks; strict; comment @# @; 1.4 date 2002.09.07.01.50.37; author curt; state Exp; branches; next 1.3; 1.3 date 2002.08.31.19.01.51; author curt; state Exp; branches; next 1.2; 1.2 date 2002.08.31.18.53.59; author curt; state Exp; branches; next 1.1; 1.1 date 2002.02.15.17.21.55; author curt; state Exp; branches; next ; desc @@ 1.4 log @Updated doxygen docs. @ text @
Main Page Class Hierarchy Compound List File List Compound Members File Members

# SGTime Class Reference

A class to calculate and manage a variety of time parameters. More...

`#include <sg_time.hxx>`

List of all members.

## Public Methods
| SGTime ()
| Default constructor.
| SGTime (double lon, double lat, const string &root, time_t init_time)
| Create an instance based on a specified position and data file path.
| SGTime (const string &root)
| Create an instance given a data file path.
| ~SGTime ()
| Destructor.
void | init (double lon, double lat, const string &root, time_t init_time)
| init common constructor code
void | update (double lon, double lat, time_t ct, long int warp)
| Update the time related variables.
void | updateLocal (double lon, double lat, const string &root)
| 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.
time_t | get_cur_time () const
char * | get_zonename () const
tm * | getGmt () const
double | getJD () const
double | getMjd () const
double | getLst () const
double | getGst () const
## Related Functions
(Note that these are not member functions.)
time_t | sgTimeGetGMT (int year, int month, int day, int hour, int minute, int second)
| Return unix time in seconds for the given data (relative to GMT).
time_t | sgTimeGetGMT (struct tm *the_time)
| this is just a wrapper for sgTimeGetGMT that allows an alternate form of input parameters.
double | sgTimeCalcMJD (int mn, double dy, int yr)
| Given a date in our form, return the equivalent modified Julian date (number of days elapsed since 1900 jan 0.5), mjd.
double | sgTimeCurrentMJD (time_t ct, long int warp)
| Given an optional offset from current time calculate the current modified julian date.
double | sgTimeCalcGST (double mjd)
| Given an mjd, calculate greenwich mean sidereal time, gst.
char * | sgTimeFormatTime (const struct tm *p, char *buf)
| Format time in a pretty form.

## Detailed Description

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.

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.

Definition at line 68 of file sg_time.hxx.

## Constructor & Destructor Documentation

SGTime::SGTime | ( | double | lon,
|  | double | lat,
|  | const string & | root,
|  | time_t | init_time
| ) |

  | 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). Parameters:
  lon | current longitude
  lat | current latitude
  root | root path point to data file location (timezone, etc.)
  init_time | provide an initialization time, 0 means use current clock time
Definition at line 112 of file sg_time.cxx. References init().

SGTime::SGTime | ( | const string & | root | ) |

  | Create an instance given a data file path. Parameters:
  root | root path point to data file location (timezone, etc.)
Definition at line 118 of file sg_time.cxx. References init().

## Member Function Documentation

time_t SGTime::get_cur_time | ( |  | ) | const`[inline]`

| Returns: current system/unix time in seconds Definition at line 170 of file sg_time.hxx.

char* SGTime::get_zonename | ( |  | ) | const`[inline]`

| Returns: time zone name for your current position Definition at line 173 of file sg_time.hxx.

struct tm* SGTime::getGmt | ( |  | ) | const`[inline]`

| Returns: GMT in a "brokent down" tm structure Definition at line 179 of file sg_time.hxx.

double SGTime::getGst | ( |  | ) | const`[inline]`

| Returns: grenich side real time (lst when longitude == 0) Definition at line 192 of file sg_time.hxx.

double SGTime::getJD | ( |  | ) | const`[inline]`

| Returns: julian date Definition at line 183 of file sg_time.hxx.

double SGTime::getLst | ( |  | ) | const`[inline]`

| Returns: local side real time Definition at line 189 of file sg_time.hxx.

double SGTime::getMjd | ( |  | ) | const`[inline]`

| Returns: modified julian date Definition at line 186 of file sg_time.hxx.

void SGTime::update | ( | double | lon,
|  | double | lat,
|  | time_t | ct,
|  | long int | warp
| ) |

  | 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. Parameters:
  lon | current longitude
  lat | current latitude
  ct | specify a unix time, otherwise specify 0 to use current clock time
  warp | an optional time offset specified in seconds. This allows us to advance or rewind "time" if we choose to.
Definition at line 204 of file sg_time.cxx. References SG_LOG, and sgTimeCurrentMJD().

void SGTime::updateLocal | ( | double | lon,
|  | double | lat,
|  | const string & | root
| ) |

  | 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. Parameters:
  lon | current longitude
  lat | current latitude
  root | base path containing time zone directory
Definition at line 276 of file sg_time.cxx. References SGPath::append(), SGPath::c_str(), SGPath::set(), SG_LOG, and sgTimeGetGMT().

## Friends And Related Function Documentation

double sgTimeCalcGST | ( | double | mjd | ) | `[related]`

  | Given an mjd, calculate greenwich mean sidereal time, gst. Parameters:
  mjd | modified julian date
Returns: greenwich mean sidereal time (gst) Definition at line 421 of file sg_time.cxx. References SG_LOG.

double sgTimeCalcMJD | ( | int | mn,
|  | double | dy,
|  | int | yr
| ) | `[related]`

  | 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. Parameters:
  mn | month
  dy | day
  yr | year
Returns: modified julian date Definition at line 327 of file sg_time.cxx.

double sgTimeCurrentMJD | ( | time_t | ct,
|  | long int | warp
| ) | `[related]`

  | Given an optional offset from current time calculate the current modified julian date. Parameters:
  ct | specify a unix time, otherwise specify 0 to use current clock time
  warp | number of seconds to offset from current time (0 if no offset)
Returns: current modified Julian date (number of days elapsed since 1900 jan 0.5), mjd. Definition at line 377 of file sg_time.cxx. References SG_LOG. Referenced by update().

char * sgTimeFormatTime | ( | const struct tm * | p,
|  | char * | buf
| ) | `[related]`

  | Format time in a pretty form. Parameters:
  p | time specified in a tm struct
  buf | buffer space to contain the result
Returns: pointer to character array containt the result Definition at line 586 of file sg_time.cxx.

time_t sgTimeGetGMT | ( | struct tm * | the_time | ) | `[related]`

  | this is just a wrapper for sgTimeGetGMT that allows an alternate form of input parameters. Parameters:
  the_time | the current GMT time in the tm structure
Returns: unix/system time in seconds Definition at line 220 of file sg_time.hxx.

time_t sgTimeGetGMT | ( | int | year,
|  | int | month,
|  | int | day,
|  | int | hour,
|  | int | minute,
|  | int | second
| ) | `[related]`

  | Return unix time in seconds for the given data (relative to GMT). Parameters:
  year | current GMT year
  month | current GMT month
  day | current GMT day
  hour | current GMT hour
  minute | current minute
  second | current second
Returns: unix/system time in seconds Definition at line 490 of file sg_time.cxx. References SG_LOG. Referenced by updateLocal().

The documentation for this class was generated from the following files:

- sg_time.hxx
- sg_time.cxx

@ 1.3 log @Oops, try again. @ text @d872 1 a872 1