A collection of clouds of uniform classification organized into a "deck" of similar altitudes. More...
#include <CloudLayer.h>

Public Member Functions | |
| CloudLayer () | |
| Default constructor. | |
| virtual | ~CloudLayer () |
| Destructor. | |
| CloudTypes | GetType () const |
| Returns the cloud type of this layer. | |
| void | SetType (CloudTypes type) |
| Sets the type of this cloud layer. | |
| void | SetEnabled (bool enabled, unsigned long fadeTimeMS=0) |
| Enable rendering of this cloud layer. | |
| bool | GetEnabled () const |
| Accesses if the CloudLayer is currently enabled for rendering. | |
| void | SetBaseWidth (double meters) |
| Sets the size of the CloudLayer along the X axis. | |
| double | GetBaseWidth () const |
| Retrieves the dimension of the CloudLayer along the X axis. | |
| void | SetBaseLength (double meters) |
| Sets the size of the CloudLayer along the Z axis. | |
| double | GetBaseLength () const |
| Retrieves the dimension of the CloudLayer along the Z axis. | |
| void | SetBaseAltitude (double meters) |
| Sets the altitude above sea level of the bottom of the CloudLayer. | |
| double | GetBaseAltitude () const |
| Retrieves the altitude above sea level of the CloudLayer botton in meters. | |
| void | SetThickness (double meters) |
| Sets the thickness of the CloudLayer in meters. | |
| double | GetThickness () const |
| Retrieves the thickness of the CloudLayer in meters. | |
| void | SetDensity (double coveragePercentage) |
| Sets the percentage of the sky that should be covered by this CloudLayer, from 0 - 1.0. | |
| double | GetDensity () const |
| Retrieves the cloud coverage set for this CloudLayer. | |
| void | SetLayerPosition (double eastCoord, double southCoord) |
| Specifies the location of the center of the CloudLayer. | |
| void | GetLayerPosition (double &east, double &south) const |
| Retrieves the east and south coordinates of the CloudLayer's center, in meters. | |
| void | 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. | |
| bool | GetIsInfinite () const |
| Returns whether this cloud layer is "infinite" and attempts to remain fixed relative to the camera position as best it can. | |
| void | 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. | |
| bool | 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. | |
| void | SetFadeTowardEdges (bool fade) |
| For infinite cloud layers or cloud layers with "wrapping" enabled (. | |
| bool | GetFadeTowardEdges () const |
| Retrieves whether an infinite or wrapping cloud layer has fade effects enabled as the clouds approach the boundaries of the layer. | |
| void | SetPrecipitation (int type, double intensity) |
| Simulates precipitation under this cloud layer of a specified type. | |
| const std::map< int, double > & | GetPrecipitation () const |
| Retrieves a map of precipitation types to intensities in millimeters per hour that are associated with this cloud layer. | |
| virtual bool | HasPrecipitationAtPosition (double x, double y, double z) const |
| Returns whether a precipitation type other than NONE will be simulated at the given camera position. | |
| virtual bool | IsInsideCloud (double x, double y, double z) const |
| Returns whether the given location is inside the bounding box of any of the clouds within this cloud layer. | |
| void | SetAlpha (double pAlpha) |
| Sets translucency for the cloud layer; 0 = transparent, 1.0 = normal opacity. | |
| double | GetAlpha () const |
| Retrieves explicit translucency set by SetAlpha(). | |
| virtual bool | SupportsShadowMaps () |
| Returns if this CloudLayer supports the generation of shadow maps. | |
| virtual void | GenerateShadowMaps (bool enable) |
| For CloudLayers that support shadow maps (see SupportsShadowMaps()), request that a shadow map and matrix is generated each frame. | |
| virtual bool | BindShadowMap (int textureStage, double *m) const |
| Bind the CloudLayer's shadow map texture to a given texture unit and retrieve the light source's (projection * view) matrix. | |
| virtual void | SeedClouds (const Atmosphere &atm)=0 |
| Generates clouds within the cloud layer. | |
| void | AddLightningListener (LightningListener *listener) |
| Adds a LightningListener - derived class to the list of LightningListeners to receive notifications of lightning strikes created by this CloudLayer. | |
| void | ClearLightningListeners () |
| Clears the list of LightningListener objects that receive notifications of lightning strikes from this CloudLayer. | |
| virtual bool | Save (const char *filePath) |
| Saves this cloud deck's clouds to a file for fast restoring later. | |
| virtual bool | Restore (const Atmosphere &atm, const char *filePath) |
| Restores a cloud deck from a file previously generated with the Save() method. | |
| virtual bool | ExportToVRML (const char *dirPath) |
| Exports each individual cloud into a numbered .WRL file within the specified directory path. | |
| virtual bool | Serialize (std::ostream &stream) |
| Flattens this object and everything in it to a stream buffer. | |
| bool | Unserialize (const Atmosphere &atm, std::istream &stream) |
| Restores this object from the stream created using Serialize(). | |
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.
| SilverLining::CloudLayer::CloudLayer | ( | ) |
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().
| virtual SilverLining::CloudLayer::~CloudLayer | ( | ) | [virtual] |
Destructor.
Removes and deletes all clouds added to this CloudLayer.
| void 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.
| virtual bool SilverLining::CloudLayer::BindShadowMap | ( | int | textureStage, | |
| double * | m | |||
| ) | const [inline, virtual] |
Bind the CloudLayer's shadow map texture to a given texture unit and retrieve the light source's (projection * view) matrix.
The shadow map texture will contain black at shadowed locations and white at unshadowed locations. Mapping world coordinates in your scene to the appropriate shadow map texture coordinates may be achieved by using the 4x4 projection * view matrix for the light source that generated the shadow map, which is passed back into the array of 16 doubles passed in as the second parameter. See the sample code for an example of using shadow maps within an application.
This method will fail under DirectX10, as there is no fixed-function pipeline for SilverLining to bind to.
| textureStage | The texture unit to bind the shadow map texture to. | |
| m | A pointer to 16 doubles which will receive the row-major projection * view matrix of the light source that generated the shadow map. |
| void 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.
| virtual bool SilverLining::CloudLayer::ExportToVRML | ( | const char * | dirPath | ) | [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/SilverLining.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.
| virtual void SilverLining::CloudLayer::GenerateShadowMaps | ( | bool | enable | ) | [inline, virtual] |
For CloudLayers that support shadow maps (see SupportsShadowMaps()), request that a shadow map and matrix is generated each frame.
This shadow map texture and matrix may then be retrieved within your rendering loop using the BindShadowMap() method.
| double SilverLining::CloudLayer::GetAlpha | ( | ) | const [inline] |
Retrieves explicit translucency set by SetAlpha().
| double SilverLining::CloudLayer::GetBaseAltitude | ( | ) | const [inline] |
Retrieves the altitude above sea level of the CloudLayer botton in meters.
| double SilverLining::CloudLayer::GetBaseLength | ( | ) | const [inline] |
Retrieves the dimension of the CloudLayer along the Z axis.
| double SilverLining::CloudLayer::GetBaseWidth | ( | ) | const [inline] |
Retrieves the dimension of the CloudLayer along the X axis.
| bool 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.
| double SilverLining::CloudLayer::GetDensity | ( | ) | const [inline] |
Retrieves the cloud coverage set for this CloudLayer.
| bool SilverLining::CloudLayer::GetEnabled | ( | ) | const [inline] |
Accesses if the CloudLayer is currently enabled for rendering.
| bool 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.
| bool 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.
| void SilverLining::CloudLayer::GetLayerPosition | ( | double & | east, | |
| double & | south | |||
| ) | const [inline] |
Retrieves the east and south coordinates of the CloudLayer's center, in meters.
| const std::map<int, double>& SilverLining::CloudLayer::GetPrecipitation | ( | ) | 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.
| double 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.
| CloudTypes SilverLining::CloudLayer::GetType | ( | ) | const [inline] |
Returns the cloud type of this layer.
| virtual bool SilverLining::CloudLayer::HasPrecipitationAtPosition | ( | double | x, | |
| double | y, | |||
| double | z | |||
| ) | 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().
| x | The position, in world coordinates, for which you wish to test for precipitation effects. | |
| y | The position, in world coordinates, for which you wish to test for precipitation effects. | |
| z | The position, in world coordinates, for which you wish to test for precipitation effects. |
| virtual bool SilverLining::CloudLayer::IsInsideCloud | ( | double | x, | |
| double | y, | |||
| double | z | |||
| ) | const [virtual] |
Returns whether the given location is inside the bounding box of any of the clouds within this cloud layer.
| x | The position, in world coordinates, for which you wish to test for a cloud intersection. | |
| y | The position, in world coordinates, for which you wish to test for a cloud intersection. | |
| z | The position, in world coordinates, for which you wish to test for a cloud intersection. |
| virtual bool SilverLining::CloudLayer::Restore | ( | const Atmosphere & | atm, | |
| const char * | filePath | |||
| ) | [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.
| atm | A const reference to the Atmosphere object that will ultimately contain this CloudLayer. | |
| filePath | The fully qualified path to the file previously created with Save(). |
| virtual bool SilverLining::CloudLayer::Save | ( | const char * | filePath | ) | [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.
| filePath | The fully qualified path to the file you wish to save this cloud deck's configuration to. |
| virtual void SilverLining::CloudLayer::SeedClouds | ( | const Atmosphere & | atm | ) | [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!
| atm | A const reference to the Atmosphere object that will ultimately contain this CloudLayer. |
| virtual bool SilverLining::CloudLayer::Serialize | ( | std::ostream & | stream | ) | [virtual] |
Flattens this object and everything in it to a stream buffer.
| void SilverLining::CloudLayer::SetAlpha | ( | double | pAlpha | ) | [inline] |
Sets translucency for the cloud layer; 0 = transparent, 1.0 = normal opacity.
Default is 1.0. This can be used to give clouds a softer appearance and blend into the background better.
| void SilverLining::CloudLayer::SetBaseAltitude | ( | double | meters | ) |
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:
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.
| void SilverLining::CloudLayer::SetBaseLength | ( | double | meters | ) | [inline] |
Sets the size of the CloudLayer along the Z axis.
See SetBaseWidth() for guidance on appropriate values for different types of CloudLayers.
| void SilverLining::CloudLayer::SetBaseWidth | ( | double | meters | ) | [inline] |
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:
| void SilverLining::CloudLayer::SetCloudWrapping | ( | bool | wrap | ) | [inline] |
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. This mode is false by default.
| void SilverLining::CloudLayer::SetDensity | ( | double | coveragePercentage | ) | [inline] |
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(). 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 and cumulonimbus cloud decks, which always represent a single cloud.
| coveragePercentage | The amount of the sky that should be covered by clouds, from 0 - 1.0. |
| void SilverLining::CloudLayer::SetEnabled | ( | bool | enabled, | |
| unsigned long | fadeTimeMS = 0 | |||
| ) |
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.
| enabled | True if this cloud layer should be rendered during Atmosphere::EndFrame(), false if it should not be rendered. | |
| fadeTimeMS | The amount of time, in milliseconds, for the cloud layer to fade in or out. |
| void SilverLining::CloudLayer::SetFadeTowardEdges | ( | bool | fade | ) | [inline] |
For infinite cloud layers or cloud layers with "wrapping" enabled (.
| void SilverLining::CloudLayer::SetIsInfinite | ( | bool | inf | ) | [inline] |
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().
| void SilverLining::CloudLayer::SetLayerPosition | ( | double | eastCoord, | |
| double | southCoord | |||
| ) |
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::BeginFrame() and Atmosphere::EndFrame().
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.
| eastCoord | The east coordinate of the CloudLayer's center position, in meters. | |
| southCoord | The south coordinate of the CloudLayer's center position, in meters. |
| void SilverLining::CloudLayer::SetPrecipitation | ( | int | type, | |
| double | intensity | |||
| ) |
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.
| type | The type of precipitation to simulate under this cloud layer - NONE, RAIN, WET_SNOW, DRY_SNOW, or SLEET. | |
| intensity | The 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. |
| void SilverLining::CloudLayer::SetThickness | ( | double | meters | ) | [inline] |
Sets the thickness of the CloudLayer in meters.
"Thickness" has different meanings for different CloudLayer types:
| void SilverLining::CloudLayer::SetType | ( | CloudTypes | type | ) | [inline] |
Sets the type of this cloud layer.
| virtual bool SilverLining::CloudLayer::SupportsShadowMaps | ( | ) | [inline, virtual] |
Returns if this CloudLayer supports the generation of shadow maps.
Cumulus cloud decks have the ability to generate a texture map suitable for simulating shadows in your application's terrain and other objects. You may call this method to discover if your cloud deck has this capability. Shadow maps are not supported under DirectX9 if the "render-offscreen" setting in resources/silverlining.config is enabled, or under DirectX10/11. For any renderer, shadow maps only work if the setting cumulus-lighting-quick-and-dirty is set to "no" (which it isn't by default.)
1.6.2