ObjLightDesc Class Reference

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

#include <object.h>

Inheritance diagram for ObjLightDesc:

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 Member Functions inherited from LightDesc
	LightDesc ()
virtual BOOL	Illuminate (ShadeContext &sc, Point3 &normal, Color &color, Point3 &dir, float &dot_nl, float &diffuseCoef)
virtual Point3	LightPosition ()
virtual CoreExport void	DeleteThis ()
Public Member Functions inherited from RenderData
virtual void	DeleteThis ()=0
virtual INT_PTR	Execute (int cmd, ULONG_PTR arg1=0, ULONG_PTR arg2=0, ULONG_PTR arg3=0)
Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor.
virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)
template<class InterfaceType >
InterfaceType *	GetTypedInterface ()

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.
Public Attributes inherited from LightDesc
BOOL	affectDiffuse
BOOL	affectSpecular
BOOL	ambientOnly
DWORD	extra

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown.
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned.
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown.
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown.
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned.
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown.
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned.
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned.
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects.
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned.
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned.
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown.
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen.
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown.
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown.
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen.
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown.
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen.
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown.
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen.
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown.
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown.
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen.
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown.
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown.
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator.
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator.
static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary.
static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary.
static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc.

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

Constructor & Destructor Documentation

ObjLightDesc()

CoreExport ObjLightDesc

(

INode *

n

)

Constructor.

The inode data member is initialized to n.

~ObjLightDesc()

virtual CoreExport ~ObjLightDesc ( )

virtual

Destructor.

Member Function Documentation

GetExclList()

virtual ExclList * GetExclList ( )

inlinevirtual

Retrieves the light's exclusion list.

Returns

See Class NameTab.

{ return NULL; }  

Update()

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

virtual

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;
}

UpdateGlobalLightLevel()

virtual CoreExport void UpdateGlobalLightLevel ( Color  globLightLevel )

inlinevirtual

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

Parameters

globLightLevel

The global light level.

{}

UpdateViewDepParams()

virtual CoreExport int UpdateViewDepParams ( const Matrix3 &  worldToCam )

virtual

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.

LightPosition()

virtual CoreExport Point3 LightPosition ( )

inlinevirtual

This method is from LightDesc.

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

Reimplemented from LightDesc.

{ return lightPos; }

TraverseVolume()

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

inlinevirtual

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

ls

LightState ls

The light state structure.

See Structure LightState.

inode

INode* inode

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

uniformScale

BOOL uniformScale

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.

lightPos

Point3 lightPos

The position of the light in camera space.

lightToWorld

Matrix3 lightToWorld

This is effectively the light node's object TM.

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

worldToLight

Matrix3 worldToLight

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

This is the inverse of lightToWorld.

lightToCam

Matrix3 lightToCam

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

This is updated in UpdateViewDepParams()

camToLight

Matrix3 camToLight

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.

renderNumber

int renderNumber

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.