diff --git a/Docs/README.3DClouds b/Docs/README.3DClouds index 67e8f6b69..97a1365e6 100644 --- a/Docs/README.3DClouds +++ b/Docs/README.3DClouds @@ -1,9 +1,107 @@ Configuring 3D Clouds ===================== -3D clouds are configured using the file data/cloudlayers.xml. +3D clouds can be created in two ways: +- By placing individual clouds using a command (e.g. from Nasal) +- Using the global weather function, which reads cloud definition from + an XML file. -This file has 3 distinct sections: layers, cloud boxes and clouds, +Placing Clouds Individually +=========================== + +Clouds are created using the "add-cloud" command, passing a property +node defining the location and characterstics of the cloud. + +Location is defined by the following properties: + + - The cloud layer number to add the cloud to. (default 0) + - A unique identifier for the cloud in the layer. If a cloud + already exists with this index, the new cloud will not be + created, and 0 is returned. + - Longitude to place the cloud, in degrees (default 0) + - Latitude t place the cloud, in degrees (default 0) + - Altitude to place the cloud, relative to the layer (!) in ft + (default 0) + - Offset in m from the lon-deg. +ve is south (default 0) + - Offset in m from the lat-deg. +ve is east (default 0) + +The cloud itself is built up of a number of "sprites" - simple 2D textures +that are always rotated to be facing the viewer. These sprites are handled +by a OpenGL Shader - a small program that is run on your graphics card. + +The cloud is defined by the following properties: + + - minimum width of the cloud in meters (default 500) + - maximum width of the cloud (default min-cloud-width-m) + - minimum height of the cloud (default min-cloud-width-m) + - maximum height of the cloud (default max-cloud-width-m) + - texture file of sprites to use (default cl_cumulus.png) + - number of cloud textures defined horizontally in the + texture file (default 4) + - number of cloud textures defined vertically in the + texture file (default 4) + - Number of sprite to generate for the cloud (default 20) + - Light multiplier for sprites at the bottom of the cloud + (default 1.0) + - minimum width of the sprites used to create the cloud + (default 200) + - maximum width of the sprites used to create the cloud + (default min-sprite-width-m) + - minimum height of the spites used to create the cloud + (default min-sprite-width-m) + - maximum height of the sprites used to create the cloud + (default max-sprite-height-m) + +The texture to use for the sprites is defined in the tag. +To allow some variation, you can create a texture file containing multiple +sprites in a grid, and define the tags. The code +decides which texture to use for a given sprite : randomly in the x-direction +and based on the altitude of the sprite within the cloud in the y-direction. +Therefore, you should put sprite textures you want to use for the bottom of +your cloud at the bottom of the texture file, and those you want to use for +the top of the cloud at the top of the texture file. + +For example, the following Nasal snippet will create a cloud immediately above the +aircraft at an altitude of 1000 ft above /environment/clouds/layer[0]/elevation-ft : + +var p = props.Node.new({ "layer" : 0, + "index": 1, + "lat-deg": getprop("/position/latitude-deg"), + "lon-deg": getprop("/position/longitude-deg"), + "alt-ft" : 1000 }); +fgcommand("add-cloud", p); + +Moving Individual Clouds +======================== + +Clouds may be moved by using the "move-cloud" command. This takes the following +property arguments. + + - The cloud layer number containing the cloud to move. (default 0) + - The unique identifier of the cloud to move. + - Longitude to place the cloud, in degrees (default 0) + - Latitude t place the cloud, in degrees (default 0) + - Altitude to place the cloud, relative to the layer (!) in ft + (default 0) + +TODO: Add offset arguments for consistency with add-cloud. + +Deleting Individual Clouds +=========================== + +Clouds may be deleted by using the "del-cloud" command. This takes the following +property arguments. + + - The cloud layer number containing the cloud to delet. (default 0) + - The unique identifier of the cloud to delete. + +Global 3D Clouds +================ + +The global weather system uses sets of clouds defined in cloudlayers.xml +in your FG_ROOT. + +The file has 3 distinct sections: layers, cloud boxes and clouds, described below. Notes for those editing clouds: @@ -23,41 +121,9 @@ Notes for those editing clouds: Clouds ====== -The section contains definitions of clouds themselves, built - up of a number of "sprites" - simple 2D textures that are always -rotated to be facing the viewer. These sprites are handled by a OpenGL -Shader - a small program that is run on your graphics card. - -Sets of these clouds are be built up into bigger masses, described below. - -Each cloud group has a completely user-defined name, and contains the -following tags. - - - minimum width of the cloud - - maximum width of the cloud - - minimum height of the cloud - - maximum height of the cloud - - texture file of sprites to use - - number of cloud textures defined horizontally in the - texture file - - number of cloud textures defined vertically in the - texture file - - Number of sprite to generate for the cloud - - Light multiplier for sprites at the bottom of the cloud. - - minimum width of the sprites used to create the cloud - - maximum width of the sprites used to create the cloud - - minimum height of the spites used to create the cloud - - maximum height of the sprites used to create the cloud - - -The texture to use for the sprites is defined in the XML tag. -To allow some variation, you can create a texture file containing multiple -sprites in a grid, and define the tags. The code -decides which texture to use for a given sprite : randomly in the x-direction -and based on the altitude of the sprite within the cloud in the y-direction. -Therefore, you should put sprite textures you want to use for the bottom of -your cloud at the bottom of the texture file, and those you want to use for -the top of the cloud at the top of the texture file. +The cloud definitions are as described above for placing individual +clouds, but no position information is used (this is defined in the +cloud box and layers below). Cloud Boxes =========== @@ -81,7 +147,7 @@ Each section contains the following tags: - The horizontal distribution of the clouds within the area. Equates to a sum of random distributions. Defaults to 1. 1 = even distribution, 2 = distributed towards the center. - 3 = very strongly distributed towards the center. + 3 = very strongly distributed towards the center. - The vertical distribution of the clouds. As for hdist. @@ -117,7 +183,7 @@ The layer type is derived from the METAR/Weather settings by FG itself. Each layer type is a named XML tag, i.e.: ns, sc, st, ac, cb, cu. If a layer type is not defined, then a 2D layer is used instead. -The layer type contains one or more definitions. This +The layer type contains one or more definitions. This defines a type of cloud box, and a weighting for that type (). For example, the following XML fragment will produce 3 "cb" cloud boxes @@ -134,4 +200,4 @@ for every 1 "cu": Clouds are randomly distributed across the sky in the x/y plane, but the height of them is set by the weather conditions, with a random height range -applied, defined by \ No newline at end of file +applied, defined by