Ogre::Light

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 = 0, LT_DIRECTIONAL = 1, LT_SPOTLIGHT = 2 }

Defines the type of light. More...

typedef std::vector
< ShadowRenderable * > ShadowRenderableList

typedef
VectorIterator
< ShadowRenderableList > ShadowRenderableListIterator

Public Member Functions

void _calcTempSquareDist (const Vector3 &worldPos)

internal method for calculating current squared distance from some world position

Light ()

Default constructor (for Python mainly).

Light (const String &name)

Normal constructor.

~Light ()

Standard destructor.

void setType (LightTypes type)

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

LightTypes getType (void) const

Returns the light type.

void setDiffuseColour (Real red, Real green, Real blue)

Sets the colour of the diffuse light given off by this source.

void setDiffuseColour (const ColourValue &colour)

Sets the colour of the diffuse light given off by this source.

const ColourValue & getDiffuseColour (void) const

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

void setSpecularColour (Real red, Real green, Real blue)

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

void setSpecularColour (const ColourValue &colour)

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

const ColourValue & getSpecularColour (void) const

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

void setAttenuation (Real range, Real constant, Real linear, Real quadratic)

Sets the attenuation parameters of the light source i.e.

Real getAttenuationRange (void) const

Returns the absolute upper range of the light.

Real getAttenuationConstant (void) const

Returns the constant factor in the attenuation formula.

Real getAttenuationLinear (void) const

Returns the linear factor in the attenuation formula.

Real getAttenuationQuadric (void) const

Returns the quadric factor in the attenuation formula.

void setPosition (Real x, Real y, Real z)

Sets the position of the light.

void setPosition (const Vector3 &vec)

Sets the position of the light.

const Vector3 & getPosition (void) const

Returns the position of the light.

void setDirection (Real x, Real y, Real z)

Sets the direction in which a light points.

void setDirection (const Vector3 &vec)

Sets the direction in which a light points.

const Vector3 & getDirection (void) const

Returns the light's direction.

void setSpotlightRange (const Radian &innerAngle, const Radian &outerAngle, Real falloff=1.0)

Sets the range of a spotlight, i.e.

const Radian & getSpotlightInnerAngle (void) const

Returns the angle covered by the spotlights inner cone.

const Radian & getSpotlightOuterAngle (void) const

Returns the angle covered by the spotlights outer cone.

Real getSpotlightFalloff (void) const

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

void setSpotlightInnerAngle (const Radian &val)

Sets the angle covered by the spotlights inner cone.

void setSpotlightOuterAngle (const Radian &val)

Sets the angle covered by the spotlights outer cone.

void setSpotlightFalloff (Real val)

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

void setPowerScale (Real power)

Set a scaling factor to indicate the relative power of a light.

Real getPowerScale (void) const

Set the scaling factor which indicates the relative power of a light.

void _notifyAttached (Node *parent, bool isTagPoint=false)

Overridden from MovableObject.

void _notifyMoved (void)

Overridden from MovableObject.

const AxisAlignedBox & getBoundingBox (void) const

Overridden from MovableObject.

void _updateRenderQueue (RenderQueue *queue)

Overridden from MovableObject.

const String & getMovableType (void) const

Overridden from MovableObject.

const Vector3 & getDerivedPosition (bool cameraRelativeIfSet=false) const

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

const Vector3 & getDerivedDirection (void) const

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

void setVisible (bool visible)

Overridden from MovableObject.

Real getBoundingRadius (void) const

Overridden from MovableObject.

Vector4 getAs4DVector (bool cameraRelativeIfSet=false) const

Gets the details of this light as a 4D vector.

virtual const
PlaneBoundedVolume & _getNearClipVolume (const Camera *const cam) const

Internal method for calculating the 'near clip volume', which is the volume formed between the near clip rectangle of the camera and the light.

virtual const
PlaneBoundedVolumeList & _getFrustumClipVolumes (const Camera *const cam) const

Internal method for calculating the clip volumes outside of the frustum which can be used to determine which objects are casting shadow on the frustum as a whole.

uint32 getTypeFlags (void) const

Override to return specific type flag.

AnimableValuePtr createAnimableValue (const String &valueName)

Create a reference-counted AnimableValuePtr for the named value.

Remarks:
You can use the returned object to animate a value on this object, using AnimationTrack. Subclasses must override this if they wish to support animation of their values.

void setCustomShadowCameraSetup (const ShadowCameraSetupPtr &customShadowSetup)

Set this light to use a custom shadow camera when rendering texture shadows.

void resetCustomShadowCameraSetup (void)

Reset the shadow camera setup to the default.

const
ShadowCameraSetupPtr & getCustomShadowCameraSetup (void) const

return a pointer to the custom shadow camera setup (null means use SceneManager global version).

void visitRenderables (Renderable::Visitor *visitor, bool debugRenderables=false)

Method to allow a caller to abstractly iterate over the Renderable instances that this MovableObject will add to the render queue when asked, if any.

Parameters:

visitor Pointer to a class implementing the Renderable::Visitor interface which will be called back for each Renderable which will be queued. Bear in mind that the state of the Renderable instances may not be finalised depending on when you call this.

debugRenderables If false, only regular renderables will be visited (those for normal display). If true, debug renderables will be included too.

size_t _getIndexInFrame () const

Gets the index at which this light is in the current render.

void _notifyIndexInFrame (size_t i)

void setShadowFarDistance (Real distance)

Sets the maximum distance away from the camera that shadows by this light will be visible.

void resetShadowFarDistance (void)

Tells the light to use the shadow far distance of the SceneManager.

Real getShadowFarDistance (void) const

Gets the maximum distance away from the camera that shadows by this light will be visible.

Real getShadowFarDistanceSquared (void) const

void _setCameraRelative (Camera *cam)

Set the camera which this light should be relative to, for camera-relative rendering.

virtual void _notifyCreator (MovableObjectFactory *fact)

Notify the object of it's creator (internal use only).

virtual
MovableObjectFactory * _getCreator (void) const

Get the creator of this object, if any (internal use only).

virtual void _notifyManager (SceneManager *man)

Notify the object of it's manager (internal use only).

virtual SceneManager * _getManager (void) const

Get the manager of this object, if any (internal use only).

virtual const String & getName (void) const

Returns the name of this object.

virtual Node * getParentNode (void) const

Returns the node to which this object is attached.

virtual SceneNode * getParentSceneNode (void) const

Returns the scene node to which this object is attached.

virtual bool isAttached (void) const

Returns true if this object is attached to a SceneNode or TagPoint.

virtual void detatchFromParent (void)

Detaches an object from a parent SceneNode or TagPoint, if attached.

virtual bool isInScene (void) const

Returns true if this object is attached to a SceneNode or TagPoint, and this SceneNode / TagPoint is currently in an active part of the scene graph.

virtual void _notifyCurrentCamera (Camera *cam)

Internal method to notify the object of the camera to be used for the next rendering operation.

virtual const
AxisAlignedBox & getWorldBoundingBox (bool derive=false) const

Retrieves the axis-aligned bounding box for this object in world coordinates.

virtual const Sphere & getWorldBoundingSphere (bool derive=false) const

Retrieves the worldspace bounding sphere for this object.

virtual bool getVisible (void) const

Gets this object whether to be visible or not, if it has a renderable component.

virtual bool isVisible (void) const

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

virtual void setRenderingDistance (Real dist)

Sets the distance at which the object is no longer rendered.

virtual Real getRenderingDistance (void) const

Gets the distance at which batches are no longer rendered.

virtual void setUserObject (UserDefinedObject *obj)

Call this to associate your own custom user object instance with this MovableObject.

virtual
UserDefinedObject * getUserObject (void)

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

virtual void setUserAny (const Any &anything)

Sets any kind of user value on this object.

virtual const Any & getUserAny (void) const

Retrieves the custom user value associated with this object.

virtual void setRenderQueueGroup (uint8 queueID)

Sets the render queue group this entity will be rendered through.

virtual uint8 getRenderQueueGroup (void) const

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

virtual const Matrix4 & _getParentNodeFullTransform (void) const

return the full transformation of the parent sceneNode or the attachingPoint node

virtual void setQueryFlags (uint32 flags)

Sets the query flags for this object.

virtual void addQueryFlags (uint32 flags)

As setQueryFlags, except the flags passed as parameters are appended to the existing flags on this object.

virtual void removeQueryFlags (unsigned long flags)

As setQueryFlags, except the flags passed as parameters are removed from the existing flags on this object.

virtual uint32 getQueryFlags (void) const

Returns the query flags relevant for this object.

virtual void setVisibilityFlags (uint32 flags)

Sets the visiblity flags for this object.

virtual void addVisibilityFlags (uint32 flags)

As setVisibilityFlags, except the flags passed as parameters are appended to the existing flags on this object.

virtual void removeVisibilityFlags (uint32 flags)

As setVisibilityFlags, except the flags passed as parameters are removed from the existing flags on this object.

virtual uint32 getVisibilityFlags (void) const

Returns the visibility flags relevant for this object.

virtual void setListener (Listener *listener)

Sets a listener for this object.

virtual Listener * getListener (void) const

Gets the current listener for this object.

virtual const LightList & queryLights (void) const

Gets a list of lights, ordered relative to how close they are to this movable object.

virtual LightList * _getLightList ()

Returns a pointer to the current list of lights for this object.

EdgeData * getEdgeList (void)

Define a default implementation of method from ShadowCaster which implements no shadows.

bool hasEdgeList (void)

Define a default implementation of method from ShadowCaster which implements no shadows.

ShadowRenderableListIterator getShadowVolumeRenderableIterator (ShadowTechnique shadowTechnique, const Light *light, HardwareIndexBufferSharedPtr *indexBuffer, bool extrudeVertices, Real extrusionDist, unsigned long flags=0)

Define a default implementation of method from ShadowCaster which implements no shadows.

const AxisAlignedBox & getLightCapBounds (void) const

Overridden member from ShadowCaster.

const AxisAlignedBox & getDarkCapBounds (const Light &light, Real dirLightExtrusionDist) const

Overridden member from ShadowCaster.

void setCastShadows (bool enabled)

Sets whether or not this object will cast shadows.

bool getCastShadows (void) const

Returns whether shadow casting is enabled for this object.

Real getPointExtrusionDistance (const Light *l) const

Get the distance to extrude for a point/spot light.

virtual void setDebugDisplayEnabled (bool enabled)

Sets whether or not the debug display of this object is enabled.

virtual bool isDebugDisplayEnabled (void) const

Gets whether debug display of this object is enabled.

const StringVector & getAnimableValueNames (void) const

Gets a list of animable value names for this object.

void * operator new (size_t sz, const char *file, int line, const char *func)

operator new, with debug line info

void * operator new (size_t sz)

void * operator new (size_t sz, void *ptr)

placement operator new

void * operator new[] (size_t sz, const char *file, int line, const char *func)

array operator new, with debug line info

void * operator new[] (size_t sz)

void operator delete (void *ptr)

void operator delete (void *ptr, const char *, int, const char *)

void operator delete[] (void *ptr)

void operator delete[] (void *ptr, const char *, int, const char *)

Static Public Member Functions

static void setDefaultQueryFlags (uint32 flags)

Set the default query flags for all future MovableObject instances.

static uint32 getDefaultQueryFlags ()

Get the default query flags for all future MovableObject instances.

static void setDefaultVisibilityFlags (uint32 flags)

Set the default visibility flags for all future MovableObject instances.

static uint32 getDefaultVisibilityFlags ()

Get the default visibility flags for all future MovableObject instances.

static void extrudeVertices (const HardwareVertexBufferSharedPtr &vertexBuffer, size_t originalVertexCount, const Vector4 &lightPos, Real extrudeDist)

Utility method for extruding vertices based on a light.

Public Attributes

Real tempSquareDist

Temp tag used for sorting.

Protected Types

typedef std::map
< String,
StringVector > AnimableDictionaryMap

Protected Member Functions

virtual void update (void) const

internal method for synchronising with parent node (if any)

const String & getAnimableDictionaryName (void) const

Get the name of the animable dictionary for this class.

Remarks:
Subclasses must override this if they want to support animation of their values.

void initialiseAnimableDictionary (StringVector &vec) const

Internal method for initialising dictionary; should be implemented by subclasses wanting to expose animable parameters.

Real getExtrusionDistance (const Vector3 &objectPos, const Light *light) const

Helper method for calculating extrusion distance.

virtual void updateEdgeListLightFacing (EdgeData *edgeData, const Vector4 &lightPos)

Tells the caster to perform the tasks necessary to update the edge data's light listing.

virtual void generateShadowVolume (EdgeData *edgeData, const HardwareIndexBufferSharedPtr &indexBuffer, const Light *light, ShadowRenderableList &shadowRenderables, unsigned long flags)

Generates the indexes required to render a shadow volume into the index buffer which is passed in, and updates shadow renderables to use it.

virtual void extrudeBounds (AxisAlignedBox &box, const Vector4 &lightPos, Real extrudeDist) const

Utility method for extruding a bounding box.

void createAnimableDictionary (void) const

Internal method for creating a dictionary of animable value names for the class, if it does not already exist.

StringVector & _getAnimableValueNames (void)

Get an updateable reference to animable value list.

Protected Attributes

LightTypes mLightType

Vector3 mPosition

ColourValue mDiffuse

ColourValue mSpecular

Vector3 mDirection

Radian mSpotOuter

Radian mSpotInner

Real mSpotFalloff

Real mRange

Real mAttenuationConst

Real mAttenuationLinear

Real mAttenuationQuad

Real mPowerScale

size_t mIndexInFrame

bool mOwnShadowFarDist

Real mShadowFarDist

Real mShadowFarDistSquared

Vector3 mDerivedPosition

Vector3 mDerivedDirection

Vector3 mDerivedCamRelativePosition

bool mDerivedCamRelativeDirty

Camera * mCameraToBeRelativeTo

PlaneBoundedVolume mNearClipVolume

PlaneBoundedVolumeList mFrustumClipVolumes

bool mDerivedTransformDirty

Is the derived transform dirty?

ShadowCameraSetupPtr mCustomShadowCameraSetup

Pointer to a custom shadow camera setup.

String mName

Name of this object.

MovableObjectFactory * mCreator

Creator of this object (if created by a factory).

SceneManager * mManager

SceneManager holding this object (if applicable).

Node * mParentNode

node to which this object is attached

bool mParentIsTagPoint

bool mVisible

Is this object visible?

bool mDebugDisplay

Is debug display enabled?

Real mUpperDistance

Upper distance to still render.

Real mSquaredUpperDistance

bool mBeyondFarDistance

Hidden because of distance?

Any mUserAny

User defined link to another object / value / whatever.

uint8 mRenderQueueID

The render queue to use when rendering this object.

bool mRenderQueueIDSet

Flags whether the RenderQueue's default should be used.

uint32 mQueryFlags

Flags determining whether this object is included / excluded from scene queries.

uint32 mVisibilityFlags

Flags determining whether this object is visible (compared to SceneManager mask).

AxisAlignedBox mWorldAABB

Cached world AABB of this object.

Sphere mWorldBoundingSphere

AxisAlignedBox mWorldDarkCapBounds

World space AABB of this object's dark cap.

bool mCastShadows

Does this object cast shadows?

bool mRenderingDisabled

Does rendering this object disabled by listener?

Listener * mListener

MovableObject listener - only one allowed (no list) for size & performance reasons. */.

LightList mLightList

List of lights for this object.

ulong mLightListUpdated

The last frame that this light list was updated in.

Static Protected Attributes

static String msMovableType

Shared class-level name for Movable type.

static uint32 msDefaultQueryFlags

Default query flags.

static uint32 msDefaultVisibilityFlags

Default visibility flags.

static
AnimableDictionaryMap msAnimableDictionary

Static map of class name to list of animable value names.

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 diffuse light, with no attenuation (does not decrease 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 have a 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 tessellation and the normals are properly set. This is particularly true for the spotlight which will only look right on highly tessellated 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.

Definition at line 67 of file OgreLight.h.

Member Typedef Documentation

typedef std::vector<ShadowRenderable*> Ogre::ShadowCaster::ShadowRenderableList [inherited]

Definition at line 123 of file OgreShadowCaster.h.

typedef VectorIterator<ShadowRenderableList> Ogre::ShadowCaster::ShadowRenderableListIterator [inherited]

Definition at line 124 of file OgreShadowCaster.h.

typedef std::map<String, StringVector> Ogre::AnimableObject::AnimableDictionaryMap [protected, inherited]

Definition at line 234 of file OgreAnimable.h.

Member Enumeration Documentation

enum Ogre::Light::LightTypes

Defines the type of light.

Enumerator:

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.

Definition at line 76 of file OgreLight.h.

Constructor & Destructor Documentation

Ogre::Light::Light ( )

Default constructor (for Python mainly).

Ogre::Light::Light ( const 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::_calcTempSquareDist ( const Vector3 & worldPos )

internal method for calculating current squared distance from some world position

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

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

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

Returns the light type.

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 emanating from light sources and affects the base colour of objects together with ambient light.

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 emanating from light sources and affects the base colour of objects together with ambient light.

const ColourValue& Ogre::Light::getDiffuseColour ( void ) const

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

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::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.

const ColourValue& Ogre::Light::getSpecularColour ( void ) const

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

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

Sets the attenuation parameters of the light source i.e.

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 attenuation 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.

Real Ogre::Light::getAttenuationRange ( void ) const

Returns the absolute upper range of the light.

Real Ogre::Light::getAttenuationConstant ( void ) const

Returns the constant factor in the attenuation formula.

Real Ogre::Light::getAttenuationLinear ( void ) const

Returns the linear factor in the attenuation formula.

Real Ogre::Light::getAttenuationQuadric ( void ) const

Returns the quadric factor in the attenuation formula.

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::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.

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

Returns the position of the light.

Note:: Applicable to point lights and spotlights only.

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::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.

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

Returns the light's direction.

Remarks:: Applicable only to the spotlight and directional light types.

void Ogre::Light::setSpotlightRange	(	const Radian &	innerAngle,
		const Radian &	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 The inner cone applicable only to Direct3