Caelum

From Ogre Wiki

Jump to: navigation, search

Author: Kencho
Project: OGRE Add-on Project (caelum)
Type: OGRE Library
Supported Platforms: Linux, Windows
Sources: SVN repository at Sourceforge.net
Binaries: Binary packages download at Sourceforge.net
Status and bug reports: Caelum Forum

Caelum is a plug-in/library for Ogre targeted to help creating 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 in the forum.

Visit the sourceforge project page at http://sourceforge.net/projects/caelum/ and the forum. Before Caelum got it's own forum there was a long thread in the main forum.

Current main features include
  • 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 with 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.

Obtaining Caelum

The latest released version of Caelum is 0.4.0; and is available for download. Auto-generated documentation is also available. There are currently no binary packages but the source should be easy to build.

If you're feeling more adventurous try to to checkout the latest version from sourceforge's svn server. To get the latest version run the following in a console: 

svn checkout https://caelum.svn.sf.net/svnroot/caelum/trunk/Caelum

To update your copy to the latest version run (from your working directory) 

svn update

Documentation for the latest versions is also available. There is no formal changelog but you can read all svn commit messages.

Windows users might find TortoiseSVN more friendly. Also, the subversion book makes very good reading for a rainy day.

Building the Caelum library (and samples)

There are project files for Visual Studio 2005 and 2009 in the repository. They require an installation of the official OGRE SDK. The OGRE_HOME environment variable should be properly set (the SDK installer does that for you). Just open the included sln file and build the library and the demo. Simply pressing "F5" on a new checkout should build and run. Ogre plugins.cfg and resources.cfg are automatically generated in postbuild events. Everything is built into bin/Debug or bin/Release.

There is also a SConstruct file included for building under linux. A scons and ogre package is likely available for your distribution. Building in this case means running "scons" in the caelum root directory. You will have to write your own plugins.cfg and resources.cfg files based on included plugins.cfg.sample and resources.cfg.sample. Executables are build in the root directory (the one with the SConstruct files)

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.

Adding Caelum to your project

Last updated: 2009-01-19, svn revision r396, release 0.4.

The primary source of information for adding Caelum to a project is the official Caelum demo, included with the source. That 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. 

#include "Caelum.h"

Then you need to create a CaelumSystem. That class controls all the sub-components 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 on the sky.

The constructor takes several parameters. Among those 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. 

mCaelumSystem = new caelum::CaelumSystem (mRoot, mSceneMgr, CAELUM_COMPONENTS_DEFAULT);

CaelumSystem and it's subcomponents have a large number of settings you can tweak; too many to document here. Most are available as get/set properties and are mention in the documentation. Aside from changing settings manually with C++ code you can also load property values from .os scripts (this requires Ogre 1.4). Sample code: 

CaelumPlugin::getSingleton ().loadCaelumSystemFromScript (mCaelumSystem, "sky_system_name");

There are samples of caelum scripting in samples/resources/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. 

// In init code:
mRoot->addFrameListener (mCaelumSystem);

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. 

// Somewhere right before updating:
mCaelumSystem->notifyCameraChanged (mCamera);

When it comes to destroying you just need to call CaelumSystem's destructor. Unfortunately if you register CaelumSystem as a FrameListener and you try to destroy it from another FrameListener then this 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: 

// Don't shutdown immediately; wait for the next frame:
mRoot->shutdown (false);

Discussion

Discuss about Caelum in 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

Retrieved from "http://www.ogre3d.org/wiki/index.php/Caelum"
Personal tools
administration