This is the "root class" of caelum. More...

#include <CaelumSystem.h>

Inheritance diagram for Caelum::CaelumSystem:

Public Types
enum	CaelumComponent { CAELUM_COMPONENT_SKY_DOME = 1 << 1, CAELUM_COMPONENT_MOON = 1 << 3, CAELUM_COMPONENT_SUN = 1 << 4, CAELUM_COMPONENT_IMAGE_STARFIELD = 1 << 5, CAELUM_COMPONENT_POINT_STARFIELD = 1 << 6, CAELUM_COMPONENT_CLOUDS = 1 << 7, CAELUM_COMPONENT_PRECIPITATION = 1 << 8, CAELUM_COMPONENT_SCREEN_SPACE_FOG = 1 << 9, CAELUM_COMPONENT_GROUND_FOG = 1 << (16 + 0), CAELUM_COMPONENTS_NONE = 0, CAELUM_COMPONENTS_DEFAULT, CAELUM_COMPONENTS_ALL }
	Flags enumeration for caelum components. More...

typedef std::set< Ogre::Viewport * >	AttachedViewportSet

Public Member Functions
	CaelumSystem (Ogre::Root root, Ogre::SceneManager sceneMgr, CaelumComponent componentsToCreate)
	Constructor. More...

void	clear ()
	Revert everything to defaults. More...

void	autoConfigure (CaelumComponent componentsToCreate)
	Create some default component with resonable default settings. More...

	~CaelumSystem ()
	Destructor.

void	shutdown (bool cleanup)
	Shuts down the system and detaches itself from the Ogre engine. More...

void	updateSubcomponents (Real timeSinceLastFrame)
	Update the whole system manually. More...

void	notifyCameraChanged (Ogre::Camera *cam)
	Notify subcomponents of camera changes. More...

Ogre::SceneManager *	getSceneMgr () const
	Get the scene manager for this caelum system. More...

Ogre::SceneNode *	getCaelumCameraNode (void) const
	Gets root scene node for camera-bound elements.

Ogre::SceneNode *	getCaelumGroundNode (void) const
	Gets root scene node for ground-bound elements.

void	setAutoNotifyCameraChanged (bool value)
	If true; listen to preViewportUpdate and automatically notifyCameraChanged();. More...

bool	getAutoNotifyCameraChanged () const

void	setAutoAttachViewportsToComponents (bool value)
	If true; automatically attach viewports to subcomponents. More...

bool	getAutoAttachViewportsToComponents () const

void	setAutoMoveCameraNode (bool value)
	If true (default); automatically move the camera node in notifyCameraChanged. More...

bool	getAutoMoveCameraNode ()

void	setAutoViewportBackground (bool value)
	If true; automatically set the viewport color to black. More...

bool	getAutoViewportBackground () const

const Ogre::Degree	getObserverLongitude () const
	Get the observer's longitude. East is positive, west is negative.

void	setObserverLongitude (Ogre::Degree value)
	Set the observer's longitude. East is positive, west is negative.

const Ogre::Degree	getObserverLatitude () const
	Get the observer's latitude. North is positive, south is negative.

void	setObserverLatitude (Ogre::Degree value)
	Set the observer's latitude. North is positive, south is negative.

LongReal	getJulianDay () const

void	setJulianDay (LongReal value)

Real	getTimeScale () const

void	setTimeScale (Real value)

void	attachViewport (Ogre::Viewport *rt)
	Attach CaelumSystem to a viewport. More...

void	detachViewport (Ogre::Viewport *rt)
	Reverse of. More...

bool	isViewportAttached (Ogre::Viewport *vp) const
	Check if one particular viewport is attached.

void	detachAllViewports ()
	Detach from all viewports.

const AttachedViewportSet &	_getAttachedViewportSet ()
	Get a reference to the set of attached viewports.

UniversalClock *	getUniversalClock () const
	Gets the universal clock.

SkyDome *	getSkyDome () const
	Get the current sky dome, or null if disabled.

void	setSkyDome (SkyDome *obj)
	Set the skydome, or null to disable.

BaseSkyLight *	getSun () const
	Gets the current sun, or null if disabled.

void	setSun (BaseSkyLight *obj)
	Set the sun, or null to disable.

Moon *	getMoon () const
	Gets the current moon, or null if disabled.

void	setMoon (Moon *obj)
	Set the moon, or null to disable.

ImageStarfield *	getImageStarfield () const
	Gets the current image starfield, or null if disabled.

void	setImageStarfield (ImageStarfield *obj)
	Set image starfield, or null to disable.

PointStarfield *	getPointStarfield () const
	Gets the current point starfield, or null if disabled.

void	setPointStarfield (PointStarfield *obj)
	Set image starfield, or null to disable.

GroundFog *	getGroundFog ()
	Get ground fog; if enabled.

void	setGroundFog (GroundFog *obj)
	Sets ground fog system, or null to disable.

CloudSystem *	getCloudSystem ()
	Get cloud system; or null if disabled.

void	setCloudSystem (CloudSystem *obj)
	Set cloud system; or null to disable.

PrecipitationController *	getPrecipitationController ()
	Get precipitation controller; or null if disabled.

void	setPrecipitationController (PrecipitationController *obj)
	Set precipitation controller; or null to disable.

DepthComposer *	getDepthComposer ()
	Get depth composer; or null if disabled.

void	setDepthComposer (DepthComposer *obj)
	Set depth composer; or null to disable.

void	setManageSceneFog (Ogre::FogMode f)
	Enables/disables Caelum managing standard Ogre::Scene fog. More...

void	disableFogMangement ()

Ogre::FogMode	getManageSceneFog () const
	Tells if Caelum is managing the fog or not. More...

void	setManageSceneFogStart (Ogre::Real from)

void	setManageSceneFogEnd (Ogre::Real to)

Ogre::Real	getManageSceneFogStart () const

Ogre::Real	getManageSceneFogEnd () const

void	setSceneFogDensityMultiplier (Real value)
	Multiplier for scene fog density (default 1). More...

Real	getSceneFogDensityMultiplier () const
	Get the value set by setSceneFogDensityMultiplier.

void	setSceneFogColourMultiplier (const Ogre::ColourValue &value)
	Set an additional multiplier for fog colour as it comes from SkyColourModel. More...

const Ogre::ColourValue	getSceneFogColourMultiplier () const
	See setSceneFogColourMultiplier.

void	setGroundFogDensityMultiplier (Real value)
	Multiplier for ground fog density (default 1). More...

Real	getGroundFogDensityMultiplier () const
	Get the value set by setGroundFogDensityMultiplier.

void	setGroundFogColourMultiplier (const Ogre::ColourValue &value)
	Set an additional multiplier for ground fog colour as it comes from SkyColourModel. More...

const Ogre::ColourValue	getGroundFogColourMultiplier () const
	See setGroundFogColourMultiplier.

void	setGlobalFogDensityMultiplier (Real value)
	Multiplier for global fog density (default 1). More...

Real	getGlobalFogDensityMultiplier () const
	Get the value set by setSceneFogDensityMultiplier.

void	setGlobalFogColourMultiplier (const Ogre::ColourValue &value)
	Set an additional multiplier for fog colour. More...

const Ogre::ColourValue	getGlobalFogColourMultiplier () const
	See setGlobalFogColourMultiplier.

void	setManageAmbientLight (bool value)
	Set this to true to have CaelumSystem manage the scene's ambient light. More...

bool	getManageAmbientLight () const
	Check if CaelumSystem is managing ambient lighting.

void	setMinimumAmbientLight (const Ogre::ColourValue &value)
	Set the minimum value for scene ambient lighting, This is only used if getManageAmbientLight() is true. More...

const Ogre::ColourValue	getMinimumAmbientLight () const

void	setEnsureSingleLightSource (bool value)
	Ensure only one of caelum's light sources is active at a time (the brightest). More...

bool	getEnsureSingleLightSource () const
	See setEnsureSingleLightSource.

void	setEnsureSingleShadowSource (bool value)
	Ensure only one of caelum's light sources casts shadows (the brightest). More...

bool	getEnsureSingleShadowSource () const
	See setEnsureSingleShadowSource.

Ogre::ColourValue	getFogColour (Real time, const Ogre::Vector3 &sunDir)
	Gets the fog colour for a certain daytime. More...

Real	getFogDensity (Real time, const Ogre::Vector3 &sunDir)
	Gets the fog density for a certain daytime. More...

Ogre::ColourValue	getSunSphereColour (Real time, const Ogre::Vector3 &sunDir)
	Get the colour of the sun sphere. More...

Ogre::ColourValue	getSunLightColour (Real time, const Ogre::Vector3 &sunDir)
	Gets the colour of sun light. More...

Ogre::ColourValue	getMoonBodyColour (const Ogre::Vector3 &moonDir)
	Gets the colour of moon's body.

Ogre::ColourValue	getMoonLightColour (const Ogre::Vector3 &moonDir)
	Gets the colour of moon's light.

void	setSkyGradientsImage (const Ogre::String &filename=DEFAULT_SKY_GRADIENTS_IMAGE)
	Set the sun gradients image.

void	setSunColoursImage (const Ogre::String &filename=DEFAULT_SUN_COLOURS_IMAGE)
	Set the sun colours image. More...

const Ogre::Vector3	getSunDirection (LongReal jday)
	Get the sun's direction at a certain time. More...

const Ogre::Vector3	getMoonDirection (LongReal jday)
	Get the moon's direction at a certain time. More...

const Ogre::Real	getMoonPhase (LongReal jday)
	Function to get the phase of the moon. More...

const Ogre::Vector3	getEclipticNorthPoleDirection (LongReal jday)
	Get the ecliptic's north pole direction at a certain time. More...

void	forceSubcomponentQueryFlags (uint mask)
	Call setQueryFlags for all subcomponents now. More...

void	forceSubcomponentVisibilityFlags (uint mask)
	Same as. More...

Public Member Functions inherited from Ogre::FrameListener
virtual bool	frameEnded (const FrameEvent &evt)

virtual bool	frameRenderingQueued (const FrameEvent &evt)

Public Member Functions inherited from Ogre::RenderTargetListener
virtual void	postRenderTargetUpdate (const RenderTargetEvent &evt)

virtual void	postViewportUpdate (const RenderTargetViewportEvent &evt)

virtual void	preRenderTargetUpdate (const RenderTargetEvent &evt)

virtual void	viewportAdded (const RenderTargetViewportEvent &evt)

virtual void	viewportRemoved (const RenderTargetViewportEvent &evt)

Static Public Attributes
static const String	DEFAULT_SKY_GRADIENTS_IMAGE

static const String	DEFAULT_SUN_COLOURS_IMAGE

Protected Member Functions
void	attachViewportImpl (Ogre::Viewport *rt)

void	detachViewportImpl (Ogre::Viewport *rt)

Detailed Description

This is the "root class" of caelum.

This class is created once for one SceneManager and will render the sky for that scene. CaelumSystem will be visible in all viewports on the scene and must be notified when those viewports are created and destroyed.

Components

Caelum is built from several classes for different sky elements (the sun, clouds, etc). Those classes know very little about each other and are connected through this class. This class is responsible for tracking and updating sub-components.

This class "owns" all of the subcomponents, using std::auto_ptr members. When you call functions like setXxx(new Xxx()) this class takes ownership of the object's lifetime and will try to update it as appropriate. All components are optional; disable one component should never cause a crash. When something is broken disabling components one by one is a very good way to find the source of the problem.

The constructor can create a bunch of components with default settings for you; based on the CaelumSystem::CaelumComponent flags passed.

Updating

This class is responsible for updating subcomponents. There are two update functions which must be get called to keep CaelumSystem functioning properly. One is per-frame and the other is per-camera.

CaelumSystem::updateSubcomponents must be called once per frame to advance world time and tie components together. That function will set certain properties on the subcomponents making up CaelumSystem If you want to force some properties beyond what CaelumSystem does by default you can do that AFTER the call to updateSubcompoments. For example you can override the moon's phase by calling Moon::setPhase.

CaelumSystem::notifyCameraChanged must be called for each camera before rendering with that camera. All viewport tweaks and camera movement must be done BEFORE calling this function. This method will recenter Caelum's domes on the camera. Also, some subcomponents can actually depend on field-of-view and viewport resolution (like PointStarfield).

You can register CaelumSystem as an Ogre::FrameListener and updateSubcomponents will be automatically called inside Ogre's rendering loop (inside frameStarted). If you want more control you should call updateSubcomponents in your own main loop. That way you can avoid potential issues with the ordering of multiple FrameListeners.

You can register CaelumSystem as an Ogre::RenderTargetListener and notifyCameraChanged will be automatically called inside preViewportUpdate. That behaviour can be disabled with setAutoNotifyCameraChanged(false). It is recommended that you call notifyCameraChanged manually before updating viewports.

RenderTargetListener::preViewportUpdate does not work as expected when compositors are involved (those inside Caelum or external). Compositors plug into preRenderTargetUpdate and render the scene to a texture BEFORE preViewportUpdate; this means that notifyCameraChanged will execute before the final compositor pass but after actual scene rendering.

If notifyCameraChanged is not called correctly the most likely result is "flickering" when moving the camera. If you move the camera AFTER notifyCameraChanged then the domes will not be positioned correctly and will appear to lag slightly after the camera. Since updates are always done every frame keeping the camera still will make problems disappear.

If you notice z-buffer issues while the camera is still update order is probably not the cause.

Member Enumeration Documentation

enum Caelum::CaelumSystem::CaelumComponent

Flags enumeration for caelum components.

This is an enumeration for the components to create by default in Caelum's constructor. You can still pass 0 and create everything by hand.

CaelumSystem's constructor used to take a number of bools but now there are too many components and this is nicer.

CAELUM_COMPONENT_ members are for individual components. CAELUM_COMPONENTS_ are standard bitmasks. CAELUM_COMPONENTS_DEFAULT picks elements that don't require modifications to external materials (right now it excludes ground fog).

Constructor & Destructor Documentation

Caelum::CaelumSystem::CaelumSystem	(	Ogre::Root *	root,
		Ogre::SceneManager *	sceneMgr,
		CaelumComponent	componentsToCreate
	)

Constructor.

Registers itself in the Ogre engine and initialises the system.

Parameters

root	The Ogre root.
scene	The Ogre scene manager.
componentsToCreate	Default components for

See also: autoConfigure.

Member Function Documentation

void Caelum::CaelumSystem::clear ( )

Revert everything to defaults.

This function will delete all subcomponents and revert everything to default values (the values which are also set on construction).

void Caelum::CaelumSystem::autoConfigure ( CaelumComponent componentsToCreate )

Create some default component with resonable default settings.

This results in a slightly cloudy morning sky. This will always call clear() before creating components. autoConfigure (0); is equivalent to clear();

void Caelum::CaelumSystem::shutdown ( bool cleanup )

Shuts down the system and detaches itself from the Ogre engine.

shutdown(true) is equivalent to deleting CaelumSystem yourself. shutdown(false) delays destruction to the next time caelum is called as a frame listener. This makes it safe to shutdown Caelum from inside another frame listener.

Parameters

cleanup If this is true then detach and destroy the CaelumSystem instantly.

void Caelum::CaelumSystem::updateSubcomponents ( Real timeSinceLastFrame )

Update the whole system manually.

You have to call this yourself if you don't register CaelumSystem as an ogre frame listener. Otherwise it's called automatically.

Parameters

timeSinceLastFrame Time passed since last frame.

void Caelum::CaelumSystem::notifyCameraChanged ( Ogre::Camera * cam )

Notify subcomponents of camera changes.

This function must be called after camera changes but before rendering with that camera. If multiple cameras are used it must be called for each camera before the camera is rendered with.

This function will move caelum's camera node to the camera position, but only if getAutoMoveCameraNode. It will also call CameraBoundElement::notifyCameraChanged

Ogre::SceneManager* Caelum::CaelumSystem::getSceneMgr ( ) const

inline

Get the scene manager for this caelum system.

This is set in the constructor. CaelumSystem can't exist without a valid scene manager.

void Caelum::CaelumSystem::setAutoNotifyCameraChanged ( bool value )

inline

If true; listen to preViewportUpdate and automatically notifyCameraChanged();.

This is on by default; but does not work with compositors.

You must attach CaelumSystem as a RenderTargetListener manually for this to work; as in version 0.3.

References value.

bool Caelum::CaelumSystem::getAutoNotifyCameraChanged ( ) const

inline

See also: setAutoNotifyCameraChanged

void Caelum::CaelumSystem::setAutoAttachViewportsToComponents ( bool value )

inline

If true; automatically attach viewports to subcomponents.

Some subcomponents use compositors and those compositors need to be attached to individual viewports. By default CaelumSystem will try take to take care of that automatically.

This property allows you to disable that behaviour. If set to false you must call functions like PrecipitationController::createViewportInstance manually.

See also: attachViewport detachViewport

References value.

bool Caelum::CaelumSystem::getAutoAttachViewportsToComponents ( ) const

inline

See also: setAutoAttachViewportsToComponents.

void Caelum::CaelumSystem::setAutoMoveCameraNode ( bool value )

inline

If true (default); automatically move the camera node in notifyCameraChanged.

If disable you get full control of the camera node; and in theory you can attach it to the scene graph however you please.

References value.

bool Caelum::CaelumSystem::getAutoMoveCameraNode ( )

inline

See also: setAutoMoveCameraNode

void Caelum::CaelumSystem::setAutoViewportBackground ( bool value )

inline

If true; automatically set the viewport color to black.

Caelum's domes relies on the viewport background being black. There's generally no reason to disable this and it's on by default.

References value.

bool Caelum::CaelumSystem::getAutoViewportBackground ( ) const

inline

See also: setAutoViewportBackground

void Caelum::CaelumSystem::attachViewport ( Ogre::Viewport * rt )

Attach CaelumSystem to a viewport.

You should call this for every new viewport looking at the scene where CaelumSystem is created.

If the viewport is already attached then nothing happens.

If getAutoAttachViewportsToComponents() this will add Caelum's compositors.

void Caelum::CaelumSystem::detachViewport ( Ogre::Viewport * rt )

Reverse of.

See also: attachViewport. You need to call this when you destroy a viewport.

If the viewport is not already attached nothing happens.

void Caelum::CaelumSystem::setManageSceneFog ( Ogre::FogMode f )

Enables/disables Caelum managing standard Ogre::Scene fog.

This makes CaelumSystem control standard Ogre::Scene fogging. It will use EXP2 fog with density from SkyColourModel.

Fog density multipliers are used; final scene fog density is: SceneMultiplier * GlobalMultiplier * SkyColourModel.GetFogDensity

When this is set to false it also disables all scene fog (but you control it afterwards).

Parameters

value New value

Ogre::FogMode Caelum::CaelumSystem::getManageSceneFog ( ) const

Tells if Caelum is managing the fog or not.

Returns: The value set in setManageSceneFog.

void Caelum::CaelumSystem::setSceneFogDensityMultiplier ( Real value )

Multiplier for scene fog density (default 1).

This is an additional multiplier for Ogre::Scene fog density. This has no effect if getManageSceneFog is false.

Final scene fog density is: SceneMultiplier * GlobalMultiplier * SkyColourModel.GetFogDensity

void Caelum::CaelumSystem::setSceneFogColourMultiplier ( const Ogre::ColourValue & value )

inline

Set an additional multiplier for fog colour as it comes from SkyColourModel.

This is 0.7 by default; to be compatible with previous versions.

References value.

void Caelum::CaelumSystem::setGroundFogDensityMultiplier ( Real value )

Multiplier for ground fog density (default 1).

This is an additional multiplier for Caelum::GroundFog DepthComposer ground fog density.

Final ground fog density is: GroundFogMultipler * GlobalMultiplier * SkyColourModel.GetFogDensity

void Caelum::CaelumSystem::setGroundFogColourMultiplier ( const Ogre::ColourValue & value )

inline

Set an additional multiplier for ground fog colour as it comes from SkyColourModel.

This is OgreColour::White by default; which has no effect.

References value.

void Caelum::CaelumSystem::setGlobalFogDensityMultiplier ( Real value )

Multiplier for global fog density (default 1).

This is an additional multiplier for fog density as received from SkyColourModel. There are other multipliers you can tweak for individual kinds of fog; but this is what you should change from whatever "game logic" you might have.

void Caelum::CaelumSystem::setGlobalFogColourMultiplier ( const Ogre::ColourValue & value )

inline

Set an additional multiplier for fog colour.

This will also affect stuff like clouds or precipitation. Careful! This is OgreColour::White by default; which has no effect.

References value.

void Caelum::CaelumSystem::setManageAmbientLight ( bool value )

inline

Set this to true to have CaelumSystem manage the scene's ambient light.

The colour and AmbientMultiplier of the sun and moon are used. This is false by default.

References value.

void Caelum::CaelumSystem::setMinimumAmbientLight ( const Ogre::ColourValue & value )

inline

Set the minimum value for scene ambient lighting, This is only used if getManageAmbientLight() is true.

By default this value is Ogre::ColourValue::Black, so it has no effect.

References value.

const Ogre::ColourValue Caelum::CaelumSystem::getMinimumAmbientLight ( ) const

inline

See also: setMinimumAmbientLight

void Caelum::CaelumSystem::setEnsureSingleLightSource ( bool value )

inline

Ensure only one of caelum's light sources is active at a time (the brightest).

This uses SkyLight::setForceDisable to disable low-intensity lightsources. Their contribution to ambient lighting is not affected. This implies a single shadow caster. This is disabled by default; and you can tweak light disabling by yourself.

References value.

void Caelum::CaelumSystem::setEnsureSingleShadowSource ( bool value )

inline

Ensure only one of caelum's light sources casts shadows (the brightest).

Disabled by default.

References value.

Ogre::ColourValue Caelum::CaelumSystem::getFogColour	(	Real	time,
		const Ogre::Vector3 &	sunDir
	)

Gets the fog colour for a certain daytime.

Parameters

time	The current time.
sunDir	The sun direction.

Returns: The fog colour.

Real Caelum::CaelumSystem::getFogDensity	(	Real	time,
		const Ogre::Vector3 &	sunDir
	)

Gets the fog density for a certain daytime.

Parameters

time	The current time.
sunDir	The sun direction.

Returns: The fog density.

Ogre::ColourValue Caelum::CaelumSystem::getSunSphereColour	(	Real	time,
		const Ogre::Vector3 &	sunDir
	)

Get the colour of the sun sphere.

This colour is used to draw the sun sphere in the sky.

Returns: The colour of the sun.

Ogre::ColourValue Caelum::CaelumSystem::getSunLightColour	(	Real	time,
		const Ogre::Vector3 &	sunDir
	)

Gets the colour of sun light.

This color is used to illuminate the scene.

Returns: The colour of the sun's light

void Caelum::CaelumSystem::setSunColoursImage ( const Ogre::String & filename = DEFAULT_SUN_COLOURS_IMAGE )

Set the sun colours image.

Sun colour is taken from this image.

const Ogre::Vector3 Caelum::CaelumSystem::getSunDirection ( LongReal jday )

Get the sun's direction at a certain time.

Parameters

jday	astronomical julian day.

See also: UniversalClock for julian day calculations.

const Ogre::Vector3 Caelum::CaelumSystem::getMoonDirection ( LongReal jday )

Get the moon's direction at a certain time.

Parameters

jday	astronomical julian day.

const Ogre::Real Caelum::CaelumSystem::getMoonPhase ( LongReal jday )

Function to get the phase of the moon.

Parameters

jday	Julian day

Returns: the phase of the moon; ranging from 0(full moon) to 1(again full moon).

const Ogre::Vector3 Caelum::CaelumSystem::getEclipticNorthPoleDirection ( LongReal jday )

Get the ecliptic's north pole direction at a certain time.

Useful as Moon's north polar axis points within 1.5 degrees of the north ecliptic pole.

Parameters

jday	astronomical julian day.

void Caelum::CaelumSystem::forceSubcomponentQueryFlags ( uint mask )

Call setQueryFlags for all subcomponents now.

This is not persistent; you can adjust the query masks of individual objects afterwards. This also means you should call this only after you created all other objects.

Has no effect on compositor-based stuff (precipitation will still show up).

void Caelum::CaelumSystem::forceSubcomponentVisibilityFlags ( uint mask )

Same as.

See also: forceSubcomponentQueryMask; but for visibility

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

/home/pavel/workspace/ogre-caelum/main/include/CaelumSystem.h

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation