head 1.4; access; symbols; locks; strict; comment @# @; 1.4 date 2002.09.07.01.50.36; author curt; state Exp; branches; next 1.3; 1.3 date 2002.08.31.19.01.51; author curt; state Exp; branches; next 1.2; 1.2 date 2002.08.31.18.53.59; author curt; state Exp; branches; next 1.1; 1.1 date 2002.02.15.17.21.55; author curt; state Exp; branches; next ; desc @@ 1.4 log @Updated doxygen docs. @ text @
Main Page Class Hierarchy Compound List File List Compound Members File Members

# SGSky Class Reference

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

`#include <sky.hxx>`

List of all members.

## Public Methods
| SGSky (void)
| Constructor.
| ~SGSky (void)
| Destructor.
void | build (double sun_size, double moon_size, int nplanets, sgdVec3 *planet_data, double planet_dist, int nstars, sgdVec3 *star_data, double star_dist)
| Initialize the sky and connect the components to the scene graph at the provided branch.
bool | repaint (sgVec4 sky_color, sgVec4 fog_color, double sun_angle, double moon_angle, int nplanets, sgdVec3 *planet_data, int nstars, sgdVec3 *star_data)
| Repaint the sky components based on current value of sun_angle, sky, and fog colors.
bool | reposition (sgVec3 view_pos, sgVec3 zero_elev, sgVec3 view_up, double lon, double lat, double alt, double spin, double gst, double sun_ra, double sun_dec, double sun_dist, double moon_ra, double moon_dec, double moon_dist)
| Reposition the sky at the specified origin and orientation.
void | modify_vis (float alt, float time_factor)
| Modify the given visibility based on cloud layers, thickness, transition range, and simulated "puffs".
void | preDraw ()
| Draw background portions of the sky ...
void | postDraw (float alt)
| Draw translucent clouds ...
void | texture_path (const string &path)
| Specify the texture path (optional, defaults to current directory).
void | enable ()
| Enable drawing of the sky.
void | disable ()
| Disable drawing of the sky in the scene graph.
void | add_cloud_layer (SGCloudLayer *layer)
| Add a cloud layer.
const SGCloudLayer * | get_cloud_layer (int i) const
| Get a cloud layer (const).
SGCloudLayer * | get_cloud_layer (int i)
| Get a cloud layer (non-const).
int | get_cloud_layer_count () const
| Return the number of cloud layers currently available.
float | get_visibility () const
void | set_visibility (float v)
| Set desired clear air 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 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.

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. A ``spin'' 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 two 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 which are likely to be translucent (depending on type) and should be drawn after your scene has been rendered. Use the postDraw() method to draw the second stage of the sky.

A typical application might do the following:

- thesky->preDraw();
- ssgCullAndDraw ( myscene ) ;
- thesky->postDraw( my_altitude );

  The current altitude in meters is passed to the postDraw() 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 184 of file sky.hxx.

  ## Member Function Documentation

  void SGSky::add_cloud_layer | ( | SGCloudLayer * | layer | ) |

    | Add a cloud layer. Transfer pointer ownership to this object. Parameters:
    layer | The new cloud layer to add.
  Definition at line 234 of file sky.cxx.

  void SGSky::build | ( | double | sun_size,
  |  | double | moon_size,
  |  | int | nplanets,
  |  | sgdVec3 * | planet_data,
  |  | double | planet_dist,
  |  | int | nstars,
  |  | sgdVec3 * | star_data,
  |  | double | star_dist
  | ) |

    | Initialize the sky and connect the components to the scene graph at the provided branch. See discussion in detailed class description. Parameters:
    sun_size | size of sun
    moon_size | size of moon
    nplanets | number of planets
    planet_data | an array of planet right ascensions, declinations, and magnitudes
    planet_dist | distance from viewer to put the planets
    nstars | number of stars
    star_data | an array of star right ascensions, declinations, and magnitudes
    star_dist | distance from viewer to put the stars
  Definition at line 59 of file sky.cxx.

  void SGSky::disable | ( |  | ) | `[inline]`

  | Disable drawing of the sky in the scene graph. The leaf node is still there, how ever it won't be traversed on by ssgCullandRender() Definition at line 346 of file sky.hxx. Referenced by repaint().

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

    | Get a cloud layer (non-const). Pointer ownership remains with this object. Parameters:
    i | The index of the cloud layer, zero-based.
  Returns: A non-const pointer to the cloud layer. Definition at line 246 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:
    i | The index of the cloud layer, zero-based.
  Returns: A const pointer to the cloud layer. Definition at line 240 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 252 of file sky.cxx.

  float SGSky::get_visibility | ( |  | ) | const`[inline]`

  | Returns: current effective visibility Definition at line 392 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". See discussion in detailed class description. Parameters:
    alt | current altitude
    time_factor | amount of time since modify_vis() last called so we can scale effect rates properly despite variable frame rates.
  Definition at line 259 of file sky.cxx.

  void SGSky::postDraw | ( | float | alt | ) |

    | Draw translucent clouds ... do this after you've drawn all the oapaque elements of your scene. See discussion in detailed class description. Parameters:
    alt | current altitude
  Definition at line 170 of file sky.cxx.

  void SGSky::preDraw | ( |  | ) |

  | Draw background portions of the sky ... do this before you draw the rest of your scene. See discussion in detailed class description. Definition at line 163 of file sky.cxx.

  bool SGSky::repaint | ( | sgVec4 | sky_color,
  |  | sgVec4 | fog_color,
  |  | double | sun_angle,
  |  | double | moon_angle,
  |  | int | nplanets,
  |  | sgdVec3 * | planet_data,
  |  | int | nstars,
  |  | sgdVec3 * | star_data
  | ) |

  | Repaint the sky components based on current value of sun_angle, sky, and fog colors. You can also specify new star and planet data so that we can optionally change the magnitude of these (for day/night transitions.) See discussion in detailed class description. Sun and moon angles are specified in degrees relative to local up

- 0 degrees = high noon
- 90 degrees = sun rise/set
- 180 degrees = darkest midnight
  Parameters:

    sky_color | the base sky color (for the top of the dome)
    fog_color | the fog color (for the horizon)
    sun_angle | the sun angle with the horizon (for sunrise/sunset effects)
    moon_angle | the moon angle (so we can make it more yellow at the horizon)
    nplanets | number of planets
    planet_data | an array of planet right ascensions, declinations, and magnitudes
    nstars | number of stars
    star_data | an array of star right ascensions, declinations, and magnitudes

  Definition at line 108 of file sky.cxx.

  References disable(), and enable().

  bool SGSky::reposition | ( | sgVec3 | view_pos,
  |  | sgVec3 | zero_elev,
  |  | sgVec3 | view_up,
  |  | double | lon,
  |  | double | lat,
  |  | double | alt,
  |  | double | spin,
  |  | double | gst,
  |  | double | sun_ra,
  |  | double | sun_dec,
  |  | double | sun_dist,
  |  | double | moon_ra,
  |  | double | moon_dec,
  |  | double | moon_dist
  | ) |

    | Reposition the sky 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 (this allows additional orientation for the sunrise/set effects and is used by the skydome and perhaps clouds. See discussion in detailed class description. Parameters:
    view_pos | specify your view position in world Cartesian coordinates
    zero_elev | the zero elevation position in world Cartesian coordinates
    view_up | the up vector in world Cartesian coordinates
    lon | current longitude
    lat | current latitude
    alt | current altitude
    spin | an offset angle for orienting the sky effects with the sun position so sunset and sunrise effects look correct.
    gst | GMT side real time
    sun_ra | the sun's current right ascension
    sun_dec | the sun's current declination
    sun_dist | the sun's distance from the current view point (to keep it inside your view volume.)
    moon_ra | the moon's current right ascension
    moon_dec | the moon's current declination
    moon_dist | the moon's distance from the current view point.
  Definition at line 140 of file sky.cxx.

  void SGSky::set_visibility | ( | float | v | ) | `[inline]`

    | Set desired clear air visibility. Parameters:
    v | visibility in meters
  Definition at line 397 of file sky.hxx.

  void SGSky::texture_path | ( | const string & | path | ) | `[inline]`

    | Specify the texture path (optional, defaults to current directory). Parameters:
    path | base path to texture locations
  Definition at line 332 of file sky.hxx.

  The documentation for this class was generated from the following files:
  - sky.hxx
  - sky.cxx

@ 1.3 log @Oops, try again. @ text @d871 1 a871 1