simgear/scene/sky/sky.hxx

   1 /**
   2  * \file sky.hxx
   3  * Provides a class to model a realistic (time/date/position) based sky.
   4  */
   5
   6 // Written by Curtis Olson, started December 1997.
   7 // SSG-ified by Curtis Olson, February 2000.
   8 //
   9 // Copyright (C) 1997-2000  Curtis L. Olson  - http://www.flightgear.org/~curt
  10 //
  11 // This library is free software; you can redistribute it and/or
  12 // modify it under the terms of the GNU Library General Public
  13 // License as published by the Free Software Foundation; either
  14 // version 2 of the License, or (at your option) any later version.
  15 //
  16 // This library is distributed in the hope that it will be useful,
  17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19 // Library General Public License for more details.
  20 //
  21 // You should have received a copy of the GNU General Public License
  22 // along with this program; if not, write to the Free Software
  23 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  24 //
  25 // $Id$
  26
  27
  28 #ifndef _SG_SKY_HXX
  29 #define _SG_SKY_HXX
  30
  31
  32 #ifndef __cplusplus
  33 # error This library requires C++
  34 #endif
  35
  36 #include <simgear/compiler.h>
  37 #include <simgear/misc/sg_path.hxx>
  38 #include <simgear/props/props.hxx>
  39
  40 #include <vector>
  41
  42 #include <osg/ref_ptr>
  43 #include <osg/MatrixTransform>
  44 #include <osg/Node>
  45 #include <osg/Switch>
  46
  47 #include <simgear/ephemeris/ephemeris.hxx>
  48 #include <simgear/math/SGMath.hxx>
  49
  50 #include <simgear/scene/sky/cloud.hxx>
  51 #include <simgear/scene/sky/dome.hxx>
  52 #include <simgear/scene/sky/moon.hxx>
  53 #include <simgear/scene/sky/oursun.hxx>
  54 #include <simgear/scene/sky/stars.hxx>
  55
  56 using std::vector;
  57
  58
  59 typedef struct {
  60         SGVec3d pos;
  61         SGGeod pos_geod;
  62         SGQuatd ori;
  63         double spin;
  64         double gst;
  65         double sun_dist;
  66         double moon_dist;
  67         double sun_angle;
  68 } SGSkyState;
  69
  70 typedef struct {
  71         SGVec3f sky_color;
  72         SGVec3f adj_sky_color;
  73         SGVec3f fog_color;
  74         SGVec3f cloud_color;
  75         double sun_angle, moon_angle;
  76 } SGSkyColor;
  77
  78 /**
  79  * A class to model a realistic (time/date/position) based sky.
  80  *
  81  * Introduction
  82  *
  83  * The SGSky class models a blended sky dome, a haloed sun, a textured
  84  * moon with phase that properly matches the date, stars and planets,
  85  * and cloud layers. SGSky is designed to be dropped into existing
  86  * plib based applications and depends heavily on plib's scene graph
  87  * library, ssg. The sky implements various time of day lighting
  88  * effects, it plays well with fog and visibility effects, and
  89  * implements scudded cloud fly-through effects. Additionally, you can
  90  * wire in the output of the SGEphemeris class to accurately position
  91  * all the objects in the sky.
  92  *
  93  * Building the sky
  94  *
  95
  96  * Once you have created an instance of SGSky you must call the
  97  * build() method.  Building the sky requires several textures. So,
  98  * you must specify the path/directory where these textures reside
  99  * before building the sky.  You do this first by calling the
 100  * texture_path() method.
 101
 102  * The arguments you pass to the build() method allow you to specify
 103  * the horizontal and vertical radiuses of the sky dome, the size of
 104  * your sun sphere and moon sphere, a number of planets, and a
 105  * multitude of stars.  For the planets and stars you pass in an array
 106  * of right ascensions, declinations, and magnitudes.
 107
 108  * Cloud Layers
 109
 110  * Cloud layers can be added, changed, or removed individually. To add
 111  * a cloud layer use the add_cloud_layer() method.  The arguments
 112  * allow you to specify base height above sea level, layer thickness,
 113  * a transition zone for entering/leaving the cloud layer, the size of
 114  * the cloud object, and the type of cloud texture. All distances are
 115  * in meters. There are additional forms of this method that allow you
 116  * to specify your own ssgSimpleState or texture name for drawing the
 117  * cloud layer.
 118
 119  * Repainting the Sky
 120
 121  * As the sun circles the globe, you can call the repaint() method to
 122  * recolor the sky objects to simulate sunrise and sunset effects,
 123  * visibility, and other lighting changes.  The arguments allow you to
 124  * specify a base sky color (for the top of the dome), a fog color
 125  * (for the horizon), the sun angle with the horizon (for
 126  * sunrise/sunset effects), the moon angle (so we can make it more
 127  * yellow at the horizon), and new star and planet data so that we can
 128  * optionally change the magnitude of these (for day / night
 129  * transitions.)
 130
 131  * Positioning Sky Objects
 132
 133  * As time progresses and as you move across the surface of the earth,
 134  * the apparent position of the objects and the various lighting
 135  * effects can change. the reposition() method allows you to specify
 136  * the positions of all the sky objects as well as your view position.
 137  * The arguments allow you to specify your view position in world
 138  * Cartesian coordinates, the zero elevation position in world
 139  * Cartesian coordinates (your longitude, your latitude, sea level),
 140  * the ``up'' vector in world Cartesian coordinates, current
 141  * longitude, latitude, and altitude. A ``spin'' angle can be
 142  * specified for orienting the sky with the sun position so sunset and
 143  * sunrise effects look correct. You must specify GMT side real time,
 144  * the sun right ascension, sun declination, and sun distance from
 145  * view point (to keep it inside your view volume.) You also must
 146  * specify moon right ascension, moon declination, and moon distance
 147  * from view point.
 148
 149  * Rendering the Sky
 150
 151  * The sky is designed to be rendered in three stages. The first stage
 152  * renders the parts that form your back drop - the sky dome, the
 153  * stars and planets, the sun, and the moon.  These should be rendered
 154  * before the rest of your scene by calling the preDraw() method. The
 155  * second stage renders the clouds that are above the viewer. This stage
 156  * is done before translucent objects in the main scene are drawn. It
 157  * is seperated from the preDraw routine to enable to implement a
 158  * multi passes technique and is located in the drawUpperClouds() method.
 159  * The third stage renders the clouds that are below the viewer an which
 160  * are likely to be translucent (depending on type) and should be drawn
 161  * after your scene has been rendered.  Use the drawLowerClouds() method
 162  * to draw the second stage of the sky.
 163
 164  * A typical application might do the following:
 165
 166  * <li> thesky->preDraw( my_altitude );
 167  * <li> thesky->drawUpperClouds();
 168  * <li> ssgCullAndDraw ( myscene ) ;
 169  * <li> thesky->drawLowerClouds();
 170
 171  * The current altitude in meters is passed to the preDraw() method
 172  * so the clouds layers can be rendered correction from most distant
 173  * to closest.
 174
 175  * Visibility Effects
 176
 177  * Visibility and fog is important for correctly rendering the
 178  * sky. You can inform SGSky of the current visibility by calling the
 179  * set_visibility() method.
 180
 181  * When transitioning through clouds, it is nice to pull in the fog as
 182  * you get close to the cloud layer to hide the fact that the clouds
 183  * are drawn as a flat polygon. As you get nearer to the cloud layer
 184  * it is also nice to temporarily pull in the visibility to simulate
 185  * the effects of flying in and out of the puffy edge of the
 186  * cloud. These effects can all be accomplished by calling the
 187  * modify_vis() method.  The arguments allow you to specify your
 188  * current altitude (which is then compared to the altitudes of the
 189  * various cloud layers.) You can also specify a time factor which
 190  * should be the length in seconds since the last time you called
 191  * modify_vis(). The time_factor value allows the puffy cloud effect
 192  * to be calculated correctly.
 193
 194  * The modify_vis() method alters the SGSky's internal idea of
 195  * visibility, so you should subsequently call get_visibility() to get
 196  * the actual modified visibility. You should then make the
 197  * appropriate glFog() calls to setup fog properly for your scene.
 198
 199  * Accessor Methods
 200
 201  * Once an instance of SGSky has been successfully initialized, there
 202  * are a couple accessor methods you can use such as get_num_layers()
 203  * to return the number of cloud layers, get_cloud_layer(i) to return
 204  * cloud layer number i, get_visibility() to return the actual
 205  * visibility as modified by the sky/cloud model.
 206
 207  */
 208
 209 class SGSky {
 210
 211 private:
 212     typedef std::vector<SGSharedPtr<SGCloudLayer> > layer_list_type;
 213     typedef layer_list_type::iterator layer_list_iterator;
 214     typedef layer_list_type::const_iterator layer_list_const_iterator;
 215
 216     // components of the sky
 217     SGSharedPtr<SGSkyDome> dome;
 218     SGSharedPtr<SGSun> oursun;
 219     SGSharedPtr<SGMoon> moon;
 220     SGSharedPtr<SGStars> planets;
 221     SGSharedPtr<SGStars> stars;
 222     layer_list_type cloud_layers;
 223
 224     osg::ref_ptr<osg::Group> pre_root, cloud_root;
 225     osg::ref_ptr<osg::Switch> pre_selector;
 226     osg::ref_ptr<osg::Group> pre_transform;
 227
 228     osg::ref_ptr<osg::MatrixTransform> _ephTransform;
 229
 230     SGPath tex_path;
 231
 232     // visibility
 233     float visibility;
 234     float effective_visibility;
 235
 236     int in_cloud;
 237     int cur_layer_pos;
 238
 239     // near cloud visibility state variables
 240     bool in_puff;
 241     double puff_length;         // in seconds
 242     double puff_progression;    // in seconds
 243     double ramp_up;             // in seconds
 244     double ramp_down;           // in seconds
 245
 246     // 3D clouds enabled
 247     bool clouds_3d_enabled;
 248
 249     // 3D cloud density
 250     double clouds_3d_density;
 251
 252 public:
 253
 254     /** Constructor */
 255     SGSky( void );
 256
 257     /** Destructor */
 258     ~SGSky( void );
 259
 260     /**
 261      * Initialize the sky and connect the components to the scene
 262      * graph at the provided branch.  See discussion in detailed class
 263      * description.
 264      * @param h_radius_m horizontal radius of sky dome
 265      * @param v_radius_m vertical radius of sky dome
 266      * @param sun_size size of sun
 267      * @param moon_size size of moon
 268      * @param nplanets number of planets
 269      * @param planet_data an array of planet right ascensions, declinations,
 270      *        and magnitudes
 271      * @param nstars number of stars
 272      * @param star_data an array of star right ascensions, declinations,
 273      *        and magnitudes
 274      */
 275     void build( double h_radius_m, double v_radius_m,
 276                 double sun_size, double moon_size,
 277                 const SGEphemeris& eph, SGPropertyNode *property_tree_node );
 278
 279     /**
 280      * Repaint the sky components based on current value of sun_angle,
 281      * sky, and fog colors.  You can also specify new star and planet
 282      * data so that we can optionally change the magnitude of these
 283      * (for day/night transitions.)  See discussion in detailed
 284      * class description.
 285      *
 286      * Sun and moon angles are specified in degrees relative to local up
 287      * <li> 0 degrees = high noon
 288      * <li> 90 degrees = sun rise/set
 289      * <li> 180 degrees = darkest midnight
 290      * @param sky_color the base sky color (for the top of the dome)
 291      * @param fog_color the fog color (for the horizon)
 292      * @param sun_angle the sun angle with the horizon (for sunrise/sunset
 293      *        effects)
 294      * @param moon_angle the moon angle (so we can make it more yellow
 295      *        at the horizon)
 296      * @param nplanets number of planets
 297      * @param planet_data an array of planet right ascensions, declinations,
 298      *        and magnitudes
 299      * @param nstars number of stars
 300      * @param star_data an array of star right ascensions, declinations,
 301      *        and magnitudes
 302      */
 303     bool repaint( const SGSkyColor &sc, const SGEphemeris& eph );
 304
 305     /**
 306      * Reposition the sky at the specified origin and orientation
 307      *
 308      * lon specifies a rotation about the Z axis
 309      * lat specifies a rotation about the new Y axis
 310      * spin specifies a rotation about the new Z axis (this allows
 311      * additional orientation for the sunrise/set effects and is used
 312      * by the skydome and perhaps clouds.  See discussion in detailed
 313      * class description.
 314      * @param view_pos specify your view position in world Cartesian
 315      *        coordinates
 316      * @param zero_elev the zero elevation position in world Cartesian
 317      *        coordinates
 318      * @param view_up the up vector in world Cartesian coordinates
 319      * @param lon current longitude
 320      * @param lat current latitude
 321      * @param alt current altitude
 322      * @param spin an offset angle for orienting the sky effects with the
 323      *        sun position so sunset and sunrise effects look correct.
 324      * @param gst GMT side real time
 325      * @param sun_ra the sun's current right ascension
 326      * @param sun_dec the sun's current declination
 327      * @param sun_dist the sun's distance from the current view point
 328      *        (to keep it inside your view volume.)
 329      * @param moon_ra the moon's current right ascension
 330      * @param moon_dec the moon's current declination
 331      * @param moon_dist the moon's distance from the current view point.
 332      */
 333     bool reposition( const SGSkyState &st, const SGEphemeris& eph, double dt = 0.0 );
 334
 335     /**
 336      * Modify the given visibility based on cloud layers, thickness,
 337      * transition range, and simulated "puffs".  See discussion in detailed
 338      * class description.
 339      * @param alt current altitude
 340      * @param time_factor amount of time since modify_vis() last called so
 341      *        we can scale effect rates properly despite variable frame rates.
 342      */
 343     void modify_vis( float alt, float time_factor );
 344
 345     osg::Node* getPreRoot() { return pre_root.get(); }
 346     osg::Node* getCloudRoot() { return cloud_root.get(); }
 347
 348     /**
 349      * Specify the texture path (optional, defaults to current directory)
 350      * @param path base path to texture locations
 351      */
 352     void texture_path( const string& path );
 353
 354     /** Enable drawing of the sky. */
 355     inline void enable() {
 356         pre_selector->setValue(0, 1);
 357     }
 358
 359     /**
 360      * Disable drawing of the sky in the scene graph.  The leaf node is still
 361      * there, how ever it won't be traversed on by ssgCullandRender()
 362      */
 363     inline void disable() {
 364         pre_selector->setValue(0, 0);
 365     }
 366
 367     /**
 368      * Get the current sun color
 369      */
 370     inline SGVec4f get_sun_color() { return oursun->get_color(); }
 371
 372     /**
 373      * Get the current scene color
 374      */
 375     inline SGVec4f get_scene_color() { return oursun->get_scene_color(); }
 376
 377     /**
 378      * Add a cloud layer.
 379      *
 380      * Transfer pointer ownership to this object.
 381      *
 382      * @param layer The new cloud layer to add.
 383      */
 384     void add_cloud_layer (SGCloudLayer * layer);
 385
 386
 387     /**
 388      * Get a cloud layer (const).
 389      *
 390      * Pointer ownership remains with this object.
 391      *
 392      * @param i The index of the cloud layer, zero-based.
 393      * @return A const pointer to the cloud layer.
 394      */
 395     const SGCloudLayer * get_cloud_layer (int i) const;
 396
 397
 398     /**
 399      * Get a cloud layer (non-const).
 400      *
 401      * Pointer ownership remains with this object.
 402      *
 403      * @param i The index of the cloud layer, zero-based.
 404      * @return A non-const pointer to the cloud layer.
 405      */
 406     SGCloudLayer * get_cloud_layer (int i);
 407
 408
 409     /**
 410      * Return the number of cloud layers currently available.
 411      *
 412      * @return The cloud layer count.
 413      */
 414     int get_cloud_layer_count () const;
 415
 416
 417     /** @return current effective visibility */
 418     inline float get_visibility() const { return effective_visibility; }
 419
 420     /** Set desired clear air visibility.
 421      * @param v visibility in meters
 422      */
 423     inline void set_visibility( float v ) {
 424         effective_visibility = visibility = (v <= 25.0) ? 25.0 : v;
 425     }
 426
 427     /** Get 3D cloud density */
 428     virtual double get_3dCloudDensity() const;
 429
 430     /** Set 3D cloud density
 431      * @param density 3D cloud density
 432      */
 433     virtual void set_3dCloudDensity(double density);
 434
 435     /** Get 3D cloud visibility range*/
 436     virtual float get_3dCloudVisRange() const;
 437
 438     /** Set 3D cloud visibility range
 439      * @param density 3D cloud visibility range
 440      */
 441     virtual void set_3dCloudVisRange(float vis);
 442
 443 };
 444
 445
 446 #endif // _SG_SKY_HXX