From 75911b6c643d8e5597565bc63c34bdc2009a037a Mon Sep 17 00:00:00 2001 From: curt Date: Sun, 25 Mar 2001 01:42:40 +0000 Subject: [PATCH] doxygen ... --- simgear/bucket/newbucket.hxx | 27 +++--- simgear/debug/logstream.hxx | 7 +- simgear/ephemeris/ephemeris.hxx | 18 ++-- simgear/io/iochannel.hxx | 6 ++ simgear/io/sg_binobj.hxx | 100 +++++++++++++++------- simgear/io/sg_file.hxx | 2 +- simgear/io/sg_serial.hxx | 4 +- simgear/io/sg_socket.hxx | 9 +- simgear/magvar/magvar.hxx | 52 +++++++++-- simgear/math/Makefile.am | 2 +- simgear/math/interpolater.cxx | 2 +- simgear/math/interpolater.hxx | 33 ++++--- simgear/math/leastsqs.hxx | 52 ++++++----- simgear/math/point3d.hxx | 25 +++--- simgear/math/polar3d.hxx | 63 ++++++++++---- simgear/math/sg_geodesy.hxx | 73 +++++++++------- simgear/math/{fg_memory.h => sg_memory.h} | 32 ++++--- simgear/math/sg_random.c | 6 +- simgear/math/sg_random.h | 29 +++++-- simgear/math/sg_types.hxx | 21 +++-- simgear/math/vector.hxx | 74 +++++++++++++--- 21 files changed, 437 insertions(+), 200 deletions(-) rename simgear/math/{fg_memory.h => sg_memory.h} (66%) diff --git a/simgear/bucket/newbucket.hxx b/simgear/bucket/newbucket.hxx index 1564987d..0cc07294 100644 --- a/simgear/bucket/newbucket.hxx +++ b/simgear/bucket/newbucket.hxx @@ -193,6 +193,7 @@ public: * * 3 bits - to represent x (0 to 7) * 3 bits - to represent y (0 to 7) + * @return tile index */ inline long int gen_index() const { return ((lon + 180) << 14) + ((lat + 90) << 6) + (y << 3) + x; @@ -201,6 +202,7 @@ public: /** * Generate the unique scenery tile index for this bucket in ascii * string form. + * @return tile index in string form */ inline string gen_index_str() const { char tmp[20]; @@ -211,11 +213,12 @@ public: /** * Build the base path name for this bucket. + * @return base path in string form */ string gen_base_path() const; /** - * Return the center lon of a tile. + * @return the center lon of a tile. */ inline double get_center_lon() const { double span = sg_bucket_span( lat + y / 8.0 + SG_HALF_BUCKET_SPAN ); @@ -228,51 +231,51 @@ public: } /** - * Return the center lat of a tile. + * @return the center lat of a tile. */ inline double get_center_lat() const { return lat + y / 8.0 + SG_HALF_BUCKET_SPAN; } /** - * Return width of the tile in degrees. + * @return the width of the tile in degrees. */ double get_width() const; /** - * Return height of the tile in degrees. + * @return the height of the tile in degrees. */ double get_height() const; /** - * Return width of the tile in meters. + * @return the width of the tile in meters. */ double get_width_m() const; /** - * Return height of the tile in meters. + * @return the height of the tile in meters. */ double get_height_m() const; // Informational methods. /** - * Return the lon of the lower left corner of this tile. + * @return the lon of the lower left corner of this tile. */ inline int get_lon() const { return lon; } /** - * Return the lat of the lower left corner of this tile. + * @return the lat of the lower left corner of this tile. */ inline int get_lat() const { return lat; } /** - * Return the x coord within the 1x1 degree chunk this tile. + * @return the x coord within the 1x1 degree chunk this tile. */ inline int get_x() const { return x; } /** - * Return the y coord within the 1x1 degree chunk this tile. + * @return the y coord within the 1x1 degree chunk this tile. */ inline int get_y() const { return y; } @@ -284,17 +287,20 @@ public: /** + * \relates SGBucket * Return the bucket which is offset from the specified dlon, dlat by * the specified tile units in the X & Y direction. * @param dlon starting lon in degrees * @param dlat starting lat in degrees * @param x number of bucket units to offset in x (lon) direction * @param y number of bucket units to offset in y (lat) direction + * @return offset bucket */ SGBucket sgBucketOffset( double dlon, double dlat, int x, int y ); /** + * \relates SGBucket * Calculate the offset between two buckets (in quantity of buckets). * @param b1 bucket 1 * @param b2 bucket 2 @@ -320,6 +326,7 @@ operator<< ( ostream& out, const SGBucket& b ) * Compare two bucket structures for equality. * @param b1 bucket 1 * @param b2 bucket 2 + * @return comparison result */ inline bool operator== ( const SGBucket& b1, const SGBucket& b2 ) diff --git a/simgear/debug/logstream.hxx b/simgear/debug/logstream.hxx index e2977bf6..63d3ed10 100644 --- a/simgear/debug/logstream.hxx +++ b/simgear/debug/logstream.hxx @@ -86,10 +86,13 @@ public: // logbuf( streambuf* sb ) : sbuf(sb) {} /** Constructor */ logbuf(); + /** Destructor */ ~logbuf(); - /** Is logging enabled? */ + /** + * Is logging enabled? + * @return true or false*/ bool enabled() { return logging_enabled; } /** @@ -230,9 +233,11 @@ logstream::operator<< ( const loglevel& l ) /** + * \relates logstream * Return the one and only logstream instance. * We use a function instead of a global object so we are assured that cerr * has been initialised. + * @return current logstream */ inline logstream& sglog() diff --git a/simgear/ephemeris/ephemeris.hxx b/simgear/ephemeris/ephemeris.hxx index 664b5c5f..cb677c3b 100644 --- a/simgear/ephemeris/ephemeris.hxx +++ b/simgear/ephemeris/ephemeris.hxx @@ -118,38 +118,38 @@ public: void update(double mjd, double lst, double lat); /** - * Returns a pointer to a Star class containing all the positional + * @return a pointer to a Star class containing all the positional * information for Earth's Sun. */ inline Star *get_sun() const { return our_sun; } - /** Returns the right ascension of the Sun. */ + /** @return the right ascension of the Sun. */ inline double getSunRightAscension() const { return our_sun->getRightAscension(); } - /** Returns the declination of the Sun. */ + /** @return the declination of the Sun. */ inline double getSunDeclination() const { return our_sun->getDeclination(); } /** - * Returns a pointer to a Moon class containing all the positional + * @return a pointer to a Moon class containing all the positional * information for Earth's Moon. */ inline MoonPos *get_moon() const { return moon; } - /** Returns the right ascension of the Moon. */ + /** @return the right ascension of the Moon. */ inline double getMoonRightAscension() const { return moon->getRightAscension(); } - /** Returns the declination of the Moon. */ + /** @return the declination of the Moon. */ inline double getMoonDeclination() const { return moon->getDeclination(); } - /** Returns the numbers of defined planets. */ + /** @return the numbers of defined planets. */ inline int getNumPlanets() const { return nplanets; } /** @@ -158,10 +158,11 @@ public: * the ``sg'' package.) An sgdVec3 is a 3 element double * array. The first element is the right ascension of the planet, * the second is the declination, and the third is the magnitude. + * @return planets array */ inline sgdVec3 *getPlanets() { return planets; } - /** Returns the numbers of defined stars. */ + /** @return the numbers of defined stars. */ inline int getNumStars() const { return stars->getNumStars(); } /** @@ -169,6 +170,7 @@ public: * format. An The first element of the sgdVec3 is the right * ascension of the planet, the second is the declination, and the * third is the magnitude. + * @returns star array */ inline sgdVec3 *getStars() { return stars->getStars(); } }; diff --git a/simgear/io/iochannel.hxx b/simgear/io/iochannel.hxx index 3b693214..76a8fb24 100644 --- a/simgear/io/iochannel.hxx +++ b/simgear/io/iochannel.hxx @@ -96,6 +96,7 @@ public: * - SG_IO_BI - data will be flowing in both directions. * - SG_IO_NONE - data will not be flowing in either direction. * This is here for the sake of completeness. + * @return result of open */ virtual bool open( const SGProtocolDir d ); @@ -109,6 +110,7 @@ public: * accomodate your input message * @param buf a char pointer to your input buffer * @param length max number of bytes to read + * @return number of bytes read */ virtual int read( char *buf, int length ); @@ -117,6 +119,7 @@ public: * stop at the first end of line encountered in the input buffer. * @param buf a char pointer to your input buffer * @param length max number of bytes to read + * @return number of bytes read */ virtual int readline( char *buf, int length ); @@ -128,6 +131,7 @@ public: * written out. The number of bytes written is returned. * @param buf a char pointer to your output buffer * @param length number of bytes to write + * @return number of bytes written */ virtual int write( const char *buf, const int length ); @@ -136,6 +140,7 @@ public: * calculate the length of a null terminated character array and * write it to the output channel. * @param buf a char pointer to your output buffer + * @return number of bytes written */ virtual int writestring( const char *str ); @@ -143,6 +148,7 @@ public: * The close() method is modeled after the close() Unix system * call and will close an open device. You should call this method * when you are done using your IO class, before it is destructed. + * @return result of close */ virtual bool close(); diff --git a/simgear/io/sg_binobj.hxx b/simgear/io/sg_binobj.hxx index a0e11aa6..dc0bdd14 100644 --- a/simgear/io/sg_binobj.hxx +++ b/simgear/io/sg_binobj.hxx @@ -1,5 +1,8 @@ -// sg_binobj.hxx -- routines to read and write low level flightgear 3d objects -// +/** + * \file sg_binobj.hxx + * Routines to read and write the low level (binary) simgear 3d object format. + */ + // Written by Curtis Olson, started January 2000. // // Copyright (C) 2000 Curtis L. Olson - curt@flightgear.org @@ -19,7 +22,6 @@ // Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. // // $Id$ -// #ifndef _SG_BINOBJ_HXX @@ -45,33 +47,49 @@ +/** STL Structure used to store object information */ typedef vector < int_list > group_list; typedef group_list::iterator group_list_iterator; typedef group_list::const_iterator const_group_list_iterator; +/** Magic Number for our file format */ #define SG_FILE_MAGIC_NUMBER ( ('S'<<24) + ('G'<<16) + SG_BINOBJ_VERSION ) -/* - scenery-file: magic, nobjects, object+ - magic: "TG" + version - object: obj_typecode, nproperties, nelements, property+, element+ - element: nbytes, BYTE+ - property: prop_typecode, nbytes, BYTE+ - obj_typecode: bounding sphere | vertices | normals | texcoords | triangles | - fans | strips - prop_typecode: material_name | ??? - nelements: SHORT (Gives us 65536 which ought to be enough, right?) - nproperties: SHORT - *_typecode: CHAR - nbytes: INTEGER (If we used short here that would mean 65536 bytes = 16384 - floats = 5461 vertices which is not enough for future - growth) - vertex: FLOAT, FLOAT, FLOAT +/** + * A class to manipulate the simgear 3d object format. + * This class provides functionality to both read and write the binary format. + * + * Here is a really quick overview of the file syntax: + * + * - scenery-file: magic, nobjects, object+ + * + * - magic: "TG" + version + * + * - object: obj_typecode, nproperties, nelements, property+, element+ + * + * - element: nbytes, BYTE+ + * + * - property: prop_typecode, nbytes, BYTE+ + * + * - obj_typecode: bounding sphere | vertices | normals | texcoords | + * triangles | fans | strips + * + * - prop_typecode: material_name | ??? + * + * - nelements: SHORT (Gives us 65536 which ought to be enough, right?) + * + * - nproperties: SHORT + * + * - *_typecode: CHAR + * + * - nbytes: INTEGER (If we used short here that would mean 65536 bytes = 16384 + * floats = 5461 vertices which is not enough for future + * growth) + * + * - vertex: FLOAT, FLOAT, FLOAT */ - - class SGBinObject { Point3D gbs_center; float gbs_radius; @@ -126,24 +144,46 @@ public: inline string_list get_fan_materials() const { return fan_materials; } inline void set_fan_materials( string_list s ) { fan_materials = s; } - // read a binary file object and populate the provided structures. + /** + * Read a binary file object and populate the provided structures. + * @param file input file name + * @return result of read + */ bool read_bin( const string& file ); - // write out the structures to a binary file. We assume that the - // groups come to us sorted by material property. If not, things - // don't break, but the result won't be as optimal. + /** + * Write out the structures to a binary file. We assume that the + * groups come to us sorted by material property. If not, things + * don't break, but the result won't be as optimal. + * @param base name of output path + * @param name name of output file + * @param b bucket for object location + * @return result of write + */ bool write_bin( const string& base, const string& name, const SGBucket& b ); - // write out the structures to an ASCII file. We assume that the - // groups come to us sorted by material property. If not, things - // don't break, but the result won't be as optimal. + /** + * Write out the structures to an ASCII file. We assume that the + * groups come to us sorted by material property. If not, things + * don't break, but the result won't be as optimal. + * @param base name of output path + * @param name name of output file + * @param b bucket for object location + * @return result of write + */ bool write_ascii( const string& base, const string& name, const SGBucket& b ); }; -// calculate the bounding sphere. Center is the center of the -// tile and zero elevation +/** + * \relates SGBinObject + * Calculate the bounding sphere of a set of nodes. + * Center is the center of the tile and zero elevation. + * @param center center of our bounding radius + * @param wgs84_nodes list of points in wgs84 coordinates + * @return radius + */ double sgCalcBoundingRadius( Point3D center, point_list& wgs84_nodes ); diff --git a/simgear/io/sg_file.hxx b/simgear/io/sg_file.hxx index b116cf1f..88ecf1e0 100644 --- a/simgear/io/sg_file.hxx +++ b/simgear/io/sg_file.hxx @@ -87,7 +87,7 @@ public: // close file bool close(); - /** Return the name of the file being manipulated. */ + /** @return the name of the file being manipulated. */ inline string get_file_name() const { return file_name; } }; diff --git a/simgear/io/sg_serial.hxx b/simgear/io/sg_serial.hxx index e37fa722..b6e43cb7 100644 --- a/simgear/io/sg_serial.hxx +++ b/simgear/io/sg_serial.hxx @@ -97,10 +97,10 @@ public: // close port bool close(); - /** Return the serial port device name */ + /** @return the serial port device name */ inline string get_device() const { return device; } - /** Return the baud rate */ + /** @return the baud rate */ inline string get_baud() const { return baud; } }; diff --git a/simgear/io/sg_socket.hxx b/simgear/io/sg_socket.hxx index be817135..795972d8 100644 --- a/simgear/io/sg_socket.hxx +++ b/simgear/io/sg_socket.hxx @@ -167,13 +167,16 @@ public: // close file bool close(); - /** Enable non-blocking mode. */ + /** + * Enable non-blocking mode. + * @return success/failure + */ bool nonblock(); - /** Return the remote host name */ + /** @return the remote host name */ inline string get_hostname() const { return hostname; } - /** Return the port number (in string form) */ + /** @return the port number (in string form) */ inline string get_port_str() const { return port_str; } }; diff --git a/simgear/magvar/magvar.hxx b/simgear/magvar/magvar.hxx index a270f5a2..4180c961 100644 --- a/simgear/magvar/magvar.hxx +++ b/simgear/magvar/magvar.hxx @@ -1,5 +1,8 @@ -// 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 @@ -34,7 +37,21 @@ # include #endif - +/** + * 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,19 +61,42 @@ 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 ); + /** @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; } }; -// lookup the magvar for any arbitrary location (doesn't save state -// and note that this is a fair amount of cpu work) +/** + * \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 ); diff --git a/simgear/math/Makefile.am b/simgear/math/Makefile.am index e6d49044..ef081362 100644 --- a/simgear/math/Makefile.am +++ b/simgear/math/Makefile.am @@ -9,13 +9,13 @@ endif lib_LIBRARIES = libsgmath.a include_HEADERS = \ - fg_memory.h \ interpolater.hxx \ leastsqs.hxx \ localconsts.hxx \ point3d.hxx \ polar3d.hxx \ sg_geodesy.hxx \ + sg_memory.h \ sg_random.h \ sg_types.hxx \ vector.hxx diff --git a/simgear/math/interpolater.cxx b/simgear/math/interpolater.cxx index 52410453..206e99a7 100644 --- a/simgear/math/interpolater.cxx +++ b/simgear/math/interpolater.cxx @@ -106,7 +106,7 @@ double SGInterpTable::interpolate(double x) { // Destructor -SGInterpTable::~SGInterpTable( void ) { +SGInterpTable::~SGInterpTable() { } diff --git a/simgear/math/interpolater.hxx b/simgear/math/interpolater.hxx index f2553a50..501e4ac8 100644 --- a/simgear/math/interpolater.hxx +++ b/simgear/math/interpolater.hxx @@ -1,7 +1,9 @@ -// -// interpolater.hxx -- routines to handle linear interpolation from a table of -// x,y The table must be sorted by "x" in ascending order -// +/** + * \file interpolater.hxx + * Routines to handle linear interpolation from a table of x,y The + * table must be sorted by "x" in ascending order + */ + // Written by Curtis Olson, started April 1998. // // Copyright (C) 1998 Curtis L. Olson - curt@me.umn.edu @@ -39,22 +41,33 @@ SG_USING_STD(string); #define MAX_TABLE_SIZE 32 - +/** + * A class that provids a simple linear 2d interpolation lookup table. + * The actual table is expected to be loaded from a file. The + * independant variable must be strictly ascending. The dependent + * variable can be anything. + */ class SGInterpTable { int size; double table[MAX_TABLE_SIZE][2]; public: - // Constructor -- loads the interpolation table from the specified - // file + /** + * Constructor. Loads the interpolation table from the specified file. + * @param file name of interpolation file + */ SGInterpTable( const string& file ); - // Given an x value, linearly interpolate the y value from the table + /** + * Given an x value, linearly interpolate the y value from the table. + * @param x independent variable + * @return interpolated dependent variable + */ double interpolate(double x); - // Destructor - ~SGInterpTable( void ); + /** Destructor */ + ~SGInterpTable(); }; diff --git a/simgear/math/leastsqs.hxx b/simgear/math/leastsqs.hxx index af7bdb35..7c8e21d3 100644 --- a/simgear/math/leastsqs.hxx +++ b/simgear/math/leastsqs.hxx @@ -1,5 +1,8 @@ -// leastsqs.h -- Implements a simple linear least squares best fit routine -// +/** + * \file leastsqs.hxx + * Implements a simple linear least squares best fit routine. + */ + // Written by Curtis Olson, started September 1997. // // Copyright (C) 1997 Curtis L. Olson - curt@infoplane.com @@ -20,7 +23,6 @@ // Boston, MA 02111-1307, USA. // // $Id$ -/// #ifndef _LEASTSQS_H @@ -32,39 +34,47 @@ #endif -/* -Least squares fit: - -y = b0 + b1x +/** +Classical least squares fit: - n*sum(xi*yi) - (sum(xi)*sum(yi)) -b1 = -------------------------------- - n*sum(xi^2) - (sum(xi))^2 +\f[ + y = b_0 + b_1 * x +\f] +\f[ + b_1 = \frac{n * \sum_0^i (x_i*y_i) - \sum_0^i x_i* \sum_0^i y_i} + {n*\sum_0^i x_i^2 - (\sum_0^i x_i)^2} +\f] -b0 = sum(yi)/n - b1*(sum(xi)/n) +\f[ + b_0 = \frac{\sum_0^i y_i}{n} - b_1 * \frac{\sum_0^i x_i}{n} +\f] */ - void least_squares(double *x, double *y, int n, double *m, double *b); -/* incrimentally update existing values with a new data point */ + +/** + * Incrimentally update existing values with a new data point. + */ void least_squares_update(double x, double y, double *m, double *b); -/* - return the least squares error: +/** + @return the least squares error:. +\f[ - (y[i] - y_hat[i])^2 - ------------------- - n + \frac{(y_i - \hat{y}_i)^2}{n} +\f] */ double least_squares_error(double *x, double *y, int n, double m, double b); -/* - return the maximum least squares error: +/** + @return the maximum least squares error. - (y[i] - y_hat[i])^2 +\f[ + (y_i - \hat{y}_i)^2 +\f] */ double least_squares_max_error(double *x, double *y, int n, double m, double b); diff --git a/simgear/math/point3d.hxx b/simgear/math/point3d.hxx index 37c3055d..0cc469b9 100644 --- a/simgear/math/point3d.hxx +++ b/simgear/math/point3d.hxx @@ -1,7 +1,13 @@ -// point3d.hxx -- a 3d point class. -// -// Adapted from algebra3 by Jean-Francois Doue, started October 1998. -// +/** + * \file point3d.hxx + * A 3d point class (depricated). This class is depricated and we are + * in the process of removing all usage of it in favor of plib's "sg" + * library of point, vector, and math routines. Plib's sg lib is less + * object oriented, but integrates more seamlessly with opengl. + * + * Adapted from algebra3 by Jean-Francois Doue, started October 1998. + */ + // Copyright (C) 1998 Curtis L. Olson - curt@me.umn.edu // // This library is free software; you can redistribute it and/or @@ -73,11 +79,9 @@ Point3D operator- (const Point3D& p); // -p1 bool operator== (const Point3D& a, const Point3D& b); // p1 == p2? -/////////////////////////// -// -// 3D Point -// -/////////////////////////// +/** + * 3D Point class. + */ class Point3D { @@ -87,8 +91,7 @@ protected: public: - // Constructors - + /** Default constructor */ Point3D(); Point3D(const double x, const double y, const double z); explicit Point3D(const double d); diff --git a/simgear/math/polar3d.hxx b/simgear/math/polar3d.hxx index fd305b48..9d7ebc07 100644 --- a/simgear/math/polar3d.hxx +++ b/simgear/math/polar3d.hxx @@ -1,5 +1,8 @@ -// polar.hxx -- routines to deal with polar math and transformations -// +/** + * \file polar3d.hxx + * Routines to deal with polar math and transformations. + */ + // Written by Curtis Olson, started June 1997. // // Copyright (C) 1997 Curtis L. Olson - curt@infoplane.com @@ -22,8 +25,8 @@ // $Id$ -#ifndef _POLAR_HXX -#define _POLAR_HXX +#ifndef _POLAR3D_HXX +#define _POLAR3D_HXX #ifndef __cplusplus @@ -37,15 +40,23 @@ #include -// Find the Altitude above the Ellipsoid (WGS84) given the Earth -// Centered Cartesian coordinate vector Distances are specified in -// meters. +/** + * Find the Altitude above the Ellipsoid (WGS84) given the Earth + * Centered Cartesian coordinate vector Distances are specified in + * meters. + * @param cp point specified in cartesian coordinates + * @return altitude above the (wgs84) earth in meters + */ double sgGeodAltFromCart(const Point3D& cp); -// Convert a polar coordinate to a cartesian coordinate. Lon and Lat -// must be specified in radians. The SG convention is for distances -// to be specified in meters +/** + * Convert a polar coordinate to a cartesian coordinate. Lon and Lat + * must be specified in radians. The SG convention is for distances + * to be specified in meters + * @param p point specified in polar coordinates + * @return the same point in cartesian coordinates + */ inline Point3D sgPolarToCart3d(const Point3D& p) { double tmp = cos( p.lat() ) * p.radius(); @@ -55,8 +66,12 @@ inline Point3D sgPolarToCart3d(const Point3D& p) { } -// Convert a cartesian coordinate to polar coordinates (lon/lat -// specified in radians. Distances are specified in meters. +/** + * Convert a cartesian coordinate to polar coordinates (lon/lat + * specified in radians. Distances are specified in meters. + * @param cp point specified in cartesian coordinates + * @return the same point in polar coordinates + */ inline Point3D sgCartToPolar3d(const Point3D& cp) { return Point3D( atan2( cp.y(), cp.x() ), SGD_PI_2 - @@ -65,10 +80,16 @@ inline Point3D sgCartToPolar3d(const Point3D& cp) { } -// calc new lon/lat given starting lon/lat, and offset radial, and -// distance. NOTE: starting point is specifed in radians, distance is -// specified in meters (and converted internally to radians) -// ... assumes a spherical world +/** + * Calculate new lon/lat given starting lon/lat, and offset radial, and + * distance. NOTE: starting point is specifed in radians, distance is + * specified in meters (and converted internally to radians) + * ... assumes a spherical world. + * @param orig specified in polar coordinates + * @param course offset radial + * @param dist offset distance + * @return destination point in polar coordinates + */ inline Point3D calc_gc_lon_lat( const Point3D& orig, double course, double dist ) { Point3D result; @@ -101,7 +122,13 @@ inline Point3D calc_gc_lon_lat( const Point3D& orig, double course, } -// calc course/dist +/** + * Calculate course/dist given two spherical points. + * @param start starting point + * @param dest ending point + * @param course resulting course + * @param dist resulting distance + */ inline void calc_gc_course_dist( const Point3D& start, const Point3D& dest, double *course, double *dist ) { // d = 2*asin(sqrt((sin((lat1-lat2)/2))^2 + @@ -157,4 +184,4 @@ inline void calc_gc_course_dist( const Point3D& start, const Point3D& dest, *dist = d * SG_RAD_TO_NM * SG_NM_TO_METER; } -#endif // _POLAR_HXX +#endif // _POLAR3D_HXX diff --git a/simgear/math/sg_geodesy.hxx b/simgear/math/sg_geodesy.hxx index b9f7d6db..48940510 100644 --- a/simgear/math/sg_geodesy.hxx +++ b/simgear/math/sg_geodesy.hxx @@ -1,8 +1,9 @@ -// sg_geodesy.hxx -- routines to convert between geodetic and geocentric -// coordinate systems. -// -// Copied and adapted directly from LaRCsim/ls_geodesy.c -// +/** + * \file sg_geodesy.hxx + * Routines to convert between geodetic and geocentric coordinate systems. + * Copied and adapted directly from LaRCsim/ls_geodesy.c + */ + // See below for the complete original LaRCsim comments. // // $Id$ @@ -21,39 +22,37 @@ #include -// sgGeocToGeod(lat_geoc, radius, *lat_geod, *alt, *sea_level_r) -// INPUTS: -// lat_geoc Geocentric latitude, radians, + = North -// radius C.G. radius to earth center (meters) -// -// OUTPUTS: -// lat_geod Geodetic latitude, radians, + = North -// alt C.G. altitude above mean sea level (meters) -// sea_level_r radius from earth center to sea level at -// local vertical (surface normal) of C.G. (meters) - +/** + * Convert from geocentric coordinates to geodetic coordinates + * @param lat_geoc (in) Geocentric latitude, radians, + = North + * @param radius (in) C.G. radius to earth center (meters) + * @param lat_geod (out) Geodetic latitude, radians, + = North + * @param alt (out) C.G. altitude above mean sea level (meters) + * @param sea_level_r (out) radius from earth center to sea level at + * local vertical (surface normal) of C.G. (meters) + */ void sgGeocToGeod( double lat_geoc, double radius, double *lat_geod, double *alt, double *sea_level_r ); -// sgGeodToGeoc( lat_geod, alt, *sl_radius, *lat_geoc ) -// INPUTS: -// lat_geod Geodetic latitude, radians, + = North -// alt C.G. altitude above mean sea level (meters) -// -// OUTPUTS: -// sl_radius SEA LEVEL radius to earth center (meters) -// (add Altitude to get true distance from earth center. -// lat_geoc Geocentric latitude, radians, + = North -// - +/** + * Convert from geodetic coordinates to geocentric coordinates + * @param lat_geod (in) Geodetic latitude, radians, + = North + * @param alt (in) C.G. altitude above mean sea level (meters) + * @param sl_radius (out) SEA LEVEL radius to earth center (meters) + * (add Altitude to get true distance from earth center. + * @param lat_geoc (out) Geocentric latitude, radians, + = North + */ void sgGeodToGeoc( double lat_geod, double alt, double *sl_radius, double *lat_geoc ); -// convert a geodetic point lon(radians), lat(radians), elev(meter) to -// a cartesian point - +/** + * Convert a geodetic point lon(radians), lat(radians), elev(meter) to + * a cartesian point. + * @param geodetic point + * @return cartesian point + */ inline Point3D sgGeodToCart(const Point3D& geod) { double gc_lon, gc_lat, sl_radius; @@ -71,8 +70,18 @@ inline Point3D sgGeodToCart(const Point3D& geod) { } -// given, alt, lat1, lon1, az1 and distance (s), calculate lat2, lon2 -// and az2. Lat, lon, and azimuth are in degrees. distance in meters +/** + * Given a starting position and an offset radial and distance, + * calculate an ending positon on a wgs84 ellipsoid. + * @param alt (in) meters + * @param lat1 (in) degrees + * @param lon1 (in) degrees + * @param az1 (in) degrees + * @param s (in) distance in meters + * @param lat2 (out) degrees + * @param lon2 (out) degrees + * @param az2 (out) return course in degrees + */ int geo_direct_wgs_84 ( double alt, double lat1, double lon1, double az1, double s, double *lat2, double *lon2, double *az2 ); diff --git a/simgear/math/fg_memory.h b/simgear/math/sg_memory.h similarity index 66% rename from simgear/math/fg_memory.h rename to simgear/math/sg_memory.h index 032f5c4b..486c9b88 100644 --- a/simgear/math/fg_memory.h +++ b/simgear/math/sg_memory.h @@ -1,5 +1,9 @@ -// fg_memory.h -- memcpy/bcopy portability declarations -// +/** + * \file sg_memory.h + * memcpy/bcopy portability declarations (not actually used by anything + * as best as I can tell. + */ + // 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 @@ -18,8 +22,8 @@ // $Id$ -#ifndef _FG_MEMORY_H -#define _FG_MEMORY_H +#ifndef _SG_MEMORY_H +#define _SG_MEMORY_H #ifdef HAVE_CONFIG_H # include @@ -31,15 +35,15 @@ # include # endif -# define fgmemcmp memcmp -# define fgmemcpy memcpy -# define fgmemzero(dest,len) memset(dest,0,len) +# define sgmemcmp memcmp +# define sgmemcpy memcpy +# define sgmemzero(dest,len) memset(dest,0,len) #elif defined(HAVE_BCOPY) -# define fgmemcmp bcmp -# define fgmemcpy(dest,src,n) bcopy(src,dest,n) -# define fgmemzero bzero +# define sgmemcmp bcmp +# define sgmemcpy(dest,src,n) bcopy(src,dest,n) +# define sgmemzero bzero #else @@ -49,12 +53,12 @@ */ # include -# define fgmemcmp zmemcmp -# define fgmemcpy zmemcpy -# define fgmemzero zmemzero +# define sgmemcmp zmemcmp +# define sgmemcpy zmemcpy +# define sgmemzero zmemzero #endif -#endif // _FG_MEMORY_H +#endif // _SG_MEMORY_H diff --git a/simgear/math/sg_random.c b/simgear/math/sg_random.c index dcabf119..31297e19 100644 --- a/simgear/math/sg_random.c +++ b/simgear/math/sg_random.c @@ -41,7 +41,7 @@ #ifdef __SUNPRO_CC extern "C" { - long int random(void); + long int random(); void srandom(unsigned int seed); } #endif @@ -49,7 +49,7 @@ // Seed the random number generater with time() so we don't see the // same sequence every time -void sg_srandom_time(void) { +void sg_srandom_time() { #ifdef HAVE_RAND srand(time(NULL)); #else @@ -70,7 +70,7 @@ void sg_srandom( unsigned int seed ) { // return a random number between [0.0, 1.0) -double sg_random(void) { +double sg_random() { #ifdef HAVE_RAND return(rand() / (double)RAND_MAX); #else diff --git a/simgear/math/sg_random.h b/simgear/math/sg_random.h index 1ff1b1de..8b263b33 100644 --- a/simgear/math/sg_random.h +++ b/simgear/math/sg_random.h @@ -1,5 +1,8 @@ -// sg_random.h -- routines to handle random number generation -// +/** + * \file sg_random.h + * Routines to handle random number generation and hide platform differences. + */ + // Written by Curtis Olson, started July 1997. // // Copyright (C) 1997 Curtis L. Olson - curt@infoplane.com @@ -31,16 +34,24 @@ extern "C" { #endif -// Seed the random number generater with time() so we don't see the -// same sequence every time -void sg_srandom_time(void); +/** + * Seed the random number generater with time() so we don't see the + * same sequence every time. + */ +void sg_srandom_time(); -// Seed the random number generater with your own seed so can set up -// repeatable randomization. +/** + * Seed the random number generater with your own seed so can set up + * repeatable randomization. + * @param seed random number generator seed + */ void sg_srandom( unsigned int seed ); -// return a random number between [0.0, 1.0) -double sg_random(void); +/** + * Return a random number between [0.0, 1.0) + * @return next "random" number in the "random" sequence + */ +double sg_random(); #ifdef __cplusplus diff --git a/simgear/math/sg_types.hxx b/simgear/math/sg_types.hxx index ef3ebd63..578c6127 100644 --- a/simgear/math/sg_types.hxx +++ b/simgear/math/sg_types.hxx @@ -1,5 +1,8 @@ -// fg_types.hxx -- commonly used types I don't want to have to keep redefining -// +/** + * \file sg_types.hxx + * Commonly used types I don't want to have to keep redefining. + */ + // Written by Curtis Olson, started March 1999. // // Copyright (C) 1999 Curtis L. Olson - curt@flightgear.org @@ -22,8 +25,8 @@ // $Id$ -#ifndef _FG_TYPES_HXX -#define _FG_TYPES_HXX +#ifndef _SG_TYPES_HXX +#define _SG_TYPES_HXX #ifndef __cplusplus @@ -41,20 +44,26 @@ SG_USING_STD(vector); SG_USING_STD(string); - +/** STL vector list of ints */ typedef vector < int > int_list; typedef int_list::iterator int_list_iterator; typedef int_list::const_iterator const_int_list_iterator; +/** STL vector list of Point3D */ typedef vector < Point3D > point_list; typedef point_list::iterator point_list_iterator; typedef point_list::const_iterator const_point_list_iterator; +/** STL vector list of strings */ typedef vector < string > string_list; typedef string_list::iterator string_list_iterator; typedef string_list::const_iterator const_string_list_iterator; +/** + * Simple 2d point class where members can be accessed as x, dist, or lon + * and y, theta, or lat + */ class point2d { public: union { @@ -70,5 +79,5 @@ public: }; -#endif // _FG_TYPES_HXX +#endif // _SG_TYPES_HXX diff --git a/simgear/math/vector.hxx b/simgear/math/vector.hxx index 84029aa3..75893c18 100644 --- a/simgear/math/vector.hxx +++ b/simgear/math/vector.hxx @@ -1,5 +1,8 @@ -// vector.hxx -- additional vector routines -// +/** + * \file vector.hxx + * Additional vector routines. + */ + // Written by Curtis Olson, started December 1997. // // Copyright (C) 1997 Curtis L. Olson - curt@infoplane.com @@ -39,6 +42,13 @@ #include +/** + * Map a vector onto a plane. + * @param normal (in) normal vector for the plane + * @param v0 (in) a point on the plane + * @param vec (in) the vector to map onto the plane + * @param result (out) the result vector + */ inline void sgmap_vec_onto_cur_surface_plane( sgVec3 normal, sgVec3 v0, sgVec3 vec, @@ -84,6 +94,11 @@ inline void sgmap_vec_onto_cur_surface_plane( sgVec3 normal, } +/** + * Copy and negate a vector. + * @param dst (out) result vector + * @param src (in) input vector + */ inline void sgCopyNegateVec4( sgVec4 dst, sgVec4 src ) { dst [ 0 ] = -src [ 0 ] ; @@ -92,31 +107,64 @@ inline void sgCopyNegateVec4( sgVec4 dst, sgVec4 src ) dst [ 3 ] = -src [ 3 ] ; } -// Given a point p, and a line through p0 with direction vector d, -// find the closest point (p1) on the line +/** + * Given a point p, and a line through p0 with direction vector d, + * find the closest point (p1) on the line (float version). + * @param p1 (out) closest point to p on the line + * @param p (in) original point + * @param p0 (in) point on the line + * @param d (in) vector defining line direction + */ void sgClosestPointToLine( sgVec3 p1, const sgVec3 p, const sgVec3 p0, const sgVec3 d ); -// Given a point p, and a line through p0 with direction vector d, -// find the closest point (p1) on the line +/** + * Given a point p, and a line through p0 with direction vector d, + * find the closest point (p1) on the line (double version). + * @param p1 (out) closest point to p on the line + * @param p (in) original point + * @param p0 (in) point on the line + * @param d (in) vector defining line direction + */ void sgdClosestPointToLine( sgdVec3 p1, const sgdVec3 p, const sgdVec3 p0, const sgdVec3 d ); -// Given a point p, and a line through p0 with direction vector d, -// find the shortest distance (squared) from the point to the line +/** + * Given a point p, and a line through p0 with direction vector d, + * find the shortest distance (squared) from the point to the line (float + * version.) + * @param p (in) original point + * @param p0 (in) point on the line + * @param d (in) vector defining line direction + * @return shortest distance (squared) from p to line + */ double sgClosestPointToLineDistSquared( const sgVec3 p, const sgVec3 p0, const sgVec3 d ); -// Given a point p, and a line through p0 with direction vector d, -// find the shortest distance (squared) from the point to the line +/** + * Given a point p, and a line through p0 with direction vector d, + * find the shortest distance (squared) from the point to the line (double + * version.) + * @param p (in) original point + * @param p0 (in) point on the line + * @param d (in) vector defining line direction + * @return shortest distance (squared) from p to line + */ double sgdClosestPointToLineDistSquared( const sgdVec3 p, const sgdVec3 p0, const sgdVec3 d ); -// This is same as -// sgMakeMatTrans4( sgMat4 sgTrans, sgVec3 trans ) -// sgPostMultMat4( sgMat, sgTRANS ); +/** + * This is same as: + * + *
  • sgMakeMatTrans4( sgMat4 sgTrans, sgVec3 trans ) + *
  • sgPostMultMat4( sgMat4 src, sgTRANS ); + * + * @param src starting sgMat4 matrix + * @param trans translation vector + */ void sgPostMultMat4ByTransMat4( sgMat4 src, const sgVec3 trans ); + #endif // _VECTOR_HXX -- 2.39.5