Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

Ogre::Light Class Reference

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

#include <OgreLight.h>

Inheritance diagram for Ogre::Light:

Ogre::MovableObject 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 StringgetName (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 AxisAlignedBoxgetBoundingBox (void) const
 Overridden from MovableObject. More...

void _updateRenderQueue (RenderQueue *queue)
 Overridden from MovableObject. More...

const String getMovableType (void) const
 Overridden from MovableObject. More...

const Vector3getDerivedPosition (void)
 Retrieves the position of the light including any transform from nodes it is attached to. More...

const Vector3getDerivedDirection (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 SceneNodegetParentNode (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 UserDefinedObjectgetUserObject (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

SceneNodemParentNode
 node to which this object is attached. More...

bool mVisible
 Is this object visible? More...

UserDefinedObjectmUserObject
 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