Light source. More...

#include <deLight.h>

Inheritance diagram for deLight:

Public Types
enum	eLightTypes { eltPoint, eltSemiPoint, eltSpot, eltProjector, eltAmbient }
	Type of the light source. More...
enum	eMovementHints { emhStatic, emhJittering, emhDynamic }
	Movement hints of the light. More...
enum	pParameterHints { ephStatic, ephActivation, ephFlicker, ephDynamic }
	Parameter hints of the light. More...
Public Member Functions
Constructors and Destructors
	deLight (deLightManager *manager)
	Creates a new light source with the given resource manager.
	~deLight ()
	Cleans up the light source.
Management
int	GetType () const
	Retrieves the type of the light source.
void	SetType (int type)
	Sets the type of the light source.
const decColor &	GetColor () const
	Retrieves the color of the light source.
void	SetColor (const decColor &color)
	Sets the color of the light source.
float	GetIntensity () const
	Retrieves the intensity of the light source.
void	SetIntensity (float intensity)
	Sets the intensity of the light source.
float	GetRange () const
	Retrieves the light range in meters.
void	SetRange (float range)
	Sets the light range in meters.
float	GetHalfIntensityDistance () const
	Retrieves the distance in meters at which the intensity is halved.
void	SetHalfIntensityDistance (float distance)
	Sets the distance in meters at which the intensity is halved.
float	GetCutOffDistance () const
	Retrieves the light cut-off distance.
void	SetCutOffDistance (float distance)
	Sets the light cut-off distance.
float	GetAmbientRatio () const
	Retrieves the ratio of ambient light in relation to the total intensity.
void	SetAmbientRatio (float ratio)
	Sets the ratio of ambient light in relation to the total intensity.
const decDVector &	GetPosition () const
	Retrieves the position of the light source.
void	SetPosition (const decDVector &position)
	Sets the position of the light source.
const decQuaternion &	GetOrientation () const
	Retrieves the orientation of the light source.
void	SetOrientation (const decQuaternion &orientation)
	Sets the orientation of the light source.
const decVector2 &	GetAngles () const
	Retrieves the light angles.
void	SetAngles (const decVector2 &angles)
	Sets the light angles.
float	GetSpotExponent () const
	Retrieves the spot exponent.
void	SetSpotExponent (float exponent)
	Sets the spot exponent.
const decVector &	GetShadowOrigin () const
	Retrieves the shadow origin.
void	SetShadowOrigin (const decVector &origin)
	Sets the shadow origin.
float	GetShadowGap () const
	Retrieves the shadow gap size.
void	SetShadowGap (float gap)
	Sets the shadow gap size.
deImage *	GetProjectorImage () const
	Retrieves the light image or null if no light image is set.
void	SetProjectorImage (deImage *image)
	Retrieves the light image or null to unset the light image.
deRenderTarget *	GetProjectorRenderTarget () const
	Retrieves the light render target or null if no light render target is set.
void	SetProjectorRenderTarget (deRenderTarget *target)
	Retrieves the light render target or null to unset the light render target.
int	GetHintLightImportance () const
	Retrieves the light importance.
void	SetHintLightImportance (int importance)
	Sets the hint light importance.
int	GetHintShadowImportance () const
	Retrieves the shadow importance.
void	SetHintShadowImportance (int importance)
	Sets the hint shadow importance.
int	GetHintMovement () const
	Retrieves the movement hint.
void	SetHintMovement (int hint)
	Sets the movement hint.
int	GetHintParameter () const
	Retrieves the parameter hint.
void	SetHintParameter (int hint)
	Sets the parameter hint.
bool	GetActivated () const
	Determines if the light is activated and emitting light.
void	SetActivated (bool activated)
	Sets if the light is activated and emitting light.
bool	GetCastShadows () const
	Determines if the light casts shadows.
void	SetCastShadows (bool castShadows)
	Sets if the light casts shadows.
Light Cage
int	GetCageShapeCount () const
	Retrieves the number of cage shapes.
decShape *	GetCageShapeAt (int index) const
	Retrieves the cage shape at the given index.
int	IndexOfCageShape (decShape *cageShape) const
	Retrieves the index of the given cage shape or -1 if not found.
bool	HasCageShape (decShape *cageShape) const
	Determines if the cage shape exists.
void	AddCageShape (decShape *cageShape)
	Adds a cage shape.
void	RemoveCageShape (decShape *cageShape)
	Removes a cage shape.
void	RemoveAllCageShapes ()
	Removes all cage shapes.
void	NotifyCageChanged ()
	Notifies the peers that the light cage changed.
System Peers
deBaseGraphicLight *	GetGraphicLight () const
	Retrieves the graphic system peer object.
void	SetGraphicLight (deBaseGraphicLight *graLigSource)
	Sets the graphic system peer object.

Detailed Description

Light source.

Lights are the only light sources you can place in a world. The other light source, the sky layers, light globally while this light sources work locally. Light sources have various parameters influencing the appearance of the lit objects. The color indicates the tint of the light source while the intensities indicate the strength of the light source. Intensities are measured in lumen. Lumen readings for various light sources can be found in literatur providing a good starting ground for realistic lighting. The intensity value indicates the strength of the light at the light source enlighting world elements facing towards the light source. The ambient intensity serves as a sort of backlit to avoid no light contribution on the backside of world elements. It is a sort of local ambient light for only this light source. This way the backlit can be adjusted for worlds if the graphic module does not use a more sophisticated lighting model. The half intensity distance and the attenuation exponent determine how the light attenuates over distance. This model is more powerful than the typical static-linear-quadratic attenuation model and requires also requires less parameters. The light is attenuated to half the strength reaching the distance set in the half intensity distance. The attenuation exponent indicates the power to which the distance of a fragment to the light source is raised. A value of 2 yields physically correct lighting while larger values produce dramatic lighting effects like light staying mostly constant over a given distance then falling off sharply. The cut off distance indicates a maximal distance the light travels before attenuated to zero strength. This is a hint for the graphic module especially for confined light sources which only illuminate objects in a small place. Each light has a position where the light starts from. Depending on the light type additional parameters are used.

Point Light Source: Point light sources emmit light in all directions equally. No additional parameters are used for this light type. Point lights are simple to use but often more expensive than a spot light. Use them therefore with care.

Spot Light Source: Spot lights work like point lights but in addition the light emission is limited to a cone. The cone is defined using the orientation quaternion. The best way to work with this parameter is to create a matrix where the Z Axis points along the center axis of the light cone and retrieving the quaternion thereof. In addition two angles and an exponent can be set. The angles define the inner and outer angle of the cone. The attenuation due to the cone is multiplied with the distance attenuation. Inside the inner angle no attenuation from the cone is contributed. Outside the outer angle light is attenuated to 0. For angles between the two cone angles an exponential decay is used with the spot exponent indicating the power to use. With these three parameters a large variety of spot lights can be modeled.

Projector Light Source: Projector lights work similar to spot lights with the difference that they are in the shape of a pyramid instead of a cone and that they use an image to multiply with the light color. Projectors can be seen as a beamer projecting an image on a world and are useful to produce all kinds of complex spot or projector lights. The image is projected along the Z Axis of matrix corresponding to the orientation with the X Axis corresponding to the image U direction and the Y Axis corresponding to the image V direction. Distance attenuation applies here like in the spot light case but no cone attenuation takes place. Apply the light shape based attenuation into the image instead.

Author:: Plüss Roland

Version:: 1.0

Date:: 2008

Member Enumeration Documentation

enum deLight::eLightTypes

Type of the light source.

Enumerator:

eltPoint	Point light source.
eltSemiPoint	Semi point light source.
eltSpot	Spot light source.
eltProjector	Projector light source.
eltAmbient	Ambient light source.

enum deLight::eMovementHints

Movement hints of the light.

Enumerator:

emhStatic	Light remains static for the entire lifetime.
emhJittering	Light remains mostly static jittering in a small area.
emhDynamic	Light moves around freely.

enum deLight::pParameterHints

Parameter hints of the light.

Enumerator:

ephStatic	Light parameters never change.
ephActivation	Light parameters never change except activation.
ephFlicker	Geometric light parameters never change but others can.
ephDynamic	All light parameters can change at will any time.

Constructor & Destructor Documentation

deLight::deLight ( deLightManager * manager )

Creates a new light source with the given resource manager.

deLight::~deLight ( )

Cleans up the light source.

Member Function Documentation

void deLight::AddCageShape ( decShape * cageShape )

Adds a cage shape.

bool deLight::GetActivated ( ) const [inline]

Determines if the light is activated and emitting light.

float deLight::GetAmbientRatio ( ) const [inline]

Retrieves the ratio of ambient light in relation to the total intensity.

const decVector2& deLight::GetAngles ( ) const [inline]

Retrieves the light angles.

decShape* deLight::GetCageShapeAt ( int index ) const

Retrieves the cage shape at the given index.

int deLight::GetCageShapeCount ( ) const

Retrieves the number of cage shapes.

bool deLight::GetCastShadows ( ) const [inline]

Determines if the light casts shadows.

const decColor& deLight::GetColor ( ) const [inline]

Retrieves the color of the light source.

float deLight::GetCutOffDistance ( ) const [inline]

Retrieves the light cut-off distance.

deBaseGraphicLight* deLight::GetGraphicLight ( ) const [inline]

Retrieves the graphic system peer object.

float deLight::GetHalfIntensityDistance ( ) const [inline]

Retrieves the distance in meters at which the intensity is halved.

int deLight::GetHintLightImportance ( ) const [inline]

Retrieves the light importance.

int deLight::GetHintMovement ( ) const [inline]

Retrieves the movement hint.

int deLight::GetHintParameter ( ) const [inline]

Retrieves the parameter hint.

int deLight::GetHintShadowImportance ( ) const [inline]

Retrieves the shadow importance.

float deLight::GetIntensity ( ) const [inline]

Retrieves the intensity of the light source.

const decQuaternion& deLight::GetOrientation ( ) const [inline]

Retrieves the orientation of the light source.

const decDVector& deLight::GetPosition ( ) const [inline]

Retrieves the position of the light source.

deImage* deLight::GetProjectorImage ( ) const [inline]

Retrieves the light image or null if no light image is set.

Used only by spot lights.

deRenderTarget* deLight::GetProjectorRenderTarget ( ) const [inline]

Retrieves the light render target or null if no light render target is set.

Used only by spot lights.

float deLight::GetRange ( ) const [inline]

Retrieves the light range in meters.

float deLight::GetShadowGap ( ) const [inline]

Retrieves the shadow gap size.

const decVector& deLight::GetShadowOrigin ( ) const [inline]

Retrieves the shadow origin.

float deLight::GetSpotExponent ( ) const [inline]

Retrieves the spot exponent.

int deLight::GetType ( ) const [inline]

Retrieves the type of the light source.

bool deLight::HasCageShape ( decShape * cageShape ) const

Determines if the cage shape exists.

int deLight::IndexOfCageShape ( decShape * cageShape ) const

Retrieves the index of the given cage shape or -1 if not found.

void deLight::NotifyCageChanged ( )

Notifies the peers that the light cage changed.

void deLight::RemoveAllCageShapes ( )

Removes all cage shapes.

void deLight::RemoveCageShape ( decShape * cageShape )

Removes a cage shape.

void deLight::SetActivated ( bool activated )

Sets if the light is activated and emitting light.

void deLight::SetAmbientRatio ( float ratio )

Sets the ratio of ambient light in relation to the total intensity.

void deLight::SetAngles ( const decVector2 & angles )

Sets the light angles.

void deLight::SetCastShadows ( bool castShadows )

Sets if the light casts shadows.

void deLight::SetColor ( const decColor & color )

Sets the color of the light source.

void deLight::SetCutOffDistance ( float distance )

Sets the light cut-off distance.

void deLight::SetGraphicLight ( deBaseGraphicLight * graLigSource )

Sets the graphic system peer object.

void deLight::SetHalfIntensityDistance ( float distance )

Sets the distance in meters at which the intensity is halved.

void deLight::SetHintLightImportance ( int importance )

Sets the hint light importance.

void deLight::SetHintMovement ( int hint )

Sets the movement hint.

void deLight::SetHintParameter ( int hint )

Sets the parameter hint.

void deLight::SetHintShadowImportance ( int importance )

Sets the hint shadow importance.

void deLight::SetIntensity ( float intensity )

Sets the intensity of the light source.

void deLight::SetOrientation ( const decQuaternion & orientation )

Sets the orientation of the light source.

void deLight::SetPosition ( const decDVector & position )

Sets the position of the light source.

void deLight::SetProjectorImage ( deImage * image )

Retrieves the light image or null to unset the light image.

If the light image is set the light parameters are bypassed and this image is projected onto the object to be lit. If the image is grayscale the light color is first multiplied otherwise the image is used as it is. Used only by spot lights.

void deLight::SetProjectorRenderTarget ( deRenderTarget * target )

Retrieves the light render target or null to unset the light render target.

If the light render target is set the light parameters are bypassed and this render target is projected onto the object to be lit. The render target is used directly without multiplying the colors. Used only by spot lights.

void deLight::SetRange ( float range )

Sets the light range in meters.

void deLight::SetShadowGap ( float gap )

Sets the shadow gap size.

void deLight::SetShadowOrigin ( const decVector & origin )

Sets the shadow origin.

void deLight::SetSpotExponent ( float exponent )

Sets the spot exponent.

void deLight::SetType ( int type )

Sets the type of the light source.

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

deLight.h

deLight Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation