SilverLining
Public Member Functions | List of all members
SilverLining::AtmosphericConditions Class Reference

A class to set the current simulation conditions for the sky. More...

#include <AtmosphericConditions.h>

Inheritance diagram for SilverLining::AtmosphericConditions:
Inheritance graph
[legend]
Collaboration diagram for SilverLining::AtmosphericConditions:
Collaboration graph
[legend]

Public Member Functions

 AtmosphericConditions ()
 Default constructor.
 
virtual ~AtmosphericConditions ()
 Destructor.
 
void SILVERLINING_API SetLocation (const Location &location, void *data=0)
 Sets the simulated geographic location.
 
const Location &SILVERLINING_API GetLocation (void *data=0) const
 Gets the current simulated location.
 
void SILVERLINING_API SetTime (const LocalTime &time, void *data=0)
 Sets the simulated time of day in local time.
 
const LocalTime &SILVERLINING_API GetTime (void *data=0)
 Retrieves the currently simulated time of day.
 
void SILVERLINING_API SetPresetConditions (ConditionPresets preset, Atmosphere &atm, void *data=0)
 A quick way to set up typical weather conditions.
 
int SILVERLINING_API SetWind (const WindVolume &windVolume)
 Sets a volume of wind for moving clouds.
 
bool SILVERLINING_API RemoveWindVolume (int windVolumeHandle)
 Removes a specific wind volume from the simulation.
 
void SILVERLINING_API ClearWindVolumes ()
 Clears all wind volumes previously set via SetWind.
 
void SILVERLINING_API GetWind (double &velocity, double &heading, double altitude) const
 Retrieves the simulated wind at a given altitude.
 
void SILVERLINING_API ApplyWind (double dt, void *data=0)
 Apply wind to cloud layers for given time step.
 
const SL_MAP (int, WindVolume) &SILVERLINING_API GetWindVolumes() const
 Get a vector of all wind volumes being simulated.
 
int SILVERLINING_API AddCloudLayer (CloudLayer *layer)
 Adds a cloud layer to the simulated atmospheric conditions.
 
bool SILVERLINING_API HasCloudLayer (const CloudLayer *layer) const
 Whether a cloud layer exists in the atmospheric conditions.
 
bool SILVERLINING_API RemoveCloudLayer (int layerHandle, void *data=0, bool destroy=true, bool removeEntry=true)
 Removes a previously added cloud deck from the scene.
 
void SILVERLINING_API RemoveAllCloudLayers (void *data=0, bool destroy=true, bool removeEntry=true)
 Removes all cloud layers from the scene.
 
bool SILVERLINING_API GetCloudLayer (int layerHandle, CloudLayer **layer)
 Obtain a pointer to a CloudLayer object.
 
 SL_MAP (int, CloudLayer *) &SILVERLINING_API GetCloudLayers()
 Obtain the stl map of CloudLayer objects.
 
void SILVERLINING_API SetTurbidity (double pTurbidity)
 Sets the "turbidity" of the simulated atmosphere.
 
double SILVERLINING_API GetTurbidity () const
 Get the simulated atmospheric turbidity.
 
void SILVERLINING_API SetVisibility (double range)
 Sets the simulated visibility in meters; this will affect the appearance of clouds in the distance.
 
double SILVERLINING_API GetVisibility () const
 Retrieves the currently simulated visibility, in meters.
 
void SILVERLINING_API SetFog (double density, double r, double g, double b)
 Explicitly sets exponential fog color and density, if you need to match an existing scene.
 
void SILVERLINING_API ClearFog ()
 Clears explicitly set fog from SetFog(), and reverts the fog to simulating the visibility specified in SetVisibility() instead.
 
void SILVERLINING_API GetFog (bool &fogIsSet, double &density, double &r, double &g, double &b)
 Retrieves the explicit fog (if any) set by SetFog().
 
void SILVERLINING_API SetLightPollution (double Wm2)
 Sets the simulated amount of nighttime light pollution, in watts per square meter.
 
double SILVERLINING_API GetLightPollution () const
 Retrieves the currently simulated light pollution, in watts per square meter.
 
void SILVERLINING_API SetPrecipitation (int precipitationType, double precipitationRate, double nearClip=-1, double farClip=-1, bool bUseDepthBuffer=false, void *data=0)
 Simulates global precipitation of a specified type.
 
void SILVERLINING_API EnablePrecipitation (bool enabled, void *data=0)
 Used to temporarily enable or disable all precipitation effects.
 
void SILVERLINING_API SetPrecipitationWind (double windX, double windZ)
 Sets a precipitation specific wind vector which is additive to any global wind set at the AtmosphericConditions level.
 
void SILVERLINING_API GetPrecipitationWind (double &windX, double &windZ) const
 Retrieves the precipitation specific wind vector.
 
void SILVERLINING_API EnableTimePassage (bool enabled, long relightFrequencyMS, void *data=0)
 By default, SilverLining will "freeze" time at the time specified by AtmosphericConditions::SetTime().
 
void SILVERLINING_API SetMillisecondTimer (const MillisecondTimer *timer, void *data=0)
 By default, SilverLining will simulate the motion of clouds in the wind and the motion of astronomical objects (when EnableTimePassage() is active) by calling the system's millisecond timer.
 
const MillisecondTimer *SILVERLINING_API GetMillisecondTimer () const
 Retrieves the MillisecondTimer previously set by SetMillisecondTimer(), or the default timer if SetMillisecondTimer() is unset or set to NULL.
 
bool SILVERLINING_API Serialize (std::ostream &stream, void *data=0)
 Flattens this object and everything in it to a stream buffer.
 
bool SILVERLINING_API Unserialize (const Atmosphere *atm, std::istream &stream, void *data=0)
 Restores this object from the stream created using Serialize()
 

Detailed Description

A class to set the current simulation conditions for the sky.

This class allows you to specify the simulated time, location, wind, visibility, haze, and cloud cover for your scene. You do so by instantiating your own AtmosphericConditions object, configuring it by calling its methods, and then passing it into your Atmosphere object via Atmosphere::SetConditions().

To make changes to the AtmosphericConditions after it has been passed into Atmosphere::SetConditions(), call Atmosphere::GetConditions() and call methods on the AtmosphericConditions reference that it returns. Atmosphere::SetConditions() copies your AtmosphericConditions into the Atmosphere class, so changes made to the AtmosphericConditions used to initialize the Atmosphere will have no effect.

Constructor & Destructor Documentation

◆ AtmosphericConditions()

SilverLining::AtmosphericConditions::AtmosphericConditions ( )

Default constructor.

Creates an AtmosphericConditions object with default settings.

◆ ~AtmosphericConditions()

virtual SilverLining::AtmosphericConditions::~AtmosphericConditions ( )
virtual

Destructor.

Destroys all members, but does not destroy the CloudLayer objects passed into AddCloudLayer().

Member Function Documentation

◆ AddCloudLayer()

int SILVERLINING_API SilverLining::AtmosphericConditions::AddCloudLayer ( CloudLayer layer)

Adds a cloud layer to the simulated atmospheric conditions.

Cloud layers are created via the CloudLayerFactory::Create() method, and won't become part of your scene until they are added to a AtmosphericConditions class that is then passed into Atmosphere::SetConditions(). The CloudLayer object will be destroyed along with this AtmosphericConditions class; there's no need to keep this object around for cleanup.

Parameters
layerA CloudLayer created via CloudLayerFactory::Create(). This CloudLayer should be configured and seeded (see CloudLayer::SeedClouds()) prior to being passed in.
Returns
An integer handle to the cloud layer that may be used in calls to RemoveCloudLayer() and GetCloudLayer().

◆ ApplyWind()

void SILVERLINING_API SilverLining::AtmosphericConditions::ApplyWind ( double  dt,
void *  data = 0 
)

Apply wind to cloud layers for given time step.

This is called by the Atmosphere class; you do not need to call this directly!

Parameters
dtLength of time to simulate wind over, in seconds.
dataAn optional ThreadCameraStreamData object that this calls pertains to.

◆ ClearFog()

void SILVERLINING_API SilverLining::AtmosphericConditions::ClearFog ( )

Clears explicitly set fog from SetFog(), and reverts the fog to simulating the visibility specified in SetVisibility() instead.

◆ ClearWindVolumes()

void SILVERLINING_API SilverLining::AtmosphericConditions::ClearWindVolumes ( )

Clears all wind volumes previously set via SetWind.

◆ EnablePrecipitation()

void SILVERLINING_API SilverLining::AtmosphericConditions::EnablePrecipitation ( bool  enabled,
void *  data = 0 
)

Used to temporarily enable or disable all precipitation effects.

Parameters
dataAn optional ThreadCameraStreamData object that this calls pertains to.

◆ EnableTimePassage()

void SILVERLINING_API SilverLining::AtmosphericConditions::EnableTimePassage ( bool  enabled,
long  relightFrequencyMS,
void *  data = 0 
)

By default, SilverLining will "freeze" time at the time specified by AtmosphericConditions::SetTime().

If you want to simulate the passage of time, call EnableTimePassage with the enabled parameter set to true.

Relighting the clouds is a relatively expensive operation, so for real time applications you probably won't want to relight the clouds every frame. The relightFrequencyMS parameter allows you to specify the interval, in milliseconds, between cloud relighting passes. The sky will continue to update in real time, along with the position of the sun, moon, and stars, between these intervals. If you have specified your own MillisecondTimer with SetMillisecondTimer(), the interval will be computed based on its concept of time.

If the enabled parameter is false (the default,) or the relightFrequencyMS parameter is set to -1, cloud relighting will only happen in response to calls to AtmosphericConditions::SetTime().

Clouds will move with respect to the simulated wind irregardless of calling this method.

Parameters
enabledTrue if you want to simulate the passage of time between calls to SetTime(); false if the simulated time should remain static.
relightFrequencyMSThe interval, in milliseconds, between cloud relighting passes. Set to -1 to prevent cloud relighting outside of calls
dataAn optional ThreadCameraStreamData object that this calls pertains to. to SetTime().

◆ GetCloudLayer()

bool SILVERLINING_API SilverLining::AtmosphericConditions::GetCloudLayer ( int  layerHandle,
CloudLayer **  layer 
)

Obtain a pointer to a CloudLayer object.

Given a cloud layer handle, obtain its underlying CloudLayer object.

Parameters
layerHandleThe integer handle to a cloud layer previously returned by AddCloudLayer().
layerA pointer to a pointer to receive the CloudLayer object pointer requested.
Returns
false if the layerHandle does not specify a CloudLayer being managed by this class.

◆ GetFog()

void SILVERLINING_API SilverLining::AtmosphericConditions::GetFog ( bool &  fogIsSet,
double &  density,
double &  r,
double &  g,
double &  b 
)

Retrieves the explicit fog (if any) set by SetFog().

Parameters
fogIsSetReturns true if SetFog has been called and ClearFog has not, meaning we are using fog with an explicitly defined application setting instead of simulating visibility.
densityThe exponential fog density term set in SetFog()
rThe red component of the fog color specified in SetFog(). Ranges from 0-1.
gThe green component of the fog color specified in SetFog(). Ranges from 0-1.
bThe blue component of the fog color specified in SetFog(). Ranges from 0-1.

◆ GetLightPollution()

double SILVERLINING_API SilverLining::AtmosphericConditions::GetLightPollution ( ) const
inline

Retrieves the currently simulated light pollution, in watts per square meter.

◆ GetLocation()

const Location &SILVERLINING_API SilverLining::AtmosphericConditions::GetLocation ( void *  data = 0) const

Gets the current simulated location.

Parameters
dataAn optional ThreadCameraStreamData object that this calls pertains to.
Returns
A const reference to a Location object that may be queried for the current simulated geographic position.

◆ GetMillisecondTimer()

const MillisecondTimer *SILVERLINING_API SilverLining::AtmosphericConditions::GetMillisecondTimer ( ) const
inline

Retrieves the MillisecondTimer previously set by SetMillisecondTimer(), or the default timer if SetMillisecondTimer() is unset or set to NULL.

◆ GetPrecipitationWind()

void SILVERLINING_API SilverLining::AtmosphericConditions::GetPrecipitationWind ( double &  windX,
double &  windZ 
) const
inline

Retrieves the precipitation specific wind vector.

See also
SetWind()

◆ GetTime()

const LocalTime &SILVERLINING_API SilverLining::AtmosphericConditions::GetTime ( void *  data = 0)

Retrieves the currently simulated time of day.

Use this to obtain the local time, time zone, and daylight savings time observance being simulated.

This will also reflect the passage of time simulated by activating EnableTimePassage(). As such, it may differ from what was originally passed into SetTime() if time passage is activated.

Parameters
dataAn optional ThreadCameraStreamData object that this calls pertains to.
Returns
A const reference to a LocalTime object, which may be queried for the local time, time zone, and DST information being simulated.

◆ GetTurbidity()

double SILVERLINING_API SilverLining::AtmosphericConditions::GetTurbidity ( ) const
inline

Get the simulated atmospheric turbidity.

See SetTurbidity() for an explanation of turbidity values.

◆ GetVisibility()

double SILVERLINING_API SilverLining::AtmosphericConditions::GetVisibility ( ) const
inline

Retrieves the currently simulated visibility, in meters.

◆ GetWind()

void SILVERLINING_API SilverLining::AtmosphericConditions::GetWind ( double &  velocity,
double &  heading,
double  altitude 
) const

Retrieves the simulated wind at a given altitude.

Parameters
velocityReceives the simulated wind velocity in meters per second
headingReceives the simulated wind direction in degrees from North
altitudeThe altitude, in meters, for which you want wind information.

◆ HasCloudLayer()

bool SILVERLINING_API SilverLining::AtmosphericConditions::HasCloudLayer ( const CloudLayer layer) const

Whether a cloud layer exists in the atmospheric conditions.

Parameters
layerA CloudLayer that is being searched for

◆ RemoveAllCloudLayers()

void SILVERLINING_API SilverLining::AtmosphericConditions::RemoveAllCloudLayers ( void *  data = 0,
bool  destroy = true,
bool  removeEntry = true 
)

Removes all cloud layers from the scene.

All CloudLayer objects currently contained by this class will be removed and deleted. Be sure your GL context or DirectX device is still active when calling this, as it will attempt to free the cloud layer's underlying graphic resources.

Parameters
dataAn optional ThreadCameraStreamData object that this calls pertains to.
destroy.internal. Do not use.
removeEntry.internal. Do not use.

◆ RemoveCloudLayer()

bool SILVERLINING_API SilverLining::AtmosphericConditions::RemoveCloudLayer ( int  layerHandle,
void *  data = 0,
bool  destroy = true,
bool  removeEntry = true 
)

Removes a previously added cloud deck from the scene.

The specified CloudLayer handle, if found, will be removed from the simulation and its CloudLayer object deleted. Be sure your GL context or DirectX device is still active when calling this, as it will attempt to free the cloud layer's underlying graphic resources.

Parameters
layerHandleThe integer handle previously returned from AddCloudLayer().
dataAn optional ThreadCameraStreamData object that this calls pertains to.
destroy.internal. Do not use.
removeEntry.internal. Do not use.
Returns
true if the cloud deck was removed, false if the handle specified was not found.

◆ RemoveWindVolume()

bool SILVERLINING_API SilverLining::AtmosphericConditions::RemoveWindVolume ( int  windVolumeHandle)

Removes a specific wind volume from the simulation.

Parameters
windVolumeHandleThe handle returned from AtmosphericConditions::SetWind().

◆ Serialize()

bool SILVERLINING_API SilverLining::AtmosphericConditions::Serialize ( std::ostream &  stream,
void *  data = 0 
)

Flattens this object and everything in it to a stream buffer.

◆ SetFog()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetFog ( double  density,
double  r,
double  g,
double  b 
)

Explicitly sets exponential fog color and density, if you need to match an existing scene.

If set, this will override the visibility effects from SetVisibility(). Color components are specified in the range 0-1. Density should be 1.0 / simulated visibility. This affects the appearance of the clouds, but not the sky. This is intended for real, thick fog, as opposed to SetVisibility(), which simulates extinction from atmospheric scattering. When using this, you'll usually want to call DrawSky() with false in the first parameter to suppress drawing the sky box, and just clear your back buffer to the fog color instead. If you do draw the sky, you may want to consider disabling the drawing of the stars, sun, and moon when calling DrawSky() if thick fog is present.

◆ SetLightPollution()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetLightPollution ( double  Wm2)
inline

Sets the simulated amount of nighttime light pollution, in watts per square meter.

Defaults to zero. A reasonable value would be in the order of 0.01

◆ SetLocation()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetLocation ( const Location location,
void *  data = 0 
)

Sets the simulated geographic location.

This affects the sun and moon positions relative to the horizon, and thereby also affects the lighting of the scene. Be sure that the location specified is consistent with the time zone specified in the LocalTime passed to SetTime(), or you will experience confusing results.

Parameters
locationA reference to a Location object that embodies the simulated latitude and longitude.
dataAn optional ThreadCameraStreamData object that this calls pertains to.

◆ SetMillisecondTimer()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetMillisecondTimer ( const MillisecondTimer timer,
void *  data = 0 
)

By default, SilverLining will simulate the motion of clouds in the wind and the motion of astronomical objects (when EnableTimePassage() is active) by calling the system's millisecond timer.

If you want to accelerate, slow, or reverse the passage of time, you may instead provide your own MillisecondTimer implementation, and pass it in here. See the documentation for the MillisecondTimer class for more details.

Parameters
timerThe MillisecondTimer object to use for moving clouds and astronomical objects over time, relative to the LocalTime passed into SetTime(). Pass NULL to restore the default timer.
dataAn optional ThreadCameraStreamData object that this calls pertains to.

◆ SetPrecipitation()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetPrecipitation ( int  precipitationType,
double  precipitationRate,
double  nearClip = -1,
double  farClip = -1,
bool  bUseDepthBuffer = false,
void *  data = 0 
)

Simulates global precipitation of a specified type.

Precipitation effects will display if the type is set to something other than NONE.

Note, you may also set precipitation effects associated with a CloudLayer that only render when the camera is underneath a rain cloud with the similar CloudLayer::SetPrecipitation() method.

For mixed precipitation, you may call SetPrecipitation multiple times with different precipitation types. To clear all precipitation, call SetPrecipitation with a type of CloudLayer::NONE. If you call this method multiple times for the same precipitation type, the intensity specified will overwrite the intensity previously specified for that type.

Parameters
precipitationTypeThe type of precipitation to simulate under this cloud layer - CloudLayer::NONE, CloudLayer::RAIN, CloudLayer::WET_SNOW, CloudLayer::DRY_SNOW, or CloudLayer::SLEET.
precipitationRateThe simulated rate of precipitation, in millimeters per hour. Reasonable ranges might be between 1 for light rain or 20 for heavier rain. This value will be clamped to the value specified by rain-max-intensity, snow-max-intensity, or sleet-max-intensity in resources/SilverLining.config, which is 30 by default.
nearClipHow close to the camera the closest precipitation particles will be rendered. The near clipping plane will be adjusted to include this distance while the precipitation is being rendered. Values less than zero will result in the default value being applied.
farClipThe farthest distance from the camera that precipitation particles will be rendered. Since there is an upper bound on the number of particles rendered per frame, changing the difference between nearClip and farClip may result in changes to the intensity of the precipitation. By default this difference is 7.5 world units. Values less than zero will result in the default value being applied.
bUseDepthBufferSet this to true if you want to enable depth buffer testing of precipitation
dataAn optional ThreadCameraStreamData object that this calls pertains to. particles against your scene.

◆ SetPrecipitationWind()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetPrecipitationWind ( double  windX,
double  windZ 
)
inline

Sets a precipitation specific wind vector which is additive to any global wind set at the AtmosphericConditions level.

The vector itself specifies the wind direction and the length of the vector provides the wind velocity.

Parameters
windXThe east vector of the precipitation specific wind, in meters/s.
windZThe south vector of the precipitation specific wind, in meters/s.
See also
GetWind()

◆ SetPresetConditions()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetPresetConditions ( ConditionPresets  preset,
Atmosphere atm,
void *  data = 0 
)

A quick way to set up typical weather conditions.

This method will create "infinite" cloud layers that remain centered at the camera, so there's no need to worry about positioning them. Typical, realistic values for cloud altitudes will be used. Finer control is available by setting up your own CloudLayer objects and passing them into AtmosphericConditions::AddCloudLayer().

To simulate storms, set up MOSTLY_CLOUDY conditions, and then position a few Cumulonimbus clouds near the camera in addition.

Any existing cloud layers in the scene will be removed. You'll still need to set up the simulated time, location, visibility, and any precipitation and wind you might want.

Parameters
presetThe cloud condition preset you wish to use; one of AtmosphericConditions::FAIR, PARTLY_CLOUDY, MOSTLY_CLOUDY, or OVERCAST.
atmThe Atmosphere object to associate the clouds with.
dataAn optional ThreadCameraStreamData object that this calls pertains to.

◆ SetTime()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetTime ( const LocalTime time,
void *  data = 0 
)

Sets the simulated time of day in local time.

You must specify if daylight savings time is currently being observed or not. Be sure that the time zone specified is consistent with the simulated Location passed to SetLocation(), or you will experience confusing results.

Parameters
timeA reference to a LocalTime object that embodies the simulated local time, time zone, and daylight savings time observation.
dataAn optional ThreadCameraStreamData object that this calls pertains to.

◆ SetTurbidity()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetTurbidity ( double  pTurbidity)
inline

Sets the "turbidity" of the simulated atmosphere.

You can think of this as a measure of "haziness." Some guidelines for setting this value:

2 = very clear, range 50 km 3 = clear, range 15 km 7 = light haze, range 8 km

Setting turbidity is not an appropriate way to simulate fog; see Atmosphere::SetHaze() for one method, or for dense fog simply clear the backbuffer to the fog color and pass false to Atmosphere::DrawSky() to suppress the sky rendering altogether.

Turbidity just lets you simulate the number of particles in the air. In practice it will vary the color of the sky from a pure light blue to a hazy, darker, yellowish color. Turbidity values below 1.8 or above 8.0 lead to unpredictable results and are clamped.

Parameters

pTurbidity The ratio of scattering due to haze to scattering due to molecules.

◆ SetVisibility()

void SILVERLINING_API SilverLining::AtmosphericConditions::SetVisibility ( double  range)
inline

Sets the simulated visibility in meters; this will affect the appearance of clouds in the distance.

Defaults to 30km. This is intended only for light haze, and serves only to blend clouds into the sky in the distance. It does not fog the sky itself. For thicker fog, see AtmosphericConditions::SetFog() and Atmosphere::SetHaze().

◆ SetWind()

int SILVERLINING_API SilverLining::AtmosphericConditions::SetWind ( const WindVolume windVolume)

Sets a volume of wind for moving clouds.

You may call this multiple times to define different wind velocities and directions at different altitudes. Wind also has some influence on cloud formation and the rendering of virga effects.

Parameters
windVolumeA WindVolume to add to the simulation.
Returns
A handle to the wind volume

◆ SL_MAP() [1/2]

SilverLining::AtmosphericConditions::SL_MAP ( int  ,
CloudLayer  
) &
inline

Obtain the stl map of CloudLayer objects.

An accessor for a reference to the STL map of CloudLayer objects managed by this AtmosphericConditions class. It is not const, and so it may be directly manipulated. Use with care.

◆ SL_MAP() [2/2]

const SilverLining::AtmosphericConditions::SL_MAP ( int  ,
WindVolume   
) const &
inline

Get a vector of all wind volumes being simulated.

Returns
A const reference to the STL vector of wind volumes currently being simulated.

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