SilverLining
Public Types | Public Member Functions | Protected Member Functions | List of all members
SilverLining::CloudLayer Class Referenceabstract

A collection of clouds of uniform classification organized into a "deck" of similar altitudes. More...

#include <CloudLayer.h>

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

Public Types

enum  CurveModes {
  SQUARE = 0, ALL, NORTH,
  SOUTH, EAST, WEST,
  NORTHWEST, NORTHEAST, SOUTHWEST,
  SOUTHEAST
}
 

Public Member Functions

 CloudLayer (const Atmosphere &atmosphere)
 Default constructor. More...
 
virtual ~CloudLayer ()
 Destructor. More...
 
virtual void ClearClouds (void *data=0)
 Removes all clouds from this cloud layer. More...
 
CloudTypes SILVERLINING_API GetType () const
 Returns the cloud type of this layer. More...
 
void SILVERLINING_API SetType (CloudTypes type)
 Sets the type of this cloud layer. More...
 
bool SILVERLINING_API Intersect (const Vector3 &Origin, const Vector3 &Direction, double &range, void *data=0) const
 Test if ray intersects one or more clouds in this cloud layer. More...
 
virtual void SILVERLINING_API SetEnabled (bool enabled, unsigned long fadeTimeMS=0, void *data=0)
 Enable rendering of this cloud layer. More...
 
bool SILVERLINING_API GetEnabled () const
 Accesses if the CloudLayer is currently enabled for rendering. More...
 
bool SILVERLINING_API IsRenderable (void *data=0) const
 Returns whether this cloud layer needs to be rendered at all; if it is disabled via SetEnabled() and any fading time has expired, this will return false. More...
 
virtual void SILVERLINING_API SetBaseWidth (double meters)
 Sets the size of the CloudLayer along the X axis. More...
 
double SILVERLINING_API GetBaseWidth () const
 Retrieves the dimension of the CloudLayer along the X axis. More...
 
virtual void SILVERLINING_API SetBaseLength (double meters)
 Sets the size of the CloudLayer along the Z axis. More...
 
double SILVERLINING_API GetBaseLength () const
 Retrieves the dimension of the CloudLayer along the Z axis. More...
 
virtual void SILVERLINING_API SetBaseAltitude (double meters, bool updateCloudPositions=true, void *data=0) const
 Sets the altitude above sea level of the bottom of the CloudLayer. More...
 
double SILVERLINING_API GetBaseAltitude (void *data=0) const
 Retrieves the altitude above sea level of the CloudLayer bottom in meters. More...
 
virtual void SILVERLINING_API SetThickness (double meters)
 Sets the thickness of the CloudLayer in meters. More...
 
double SILVERLINING_API GetThickness () const
 Retrieves the thickness of the CloudLayer in meters. More...
 
virtual void SILVERLINING_API SetDensity (double coveragePercentage)
 Sets the percentage of the sky that should be covered by this CloudLayer, from 0 - 1.0. More...
 
double SILVERLINING_API GetDensity () const
 Retrieves the cloud coverage set for this CloudLayer. More...
 
virtual void SILVERLINING_API SetLayerPosition (double eastCoord, double southCoord, void *data=0) const
 Specifies the location of the center of the CloudLayer. More...
 
void SILVERLINING_API GetLayerPosition (double &east, double &south, void *data=0) const
 Retrieves the east and south coordinates of the CloudLayer's center, in meters. More...
 
virtual void SILVERLINING_API SetIsInfinite (bool inf)
 Selects whether this cloud layer is "infinite" - that is, it will always surround the camera when feasible, and never gets blown away by wind. More...
 
bool SILVERLINING_API GetIsInfinite () const
 Returns whether this cloud layer is "infinite" and attempts to remain fixed relative to the camera position as best it can. More...
 
void SILVERLINING_API SetWind (double windX, double windZ)
 Sets a cloud layer specific wind vector which is additive to any global wind set at the AtmosphericConditions level. More...
 
void SILVERLINING_API GetWind (double &windX, double &windZ) const
 Retrieves the cloud layer specific wind vector. More...
 
virtual void SILVERLINING_API SetCloudAnimationEffects (double voxelSpinRate, bool enableGrowth, int initialGrowthIterations=0, int timeStepInterval=0)
 Controls cloud animation effects over time. More...
 
virtual void SILVERLINING_API SetCloudWrapping (bool wrap)
 Infinite cloud layers will always wrap the clouds around the camera position, but you can also enable this behavior relative to the position of a non-infinite cloud layer. More...
 
bool SILVERLINING_API GetCloudWrapping () const
 Returns whether non-infinite cloud layer types will wrap wind-blown clouds to remain within the original bounds of the layer, or if wind will move the entire layer indefinitely. More...
 
void SILVERLINING_API SetFadeTowardEdges (bool fade)
 For infinite cloud layers or cloud layers with "wrapping" enabled this option allows you to automatically fade clouds out as they approach the boundary of the cloud layer where they will pop out and reappear on the opposite side of the layer. More...
 
bool SILVERLINING_API GetFadeTowardEdges () const
 Retrieves whether an infinite or wrapping cloud layer has fade effects enabled as the clouds approach the boundaries of the layer. More...
 
void SILVERLINING_API SetPrecipitation (int type, double intensity, double nearClip=-1.0, double farClip=-1.0, bool useDepthBuffer=false)
 Simulates precipitation under this cloud layer of a specified type. More...
 
const SL_MAP (int, double) &SILVERLINING_API GetPrecipitation() const
 Retrieves a map of precipitation types to intensities in millimeters per hour that are associated with this cloud layer. More...
 
virtual bool SILVERLINING_API HasPrecipitationAtPosition (const Camera *camera, void *data=0) const
 Returns whether a precipitation type other than NONE will be simulated at the given camera position. More...
 
virtual bool SILVERLINING_API IsInsideCloud (const Camera *camera, void *data=0) const
 Returns whether the given location is inside the bounding box of any of the clouds within this cloud layer. More...
 
virtual bool SILVERLINING_API HasPrecipitationAtPosition (double x, double y, double z, void *data=0) const
 Returns whether a precipitation type other than NONE will be simulated at the given camera position. More...
 
virtual bool SILVERLINING_API IsInsideCloud (double x, double y, double z, void *data=0) const
 Returns whether the given location is inside the bounding box of any of the clouds within this cloud layer. More...
 
void SILVERLINING_API SetAlpha (double pAlpha)
 Sets translucency for the cloud layer; 0 = transparent, 1.0 = normal opacity. More...
 
double SILVERLINING_API GetAlpha () const
 Retrieves explicit translucency set by SetAlpha(). More...
 
virtual bool SILVERLINING_API SeedClouds (const Atmosphere &atm, void *data=0)=0
 Generates clouds within the cloud layer. More...
 
virtual bool SILVERLINING_API AddCloudAt (const Atmosphere &atm, const Vector3 &relativePosition, const Vector3 &dimensions, ThreadCameraStreamData *tcsData)
 Adds an individual cloud to an already-seeded cloud layer. More...
 
virtual bool SILVERLINING_API SupportsAddCloudAt () const
 Indicates whether this cloud layer supports the CloudLayer::AddCloudAt() method for adding user-positioned clouds to the procedural clouds. More...
 
void SILVERLINING_API AddLightningListener (LightningListener *listener)
 Adds a LightningListener - derived class to the list of LightningListeners to receive notifications of lightning strikes created by this CloudLayer. More...
 
void SILVERLINING_API ClearLightningListeners ()
 Clears the list of LightningListener objects that receive notifications of lightning strikes from this CloudLayer. More...
 
virtual bool SILVERLINING_API ForceLightning (bool value=true, void *data=0)
 Forces a lightning strike starting with this frame on cloud layers that support lightning. More...
 
virtual void SILVERLINING_API SetLightningDischargeMode (LightningDischargeMode mode)
 Sets the lightning mode. More...
 
virtual LightningDischargeMode SILVERLINING_API GetLightningDischargeMode ()
 Returns the current lightning discharge mode for this cloud layer, or MAX_DISCHARGE_MODE on layer that don't support lightning. More...
 
virtual bool SILVERLINING_API Save (const char *filePath, void *data=0)
 Saves this cloud deck's clouds to a file for fast restoring later. More...
 
virtual bool SILVERLINING_API Restore (const Atmosphere &atm, const char *filePath, void *data=0)
 Restores a cloud deck from a file previously generated with the Save() method. More...
 
virtual bool SILVERLINING_API ExportToVRML (const char *dirPath, void *data=0)
 Exports each individual cloud into a numbered .WRL file within the specified directory path. More...
 
virtual bool SILVERLINING_API Serialize (std::ostream &stream, void *data=0)
 Flattens this object and everything in it to a stream buffer. More...
 
virtual bool SILVERLINING_API Unserialize (const Atmosphere &atm, std::istream &stream, void *data=0)
 Restores this object from the stream created using Serialize() More...
 
const SL_VECTOR (Cloud *) &SILVERLINING_API GetClouds(void *data=0) const
 Retrieve the vector of underlying cloud objects (useful only to licensed users with the full source and private headers.) More...
 
virtual double SILVERLINING_API GetMaxHeight () const
 Retrieves the height of the bounding box enclosing this cloud layer. More...
 
virtual double SILVERLINING_API GetMaxSize () const
 Retrieves the diameter of the largest individual cloud in this cloud layer; only meaningful for cumulus cloud types. More...
 
virtual void SILVERLINING_API SetDensityMultiplier (double multiplier)
 This allows you to reduce the coverage of cloud layers that contain multiple clouds (currently cumulus congestus or cumulus mediocris) at runtime. More...
 
virtual double SILVERLINING_API GetDensityMultiplier () const
 Returns the value last set by CloudLayer::SetDensityMultiplier(), or the default value of 1.0. More...
 
virtual void SILVERLINING_API SetCurveTowardGround (bool curve)
 Sets whether the cloud layer should curve down to meet the ground at its extents. More...
 
virtual bool SILVERLINING_API GetCurveTowardGround () const
 Retrieves whether this cloud layer was created with SetCurveTowardGround(true). More...
 
void SILVERLINING_API OverrideCloudColor (const Vector3 &forcedCloudColor, bool doLighting=true)
 Force the clouds in this layer to use a specific color for their directional and ambient lighting. More...
 
void SILVERLINING_API ClearCloudColorOverride ()
 Clears usage of a specific cloud lighting color set previously with CloudLayer::OverrideCloudColor(). More...
 
bool SILVERLINING_API GetOverriddenCloudColor (Vector3 &color, bool &doLighting) const
 Returns true and populates the color parameter with the cloud color override set via CloudLayer::OverrideCloudColor(), or returns false if a cloud color override is not currently in use for this layer. More...
 
void SILVERLINING_API SetRoundEdges (CurveModes mode)
 Rounds specific corners of this square cloud layer, which can help with smooth grids of cloud layers or just providing more natural edges to the layer. More...
 
CurveModes SILVERLINING_API GetRoundEdges () const
 Retrieves the current edge rounding mode for this cloud layer. More...
 
void SILVERLINING_API SetName (const char *name)
 Set the name of the layer. More...
 
const char *SILVERLINING_API GetName (void) const
 Get the name of the layer. More...
 
virtual void ReloadShaders (ThreadCameraStreamData *tcsData)
 do not use directly!
 

Protected Member Functions

CloudLayerTcsUserData * GetOrCreateTcsNamedUserData (ThreadCameraStreamData *data) const
 internal. do not use!
 

Detailed Description

A collection of clouds of uniform classification organized into a "deck" of similar altitudes.

CloudLayer is a bse class that cannot be directly instantiated; instead, it is returned by the class factory CloudLayerFactory. Call CloudLayerFactory::Create() to obtain a CloudLayer object for a specific cloud type.

Once created, you'll want to set the CloudLayer's dimensions and density (coverage) using the SetBaseWidth(), SetBaseLength(), SetBaseAltitude(), SetThickness(), and SetDensity() methods. You will also need to position it using SetLayerPosition().

Initially, a CloudLayer will not contain any clouds. Once specifying your preferences for the layer's dimensions and density, you must then call SeedClouds() to simulate cloud growth within the cloud deck.

Once your CloudLayer object is created, configured, and seeded, you may then pass it into AtmosphericConditions::AddCloudLayer() to add it to your scene.

Once "seeded", the above methods to modify the layer's dimensions and density will have no effect - they are burned in at that point. You may, however, call SetLayerPosition() at runtime. To change the other properties of the cloud layer at runtime, you need to remove the cloud layer and re-create it.

See SetBaseWidth() for information on important differences between different types of CloudLayers.

Member Enumeration Documentation

◆ CurveModes

Defines the rounding applied to the edges of a square cloud layer; used in CloudLayer::SetRoundEdges

Enumerator
SQUARE 

Keep it square

ALL 

Round all corners

NORTH 

Round the Northern half

SOUTH 

Round the Southern half

EAST 

Round the Eastern half

WEST 

Round the Western half

NORTHWEST 

Round the NW corner

NORTHEAST 

Round the NE corner

SOUTHWEST 

Round the SW corner

SOUTHEAST 

Round the SE corner

Constructor & Destructor Documentation

◆ CloudLayer()

SilverLining::CloudLayer::CloudLayer ( const Atmosphere atmosphere)

Default constructor.

This is a virtual base class, so this constructor is not directly invoked by your application. CloudLayer objects are instantiated by calling CloudLayerFactory::Create().

◆ ~CloudLayer()

virtual SilverLining::CloudLayer::~CloudLayer ( )
virtual

Destructor.

Removes and deletes all clouds added to this CloudLayer.

Member Function Documentation

◆ AddCloudAt()

virtual bool SILVERLINING_API SilverLining::CloudLayer::AddCloudAt ( const Atmosphere atm,
const Vector3 relativePosition,
const Vector3 dimensions,
ThreadCameraStreamData *  tcsData 
)
inlinevirtual

Adds an individual cloud to an already-seeded cloud layer.

Note this method will only work on cloud layers that contain many clouds, such as cumulus congestus and cumulus mediocris. If you attempt to use this on a layer that inherently contains a single cloud (such as stratus, cumulonimbus, or cirrus,) this method will do nothing and return false. To be sure, use the CloudLayer::SupportsAddCloudAt() method to see if this method is avaialble on this cloud layer type.

All positions are relative to the cloud layer position, and must fall within the bounds defined by the cloud layer's width, depth, and height. If it does not, false will be returned and the cloud will not be added.

This method may be used to provide finer control over cloud formations and frontal boundaries. Even if you plan to manually position every cloud in the layer, you must still call CloudLayer::SeedClouds() first with a cloud coverage of 0 (via CloudLayer::SetDensity() ). SeedClouds() performs some required initialization for the cloud layer. If you attempt to call AddCloudAt() on a layer that has not been seeded, again false will be returned.

Again: first call CloudLayer::SeedClouds(), then CloudLayer::AddCloudAt() repeatedly for each cloud you wish to add.

You may also mix and match procedurally-created clouds with your own clouds by setting the cloud layer coverage to a non-zero value, calling SeedClouds(), and then calling AddClouds() to add your clouds to the procedurally generated ones.

Parameters
atmA const reference to the Atmosphere object that will ultimately contain this CloudLayer. This atmosphere must have been initialized with Atmosphere::Initialize(), or this method will fail.
relativePositionThe center position of the cloud relative to the center of the cloud layer. Regardless of your coordinate system, this position should assume that positive Y is "up", X is along the "east" axis, and Z along the "south". These coordinates must fall within the bounds defined by the cloud layer's width and length, or this method will return false. Note that in infinite cloud layers (CloudLayer::SetIsInfinite()), each cloud may get repositioned to wrap around the edges of the layer as the camera moves. You should take care not to position clouds too closely on top of each other, or popping artifacts may result if they re-sort in a different order as the view angle changes.
dimensionsThe size of this cloud. The X component represents the cloud width along the "east" dimension, Y represents the cloud height, and Z the cloud length along the "south" dimension.
Returns
True if the cloud was successfully added. False may be returned if the cloud layer has not yet been seeded with CloudLayer::SeedClouds(), if an attempt was made to place a cloud outside of the cloud layer's bounds, if an uninitialized Atmosphere was passed in, this size of the cloud is smaller than the size of a single cloud puff, or if this cloud layer does not support AddCloudAt().

◆ AddLightningListener()

void SILVERLINING_API SilverLining::CloudLayer::AddLightningListener ( LightningListener listener)

Adds a LightningListener - derived class to the list of LightningListeners to receive notifications of lightning strikes created by this CloudLayer.

The CloudLayer will not destroy the LightningListener; its memory management is up to the caller.

See also
ClearLightningListeners()

◆ ClearCloudColorOverride()

void SILVERLINING_API SilverLining::CloudLayer::ClearCloudColorOverride ( )

Clears usage of a specific cloud lighting color set previously with CloudLayer::OverrideCloudColor().

◆ ClearClouds()

virtual void SilverLining::CloudLayer::ClearClouds ( void *  data = 0)
virtual

Removes all clouds from this cloud layer.

Parameters
data.experimental. Do not use.

◆ ClearLightningListeners()

void SILVERLINING_API SilverLining::CloudLayer::ClearLightningListeners ( )

Clears the list of LightningListener objects that receive notifications of lightning strikes from this CloudLayer.

It does not delete the LightingListener objects.

See also
AddLightningListener()

◆ ExportToVRML()

virtual bool SILVERLINING_API SilverLining::CloudLayer::ExportToVRML ( const char *  dirPath,
void *  data = 0 
)
virtual

Exports each individual cloud into a numbered .WRL file within the specified directory path.

Each .WRL file will be a simple collection of translated spheres that represent the metaballs that make up each cloud.

These .WRL files may then be tweaked using a 3D graphics package, and then re-imported by placing them in resources/clouds/(cloudtype)/. (cloudtype) is the config file prefix for the settings for the given cloud layer type in resources/Atmosphere.config, for example cumulus-congestus or cumulonimbus.

If a given cloud type has .WRL files in its matching resources/clouds/ subdirectory, SilverLining will randomly select these files as the layer is initialized in SeedClouds(), instead of generating the clouds algorithmically from a cellular automata.

This will currently only produce output for cumulus cloud decks.

Parameters
data.experimental. Do not use.
See also
SeedClouds()

◆ ForceLightning()

virtual bool SILVERLINING_API SilverLining::CloudLayer::ForceLightning ( bool  value = true,
void *  data = 0 
)
inlinevirtual

Forces a lightning strike starting with this frame on cloud layers that support lightning.

If the lightning discharge mode is FORCE_ON_OFF, the value parameter controls whether lightning is on or off.

Parameters
data.experimental. Do not use.

◆ GetAlpha()

double SILVERLINING_API SilverLining::CloudLayer::GetAlpha ( ) const
inline

Retrieves explicit translucency set by SetAlpha().

◆ GetBaseAltitude()

double SILVERLINING_API SilverLining::CloudLayer::GetBaseAltitude ( void *  data = 0) const

Retrieves the altitude above sea level of the CloudLayer bottom in meters.

Parameters
data.experimental. Do not use.

◆ GetBaseLength()

double SILVERLINING_API SilverLining::CloudLayer::GetBaseLength ( ) const
inline

Retrieves the dimension of the CloudLayer along the Z axis.

See also
SetBaseLength()

◆ GetBaseWidth()

double SILVERLINING_API SilverLining::CloudLayer::GetBaseWidth ( ) const
inline

Retrieves the dimension of the CloudLayer along the X axis.

See also
SetBaseWidth()

◆ GetCloudWrapping()

bool SILVERLINING_API SilverLining::CloudLayer::GetCloudWrapping ( ) const
inline

Returns whether non-infinite cloud layer types will wrap wind-blown clouds to remain within the original bounds of the layer, or if wind will move the entire layer indefinitely.

◆ GetCurveTowardGround()

virtual bool SILVERLINING_API SilverLining::CloudLayer::GetCurveTowardGround ( ) const
inlinevirtual

Retrieves whether this cloud layer was created with SetCurveTowardGround(true).

◆ GetDensity()

double SILVERLINING_API SilverLining::CloudLayer::GetDensity ( ) const
inline

Retrieves the cloud coverage set for this CloudLayer.

Returns
The cloud coverage of this deck from 0 - 1.0.
See also
SetDensity()

◆ GetDensityMultiplier()

virtual double SILVERLINING_API SilverLining::CloudLayer::GetDensityMultiplier ( ) const
inlinevirtual

Returns the value last set by CloudLayer::SetDensityMultiplier(), or the default value of 1.0.

◆ GetEnabled()

bool SILVERLINING_API SilverLining::CloudLayer::GetEnabled ( ) const
inline

Accesses if the CloudLayer is currently enabled for rendering.

See also
SetEnabled()

◆ GetFadeTowardEdges()

bool SILVERLINING_API SilverLining::CloudLayer::GetFadeTowardEdges ( ) const
inline

Retrieves whether an infinite or wrapping cloud layer has fade effects enabled as the clouds approach the boundaries of the layer.

See also
SetFadeTowardEdges() .

◆ GetIsInfinite()

bool SILVERLINING_API SilverLining::CloudLayer::GetIsInfinite ( ) const
inline

Returns whether this cloud layer is "infinite" and attempts to remain fixed relative to the camera position as best it can.

See also
SetIsInfinite()

◆ GetLayerPosition()

void SILVERLINING_API SilverLining::CloudLayer::GetLayerPosition ( double &  east,
double &  south,
void *  data = 0 
) const

Retrieves the east and south coordinates of the CloudLayer's center, in meters.

Parameters
data.experimental. Do not use.
See also
SetLayerPosition()

◆ GetLightningDischargeMode()

virtual LightningDischargeMode SILVERLINING_API SilverLining::CloudLayer::GetLightningDischargeMode ( )
inlinevirtual

Returns the current lightning discharge mode for this cloud layer, or MAX_DISCHARGE_MODE on layer that don't support lightning.

◆ GetMaxHeight()

virtual double SILVERLINING_API SilverLining::CloudLayer::GetMaxHeight ( ) const
inlinevirtual

Retrieves the height of the bounding box enclosing this cloud layer.

For cumulus cloud types, this is different than GetThickness(), which specifies the variation in cloud base heights.

◆ GetMaxSize()

virtual double SILVERLINING_API SilverLining::CloudLayer::GetMaxSize ( ) const
inlinevirtual

Retrieves the diameter of the largest individual cloud in this cloud layer; only meaningful for cumulus cloud types.

◆ GetName()

const char* SILVERLINING_API SilverLining::CloudLayer::GetName ( void  ) const

Get the name of the layer.

◆ GetOverriddenCloudColor()

bool SILVERLINING_API SilverLining::CloudLayer::GetOverriddenCloudColor ( Vector3 color,
bool &  doLighting 
) const

Returns true and populates the color parameter with the cloud color override set via CloudLayer::OverrideCloudColor(), or returns false if a cloud color override is not currently in use for this layer.

◆ GetRoundEdges()

CurveModes SILVERLINING_API SilverLining::CloudLayer::GetRoundEdges ( ) const
inline

Retrieves the current edge rounding mode for this cloud layer.

◆ GetThickness()

double SILVERLINING_API SilverLining::CloudLayer::GetThickness ( ) const
inline

Retrieves the thickness of the CloudLayer in meters.

See SetThickness() for descriptions of what this value represents for various cloud types.

◆ GetType()

CloudTypes SILVERLINING_API SilverLining::CloudLayer::GetType ( ) const
inline

Returns the cloud type of this layer.

◆ GetWind()

void SILVERLINING_API SilverLining::CloudLayer::GetWind ( double &  windX,
double &  windZ 
) const
inline

Retrieves the cloud layer specific wind vector.

See also
SetWind()

◆ HasPrecipitationAtPosition() [1/2]

virtual bool SILVERLINING_API SilverLining::CloudLayer::HasPrecipitationAtPosition ( const Camera camera,
void *  data = 0 
) const
virtual

Returns whether a precipitation type other than NONE will be simulated at the given camera position.

If you're under a cloud and precipitation has been assigned to this cloud layer using SetPrecipitation(), this will return true. The specific effect may be retrieved with GetPrecipitation().

Parameters
cameraThe camera, and hence whose position, in world coordinates, for which you wish to test for precipitation effects.
data.experimental. Do not use.

◆ HasPrecipitationAtPosition() [2/2]

virtual bool SILVERLINING_API SilverLining::CloudLayer::HasPrecipitationAtPosition ( double  x,
double  y,
double  z,
void *  data = 0 
) const
virtual

Returns whether a precipitation type other than NONE will be simulated at the given camera position.

If you're under a cloud and precipitation has been assigned to this cloud layer using SetPrecipitation(), this will return true. The specific effect may be retrieved with GetPrecipitation().

Parameters
data.experimental. Do not use.

This method is deprecated and will be removed in SilverLining 6 in favor of the API that takes a Camera object.

◆ Intersect()

bool SILVERLINING_API SilverLining::CloudLayer::Intersect ( const Vector3 Origin,
const Vector3 Direction,
double &  range,
void *  data = 0 
) const

Test if ray intersects one or more clouds in this cloud layer.

Currently only supported on cumulus cloud layers.

Parameters
OriginThe origin of the ray used for the intersection test, in world coordinates.
DirectionThe unit-length direction of the ray
rangeReceives the distance to the closest intersection, if any. This value is only for output; any existing value in this parameter will be ignored.
data.experimental. Do not use.
Returns
True if an intersection with a cloud was found, false if not.

◆ IsInsideCloud() [1/2]

virtual bool SILVERLINING_API SilverLining::CloudLayer::IsInsideCloud ( const Camera camera,
void *  data = 0 
) const
virtual

Returns whether the given location is inside the bounding box of any of the clouds within this cloud layer.

Parameters
xcamera The camera, and hence whose position, in world coordinates, for which you wish to test for cloud intersection.
data.experimental. Do not use.

◆ IsInsideCloud() [2/2]

virtual bool SILVERLINING_API SilverLining::CloudLayer::IsInsideCloud ( double  x,
double  y,
double  z,
void *  data = 0 
) const
virtual

Returns whether the given location is inside the bounding box of any of the clouds within this cloud layer.

Parameters
data.experimental. Do not use.

This method is deprecated and will be removed in SilverLining 6 in favor of the API that takes a Camera object.

◆ IsRenderable()

bool SILVERLINING_API SilverLining::CloudLayer::IsRenderable ( void *  data = 0) const

Returns whether this cloud layer needs to be rendered at all; if it is disabled via SetEnabled() and any fading time has expired, this will return false.

Parameters
data.experimental. Do not use.
See also
SetEnabled()

◆ OverrideCloudColor()

void SILVERLINING_API SilverLining::CloudLayer::OverrideCloudColor ( const Vector3 forcedCloudColor,
bool  doLighting = true 
)

Force the clouds in this layer to use a specific color for their directional and ambient lighting.

Call CloudLayer::ClearCloudColorOverride() to go back to using the simulated color for the given time and location. The color passed in will be used as-is, so be sure to scale it for day vs. night for example.

Parameters
forcedCloudColorThe color you wish to force this cloud layer to become.
doLightingWhether the color should be darkened automatically according to the time of day.

◆ Restore()

virtual bool SILVERLINING_API SilverLining::CloudLayer::Restore ( const Atmosphere atm,
const char *  filePath,
void *  data = 0 
)
virtual

Restores a cloud deck from a file previously generated with the Save() method.

It is not necessary to explicitly configure the cloud's dimensions, position, and density, or to call SeedClouds(), when Restore() is called on a newly instantiated cloud layer. Restore() offers a way to quickly load a known good cloud layer without recreating it from scratch every time using SeedClouds(). It will create the layer more quickly than SeedClouds(), but you'll lose the randomness of the clouds within the layer by using this method.

Parameters
atmA const reference to the Atmosphere object that will ultimately contain this CloudLayer.
filePathThe fully qualified path to the file previously created with Save().
data.experimental. Do not use.
See also
Save()
SeedClouds()
Returns
True if the file was successfully restored; false if the file could not be found or was an invalid file format.

◆ Save()

virtual bool SILVERLINING_API SilverLining::CloudLayer::Save ( const char *  filePath,
void *  data = 0 
)
virtual

Saves this cloud deck's clouds to a file for fast restoring later.

This is faster than calling SeedClouds to generate the deck at runtime, and also allows a way to reproduce the same cloud decks by bypassing the randomness of SeedClouds.

Parameters
filePathThe fully qualified path to the file you wish to save this cloud deck's configuration to.
data.experimental. Do not use.
See also
SeedClouds()
Restore()
Returns
True if the file was successfully written.

◆ SeedClouds()

virtual bool SILVERLINING_API SilverLining::CloudLayer::SeedClouds ( const Atmosphere atm,
void *  data = 0 
)
pure virtual

Generates clouds within the cloud layer.

SeedClouds() may only be called after configuring the CloudLayer by calling the SetBaseWidth(), SetBaseLength(), SetBaseAltitude(), SetThickness(), SetDensity(), and SetLayerPosition() methods. When called, it will invoke a cloud growth model to fill the cloud layer with clouds to meet the specified properties of the CloudLayer.

Once a cloud layer is seeded, you may use the Save() method to save it to disk if you'd like to be able to quickly restore it with the Restore() method, instead of recreating the layer from scratch every time.

No clouds will appear within your CloudLayer unless SeedClouds() is called!

Parameters
atmA const reference to the Atmosphere object that will ultimately contain this CloudLayer. This atmosphere must have been initialized with Atmosphere::Initialize(), or this method will fail.
data.experimental. Do not use.
See also
Save()
Restore();

◆ Serialize()

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

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

Parameters
data.experimental. Do not use.

◆ SetAlpha()

void SILVERLINING_API SilverLining::CloudLayer::SetAlpha ( double  pAlpha)
inline

Sets translucency for the cloud layer; 0 = transparent, 1.0 = normal opacity.

Default varies by cloud type, so if you need a specific opacity be sure to specify it here. This can be used to give clouds a softer appearance and blend into the background better.

◆ SetBaseAltitude()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetBaseAltitude ( double  meters,
bool  updateCloudPositions = true,
void *  data = 0 
) const
virtual

Sets the altitude above sea level of the bottom of the CloudLayer.

Here's some guidance on realistic settings (in meters) for various CloudLayer types:

  • Cumulus congestus, cumulus mediocris: Typically found fairly low; between 1000-4000m.
  • Cumulonimbus: Generally extends to the ground if it's raining. 400m is an appropriate setting.
  • Stratus: Found very low; typically 500-2000 m.
  • Cirrus: Found very high; 6000 m or higher.
  • Sandstorm: Set to the local ground altitude to position the sandstorm on the ground.

SetBaseAltitude() may be called at runtime after a cloud layer has been seeded to change its position, and should be called before seeding the cloud layer.

For cumulus clouds, this altitude specifies the mean altitude of the centers of the bottom-most puffs of the cloud, where the cloud will become opaque. The "wispiness" of the cloud may extend to lower altitudes, up to the size of one puff (300 meters by default.)

Stratus clouds have a "scud" effect, also 300 meters by default, that may result in fog effects kicking in at a lower altitude. Generally the base altitude refers to the point where you can know that you are within the clouds, but there is some random variation in real life that we simulate. If you wish to define the base altitude as the lowest point at which any cloud puff might be encountered, you may wish to add 300 meters to your base altitudes specified for cumulus and/or stratus clouds.

The updateCloudPositions indicates whether the cloud altitudes within this layer should be updated immediately. If set to false, individual clouds will not update until they are repositioned by other means, such as wrapping around an infinite cloud layer or a call to SeedClouds().

Parameters
data.experimental. Do not use.

◆ SetBaseLength()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetBaseLength ( double  meters)
inlinevirtual

Sets the size of the CloudLayer along the Z axis.

See SetBaseWidth() for guidance on appropriate values for different types of CloudLayers.

◆ SetBaseWidth()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetBaseWidth ( double  meters)
inlinevirtual

Sets the size of the CloudLayer along the X axis.

The cloud layer must be at least as big as the size of individual clouds within it. The size of the cloud layer may have important performance and visual impacts, so it should be chosen with care. Here are some general guidelines for setting the cloud layer dimensions:

  • Cumulus congestus, mediocris, and sandstorms: The number of clouds created is proportional to the square of the layer dimensions, so performance will degrade quickly if unreasonably high dimensions are chosen. A balance must be found between performance (not having too many clouds to render at real-time speed) and visual acceptability (having enough clouds to fill the scene.) Dimensions of around 30 km or so generally fulfill both demands, but the number of clouds also depends on the cloud layer density (see SetDensity()).
  • Stratus: The width represents the size of the entire stratus cloud layer. If this is an infinite stratus layer, this value is ignored and the SilverLining.config setting stratus-deck-width is used instead.
  • Cumulonimbus: Due to the large size of cumulonimbus clouds and their isolated organization along "squall lines", it's not realistic to have a rectangular deck of cumulonimbus clouds. Instead, the size of the cumulonimbus cloud layer will reflect the size of a single cumulonimbus cloud that fills the entire layer. Choose dimensions that reflect the size of the cloud itself, typically on the order of 5 km.
  • Cirrus: Cirrus decks are rendered as a high, textured plane, but it does not extend infinitely like stratus decks do. A large enough dimension should be chosen to fill the sky of your scene at the deck's altitude; typically, 100,000 meters is appropriate.
  • Stratocumulus: Stratocumulus clouds are rendered using 3D volumetric data that can be very memory-intensive. Cloud layer sizes above 50,000 meters are not recommended, and will also result in sampling artifacts. This upper bound is enforced by the stratocumulus-max-size setting in resources/silverlining.config.
  • Stratocumulus - particles: This stratocumulus representation relies on billboard puffs instead of GPU ray casting, and is very efficient. A size of 100km or even 200km can be handled easily on modern hardware.

◆ SetCloudAnimationEffects()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetCloudAnimationEffects ( double  voxelSpinRate,
bool  enableGrowth,
int  initialGrowthIterations = 0,
int  timeStepInterval = 0 
)
inlinevirtual

Controls cloud animation effects over time.

This only affects cumulus and cumulonimbus cloud types. Must be called prior to CloudLayer::SeedClouds().

Parameters
voxelSpinRateFor cumulus clouds, the maximum rate at which individual cloud voxels rotate to simulate convection in the cloud. Specified in radians per second. Set to 0 for no animation.
enableGrowthControls whether the shape of the cloud itself evolves over time, via cellular automata techniques. This can cause clouds to "grow" over time, but comes with a performance cost. Only affects cumulus congestus cloud layers.
initialGrowthIterationsIf enableGrowth is true, this controls the initial number of iterations of the cullular automata to run to form each cloud prior to the first frame. If you leave this set to zero, the default vaule for the specific cloud type will be used, resulting in a fully-formed cloud at the outset. However, you could set this as low as 1, resulting in clouds growing over time from very small clouds.
timeStepIntervalThe time between cellular automata iterations, in seconds. Changes will be interpolated across this time. Longer times will result in slower cloud formation. To use the default settings for this cloud type, use a value of 0.

◆ SetCloudWrapping()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetCloudWrapping ( bool  wrap)
inlinevirtual

Infinite cloud layers will always wrap the clouds around the camera position, but you can also enable this behavior relative to the position of a non-infinite cloud layer.

This means that as the wind blows individual clouds, they will remain within the original bounds of the cloud layer rather than allowing the entire layer to move with the wind. Cirrus, cirrocumulus, and cumulonimbus cloud layers cannot be wrapped. This mode is false by default.

See also
GetCloudWrapping()

◆ SetCurveTowardGround()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetCurveTowardGround ( bool  curve)
inlinevirtual

Sets whether the cloud layer should curve down to meet the ground at its extents.

Can be useful for creating the illusion of cloud layers that are bigger than they really are. Generally this should be called before seeding the cloud layer. Default is false. With cumulus clouds, this effect is strongest when the camera is near the ground (as determined from the altitude passed in via the Location object) and goes away when the altitude reaches the cloud layer's base altitude.

◆ SetDensity()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetDensity ( double  coveragePercentage)
inlinevirtual

Sets the percentage of the sky that should be covered by this CloudLayer, from 0 - 1.0.

For cumulus congestus and cumulus mediocris decks, this will affect the number of clouds generated during SeedClouds(), within a coverage tolerance of 5%. For stratus decks, setting a value less than 1.0 will result in a "broken" cloud deck, which results in extremely high performance characteristics for variable cloud clover, but is much less visually realistic than a cumulus congestus deck. This value is ignored for cirrus, cirrocumulus and cumulonimbus cloud decks, which always represent a single cloud.

Parameters
coveragePercentageThe amount of the sky that should be covered by clouds, from 0 - 1.0.

◆ SetDensityMultiplier()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetDensityMultiplier ( double  multiplier)
virtual

This allows you to reduce the coverage of cloud layers that contain multiple clouds (currently cumulus congestus or cumulus mediocris) at runtime.

The cloud layer will initially create enough clouds in the scene to achieve the coverage specified in CloudLayer::SetDensity(). By calling CloudLayer::SetDensityMultiplier, we'll randomly fade some clouds in or out to reduce the coverage from the original density. The clouds you don't see will still be using memory, so use this technique with care and only if you need to vary the layer density continuously.

So, one technique would be to create a cloud layer with SetDensity(1.0), and then use SetDensityMultiplier() to change the density to whatever you want at runtime.

Parameters
multiplierA value from 0 to 1.0 controlling what percentage of this cloud layer's clouds will actually be displayed.

◆ SetEnabled()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetEnabled ( bool  enabled,
unsigned long  fadeTimeMS = 0,
void *  data = 0 
)
virtual

Enable rendering of this cloud layer.

New cloud layers are enabled by default.

Why would you want to explicitly enable and disable a cloud layer? Well, creating and seeding cloud layers - especially cumulus cloud layers - is computationally expensive and can take up to a second or two. If your application requires several cloud layers that are displayed at different times, it may make sense to create them all when your application initializes, and then just enable and disable them as needed, which is a much faster operation.

Optionally, you may fade cloud layers in or out over time to smoothly introduce them into your scene. Specify fadeTimeMS in order to enable this effect when enabling or disabling a cloud layer. Fading effects on cumulus layers are only supported on systems that support vertex shaders.

Parameters
enabledTrue if this cloud layer should be rendered during Atmosphere::DrawObjects(), false if it should not be rendered.
fadeTimeMSThe amount of time, in milliseconds, for the cloud layer to fade in
data.experimental. Do not use. or out.

◆ SetFadeTowardEdges()

void SILVERLINING_API SilverLining::CloudLayer::SetFadeTowardEdges ( bool  fade)
inline

For infinite cloud layers or cloud layers with "wrapping" enabled this option allows you to automatically fade clouds out as they approach the boundary of the cloud layer where they will pop out and reappear on the opposite side of the layer.

This fading hides the popping in the distance. This must be set prior to calling CloudLayer::SeedClouds().

See also
SetCloudWrapping()
SetIsInfinite()

◆ SetIsInfinite()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetIsInfinite ( bool  inf)
inlinevirtual

Selects whether this cloud layer is "infinite" - that is, it will always surround the camera when feasible, and never gets blown away by wind.

For layers of cumulus clouds, individual clouds will wrap around the boundaries of the layer to keep the layer centered at the camera position at all times.

The specific effect of "infinite" varies by the cloud layer type. Cumulus congestus and mediocris cloud layers behave as described above, where individual clouds wrap around the cloud layer's boundaries relative to the camera position. For cirrus and cirrocumulus clouds, setting them to "infinite" means they are not affected by wind and remain fixed above the camera position. Infinite stratus cloud layers remain positioned relative to the camera position and simulate relative motion by rotating its texture coordinates. This method does not affect cumulonimbus cloud layers, as they only contain a single cloud.

Be default, cloud layers are not infinite and must be positioned using SetLayerPosition().

See also
GetIsInfinite()

◆ SetLayerPosition()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetLayerPosition ( double  eastCoord,
double  southCoord,
void *  data = 0 
) const
virtual

Specifies the location of the center of the CloudLayer.

Sets the "East" and "South" coordinates of the CloudLayer's center position. For a right-handed coordinate system where Z points in, you'd pass in the X and Z coordinates of where you want the cloudlayer to be centered over, for example. A right-handed coordinate system where Z points up would pass in X and -Y instead.

Cloud positions may move over time in response to simulated wind (see AtmosphericConditions::SetWind()).

If you are using a custom set of basis vectors, be sure that you have called Atmosphere::SetUpVector() and Atmosphere::SetRightVector() before calling this method. The cloud layer will be oriented according to the basis defined by the current up and right vectors when SetLayerPosition() is called. If you're in a geocentric, round-Earth system, you'll want to set the up and right vectors to reflect the local basis at the cloud's location, and then set these back to reflect the eyepoint before rendering with Atmosphere::DrawSky() and Atmosphere::DrawObjects().

Calling SetLayerPosition will reset any accumulated wind drift as well.

SetLayerPosition() and SetBaseAltitude() are the only methods on a CloudLayer that you may change at runtime, after the CloudLayer has been seeded and added into the scene. Modifying other properties of the CloudLayer after it's been seeded require removing the CloudLayer from your AtmosphericConditions, and re-creating the layer.

This method is not needed with infinite cloud layers, which are always positioned relative to the camera.

Parameters
eastCoordThe east coordinate of the CloudLayer's center position, in meters.
southCoordThe south coordinate of the CloudLayer's center position, in meters.
data.experimental. Do not use.

◆ SetLightningDischargeMode()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetLightningDischargeMode ( LightningDischargeMode  mode)
inlinevirtual

Sets the lightning mode.

AUTO_DISCHARGE will fire lightning automatically at random. FORCE_ON_OFF gives the application explicit control via CloudLayer::ForceLightning(). FIRE_AND_FORGET allows lightning to be initiated via CloudLayer::ForceLightning(), but the lightning strike will then finish automatically.

◆ SetName()

void SILVERLINING_API SilverLining::CloudLayer::SetName ( const char *  name)

Set the name of the layer.

◆ SetPrecipitation()

void SILVERLINING_API SilverLining::CloudLayer::SetPrecipitation ( int  type,
double  intensity,
double  nearClip = -1.0,
double  farClip = -1.0,
bool  useDepthBuffer = false 
)

Simulates precipitation under this cloud layer of a specified type.

Any time the camera is under a cloud of this layer, precipitation effects will display if the type is set to something other than NONE.

Note, you may also set global precipitation effects that are not associated with a CloudLayer with the similar AtmosphericConditions::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 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
typeThe type of precipitation to simulate under this cloud layer - NONE, RAIN, WET_SNOW, DRY_SNOW, or SLEET.
intensityThe 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 rendererd. 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.
useDepthBufferSet this to true if you want to enable depth buffer testing of precipitation particles against your scene.
See also
HasPrecipitationAtPosition()
GetPrecipitation()

◆ SetRoundEdges()

void SILVERLINING_API SilverLining::CloudLayer::SetRoundEdges ( CurveModes  mode)

Rounds specific corners of this square cloud layer, which can help with smooth grids of cloud layers or just providing more natural edges to the layer.

Currently only supported with cumulus and stratocumulus cloud layers.

◆ SetThickness()

virtual void SILVERLINING_API SilverLining::CloudLayer::SetThickness ( double  meters)
inlinevirtual

Sets the thickness of the CloudLayer in meters.

"Thickness" has different meanings for different CloudLayer types:

  • Cumulus congestus, mediocris: The thickness specifies the variance in the altitude of the bottoms of each individual cloud within the CloudLayer. The actual height of each cloud is determined procedurally as part of the cloud growth model, and is not affected by SetThickness(). So, setting the thickness to 0 would result in a layer of clouds that all start at the same base altitude; setting a thickness of 100 would provide for some variance for increased realism. In reality, cloud layers rest on top of an air mass that cause most of the clouds to have flattened bottoms that start at roughly the same altitude.
  • Cumulonimbus: SetThickness() determines the height of the cloud you wish to produce.
  • Stratus: The thickness in this case specifies the actual thickness of the stratus deck, that is, the distance between the top and bottom of the stratus layer. Stratus clouds vary in thickness; 1000-2000 m are reasonable values. The thickness of the stratus deck will not impact performance, unlike cumulus decks.
  • Stratocumulus: The thickness defines the height of the bounding volume used to render the volumetric cloud effect. It must be large enough to contain the procedurally grown clouds within the layer, or else clipping and unrealistic lighting will occur. Typically 3000 - 5000 meters should be a good choice. The actual height of the bounding volume will be reduced after seeding the cloud layer if possible to fit the actual height of the clouds within the layer, in order to help performance. As such, subsequent calls to GetThickness() may return a lower value than what you originally specified.
  • Stratocumulus_particles: Like stratus, the thickness in this case specifies the actual thickness of the stratocumulus layer. This needs to be thick enough to contain the clouds within this layer; typically 3000 meters should suffice. If it's too small, the clouds will be unrealistically small.
  • Cirrus: The thickness is ignored for cirrus decks; cirrus decks are modeled as infinitely thin layers of ice crystals at high altitude.
  • Sandstorm: Pass 0 to ensure a flat bottom to the sandstorm, or just leave this unspecified.

◆ SetType()

void SILVERLINING_API SilverLining::CloudLayer::SetType ( CloudTypes  type)
inline

Sets the type of this cloud layer.

◆ SetWind()

void SILVERLINING_API SilverLining::CloudLayer::SetWind ( double  windX,
double  windZ 
)
inline

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

The vector itself specifies the direction the wind is coming from, and the length of the vector provides the wind velocity.

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

◆ SL_MAP()

const SilverLining::CloudLayer::SL_MAP ( int  ,
double   
) const &
inline

Retrieves a map of precipitation types to intensities in millimeters per hour that are associated with this cloud layer.

Precipitation types include RAIN, WET_SNOW, DRY_SNOW, or SLEET.

See also
SetPrecipitation()
HasPrecipitationAtPosition()

◆ SL_VECTOR()

const SilverLining::CloudLayer::SL_VECTOR ( Cloud *  ) const &
pure virtual

Retrieve the vector of underlying cloud objects (useful only to licensed users with the full source and private headers.)

Parameters
data.experimental. Do not use.

◆ SupportsAddCloudAt()

virtual bool SILVERLINING_API SilverLining::CloudLayer::SupportsAddCloudAt ( ) const
inlinevirtual

Indicates whether this cloud layer supports the CloudLayer::AddCloudAt() method for adding user-positioned clouds to the procedural clouds.

◆ Unserialize()

virtual bool SILVERLINING_API SilverLining::CloudLayer::Unserialize ( const Atmosphere atm,
std::istream &  stream,
void *  data = 0 
)
virtual

Restores this object from the stream created using Serialize()

Parameters
data.experimental. Do not use.

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