Ensure individual log-level setting works.

[simgear.git] / simgear / magvar / magvar.hxx

diff --git a/simgear/magvar/magvar.hxx b/simgear/magvar/magvar.hxx
index a08ea98ca2a2cb49d22940e19ceded8c30850cb2..605bece722bc09a99a80a249f803db8e84870048 100644 (file)
--- a/simgear/magvar/magvar.hxx
+++ b/simgear/magvar/magvar.hxx
@@ -1,8 +1,11 @@
-// magvar.hxx -- magnetic variation wrapper class
-//
+/** 
+ * \file magvar.hxx
+ * Magnetic variation wrapper class.
+ */
+
 // Written by Curtis Olson, started July 2000.
 //
-// Copyright (C) 2000  Curtis L. Olson  - curt@flightgear.org
+// Copyright (C) 2000  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
@@ -16,7 +19,7 @@
 //
 // 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,16 +28,29 @@
 #define _MAGVAR_HXX
 
 
-#ifndef __cplusplus                                                          
+#ifndef __cplusplus
 # error This library requires C++
-#endif                                   
-
-
-#ifdef HAVE_CONFIG_H
-#  include <config.h>
 #endif
 
 
+// forward decls
+class SGGeod;
+
+/**
+ * Magnetic variation wrapper class.
+ *
+ * The SGMagVar class calculates the magnetic variation and dip for
+ * any position, altitude, and time. It is a complete
+ * re-implimentation of the NIMA WMM 2000 (not derived from their demo
+ * code.)
+ *
+ * The SGMagVar class is really a simple wrapper around the core Ed
+ * Williams code which does all the hard work.  This class allows you
+ * to crunch the math once and then do multiple polls of the
+ * data. However, if your position, altitude, or time has changed
+ * significantly, you should call the update() method to recrunch new
+ * numbers.
+ */
 class SGMagVar {
 
 private:
@@ -44,15 +60,52 @@ private:
 
 public:
 
+    /**
+     * This creates an instance of the SGMagVar object.
+     * You must call the update() method before any queries will be valid.
+     */
     SGMagVar();
+
+    /** Destructor */
     ~SGMagVar();
 
-    // recalculate the magnetic offset and dip
+    /** Recalculate the magnetic offset and dip.
+     * The update() method requires you to pass in your position and
+     * the julian date. Lon and lat are specified in radians, altitude
+     * is specified in meters. Julian date can be conveniently
+     * calculated by using an instance of the SGTime class.
+     * @param lon longitude in radians
+     * @param lat latitude in radians
+     * @param alt_m altitude above sea level in meters
+     * @param jd julian date
+     */
     void update( double lon, double lat, double alt_m, double jd );
 
+    /**
+     * overloaded variant taking an SGGeod to specify position
+     */
+    void update( const SGGeod& geod, double jd );
+
+    /** @return the current magnetic variation in radians. */
     double get_magvar() const { return magvar; }
+
+    /** @return the current magnetic dip in radians. */
     double get_magdip() const { return magdip; }
 };
 
 
-#endif // _LIGHT_HXX
+/**
+ * \relates SGMagVar
+ * Lookup the magvar for any arbitrary location (This function doesn't
+ * save state like the SGMagVar class.  This function triggers a fair
+ * amount of CPU work, so use it cautiously.
+ * @return the magvar in radians
+ */
+double sgGetMagVar( double lon, double lat, double alt_m, double jd );
+
+/**
+ * overload version of the above to take a SGGeod
+ */
+double sgGetMagVar( const SGGeod& pos, double jd );
+
+#endif // _MAGVAR_HXX