---

Ogre::Light Class Reference

Representation of a dynamic light source in the scene. More...

#include <OgreLight.h>

Inheritance diagram for Ogre::Light:

List of all members.

Public Types
enum	LightTypes { LT_POINT, LT_DIRECTIONAL, LT_SPOTLIGHT }
	Defines the type of light. More...
Public Methods
	Light ()
	Default constructor (for Python mainly). More...
	Light (String name)
	Normal constructor. More...
	~Light ()
	Standard destructor. More...
const String &	getName (void) const
	Returns the name of this light (cannot be modified). More...
void	setType (LightTypes type)
	Sets the type of light - see LightTypes for more info. More...
LightTypes	getType (void)
	Returns the light type. More...
void	setDiffuseColour (Real red, Real green, Real blue)
	Sets the colour of the diffuse light given off by this source. More...
void	setDiffuseColour (const ColourValue &colour)
	Sets the colour of the diffuse light given off by this source. More...
ColourValue	getDiffuseColour (void)
	Returns the colour of the diffuse light given off by this light source (see setDiffuseColour for more info). More...
void	setSpecularColour (Real red, Real green, Real blue)
	Sets the colour of the specular light given off by this source. More...
void	setSpecularColour (const ColourValue &colour)
	Sets the colour of the specular light given off by this source. More...
ColourValue	getSpecularColour (void)
	Returns the colour of specular light given off by this light source. More...
void	setAttenuation (Real range, Real constant, Real linear, Real quadratic)
	Sets the attenuation parameters of the light source ie how it diminishes with distance. More...
Real	getAttenuationRange (void)
	Returns the absolute upper range of the light. More...
Real	getAttenuationConstant (void)
	Returns the constant factor in the attenuation formula. More...
Real	getAttenuationLinear (void)
	Returns the linear factor in the attenuation formula. More...
Real	getAttenuationQuadric (void)
	Returns the quadric factor in the attenuation formula. More...
void	setPosition (Real x, Real y, Real z)
	Sets the position of the light. More...
void	setPosition (const Vector3 &vec)
	Sets the position of the light. More...
Vector3	getPosition (void)
	Returns the position of the light. More...
void	setDirection (Real x, Real y, Real z)
	Sets the direction in which a light points. More...
void	setDirection (const Vector3 &vec)
	Sets the direction in which a light points. More...
Vector3	getDirection (void)
	Returns the light's direction. More...
void	setSpotlightRange (Real innerAngle, Real outerAngle, Real falloff=1.0)
	Sets the range of a spotlight, i.e. More...
Real	getSpotlightInnerAngle (void)
	Returns the angle covered by the spotlights inner cone, in degrees. More...
Real	getSpotlightOuterAngle (void)
	Returns the angle covered by the spotlights outer cone, in degrees. More...
Real	getSpotlightFalloff (void)
	Returns the falloff between the inner and outer cones of the spotlight. More...
bool	isModified (void)
	Returns a true/false value indicating if this light has changed since it was last issued to the renderer. More...
void	_clearModified (void)
	Clears the light's modified flag (should only be done by the engine itself). More...
void	_notifyCurrentCamera (Camera *cam)
	Overridden from MovableObject. More...
const AxisAlignedBox &	getBoundingBox (void) const
	Overridden from MovableObject. More...
void	_updateRenderQueue (RenderQueue *queue)
	Overridden from MovableObject. More...
const String	getMovableType (void) const
	Overridden from MovableObject. More...
const Vector3 &	getDerivedPosition (void)
	Retrieves the position of the light including any transform from nodes it is attached to. More...
const Vector3 &	getDerivedDirection (void)
	Retrieves the direction of the light including any transform from nodes it is attached to. More...
void	setVisible (bool visible)
	Overridden from MovableObject. More...
virtual SceneNode *	getParentNode (void)
	Returns the node to which this object is attached. More...
virtual void	_notifyAttached (SceneNode *parent)
	Internal method called to notify the object that it has been attached to a node. More...
virtual bool	isAttached (void) const
	Returns true if this object is attached to a SceneNode. More...
virtual bool	isVisible (void) const
	Returns whether or not this object is supposed to be visible or not. More...
virtual void	setUserObject (UserDefinedObject *obj)
	Call this to associate your own custom user object instance with this MovableObject. More...
virtual UserDefinedObject *	getUserObject (void)
	Retrieves a pointer to a custom application object associated with this movable by an earlier call to setUserObject. More...
virtual void	setRenderQueueGroup (RenderQueueGroupID queueID)
	Sets the render queue group this entity will be rendered through. More...
virtual RenderQueueGroupID	getRenderQueueGroup (void)
	Gets the queue group for this entity, see setRenderQueueGroup for full details. More...
Protected Attributes
SceneNode *	mParentNode
	node to which this object is attached. More...
bool	mVisible
	Is this object visible? More...
UserDefinedObject *	mUserObject
	User defined object which is linked to this object. More...
RenderQueueGroupID	mRenderQueueID
	The render queue to use when rendering this object. More...
Private Attributes
String	mName
LightTypes	mLightType
Vector3	mPosition
ColourValue	mDiffuse
ColourValue	mSpecular
Vector3	mDirection
Real	mSpotOuter
Real	mSpotInner
Real	mSpotFalloff
Real	mRange
Real	mAttenuationConst
Real	mAttenuationLinear
Real	mAttenuationQuad
bool	mModified
Vector3	mDerivedPosition
Vector3	mDerivedDirection
Quaternion	mLastParentOrientation
	Stored versions of parent orientation / position. More...
Vector3	mLastParentPosition
Static Private Attributes
String	msMovableType = "Light"
	Shared class-level name for Movable type. More...

---

Detailed Description

Representation of a dynamic light source in the scene.

Remarks:

Lights are added to the scene like any other object. They contain various parameters like type, position, attenuation (how light intensity fades with distance), colour etc.

The defaults when a light is created is pure white diffues light, with linear attenuation (decreases steadily with distance) and a range of 1000 world units.

Lights are created by using the SceneManager::createLight method. They can subsequently be added to a SceneNode if required to allow them to move relative to a node in the scene. A light attached to a SceneNode is assumed to havea base position of (0,0,0) and a direction of (0,0,1) before modification by the SceneNode's own orientation. If not attached to a SceneNode, the light's position and direction is as set using setPosition and setDirection.

Remember also that dynamic lights rely on modifying the colour of vertices based on the position of the light compared to an object's vertex normals. Dynamic lighting will only look good if the object being lit has a fair level of tesselation and the normals are properly set. This is particularly true for the spotlight which will only look right on highly tesselated models. In the future OGRE may be extended for certain scene types so an alternative to the standard dynamic lighting may be used, such as dynamic lightmaps.

---

Member Enumeration Documentation

enum Ogre::Light::LightTypes

Defines the type of light. Enumeration values: LT_POINT  Point light sources give off light equally in all directions, so require only position not direction. LT_DIRECTIONAL  Directional lights simulate parallel light beams from a distant source, hence have direction but no position. LT_SPOTLIGHT  Spotlights simulate a cone of light from a source so require position and direction, plus extra values for falloff.

---

Constructor & Destructor Documentation

Ogre::Light::Light (    )

Default constructor (for Python mainly).

Ogre::Light::Light (  String    name )

Normal constructor. Should not be called directly, but rather the SceneManager::createLight method should be used.

Ogre::Light::~Light (    )

Standard destructor.

---

Member Function Documentation

void Ogre::Light::_clearModified (  void    )

Clears the light's modified flag (should only be done by the engine itself).

void Ogre::MovableObject::_notifyAttached (  SceneNode *    parent )  [virtual, inherited]

Internal method called to notify the object that it has been attached to a node. Reimplemented in Ogre::SimpleRenderable.

void Ogre::Light::_notifyCurrentCamera (  Camera *    cam )  [virtual]

Overridden from MovableObject. Implements Ogre::MovableObject.

void Ogre::Light::_updateRenderQueue (  RenderQueue *    queue )  [virtual]

Overridden from MovableObject. Implements Ogre::MovableObject.

Real Ogre::Light::getAttenuationConstant (  void    )

Returns the constant factor in the attenuation formula.

Real Ogre::Light::getAttenuationLinear (  void    )

Returns the linear factor in the attenuation formula.

Real Ogre::Light::getAttenuationQuadric (  void    )

Returns the quadric factor in the attenuation formula.

Real Ogre::Light::getAttenuationRange (  void    )

Returns the absolute upper range of the light.

const AxisAlignedBox & Ogre::Light::getBoundingBox (  void    )  const [virtual]

Overridden from MovableObject. Implements Ogre::MovableObject.

const Vector3 & Ogre::Light::getDerivedDirection (  void    )

Retrieves the direction of the light including any transform from nodes it is attached to.

const Vector3 & Ogre::Light::getDerivedPosition (  void    )

Retrieves the position of the light including any transform from nodes it is attached to.

ColourValue Ogre::Light::getDiffuseColour (  void    )

Returns the colour of the diffuse light given off by this light source (see setDiffuseColour for more info).

Vector3 Ogre::Light::getDirection (  void    )

Returns the light's direction. Remarks: Applicable only to the spotlight and directional light types.

const String Ogre::Light::getMovableType (  void    )  const [virtual]

Overridden from MovableObject. Implements Ogre::MovableObject.

const String & Ogre::Light::getName (  void    )  const [virtual]

Returns the name of this light (cannot be modified). Implements Ogre::MovableObject.

SceneNode * Ogre::MovableObject::getParentNode (  void    )  [virtual, inherited]

Returns the node to which this object is attached. Remarks: An object is not visible in the scene unless attached to a SceneNode. Attaching an object is done via the SceneNode::attachObject method. Reimplemented in Ogre::SimpleRenderable.

Vector3 Ogre::Light::getPosition (  void    )

Returns the position of the light. Note: Applicable to point lights and spotlights only.

RenderQueueGroupID Ogre::MovableObject::getRenderQueueGroup (  void    )  [virtual, inherited]

Gets the queue group for this entity, see setRenderQueueGroup for full details.

ColourValue Ogre::Light::getSpecularColour (  void    )

Returns the colour of specular light given off by this light source.

Real Ogre::Light::getSpotlightFalloff (  void    )

Returns the falloff between the inner and outer cones of the spotlight.

Real Ogre::Light::getSpotlightInnerAngle (  void    )

Returns the angle covered by the spotlights inner cone, in degrees.

Real Ogre::Light::getSpotlightOuterAngle (  void    )

Returns the angle covered by the spotlights outer cone, in degrees.

Light::LightTypes Ogre::Light::getType (  void    )

Returns the light type.

virtual UserDefinedObject* Ogre::MovableObject::getUserObject (  void    )  [inline, virtual, inherited]

Retrieves a pointer to a custom application object associated with this movable by an earlier call to setUserObject.

bool Ogre::MovableObject::isAttached (  void    )  const [virtual, inherited]

Returns true if this object is attached to a SceneNode.

bool Ogre::Light::isModified (  void    )

Returns a true/false value indicating if this light has changed since it was last issued to the renderer.

bool Ogre::MovableObject::isVisible (  void    )  const [virtual, inherited]

Returns whether or not this object is supposed to be visible or not.

void Ogre::Light::setAttenuation (  Real    range, Real    constant, Real    linear, Real    quadratic )

Sets the attenuation parameters of the light source ie how it diminishes with distance. Remarks: Lights normally get fainter the further they are away. Also, each light is given a maximum range beyond which it cannot affect any objects. Light attentuation is not applicable to directional lights since they have an infinite range and constant intensity. This follows a standard attenuation approach - see any good 3D text for the details of what they mean since i don't have room here! Parameters: range  The absolute upper range of the light in world units constant  The constant factor in the attenuation formula: 1.0 means never attenuate, 0.0 is complete attenuation linear  The linear factor in the attenuation formula: 1 means attenuate evenly over the distance quadratic  The quadratic factor in the attenuation formula: adds a curvature to the attenuation formula.

void Ogre::Light::setDiffuseColour (  const ColourValue &    colour )

Sets the colour of the diffuse light given off by this source. Remarks: Material objects have ambient, diffuse and specular values which indicate how much of each type of light an object reflects. This value denotes the amount and colour of this type of light the light exudes into the scene. The actual appearance of objects is a combination of the two. Diffuse light simulates the typical light emenating from light sources and affects the base colour of objects together with ambient light.

void Ogre::Light::setDiffuseColour (  Real    red, Real    green, Real    blue )

Sets the colour of the diffuse light given off by this source. Remarks: Material objects have ambient, diffuse and specular values which indicate how much of each type of light an object reflects. This value denotes the amount and colour of this type of light the light exudes into the scene. The actual appearance of objects is a combination of the two. Diffuse light simulates the typical light emenating from light sources and affects the base colour of objects together with ambient light.

void Ogre::Light::setDirection (  const Vector3 &    vec )

Sets the direction in which a light points. Remarks: Applicable only to the spotlight and directional light types. Note: This will be overridden if the light is attached to a SceneNode.

void Ogre::Light::setDirection (  Real    x, Real    y, Real    z )

Sets the direction in which a light points. Remarks: Applicable only to the spotlight and directional light types. Note: This will be overridden if the light is attached to a SceneNode.

void Ogre::Light::setPosition (  const Vector3 &    vec )

Sets the position of the light. Remarks: Applicable to point lights and spotlights only. Note: This will be overridden if the light is attached to a SceneNode.

void Ogre::Light::setPosition (  Real    x, Real    y, Real    z )

Sets the position of the light. Remarks: Applicable to point lights and spotlights only. Note: This will be overridden if the light is attached to a SceneNode.

void Ogre::MovableObject::setRenderQueueGroup (  RenderQueueGroupID    queueID )  [virtual, inherited]

Sets the render queue group this entity will be rendered through. Remarks: Render queues are grouped to allow you to more tightly control the ordering of rendered objects. If you do not call this method, all Entity objects default to RENDER_QUEUE_MAIN which is fine for most objects. You may want to alter this if you want this entity to always appear in front of other objects, e.g. for a 3D menu system or such. See RenderQueue for more details. Parameters: queueID  Enumerated value of the queue group to use.

void Ogre::Light::setSpecularColour (  const ColourValue &    colour )

Sets the colour of the specular light given off by this source. Remarks: Material objects have ambient, diffuse and specular values which indicate how much of each type of light an object reflects. This value denotes the amount and colour of this type of light the light exudes into the scene. The actual appearance of objects is a combination of the two. Specular light affects the appearance of shiny highlights on objects, and is also dependent on the 'shininess' Material value.

void Ogre::Light::setSpecularColour (  Real    red, Real    green, Real    blue )

Sets the colour of the specular light given off by this source. Remarks: Material objects have ambient, diffuse and specular values which indicate how much of each type of light an object reflects. This value denotes the amount and colour of this type of light the light exudes into the scene. The actual appearance of objects is a combination of the two. Specular light affects the appearance of shiny highlights on objects, and is also dependent on the 'shininess' Material value.

void Ogre::Light::setSpotlightRange (  Real    innerAngle, Real    outerAngle, Real    falloff = 1.0 )

Sets the range of a spotlight, i.e. the angle of the inner and outer cones and the rate of falloff between them. Parameters: innerAngle  Angle covered by the bright inner cone, in degrees outerAngle  Angle covered by the outer cone, in degrees falloff  The rate of falloff between the inner and outer cones. 1.0 means a linear falloff, less means slower falloff, higher means faster falloff.

void Ogre::Light::setType (  LightTypes    type )

Sets the type of light - see LightTypes for more info.

virtual void Ogre::MovableObject::setUserObject (  UserDefinedObject *    obj )  [inline, virtual, inherited]

Call this to associate your own custom user object instance with this MovableObject. Remarks: By simply making your game / application object a subclass of UserDefinedObject, you can establish a link between an OGRE instance of MovableObject and your own application classes. Call this method to establish the link.

void Ogre::Light::setVisible (  bool    visible )  [virtual]

Overridden from MovableObject. Remarks: Although lights themselves are not 'visible', setting a light to invisible means it no longer affects the scene. Reimplemented from Ogre::MovableObject.

---

Member Data Documentation

Real Ogre::Light::mAttenuationConst [private]

Real Ogre::Light::mAttenuationLinear [private]

Real Ogre::Light::mAttenuationQuad [private]

Vector3 Ogre::Light::mDerivedDirection [private]

Vector3 Ogre::Light::mDerivedPosition [private]

ColourValue Ogre::Light::mDiffuse [private]

Vector3 Ogre::Light::mDirection [private]

Quaternion Ogre::Light::mLastParentOrientation [private]

Stored versions of parent orientation / position.

Vector3 Ogre::Light::mLastParentPosition [private]

LightTypes Ogre::Light::mLightType [private]

bool Ogre::Light::mModified [private]

String Ogre::Light::mName [private]

SceneNode* Ogre::MovableObject::mParentNode [protected, inherited]

node to which this object is attached.

Vector3 Ogre::Light::mPosition [private]

Real Ogre::Light::mRange [private]

RenderQueueGroupID Ogre::MovableObject::mRenderQueueID [protected, inherited]

The render queue to use when rendering this object.

String Ogre::Light::msMovableType = "Light" [static, private]

Shared class-level name for Movable type.

ColourValue Ogre::Light::mSpecular [private]

Real Ogre::Light::mSpotFalloff [private]

Real Ogre::Light::mSpotInner [private]

Real Ogre::Light::mSpotOuter [private]

UserDefinedObject* Ogre::MovableObject::mUserObject [protected, inherited]

User defined object which is linked to this object.

bool Ogre::MovableObject::mVisible [protected, inherited]

Is this object visible?

Copyright © 2002 by The OGRE Team