simgear  3.5.0 [next] git://gitorious.org/fg/simgear.git
SimGear - Simulator Construction Tools
SGSky Class Reference

#include <sky.hxx>

Public Member Functions

 SGSky (void)
 
 ~SGSky (void)
 
void add_cloud_layer (SGCloudLayer *layer)
 
void build (double h_radius_m, double v_radius_m, double sun_size, double moon_size, const SGEphemeris &eph, SGPropertyNode *node, simgear::SGReaderWriterOptions *options)
 
double get_3dCloudDensity () const
 
float get_3dCloudImpostorDistance () const
 
float get_3dCloudLoD1Range () const
 
float get_3dCloudLoD2Range () const
 
bool get_3dCloudUseImpostors () const
 
float get_3dCloudVisRange () const
 
bool get_3dCloudWrap () const
 
const SGCloudLayerget_cloud_layer (int i) const
 
SGCloudLayerget_cloud_layer (int i)
 
int get_cloud_layer_count () const
 
SGVec4f get_scene_color ()
 
SGVec4f get_sun_color ()
 
float get_visibility () const
 
osg::GroupgetCloudRoot ()
 
osg::GroupgetPreRoot ()
 
void modify_vis (float alt, float time_factor)
 
bool repaint (const SGSkyColor &sky_color, const SGEphemeris &eph)
 
bool reposition (const SGSkyState &sky_state, const SGEphemeris &eph, double dt=0.0)
 
void set_3dCloudDensity (double density)
 
void set_3dCloudImpostorDistance (float vis)
 
void set_3dCloudLoD1Range (float vis)
 
void set_3dCloudLoD2Range (float vis)
 
void set_3dCloudUseImpostors (bool imp)
 
void set_3dCloudVisRange (float vis)
 
void set_3dCloudWrap (bool wrap)
 
void set_clouds_enabled (bool enabled)
 
void set_visibility (float v)
 
void texture_path (const std::string &path)
 

Private Types

typedef layer_list_type::const_iterator layer_list_const_iterator
 
typedef layer_list_type::iterator layer_list_iterator
 
typedef std::vector< SGSharedPtr< SGCloudLayer > > layer_list_type
 

Private Attributes

osg::ref_ptr< osg::MatrixTransform_ephTransform
 
layer_list_type cloud_layers
 
osg::ref_ptr< osg::Switchcloud_root
 
double clouds_3d_density
 
bool clouds_3d_enabled
 
SGSharedPtr< SGSkyDomedome
 
float effective_visibility
 
int in_cloud
 
bool in_puff
 
SGSharedPtr< SGMoonmoon
 
SGSharedPtr< SGSunoursun
 
SGSharedPtr< SGStarsplanets
 
osg::ref_ptr< osg::Grouppre_root
 
osg::ref_ptr< osg::Grouppre_transform
 
double puff_length
 
double puff_progression
 
double ramp_down
 
double ramp_up
 
mt seed
 
SGSharedPtr< SGStarsstars
 
SGPath tex_path
 
float visibility
 

Detailed Description

A class to model a realistic (time/date/position) based sky.

Introduction

The SGSky class models a blended sky dome, a haloed sun, a textured moon with phase that properly matches the date, stars and planets, and cloud layers. SGSky is designed to be dropped into existing plib based applications and depends heavily on plib's scene graph library, ssg. The sky implements various time of day lighting effects, it plays well with fog and visibility effects, and implements scudded cloud fly-through effects. Additionally, you can wire in the output of the SGEphemeris class to accurately position all the objects in the sky.

Building the sky

Once you have created an instance of SGSky you must call the build() method. Building the sky requires several textures. So, you must specify the path/directory where these textures reside before building the sky. You do this first by calling the texture_path() method.

The arguments you pass to the build() method allow you to specify 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

Cloud layers can be added, changed, or removed individually. To add a cloud layer use the add_cloud_layer() method. The arguments allow you to specify base height above sea level, layer thickness, a transition zone for entering/leaving the cloud layer, the size of the cloud object, and the type of cloud texture. All distances are in meters. There are additional forms of this method that allow you to specify your own ssgSimpleState or texture name for drawing the cloud layer.

Repainting the Sky

As the sun circles the globe, you can call the repaint() method to recolor the sky objects to simulate sunrise and sunset effects, visibility, and other lighting changes. The arguments allow you to specify a base sky color (for the top of the dome), a fog color (for the horizon), the sun angle with the horizon (for sunrise/sunset effects), the moon angle (so we can make it more yellow at the horizon), and new star and planet data so that we can optionally change the magnitude of these (for day / night transitions.)

Positioning Sky Objects

As time progresses and as you move across the surface of the earth, the apparent position of the objects and the various lighting effects can change. the reposition() method allows you to specify the positions of all the sky objects as well as your view position. The arguments allow you to specify your view position in world Cartesian coordinates, the zero elevation position in world Cartesian coordinates (your longitude, your latitude, sea level), the up'' vector in world Cartesian coordinates, current longitude, latitude, and altitude. Aspin'' angle can be specified for orienting the sky with the sun position so sunset and sunrise effects look correct. You must specify GMT side real time, the sun right ascension, sun declination, and sun distance from view point (to keep it inside your view volume.) You also must specify moon right ascension, moon declination, and moon distance from view point.

Rendering the Sky

The sky is designed to be rendered in three stages. The first stage renders the parts that form your back drop - the sky dome, the stars and planets, the sun, and the moon. These should be rendered before the rest of your scene by calling the preDraw() method. The second stage renders the clouds that are above the viewer. This stage is done before translucent objects in the main scene are drawn. It is seperated from the preDraw routine to enable to implement a multi passes technique and is located in the drawUpperClouds() method. The third stage renders the clouds that are below the viewer an which are likely to be translucent (depending on type) and should be drawn after your scene has been rendered. Use the drawLowerClouds() method to draw the second stage of the sky.

A typical application might do the following:

  • thesky->preDraw( my_altitude );
  • thesky->drawUpperClouds();
  • ssgCullAndDraw ( myscene ) ;
  • thesky->drawLowerClouds();

The current altitude in meters is passed to the preDraw() method so the clouds layers can be rendered correction from most distant to closest.

Visibility Effects

Visibility and fog is important for correctly rendering the sky. You can inform SGSky of the current visibility by calling the set_visibility() method.

When transitioning through clouds, it is nice to pull in the fog as you get close to the cloud layer to hide the fact that the clouds are drawn as a flat polygon. As you get nearer to the cloud layer it is also nice to temporarily pull in the visibility to simulate the effects of flying in and out of the puffy edge of the cloud. These effects can all be accomplished by calling the modify_vis() method. The arguments allow you to specify your current altitude (which is then compared to the altitudes of the various cloud layers.) You can also specify a time factor which should be the length in seconds since the last time you called modify_vis(). The time_factor value allows the puffy cloud effect to be calculated correctly.

The modify_vis() method alters the SGSky's internal idea of visibility, so you should subsequently call get_visibility() to get the actual modified visibility. You should then make the appropriate glFog() calls to setup fog properly for your scene.

Accessor Methods

Once an instance of SGSky has been successfully initialized, there are a couple accessor methods you can use such as get_num_layers() to return the number of cloud layers, get_cloud_layer(i) to return cloud layer number i, get_visibility() to return the actual visibility as modified by the sky/cloud model.

Definition at line 213 of file sky.hxx.

Member Typedef Documentation

typedef layer_list_type::const_iterator SGSky::layer_list_const_iterator
private

Definition at line 218 of file sky.hxx.

typedef layer_list_type::iterator SGSky::layer_list_iterator
private

Definition at line 217 of file sky.hxx.

typedef std::vector<SGSharedPtr<SGCloudLayer> > SGSky::layer_list_type
private

Definition at line 216 of file sky.hxx.

Constructor & Destructor Documentation

SGSky::SGSky ( void  )

Constructor

Definition at line 40 of file sky.cxx.

SGSky::~SGSky ( void  )

Destructor

Definition at line 75 of file sky.cxx.

Member Function Documentation

void SGSky::add_cloud_layer ( SGCloudLayer layer)

Add a cloud layer.

Transfer pointer ownership to this object.

Parameters
layerThe new cloud layer to add.

Definition at line 198 of file sky.cxx.

void SGSky::build ( double  h_radius_m,
double  v_radius_m,
double  sun_size,
double  moon_size,
const SGEphemeris eph,
SGPropertyNode node,
simgear::SGReaderWriterOptions options 
)

Initialize the sky and connect the components to the scene graph at the provided branch.

Note
See discussion in detailed class description.
Parameters
h_radius_mHorizontal radius of sky dome
v_radius_mVertical radius of sky dome
sun_sizeSize of sun
moon_sizeSize of moon
ephCurrent positions of planets and stars
nodeProperty node connecting sun with environment
options

Definition at line 82 of file sky.cxx.

double SGSky::get_3dCloudDensity ( ) const

Get 3D cloud density

Definition at line 224 of file sky.cxx.

float SGSky::get_3dCloudImpostorDistance ( ) const

Get 3D cloud impostor distance

Definition at line 245 of file sky.cxx.

float SGSky::get_3dCloudLoD1Range ( ) const

Get 3D cloud LoD1 Range

Definition at line 257 of file sky.cxx.

float SGSky::get_3dCloudLoD2Range ( ) const

Get 3D cloud LoD2 Range

Definition at line 269 of file sky.cxx.

bool SGSky::get_3dCloudUseImpostors ( ) const

Get 3D cloud impostor usage

Definition at line 290 of file sky.cxx.

float SGSky::get_3dCloudVisRange ( ) const

Get 3D cloud visibility range

Definition at line 233 of file sky.cxx.

bool SGSky::get_3dCloudWrap ( ) const

Get 3D cloud wrapping

Definition at line 281 of file sky.cxx.

const SGCloudLayer * SGSky::get_cloud_layer ( int  i) const

Get a cloud layer (const).

Pointer ownership remains with this object.

Parameters
iThe index of the cloud layer, zero-based.
Returns
A const pointer to the cloud layer.

Definition at line 207 of file sky.cxx.

SGCloudLayer * SGSky::get_cloud_layer ( int  i)

Get a cloud layer (non-const).

Pointer ownership remains with this object.

Parameters
iThe index of the cloud layer, zero-based.
Returns
A non-const pointer to the cloud layer.

Definition at line 213 of file sky.cxx.

int SGSky::get_cloud_layer_count ( ) const

Return the number of cloud layers currently available.

Returns
The cloud layer count.

Definition at line 219 of file sky.cxx.

SGVec4f SGSky::get_scene_color ( )
inline

Get the current scene color

Definition at line 339 of file sky.hxx.

SGVec4f SGSky::get_sun_color ( )
inline

Get the current sun color

Definition at line 334 of file sky.hxx.

float SGSky::get_visibility ( ) const
inline
Returns
current effective visibility

Definition at line 382 of file sky.hxx.

osg::Group* SGSky::getCloudRoot ( )
inline

Definition at line 322 of file sky.hxx.

osg::Group* SGSky::getPreRoot ( )
inline

Definition at line 321 of file sky.hxx.

void SGSky::modify_vis ( float  alt,
float  time_factor 
)

Modify the given visibility based on cloud layers, thickness, transition range, and simulated "puffs".

Note
See discussion in detailed class description.
Parameters
altcurrent altitude
time_factoramount of time since modify_vis() last called so we can scale effect rates properly despite variable frame rates.

Definition at line 305 of file sky.cxx.

bool SGSky::repaint ( const SGSkyColor sky_color,
const SGEphemeris eph 
)

Repaint the sky components based on current sun angle, and sky and fog colors.

Note
See discussion in detailed class description.
Parameters
sky_colorThe base sky color (for the top of the dome)
ephCurrent positions of planets and stars

Definition at line 117 of file sky.cxx.

bool SGSky::reposition ( const SGSkyState sky_state,
const SGEphemeris eph,
double  dt = 0.0 
)

Reposition the sky at the specified origin and orientation.

Note
See discussion in detailed class description.

Definition at line 145 of file sky.cxx.

void SGSky::set_3dCloudDensity ( double  density)

Set 3D cloud density

Parameters
density3D cloud density

Definition at line 228 of file sky.cxx.

void SGSky::set_3dCloudImpostorDistance ( float  vis)

Set 3D cloud impostor distance

Parameters
vis3D cloud impostor distance

Definition at line 249 of file sky.cxx.

void SGSky::set_3dCloudLoD1Range ( float  vis)

Set 3D cloud LoD1 Range

Parameters
visLoD1 Range

Definition at line 261 of file sky.cxx.

void SGSky::set_3dCloudLoD2Range ( float  vis)

Set 3D cloud LoD2 Range

Parameters
visLoD2 Range

Definition at line 273 of file sky.cxx.

void SGSky::set_3dCloudUseImpostors ( bool  imp)

Set 3D cloud impostor usage

Parameters
impwhether use impostors for 3D clouds

Definition at line 294 of file sky.cxx.

void SGSky::set_3dCloudVisRange ( float  vis)

Set 3D cloud visibility range

Parameters
vis3D cloud visibility range

Definition at line 237 of file sky.cxx.

void SGSky::set_3dCloudWrap ( bool  wrap)

Set 3D cloud wrapping

Parameters
wrapwhether to wrap 3D clouds

Definition at line 285 of file sky.cxx.

void SGSky::set_clouds_enabled ( bool  enabled)

Definition at line 432 of file sky.cxx.

void SGSky::set_visibility ( float  v)

Set desired clear air visibility.

Parameters
vvisibility in meters

Definition at line 192 of file sky.cxx.

void SGSky::texture_path ( const std::string &  path)

Specify the texture path (optional, defaults to current directory)

Parameters
pathBase path to texture locations

Definition at line 299 of file sky.cxx.

Member Data Documentation

osg::ref_ptr<osg::MatrixTransform> SGSky::_ephTransform
private

Definition at line 231 of file sky.hxx.

Referenced by build(), reposition(), and SGSky().

osg::ref_ptr<osg::Switch> SGSky::cloud_root
private

Definition at line 229 of file sky.hxx.

Referenced by add_cloud_layer(), set_clouds_enabled(), and SGSky().

double SGSky::clouds_3d_density
private

Definition at line 252 of file sky.hxx.

Referenced by SGSky().

bool SGSky::clouds_3d_enabled
private

Definition at line 249 of file sky.hxx.

Referenced by add_cloud_layer(), and SGSky().

SGSharedPtr<SGSkyDome> SGSky::dome
private

Definition at line 221 of file sky.hxx.

Referenced by build(), repaint(), and reposition().

float SGSky::effective_visibility
private

Definition at line 237 of file sky.hxx.

Referenced by get_visibility(), modify_vis(), repaint(), and SGSky().

int SGSky::in_cloud
private

Definition at line 239 of file sky.hxx.

Referenced by SGSky().

bool SGSky::in_puff
private

Definition at line 242 of file sky.hxx.

Referenced by modify_vis(), and SGSky().

SGSharedPtr<SGMoon> SGSky::moon
private

Definition at line 223 of file sky.hxx.

Referenced by build(), repaint(), and reposition().

SGSharedPtr<SGSun> SGSky::oursun
private

Definition at line 222 of file sky.hxx.

Referenced by build(), repaint(), and reposition().

SGSharedPtr<SGStars> SGSky::planets
private

Definition at line 224 of file sky.hxx.

Referenced by build(), and repaint().

osg::ref_ptr<osg::Group> SGSky::pre_root
private

Definition at line 228 of file sky.hxx.

Referenced by build(), and SGSky().

osg::ref_ptr<osg::Group> SGSky::pre_transform
private

Definition at line 228 of file sky.hxx.

Referenced by build(), and SGSky().

double SGSky::puff_length
private

Definition at line 243 of file sky.hxx.

Referenced by modify_vis(), and SGSky().

double SGSky::puff_progression
private

Definition at line 244 of file sky.hxx.

Referenced by modify_vis(), and SGSky().

double SGSky::ramp_down
private

Definition at line 246 of file sky.hxx.

Referenced by modify_vis(), and SGSky().

double SGSky::ramp_up
private

Definition at line 245 of file sky.hxx.

Referenced by modify_vis(), and SGSky().

mt SGSky::seed
private

Definition at line 255 of file sky.hxx.

Referenced by modify_vis(), and SGSky().

SGSharedPtr<SGStars> SGSky::stars
private

Definition at line 225 of file sky.hxx.

Referenced by build(), and repaint().

SGPath SGSky::tex_path
private

Definition at line 233 of file sky.hxx.

Referenced by build(), and texture_path().

float SGSky::visibility
private

Definition at line 236 of file sky.hxx.

Referenced by modify_vis(), set_visibility(), and SGSky().


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