Light source. More...

#include <deLight.h>

Inheritance diagram for deLight:

Public Types
enum	eLightTypes { eltPoint , eltSpot , eltProjector }
	Light type. More...

enum	eMovementHints { emhStationary , emhJittering , emhDynamic }
	Movement hints. More...

enum	eParameterHints { ephStatic , ephActivation , ephFlicker , ephDynamic }
	Parameter hints. More...

typedef deTObjectReference< deLight >	Ref
	Type holding strong reference. More...

Public Types inherited from deResource
typedef deTObjectReference< deResource >	Ref
	Type holding strong reference. More...

Public Types inherited from deObject
typedef deTObjectReference< deObject >	Ref
	Type holding strong reference. More...

Public Member Functions
Management
eLightTypes	GetType () const
	Light type. More...

void	SetType (eLightTypes type)
	Set light type. More...

const decColor &	GetColor () const
	Light color. More...

void	SetColor (const decColor &color)
	Set light color. More...

float	GetIntensity () const
	Intensity. More...

void	SetIntensity (float intensity)
	Set intensity. More...

float	GetRange () const
	Range in meters. More...

void	SetRange (float range)
	Set light range in meters. More...

float	GetHalfIntensityDistance () const
	Distance in meters at which the intensity is halved. More...

void	SetHalfIntensityDistance (float distance)
	Set distance in meters at which the intensity is halved. More...

float	GetAmbientRatio () const
	Ratio of ambient light in relation to intensity. More...

void	SetAmbientRatio (float ratio)
	Set ratio of ambient light in relation to intensity. More...

const decDVector &	GetPosition () const
	Position. More...

void	SetPosition (const decDVector &position)
	Set position. More...

const decQuaternion &	GetOrientation () const
	Orientation. More...

void	SetOrientation (const decQuaternion &orientation)
	Set orientation. More...

float	GetSpotAngle () const
	Outer spot Angle. More...

void	SetSpotAngle (float angle)
	Set outer spot angle. More...

float	GetSpotRatio () const
	Spot ratio as height divided by width. More...

void	SetSpotRatio (float ratio)
	Set spot ratio as height divided by width. More...

float	GetSpotSmoothness () const
	Spot smoothness. More...

void	SetSpotSmoothness (float smoothness)
	Set spot smoothness. More...

float	GetSpotExponent () const
	Spot exponent. More...

void	SetSpotExponent (float exponent)
	Set spot exponent. More...

const decShapeList &	GetShape () const
	Light shape. More...

void	SetShape (const decShapeList &shape)
	Set light shape. More...

deSkin *	GetLightSkin () const
	Light skin or NULL if not used. More...

void	SetLightSkin (deSkin *skin)
	Set light skin or NULL if not used. More...

deCanvasView *	GetLightCanvas () const
	Light canvas view or NULL if not used. More...

void	SetLightCanvas (deCanvasView *canvas)
	Set light canvas view or NULL if not used. More...

deDynamicSkin *	GetDynamicSkin () const
	Light dynamic skin or NULL if not used. More...

void	SetDynamicSkin (deDynamicSkin *dynamicSkin)
	Set light dynamic skin or NULL if not used. More...

const decTexMatrix2 &	GetTransform () const
	Light texture coordinate transformation matrix. More...

void	SetTransform (const decTexMatrix2 &matrix)
	Set light texture coordinate transformation matrix. More...

int	GetHintLightImportance () const
	Hint light importance. More...

void	SetHintLightImportance (int importance)
	Set hint light importance. More...

int	GetHintShadowImportance () const
	Hint shadow importance. More...

void	SetHintShadowImportance (int importance)
	Set hint shadow importance. More...

eMovementHints	GetHintMovement () const
	Movement hint. More...

void	SetHintMovement (eMovementHints hint)
	Set movement hint. More...

eParameterHints	GetHintParameter () const
	Parameter hint. More...

void	SetHintParameter (eParameterHints hint)
	Set parameter hint. More...

const decShapeList &	GetCage () const
	Light cage. More...

void	SetCage (const decShapeList &cage)
	Set light cage. More...

const decLayerMask &	GetLayerMask () const
	Layer mask affecting lighting. More...

void	SetLayerMask (const decLayerMask &layerMask)
	Set layer mask affecting lighting. More...

const decLayerMask &	GetLayerMaskShadow () const
	Layer mask affecting shadow casting. More...

void	SetLayerMaskShadow (const decLayerMask &layerMask)
	Set layer mask affecting shadow casting. More...

bool	GetActivated () const
	Light is activated. More...

void	SetActivated (bool activated)
	Set if light is activated. More...

bool	GetCastShadows () const
	Light casts shadows. More...

void	SetCastShadows (bool castShadows)
	Set if light casts shadows. More...

Shadow ignore components
int	GetShadowIgnoreComponentCount () const
	Number of components to ignore for shadow casting. More...

deComponent *	GetShadowIgnoreComponentAt (int index) const
	Component to ignore for shadow casting at index. More...

bool	HasShadowIgnoreComponent (deComponent *component) const
	Component to ignore for shadow casting is present. More...

void	AddShadowIgnoreComponent (deComponent *component)
	Add component to ignore for shadow casting. More...

void	RemoveShadowIgnoreComponent (deComponent *component)
	Remove component to ignore for shadow casting. More...

void	RemoveAllShadowIgnoreComponents ()
	Remove all components to ignore for shadow casting. More...

System Peers
deBaseGraphicLight *	GetPeerGraphic () const
	Graphic system peer. More...

void	SetPeerGraphic (deBaseGraphicLight *peer)
	Set graphic system peer. More...

Linked List
deWorld *	GetParentWorld () const
	Parent world or NULL. More...

void	SetParentWorld (deWorld *world)
	Set parent world or NULL. More...

deLight *	GetLLWorldPrev () const
	Previous light in the parent world linked list. More...

void	SetLLWorldPrev (deLight *light)
	Set next light in the parent world linked list. More...

deLight *	GetLLWorldNext () const
	Next light in the parent world linked list. More...

void	SetLLWorldNext (deLight *light)
	Set next light in the parent world linked list. More...

Public Member Functions inherited from deResource
deResourceManager *	GetResourceManager () const
	Resource manager or NULL if resource is leaking. More...

deEngine *	GetEngine () const
	Game engine object from resource manager. More...

deResource *	GetLLManagerPrev () const
	Previous resource in the resource manager linked list. More...

void	SetLLManagerPrev (deResource *resource)
	Set next resource in the resource manager linked list. More...

deResource *	GetLLManagerNext () const
	Next resource in the resource manager linked list. More...

void	SetLLManagerNext (deResource *resource)
	Set next resource in the resource manager linked list. More...

void	MarkLeaking ()
	Marks the resource leaking. More...

	deResource (deResourceManager *resourceManager)
	Create resource. More...

Public Member Functions inherited from deObject
int	GetRefCount () const
	Reference count. More...

void	AddReference ()
	Add reference increasing reference count by 1. More...

void	FreeReference ()
	Decrease reference count by one and delete object if count reaches 0. More...

	deObject ()
	Create object with reference count of 1. More...

Constructors and Destructors
	deLight (deLightManager *manager)
	Create light source. More...

virtual	~deLight ()
	Clean up light source. More...

Additional Inherited Members
Protected Member Functions inherited from deResource
virtual	~deResource ()
	Clean up resource. More...

Protected Member Functions inherited from deObject
virtual	~deObject ()
	Clean up object. More...

Detailed Description

Light source.

Places a local light source in the world. Light sources have various parameters influencing the light appearance. The color indicates the tint of the light source while the intensities indicate the strength of the light source.

Intensities are measured in an engine specific version of lumen. A value of 1 equals to a lit living room. A value of 20 equals to direct sun light at a sunny and clear sky. This is a resclaing of lumen scala found in literature to avoid large values.

The ambient ratio defines the amount of intensity affecting objects in shadow. Using ambient intensity larger than 0 allows to simulate overhead lights in rooms without needing multiple light sources to cancel out pitch black areas. Using fewer light sources is faster than more. The ambient ratio can be set in the range from 0 to 1. Increasing the ambient ratio only affects shadow areas. The light intensity is not altered.

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 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 and harsher lighting effects like light staying mostly constant over a given distance then falling off sharply.

The light cage is a hint for graphic modules to optimize lighting. Objects outside the cage shape should not be reachable by the light source. If set properly performance can be increased due to the graphic module requiring less objects to be considered for lighting or shadow casting.

By default light sources have a uniform light color attenuated by the light type and other factors. The light color can be modified using an image, video or canvas. The required image type depends on the light type. For spot and projector lights regular flat images are used. For point lights 3D images are required. The texture coordinates used to sample the image are predefined similar to skin textures.

Lights can be set to not cast shadows. This way point lights can be used to simulate ambient lighting.

The layer mask defines which cameras are affected by light. Matches layer masks in deCamera. The shadow layer mask defines which world content does cast shadows. Matches layer masks in deComponent. If empty both layer mask match everything. A typical use for these layer masks is to use two bits. The light layer mask has the first bit set and the shadow layer mask the second. Cameras have the first bit set so the light is used during rendering. All components have the first bit set to be rendered with the same camera and receive lighting. Only those casting shadows have also the second bit set. This allows to modify shadow casting on a per component level without modifying skin texture properties.

It is also possible to add specific components to a list of components to ignore for shadow casting. This is useful for light source models. The light can be placed inside the model where it is physically correctly located without the model itself causing troubles to the light. Only this light ignores this specific component. All other lights still cast shadows using this specific component.

Light shape can be used to create area lights. It is best to use one shape in the list but potentially more can be set. How well graphic module can handle this situation differs.

Point Light

Point lights 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 or projector lights especially for shadow casting.

If a light image is used the image data has to be a 3D image. If the image has a depth of 1 it has to be a spherical image (mercartor projection). If the image has a depth of 6 it has to be a cube map type image with each layer representing one cube map face. The order is X+, X-, Y+, Y-, Z+ and Z-. The image is oriented using the light coordinate frame. The light direction equals to the Z+.

Spot and Projector Light

Spot lights emit light in a cone shape. The cone is defined using the light orientation. The angle parameters 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.

If a light image is used the image data has to be a 2D image. The image is applied as if the light source shines through the image like through a slide. The image boundary lines up with the outer cone angle. Due to the cone shape only a radial area fitting into the image are used.

Projector Light Source

Projector lights work similar to spot lights but have a pyramidal shape. This allows to have rectangular shaped lights whereas spot lights are always symmetrical. The angle parameters define the width and height of the pyramid.

Member Typedef Documentation

◆ Ref

typedef deTObjectReference<deLight> deLight::Ref

Type holding strong reference.

Member Enumeration Documentation

◆ eLightTypes

enum deLight::eLightTypes

Light type.

Enumerator
eltPoint	Point light.
eltSpot	Spot light.
eltProjector	Projector light.

◆ eMovementHints

enum deLight::eMovementHints

Movement hints.

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

◆ eParameterHints

enum deLight::eParameterHints

Parameter hints.

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::deLight ( deLightManager * manager )

Create light source.

◆ ~deLight()

virtual deLight::~deLight ( )

protectedvirtual

Clean up light source.

Note: Subclasses should set their destructor protected too to avoid users accidently deleting a reference counted object through the object pointer. Only FreeReference() is allowed to delete the object.

Member Function Documentation

◆ AddShadowIgnoreComponent()

void deLight::AddShadowIgnoreComponent ( deComponent * component )

Add component to ignore for shadow casting.

Exceptions

deeInvalidParam component is present.

◆ GetActivated()

bool deLight::GetActivated ( ) const

inline

Light is activated.

◆ GetAmbientRatio()

float deLight::GetAmbientRatio ( ) const

inline

Ratio of ambient light in relation to intensity.

◆ GetCage()

const decShapeList& deLight::GetCage ( ) const

inline

Light cage.

◆ GetCastShadows()

bool deLight::GetCastShadows ( ) const

inline

Light casts shadows.

◆ GetColor()

const decColor& deLight::GetColor ( ) const

inline

Light color.

◆ GetDynamicSkin()

deDynamicSkin* deLight::GetDynamicSkin ( ) const

inline

Light dynamic skin or NULL if not used.

◆ GetHalfIntensityDistance()

float deLight::GetHalfIntensityDistance ( ) const

inline

Distance in meters at which the intensity is halved.

◆ GetHintLightImportance()

int deLight::GetHintLightImportance ( ) const

inline

Hint light importance.

◆ GetHintMovement()

eMovementHints deLight::GetHintMovement ( ) const

inline

Movement hint.

◆ GetHintParameter()

eParameterHints deLight::GetHintParameter ( ) const

inline

Parameter hint.

◆ GetHintShadowImportance()

int deLight::GetHintShadowImportance ( ) const

inline

Hint shadow importance.

◆ GetIntensity()

float deLight::GetIntensity ( ) const

inline

Intensity.

◆ GetLayerMask()

const decLayerMask& deLight::GetLayerMask ( ) const

inline

Layer mask affecting lighting.

◆ GetLayerMaskShadow()

const decLayerMask& deLight::GetLayerMaskShadow ( ) const

inline

Layer mask affecting shadow casting.

◆ GetLightCanvas()

deCanvasView* deLight::GetLightCanvas ( ) const

inline

Light canvas view or NULL if not used.

◆ GetLightSkin()

deSkin* deLight::GetLightSkin ( ) const

inline

Light skin or NULL if not used.

◆ GetLLWorldNext()

deLight* deLight::GetLLWorldNext ( ) const

inline

Next light in the parent world linked list.

◆ GetLLWorldPrev()

deLight* deLight::GetLLWorldPrev ( ) const

inline

Previous light in the parent world linked list.

◆ GetOrientation()

const decQuaternion& deLight::GetOrientation ( ) const

inline

Orientation.

◆ GetParentWorld()

deWorld* deLight::GetParentWorld ( ) const

inline

Parent world or NULL.

◆ GetPeerGraphic()

deBaseGraphicLight* deLight::GetPeerGraphic ( ) const

inline

Graphic system peer.

◆ GetPosition()

const decDVector& deLight::GetPosition ( ) const

inline

Position.

◆ GetRange()

float deLight::GetRange ( ) const

inline

Range in meters.

◆ GetShadowIgnoreComponentAt()

deComponent* deLight::GetShadowIgnoreComponentAt ( int index ) const

Component to ignore for shadow casting at index.

Exceptions

deeInvalidParam	index is less than 0.
deeInvalidParam	index is greater or equal than GetIgnoreComponentCount()-1.

◆ GetShadowIgnoreComponentCount()

int deLight::GetShadowIgnoreComponentCount ( ) const

Number of components to ignore for shadow casting.

◆ GetShape()

const decShapeList& deLight::GetShape ( ) const

inline

Light shape.

◆ GetSpotAngle()

float deLight::GetSpotAngle ( ) const

inline

Outer spot Angle.

◆ GetSpotExponent()

float deLight::GetSpotExponent ( ) const

inline

Spot exponent.

◆ GetSpotRatio()

float deLight::GetSpotRatio ( ) const

inline

Spot ratio as height divided by width.

◆ GetSpotSmoothness()

float deLight::GetSpotSmoothness ( ) const

inline

Spot smoothness.

◆ GetTransform()

const decTexMatrix2& deLight::GetTransform ( ) const

inline

Light texture coordinate transformation matrix.

◆ GetType()

eLightTypes deLight::GetType ( ) const

inline

Light type.

◆ HasShadowIgnoreComponent()

bool deLight::HasShadowIgnoreComponent ( deComponent * component ) const

Component to ignore for shadow casting is present.

◆ RemoveAllShadowIgnoreComponents()

void deLight::RemoveAllShadowIgnoreComponents ( )

Remove all components to ignore for shadow casting.

◆ RemoveShadowIgnoreComponent()

void deLight::RemoveShadowIgnoreComponent ( deComponent * component )

Remove component to ignore for shadow casting.

Exceptions

deeInvalidParam component is absent.

◆ SetActivated()

void deLight::SetActivated ( bool activated )

Set if light is activated.

◆ SetAmbientRatio()

void deLight::SetAmbientRatio ( float ratio )

Set ratio of ambient light in relation to intensity.

◆ SetCage()

void deLight::SetCage ( const decShapeList & cage )

Set light cage.

◆ SetCastShadows()

void deLight::SetCastShadows ( bool castShadows )

Set if light casts shadows.

◆ SetColor()

void deLight::SetColor ( const decColor & color )

Set light color.

◆ SetDynamicSkin()

void deLight::SetDynamicSkin ( deDynamicSkin * dynamicSkin )

Set light dynamic skin or NULL if not used.

◆ SetHalfIntensityDistance()

void deLight::SetHalfIntensityDistance ( float distance )

Set distance in meters at which the intensity is halved.

◆ SetHintLightImportance()

void deLight::SetHintLightImportance ( int importance )

Set hint light importance.

◆ SetHintMovement()

void deLight::SetHintMovement ( eMovementHints hint )

Set movement hint.

◆ SetHintParameter()

void deLight::SetHintParameter ( eParameterHints hint )

Set parameter hint.

◆ SetHintShadowImportance()

void deLight::SetHintShadowImportance ( int importance )

Set hint shadow importance.

◆ SetIntensity()

void deLight::SetIntensity ( float intensity )

Set intensity.

◆ SetLayerMask()

void deLight::SetLayerMask ( const decLayerMask & layerMask )

Set layer mask affecting lighting.

◆ SetLayerMaskShadow()

void deLight::SetLayerMaskShadow ( const decLayerMask & layerMask )

Set layer mask affecting shadow casting.

◆ SetLightCanvas()

void deLight::SetLightCanvas ( deCanvasView * canvas )

Set light canvas view or NULL if not used.

◆ SetLightSkin()

void deLight::SetLightSkin ( deSkin * skin )

Set light skin or NULL if not used.

◆ SetLLWorldNext()

void deLight::SetLLWorldNext ( deLight * light )

Set next light in the parent world linked list.

◆ SetLLWorldPrev()

void deLight::SetLLWorldPrev ( deLight * light )

Set next light in the parent world linked list.

◆ SetOrientation()

void deLight::SetOrientation ( const decQuaternion & orientation )

Set orientation.

◆ SetParentWorld()

void deLight::SetParentWorld ( deWorld * world )

Set parent world or NULL.

◆ SetPeerGraphic()

void deLight::SetPeerGraphic ( deBaseGraphicLight * peer )

Set graphic system peer.

◆ SetPosition()

void deLight::SetPosition ( const decDVector & position )

Set position.

◆ SetRange()

void deLight::SetRange ( float range )

Set light range in meters.

◆ SetShape()

void deLight::SetShape ( const decShapeList & shape )

Set light shape.

◆ SetSpotAngle()

void deLight::SetSpotAngle ( float angle )

Set outer spot angle.

◆ SetSpotExponent()

void deLight::SetSpotExponent ( float exponent )

Set spot exponent.

◆ SetSpotRatio()

void deLight::SetSpotRatio ( float ratio )

Set spot ratio as height divided by width.

◆ SetSpotSmoothness()

void deLight::SetSpotSmoothness ( float smoothness )

Set spot smoothness.

◆ SetTransform()

void deLight::SetTransform ( const decTexMatrix2 & matrix )

Set light texture coordinate transformation matrix.

◆ SetType()

void deLight::SetType ( eLightTypes type )

Set light type.

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

deLight.h

Public Types

Public Member Functions

Constructors and Destructors

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Ref

Member Enumeration Documentation

◆ eLightTypes

◆ eMovementHints

◆ eParameterHints

Constructor & Destructor Documentation

◆ deLight()

◆ ~deLight()

Member Function Documentation

◆ AddShadowIgnoreComponent()

◆ GetActivated()

◆ GetAmbientRatio()

◆ GetCage()

◆ GetCastShadows()

◆ GetColor()

◆ GetDynamicSkin()

◆ GetHalfIntensityDistance()

◆ GetHintLightImportance()

◆ GetHintMovement()

◆ GetHintParameter()

◆ GetHintShadowImportance()

◆ GetIntensity()

◆ GetLayerMask()

◆ GetLayerMaskShadow()

◆ GetLightCanvas()

◆ GetLightSkin()

◆ GetLLWorldNext()

◆ GetLLWorldPrev()

◆ GetOrientation()

◆ GetParentWorld()

◆ GetPeerGraphic()

◆ GetPosition()

◆ GetRange()

◆ GetShadowIgnoreComponentAt()

◆ GetShadowIgnoreComponentCount()

◆ GetShape()

◆ GetSpotAngle()

◆ GetSpotExponent()

◆ GetSpotRatio()

◆ GetSpotSmoothness()

◆ GetTransform()

◆ GetType()

◆ HasShadowIgnoreComponent()

◆ RemoveAllShadowIgnoreComponents()

◆ RemoveShadowIgnoreComponent()

◆ SetActivated()

◆ SetAmbientRatio()

◆ SetCage()

◆ SetCastShadows()

◆ SetColor()

◆ SetDynamicSkin()

◆ SetHalfIntensityDistance()

◆ SetHintLightImportance()

◆ SetHintMovement()

◆ SetHintParameter()

◆ SetHintShadowImportance()

◆ SetIntensity()

◆ SetLayerMask()

◆ SetLayerMaskShadow()

◆ SetLightCanvas()

◆ SetLightSkin()

◆ SetLLWorldNext()

◆ SetLLWorldPrev()

◆ SetOrientation()

◆ SetParentWorld()

◆ SetPeerGraphic()

◆ SetPosition()

◆ SetRange()

◆ SetShape()

◆ SetSpotAngle()

◆ SetSpotExponent()

◆ SetSpotRatio()

◆ SetSpotSmoothness()

◆ SetTransform()