3ds Max C++ API Reference
Loading...
Searching...
No Matches
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 ExclListGetExclList ()
 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 BaseInterfaceGetInterface (Interface_ID id)
 
template<class InterfaceType >
InterfaceType * GetTypedInterface ()
 

Public Attributes

LightState ls
 The light state structure.
 
INodeinode
 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 voidoperator new (size_t size)
 Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator new[] (size_t size)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator new[] (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate arrays of objects.
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidaligned_malloc (size_t size, size_t alignment)
 Allocates memory on a specified alignment boundary.
 
static UtilExport voidaligned_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()

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.
3383{ return NULL; }
#define NULL
Definition: autoptr.h:18

◆ 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
tThe time of the render.
rcSee Class RendContext.
rgcThis pointer may be used to retireve information about the global rendering enviornment.
shadowsTRUE if shadows are turned on (in the render parameters, not the light parameters); otherwise FALSE.
shadowGeomChangedThis 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;
LightObject* lob = (LightObject *)os.obj;
lob->EvalLightState(t, valid, &ls);
uniformScale = IsUniformScale(lightToWorld);
}
else {
uniformScale = TRUE;
}
return 1;
}
virtual const ObjectState & EvalWorldState(TimeValue time, BOOL evalHidden=TRUE)=0
virtual Matrix3 GetObjTMAfterWSM(TimeValue time, Interval *valid=NULL)=0
Definition: interval.h:36
BOOL affectDiffuse
Definition: imtl.h:125
BOOL ambientOnly
Definition: imtl.h:127
BOOL affectSpecular
Definition: imtl.h:126
This is the base class from which plug-in lights may be derived.
Definition: object.h:3534
virtual RefResult EvalLightState(TimeValue time, Interval &valid, LightState *ls)=0
This method is called to update the passed LightState and validity interval of the light.
void IdentityMatrix()
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 positio...
LightState ls
The light state structure.
Definition: object.h:3354
INode * inode
The INode pointer of the instance of the light that created the current object.
Definition: object.h:3355
Matrix3 lightToWorld
This is effectively the light node's object TM.
Definition: object.h:3358
BOOL uniformScale
Indicates if the light's scale is uniform or not.
Definition: object.h:3356
Matrix3 worldToLight
This matrix will transform points from world space to light space.
Definition: object.h:3359
The ObjectState is the structure that flows up the geometry pipeline.
Definition: object.h:287
Object * obj
Pointer to the object in the pipeline.
Definition: object.h:298
CoreExport SClass_ID SuperClassID() override
Retrieves a constant representing the type of the plugin.
This class is passed into the method ObjLightDesc::Update().
Definition: RendContext.h:27
Definition: RenderGlobalContext.h:146
DMatrix3 Inverse(const DMatrix3 &m)
Return the inverse of the matrix.
#define assert(expr)
Definition: assert1.h:82
#define LIGHT_CLASS_ID
Light object super-class ID.
Definition: plugapi.h:444
int TimeValue
Definition: maxtypes.h:31
BOOL affectDiffuse
TRUE if affect diffuse is on; otherwise FALSE.
Definition: object.h:3031
BOOL ambientOnly
Definition: object.h:3034
BOOL affectSpecular
TRUE if affect specular is on; otherwise FALSE.
Definition: object.h:3033

◆ 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
globLightLevelThe global light level.
3432{}

◆ 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
worldToCamThe 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.

3447{ return lightPos; }
Point3 lightPos
The position of the light in camera space.
Definition: object.h:3357

◆ 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
scThis 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.
rayDefines the world space ray that will be traversed.
samplesThe 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.
tStopThis 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.
attenStartSpecifies 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.
attenEndThis specifies the ending percent of the light attenuation distances that should be used for lighting during the traversal.
flagsThere 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.
procA developer derives a class from LightRayTraversal and implements the Step() method. A pointer to it is passed here as the callback object.
3518 {}

Member Data Documentation

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