- Tweaks to doxygen main page.

- Added documentation for SGCloudLayer
- Updated the SGSky interface a bit to make it more sensible, flexible,
  and generic.  This requires a code tweak on the FlightGear side as well.

DoxygenMain.cxx

@@ -33,6 +33,11 @@
  *   planets for a given time, date, season, earth location, etc.
  *   (SGEphemeris)
  *
+ * - Code to render a realistic sky dome, cloud layers, sun, moon,
+ *   stars, and planets all with realistic day/night/sunset/sunrise
+ *   effects.  Includes things like correct moon phase, textured moon,
+ *   sun halo, etc. (SGSky is built on top of SGCloudLayer ...)
+ *
  * - Simple serial (SGSerial), file (SGFile), socket (SGSocket), and
  *   UDP socket (SGSocketUDP) I/O abstractions.
  *

simgear/scene/sky/cloud.hxx

@@ -1,5 +1,8 @@
-// cloud.hxx -- model a single cloud layer
-//
+/**
+ * \file cloud.hxx
+ * Provides a class to model a single cloud layer
+ */
+
 // Written by Curtis Olson, started June 2000.
 //
 // Copyright (C) 2000  Curtis L. Olson  - curt@flightgear.org
@@ -33,10 +36,15 @@
 SG_USING_STD(string);
 
 
+/**
+ * A class layer to model a single cloud layer
+ */
 class SGCloudLayer {
-
 public:
 
+    /**
+     * This is the list of available cloud coverages/textures
+     */
     enum Coverage {
 	SG_CLOUD_OVERCAST = 0,
 	SG_CLOUD_BROKEN,
@@ -47,48 +55,85 @@ public:
 	SG_MAX_CLOUD_COVERAGES
     };
 
-    // Constructors
+    /**
+     * Constructor
+     * @param tex_path the path to the set of cloud textures
+     */
     SGCloudLayer( const string &tex_path );
 
-    // Destructor
+    /**
+     * Destructor
+     */
     ~SGCloudLayer( void );
 
+    /** get the cloud span (in meters) */
     float getSpan_m () const;
+    /**
+     * set the cloud span
+     * @param span_m the cloud span in meters
+     */
     void setSpan_m (float span_m);
 
+    /** get the layer elevation (in meters) */
     float getElevation_m () const;
+    /**
+     * set the layer elevation.  Note that this specifies the bottom
+     * of the cloud layer.  The elevation of the top of the layer is
+     * elevation_m + thickness_m.
+     * @param elevation_m the layer elevation in meters
+     */
     void setElevation_m (float elevation_m);
 
+    /** get the layer thickness */
     float getThickness_m () const;
+    /**
+     * set the layer thickness.
+     * @param thickness_m the layer thickness in meters.
+     */
     void setThickness_m (float thickness_m);
 
+    /**
+     * get the transition/boundary layer depth in meters.  This
+     * allows gradual entry/exit from the cloud layer via adjusting
+     * visibility.
+     */
     float getTransition_m () const;
+    /**
+     * set the transition layer size in meters
+     * @param transition_m the transition layer size in meters
+     */
     void setTransition_m (float transition_m);
 
+    /** get coverage type */
     Coverage getCoverage () const;
+    /**
+     * set coverage type
+     * @param coverage the coverage type
+     */
     void setCoverage (Coverage coverage);
 
-    // build the cloud object
+    /** build the cloud object */
     void rebuild();
 
-    // repaint the cloud colors based on current value of sun_angle,
-    // sky, and fog colors.  This updates the color arrays for
-    // ssgVtxTable.
-    // sun angle in degrees relative to verticle
-    // 0 degrees = high noon
-    // 90 degrees = sun rise/set
-    // 180 degrees = darkest midnight
+    /**
+     * repaint the cloud colors based on the specified fog_color
+     * @param fog_color the fog color
+     */
     bool repaint( sgVec3 fog_color );
 
-    // reposition the cloud layer at the specified origin and
-    // orientation
-    // lon specifies a rotation about the Z axis
-    // lat specifies a rotation about the new Y axis
-    // spin specifies a rotation about the new Z axis (and orients the
-    // sunrise/set effects
+    /**
+     * reposition the cloud layer at the specified origin and
+     * orientation.
+     * @param p position vector
+     * @param up the local up vector
+     * @param lon specifies a rotation about the Z axis
+     * @param lat specifies a rotation about the new Y axis
+     * @param spin specifies a rotation about the new Z axis
+     *        (and orients the sunrise/set effects)
+     */
     bool reposition( sgVec3 p, sgVec3 up, double lon, double lat, double alt );
 
-    // draw the cloud layer
+    /** draw the cloud layer */
     void draw();
 
 private:

simgear/scene/sky/sky.cxx

@@ -56,10 +56,10 @@ SGSky::~SGSky( void )
 
 // initialize the sky and connect the components to the scene graph at
 // the provided branch
-void SGSky::build(  double sun_size, double moon_size,
+void SGSky::build( double h_radius_m, double v_radius_m,
+                   double sun_size, double moon_size,
 		   int nplanets, sgdVec3 *planet_data,
-		    double planet_dist,
-		    int nstars, sgdVec3 *star_data, double star_dist )
+		   int nstars, sgdVec3 *star_data )
 {
     pre_root = new ssgRoot;
     post_root = new ssgRoot;
@@ -71,15 +71,13 @@ void SGSky::build(  double sun_size, double moon_size,
     post_transform = new ssgTransform;
 
     dome = new SGSkyDome;
-    pre_transform -> addKid( dome->build() );
+    pre_transform -> addKid( dome->build( h_radius_m, v_radius_m ) );
 
     planets = new SGStars;
-    pre_transform -> addKid( planets->build(nplanets, planet_data,
-					    planet_dist)
-			     );
+    pre_transform -> addKid(planets->build(nplanets, planet_data, h_radius_m));
 
     stars = new SGStars;
-    pre_transform -> addKid( stars->build(nstars, star_data, star_dist) );
+    pre_transform -> addKid( stars->build(nstars, star_data, h_radius_m) );
     
     moon = new SGMoon;
     pre_transform -> addKid( moon->build(tex_path, moon_size) );

simgear/scene/sky/sky.hxx

@@ -80,10 +80,10 @@ typedef layer_list_type::const_iterator layer_list_const_iterator;
  * texture_path() method.
 
  * The arguments you pass to the build() method allow you to specify
- * the size of your sun sphere and moon sphere, a number of planets,
- * and a multitude of stars.  For the planets and stars you pass in an
- * array of right ascensions, declinations, magnitudes, and the
- * distance from the view point.
+ * the horizontal and vertical radiuses of the sky dome, the size of
+ * your sun sphere and moon sphere, a number of planets, and a
+ * multitude of stars.  For the planets and stars you pass in an array
+ * of right ascensions, declinations, and magnitudes.
 
  * Cloud Layers 
 
@@ -223,19 +223,21 @@ public:
      * Initialize the sky and connect the components to the scene
      * graph at the provided branch.  See discussion in detailed class
      * description.
+     * @param h_radius_m horizontal radius of sky dome
+     * @param v_radius_m vertical radius of sky dome
      * @param sun_size size of sun
      * @param moon_size size of moon
      * @param nplanets number of planets
      * @param planet_data an array of planet right ascensions, declinations,
      *        and magnitudes
-     * @param planet_dist distance from viewer to put the planets
      * @param nstars number of stars
      * @param star_data an array of star right ascensions, declinations,
      *        and magnitudes
-     * @param star_dist distance from viewer to put the stars */
-    void build( double sun_size, double moon_size,
-		int nplanets, sgdVec3 *planet_data, double planet_dist,
-		int nstars, sgdVec3 *star_data, double star_dist );
+     */
+    void build( double h_radius_m, double v_radius_m,
+                double sun_size, double moon_size,
+		int nplanets, sgdVec3 *planet_data,
+		int nstars, sgdVec3 *star_data );
 
     /**
      * Repaint the sky components based on current value of sun_angle,