History: Caelum

Source of version: 12 (current)

{img src="img/wiki_up/Caelum.jpg" alt="" imalign="right"}
__Author__: ((User:Kencho|Kencho))
__Current Maintainer__: ((User:tdev|tdev))
__Project__: OGRE Add-on Project (caelum)
__Type__: OGRE Library
__Supported Platforms__: Linux, Windows
__Source Repository__: [https://github.com/OGRECave/ogre-caelum|Source Code repository at github]
---
{maketoc}

Caelum is a plug-in/library for Ogre targeted to help __create__ nice-looking (photorealistic if possible) __atmospheric effects__ such as sky colour, clouds and weather phenomena such as rain or snow.

The library is released under the LGPL license. This means you can use it as a DLL in any commercial project but you must send any changes you make back to the project. Generally this means you should post patches there: http://code.google.com/p/caelum/issues/list.

Visit the project page at [https://github.com/OGRECave/ogre-caelum] and the [http://www.ogre3d.org/addonforums/21/|forum]. Before Caelum got its own forum there was a [http://www.ogre3d.org/phpBB2/viewtopic.php?t=24961|long thread] in the main forum.

{DL()}
Current main features include:: {DL}

* Sky colour; depending on time of the day.
* Drawing the sun and moon (including phases).
* Multiple animated cloud layers with controllable intensity.
* Astronomically correct sun and moon position based on calendar date and geographic position.
* Texture-based starfield (deprecated)
* Point-based starfield based on bright star catalogue.
* Precipitation compositor. It's a non-particle implementation of precipitation which is very fast on larger displays.
* Depth-based fog compositor. It can provide more complex fogging without requiring changes in your own materials.
* Easy to integrate into your own project.


!!Building the Caelum library (and samples)

You might also want to integrate Caelum into your own project's build system and source control. That might require writing your own build scripts for caelum. There are only 3 directories you need to care about:
* main/src: Contains C++ source files for the library.
* main/include: Contains C++ header files. This folder should be in the include path.
* main/resources: Resources for the main library (bitmaps, material scripts, etc). This folder should be added to ogre's resource paths.


The primary source of information for adding Caelum to a project is the official Caelum demo, included with the source. This code will always be up-to-date. There is also a more complex demo called "CaelumLab" which provides various sliders to tweak parameters. If you have any problem with Caelum it's always useful to try to reproduce it with one of the demos.

Caelum is a loose collection of components useful for rendering sky and atmosphere. All the individual parts are managed by a root "CaelumSystem" class. CaelumSystem is updated every frame and it updates in turn the individual parts. A neat feature of this is that all the individual components are optional and some can even have multiple implementations. If you want you can switch the implementation of the sun or completely disable the clouds at runtime.

First of all you need to include Caelum headers in your project. The main Caelum.h header will include everything else that you need.
{CODE(wrap="1", colors="c++")} #include "Caelum.h"
{CODE}
Then you need to create a CaelumSystem. This class controls all the subcomponents used to render the sky and will update them at the appropriate time. In theory none of the subcomponents directly depend on CaelumSystem and can be used by themselves. In practice it's easier to rely on CaelumSystem to move the sun through the sky.

The constructor takes several parameters. Among them is a CaelumComponent bitmask which indicates which sub-components to create by default. CAELUM_COMPONENTS_DEFAULT should include the easy-to-use stable components. If you get in trouble you can try to remove individual components.
{CODE(wrap="1", colors="c++")} mCaelumSystem = new caelum::CaelumSystem (mRoot, mSceneMgr, CAELUM_COMPONENTS_DEFAULT);
{CODE}
If you are using subcomponents that require a viewport, such as PrecipitationController or DepthComposer, you will need to add the viewport to CaelumSystem.
{CODE(wrap="1", colors="c++")} mCaelumSystem->attachViewport(mViewport);
{CODE}
By default, CaelumSystem will automatically attach its viewports to any subcomponents that might need it. If you need more control, you can disable this feature and manually add viewports to the subcomponents yourself.

CaelumSystem and its subcomponents have a large number of settings you can tweak - too many to document here. Most are available as get/set properties and are mentioned in the documentation. Aside from changing settings manually with C++ code you can also load property values from .os scripts (this requires Ogre 1.6). Sample code:
{CODE(wrap="1", colors="c++")} CaelumPlugin::getSingleton ().loadCaelumSystemFromScript (mCaelumSystem, "sky_system_name");
{CODE}
There are samples of caelum scripting in TestSkyScript.os. Caelum scripts are very similar to ogre material scripts and support much of the same features (overriding and variables). The names of the properties in scripting are the names of the get/set functions converted to an ogre_script_convetion. Loading from a script will reset CaelumSystem, so if you use scripts you should probably pass CAELUM_COMPONENTS_NONE to the constructor to reconstruction.

!!!Updating CaelumSystem
Unfortunately updating CaelumSystem is not very easy. The issues are discussed in CaelumSystem documentation. There are two updates: per-frame and per-camera.

For the per-frame update you can add CaelumSystem as FrameListener and let it update itself, or you can call updateSubcomponents by hand every frame. The first method is easier; the second gives you more control.
{CODE(wrap="1", colors="c++")} // In init code:
 mRoot->addFrameListener (mCaelumSystem);
{CODE}
For the per-camera update you can add Caelum as a RenderTargetListener for every render target you create; or you can call notifyCameraChanged immediately before rendering with each camera. The second alternative is required if you use compositors.
{CODE(wrap="1", colors="c++")} // Somewhere right before updating:
 mCaelumSystem->notifyCameraChanged (mCamera);
{CODE}
When it comes to destroying you just need to call CaelumSystem's destructor. However, if you register CaelumSystem as a FrameListener and you try to destroy it from another FrameListener, the program will crash if the caelum listener is called after your listener. It that case it's safest to tell CaelumSystem to destroy itself next time it's called as a frame listener:
{CODE(wrap="1", colors="c++")} // Don't shutdown immediately; wait for the next frame:
 mRoot->shutdown (false);
{CODE}
!!Discussion


Discuss about Caelum in [http://www.ogre3d.org/addonforums/viewforum.php?f=21|Ogre addons forums]. Bug reports, small fixes and shader tweaks are always welcome, as well as entire new components :). Please try to give as much information as possible when reporting issues; including the contents of Ogre.log and relevant callstacks.

!!See also
* ((CaelumSharp)) - a .NET port for use with ((MOGRE|Mogre))
* ((SkyX)) - an alternative sky and weather system

Documents for implementing both dynamic sky and atmospheric light scattering:
* [http://www2.imm.dtu.dk/pubdb/views/edoc_download.php/2554/pdf/imm2554.pdf|imm2554.pdf] at imm.dtu.dk
* [http://www.cs.utah.edu/~shirley/papers/sunsky/sunsky.pdf|sunsky.pdf] at cs.utah.edu
* [http://ati.amd.com/developer/dx9/ATI-LightScattering.pdf|ATI-LightScattering.pdf] at ati.amd.com
* [http://developer.amd.com/media/gpu_assets/PreethamSig2003CourseNotes.pdf|PreethamSig2003CourseNotes.pdf] at developer.amd.com
* [http://portal.acm.org/citation.cfm?id=1178574|portal.acm.org/citation.cfm?id=1178574]
History: Caelum

Source of version: 12 (current)

Search by Tags

Latest Changes

Search

Online Users
