ObjLightDesc Class Reference

This reference page is linked to from the following overview topics: Principal Light Classes.

---

Search for all occurrences

---

Detailed Description

A light must be able to create one of these objects to give to the renderer.

As the renderer is getting ready to render, it will ask for one of these from each of the lights. The Illuminate() method (inherited from LightDesc) is called by the renderer to illuminate a surface point. There is an ObjLightDesc for every instance of the light. The renderer will ask each light object to produce one of these ObjLightDescs. It will then set this data up in the node's render data (See Class RenderData). For example in 3ds Max's volume light implementation of Atmospheric::Update() it goes through its node references to lights and calls GetRenderData(). It then casts this as an ObjLightDesc. This is how a atmosphere effect can get access to these descriptors at render time.

See also:

Class LightDesc, Class LightRayTraversal, Class INode, Class Point3

Class Matrix3, Class Ray, Class RendContext, Class ShadeContext, Class RenderInstance

#include <object.h>

Inheritance diagram for ObjLightDesc:

List of all members.

Public Member Functions
CoreExport	ObjLightDesc (INode *n)
	Constructor.
virtual CoreExport	~ObjLightDesc ()
	Destructor.
virtual ExclList *	GetExclList ()
	Retrieves the light's exclusion list.
virtual CoreExport int	Update (TimeValue t, const RendContext &rc, RenderGlobalContext *rgc, BOOL shadows, BOOL shadowGeomChanged)
	This method is called once per render to update the light state for things that depend on the position of objects and lights in world space.
virtual CoreExport void	UpdateGlobalLightLevel (Color globLightLevel)
	This method is called to update the light state that depends on the global light level.
virtual CoreExport int	UpdateViewDepParams (const Matrix3 &worldToCam)
	This method is called to update the light state that depends on the view matrix.
virtual CoreExport Point3	LightPosition ()
	This method is from LightDesc.
virtual void	TraverseVolume (ShadeContext &sc, const Ray &ray, int samples, float tStop, float attenStart, float attenEnd, DWORD flags, LightRayTraversal *proc)
	This function traverses a ray through the light volume.
Public Attributes
LightState	ls
	The light state structure.
INode *	inode
	The INode pointer of the instance of the light that created the current object.
BOOL	uniformScale
	Indicates if the light's scale is uniform or not.
Point3	lightPos
	The position of the light in camera space.
Matrix3	lightToWorld
	This is effectively the light node's object TM.
Matrix3	worldToLight
	This matrix will transform points from world space to light space.
Matrix3	lightToCam
	This matrix will transform points from light space to camera space.
Matrix3	camToLight
	This matrix will transform points from camera space to light space.
int	renderNumber
	This is set by the renderer.

---

Constructor & Destructor Documentation

CoreExport ObjLightDesc

(

INode *

n

)

Constructor.

The inode data member is initialized to n.

virtual CoreExport ~ObjLightDesc

(

)

[virtual]

Destructor.

---

Member Function Documentation

virtual ExclList* GetExclList

(

)

[inline, virtual]

Search for all occurrences

Retrieves the light's exclusion list.

Returns:

See Class NameTab.

{ return NULL; }  

virtual CoreExport int Update	(	TimeValue	t,
		const RendContext &	rc,
		RenderGlobalContext *	rgc,
		BOOL	shadows,
		BOOL	shadowGeomChanged
	)		[virtual]

Search for all occurrences

This method is called once per render to update the light state for things that depend on the position of objects and lights in world space.

A plug-in light could update any data it would need to here. The default implementation is shown below.

Parameters:

t	The time of the render.
rc	See Class RendContext.
rgc	This pointer may be used to retireve information about the global rendering enviornment.
shadows	TRUE if shadows are turned on (in the render parameters, not the light parameters); otherwise FALSE.
shadowGeomChanged	This tells the Update procedure that the geometry of the objects that are shadowed by the light has changed (TRUE) or not (FALSE). If it is a shadow buffer, shadowGeomChanged == TRUE means it has to re-render the shadow buffer, shadowGeomChanged == FALSE means it can use the shadow buffer from the previous frame.

Returns:

The value return should normally be 1. A returned value of 0 means an error has occured (such as out of memory) and the render will be halted.

Default Implementation:

    int ObjLightDesc::Update(TimeValue t, const RendContext& rc, RenderGlobalContext *rgc, BOOL shadows, BOOL shadowGeomChanged)
    {
        if (inode) {
            Interval valid;
            ObjectState os = inode->EvalWorldState(t);
            assert(os.obj->SuperClassID()==LIGHT_CLASS_ID);
            LightObject* lob = (LightObject *)os.obj;
            lob->EvalLightState(t, valid, &ls);
            lightToWorld = inode->GetObjTMAfterWSM(t);
            worldToLight = Inverse(lightToWorld);
            uniformScale = IsUniformScale(lightToWorld);
            affectDiffuse = ls.affectDiffuse;
            affectSpecular = ls.affectSpecular;
            ambientOnly = ls.ambientOnly;
        }
        else {
            uniformScale = TRUE;
            lightToWorld.IdentityMatrix();
            worldToLight.IdentityMatrix();
        }
        return 1;
    }

virtual CoreExport void UpdateGlobalLightLevel

(

Color

globLightLevel

)

[inline, virtual]

Search for all occurrences

This method is called to update the light state that depends on the global light level.

Parameters:

globLightLevel

The global light level.

{}

virtual CoreExport int UpdateViewDepParams

(

const Matrix3 &

worldToCam

)

[virtual]

Search for all occurrences

This method is called to update the light state that depends on the view matrix.

This is used to cache certain computed quantities that are dependent on where you are looking from. In a given scene at a given time, the system may render from several viewpoints. This is because of things like reflection maps and mirrors that need to get rendered. This method is called for each of these different viewpoints.

Parameters:

worldToCam

The world space to camera space transformation matrix.

virtual CoreExport Point3 LightPosition

(

)

[inline, virtual]

Search for all occurrences

This method is from LightDesc.

Here it provides a default implementation returning the lightPos data member.

Reimplemented from LightDesc.

{ return lightPos; }

virtual void TraverseVolume	(	ShadeContext &	sc,
		const Ray &	ray,
		int	samples,
		float	tStop,
		float	attenStart,
		float	attenEnd,
		DWORD	flags,
		LightRayTraversal *	proc
	)		[inline, virtual]

Search for all occurrences

This function traverses a ray through the light volume.

This method is implemented by plug-in lights.

Consider how the 3ds Max atmospheric effects like the volume lights use

this information. For each light the atmospheric effect is bound to, it calls the this method (TraverseVolume()) on the light. The volume light atmospheric effect passes a callback to this method (proc). The light then calls the Step() method of the callback for each partial segment of the ray. Given the illumination on the segment it computes the fog density over that segment. The density may be constant if noise is not turned on, or it may change if noise is turned on. Using the fog density and the illumination it computes the light reflected off the atmosphere for the segment.

Parameters:

sc	This is the ShadeContext passed into the Shade() method of the Atmospheric effect. The shade context passed in should only be used for state (like are shadows globally disabled). The position, normal, etc. serve no purpose.
ray	Defines the world space ray that will be traversed.
samples	The number of samples to sample along the ray. A reasonable range is from 25-100. This is more or less the suggested number of times the proc->Step() callback will be called. It is not precisely however because the system may take greater or fewer steps than specified as it needs to.
tStop	This is the end of the ray. This is the point at which the traversal will stop (ray.p+tStop*ray.dir). Note that the traversal can terminate earlier if the callback returns FALSE.
attenStart	Specifies a percent of the light attenuation distances that should be used for lighting during the traversal. This is used so a light can have an attenuation set to a certain percent, and then have the volume light be attenuated at a different point.
attenEnd	This specifies the ending percent of the light attenuation distances that should be used for lighting during the traversal.
flags	There are three ways the shadow maps can be sampled. If none of these flags are set, the shadow map is sampled directly (this is the fastest). One of the following values: TRAVERSE_LOWFILTSHADOWS This is a simple filtering where the system samples a point in the shadow map and then some of the neighboring points. This corresponds to 'Medium' in the Volume Light user interface (a value of 0 for flags is 'Low' -- just sampling the shadow map with no filtering at all). TRAVERSE_HIFILTSHADOWS This is a higher resolution sampling. This corresponds to 'High' in the Volume Light user interface. TRAVERSE_USESAMPLESIZE This produces the highest quality. This corresponds to 'Use Light Sample Range' in the Volume Light user interface. This is like a box filter, but also takes into consideration the position of the point within the pixel to do additional weighting.
proc	A developer derives a class from LightRayTraversal and implements the Step() method. A pointer to it is passed here as the callback object.

                                 {}

---

Member Data Documentation

LightState ls

Search for all occurrences

The light state structure.

See Structure LightState.

INode* inode

Search for all occurrences

The INode pointer of the instance of the light that created the current object.

BOOL uniformScale

Search for all occurrences

Indicates if the light's scale is uniform or not.

TRUE if uniform, FALSE if not. This saves some steps in the renderer if the scale is uniform.

Point3 lightPos

Search for all occurrences

The position of the light in camera space.

Matrix3 lightToWorld

Search for all occurrences

This is effectively the light node's object TM.

This matrix will transform points from light space to world space.

Matrix3 worldToLight

Search for all occurrences

This matrix will transform points from world space to light space.

This is the inverse of lightToWorld.

Matrix3 lightToCam

Search for all occurrences

This matrix will transform points from light space to camera space.

This is updated in UpdateViewDepParams()

Matrix3 camToLight

Search for all occurrences

This matrix will transform points from camera space to light space.

This is updated in UpdateViewDepParams(). For example, the renderer would have points in camera space. To figure out if a point was in shadow it would transform the point from camera space to light space using this matrix. It could then look in the shadow buffer to see if the point was in shadow.

int renderNumber

Search for all occurrences

This is set by the renderer.

It is used in RenderInstance::CastsShadowsFrom(). This is a number used by the renderer to identify the lights so it can quickly determine if a given light casts shadows from a given object. It is for use by the renderer.