From 70f763dbe049b5e52197aece1796b898aa3e3340 Mon Sep 17 00:00:00 2001 From: curt Date: Wed, 11 Jun 2003 18:55:36 +0000 Subject: [PATCH] - 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 | 5 +++ simgear/scene/sky/cloud.hxx | 85 ++++++++++++++++++++++++++++--------- simgear/scene/sky/sky.cxx | 16 +++---- simgear/scene/sky/sky.hxx | 20 +++++---- 4 files changed, 88 insertions(+), 38 deletions(-) diff --git a/DoxygenMain.cxx b/DoxygenMain.cxx index 8a65e965..592e9409 100644 --- a/DoxygenMain.cxx +++ b/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. * diff --git a/simgear/scene/sky/cloud.hxx b/simgear/scene/sky/cloud.hxx index 92463f1d..3853aeb3 100644 --- a/simgear/scene/sky/cloud.hxx +++ b/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: diff --git a/simgear/scene/sky/sky.cxx b/simgear/scene/sky/sky.cxx index 0a767aa2..00dd715e 100644 --- a/simgear/scene/sky/sky.cxx +++ b/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, - int nplanets, sgdVec3 *planet_data, - double planet_dist, - int nstars, sgdVec3 *star_data, double star_dist ) +void SGSky::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 ) { 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) ); diff --git a/simgear/scene/sky/sky.hxx b/simgear/scene/sky/sky.hxx index 46d69cda..c05b31ce 100644 --- a/simgear/scene/sky/sky.hxx +++ b/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,