#include <imrLightTranslation.h>

Class Description

An interface used to translate custom lights to mental ray.

This interface makes it possible for 3rd party light plugins to specify their own shaders and properties for use with mental ray. This interface is basically used to fill up the miLight structure (see the mental ray documentation for details on the miLight structure). Any miLight parameter which is not supported by this interface is queried on class LightObject instead. The shadow options, for example, are retrieved through the shadow generator plugin assigned to the light.

Inheritance diagram for imrLightTranslation:

Classes
union	AreaPrimitive
	Describes an area primitive, equivalent to miLight::primitive in the mental ray API. More...

struct	VectorStruct
	A simple vector structure, equivalent to miVector in the mental ray API. More...

Public Types
enum	LightType { kLightType_Origin, kLightType_Directional, kLightType_DirectionalWithOrigin, kLightType_Spot }
	Identifies the type of light to be used in the mental ray API. More...

enum	AreaType { kAreaType_None, kAreaType_Rectangle, kAreaType_Disc, kAreaType_Sphere, kAreaType_Cylinder, kAreaType_User }
	Identifies the type of area light to be created. More...

Public Types inherited from BaseInterface
enum	LifetimeType { noRelease, immediateRelease, wantsRelease, serverControlled }

Public Member Functions
virtual bool	HasCustomFlux (INode &node)=0
	Used by the translator to determine whether this light calculates its own flux. More...

virtual float	GetFlux (INode &node, imrTranslation &translationInterface, TimeValue t, Interval &valid)=0
	Returns the flux to be used with this light for GI and caustics. More...

virtual LightType	GetLightType (TimeValue t, Interval &validity)=0
	Returns the type of light to be created in mental ray. More...

virtual AreaType	GetAreaType (TimeValue t, Interval &validity)=0
	Returns the type of area light to be created in mental ray. More...

virtual void	GetAreaPrimitive (AreaPrimitive &areaPrimitive, TimeValue t, Interval &validity)=0
	Returns the description of the area primitive to be created in mental ray. More...

virtual short	GetAreaSamples (TimeValue t, Interval &validity)=0
	Returns the number of area samples to be used for this area light. More...

virtual short	GetAreaLowSamples (TimeValue t, Interval &validity)=0
	Returns the number of area samples to be used once the trance depth given in "low_level is reached. More...

virtual short	GetAreaLowLevel (TimeValue t, Interval &validity)=0
	Returns the trace depth level at which the number of area samples is changed to "low_samples". More...

virtual bool	GetAreaVisible (TimeValue t, Interval &validity)=0
	Returns whether this area light is visible. More...


virtual Texmap *	GetLightShader (INode &node)=0
	Return the light and emitter shaders to be used for this light. More...

virtual Texmap *	GetPhotonEmitterShader (INode &node)=0

Public Member Functions inherited from BaseInterface
virtual UtilExport	~BaseInterface ()
	Destructor. More...

UtilExport BaseInterface *	GetInterface (Interface_ID id)

virtual UtilExport Interface_ID	GetID ()

virtual LifetimeType	LifetimeControl ()

virtual bool	RegisterNotifyCallback (InterfaceNotifyCallback *incb)

virtual void	UnRegisterNotifyCallback (InterfaceNotifyCallback *incb)

virtual BaseInterface *	AcquireInterface ()

virtual void	ReleaseInterface ()

virtual void	DeleteInterface ()

virtual BaseInterface *	CloneInterface (void *remapDir=NULL)

Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

Static Public Member Functions
static CoreExport Interface_ID	GetInterfaceID ()
	Returns the interface ID of this class. More...

static CoreExport imrLightTranslation *	GetInterface (InterfaceServer &iserver)
	Queries a pointer to this class from an interface server. More...

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

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

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

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

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

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

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

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

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

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

static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...

static UtilExport void	operator delete (void ptr, void placement_ptr)
	Placement delete operator. More...

Member Enumeration Documentation

enum LightType

Identifies the type of light to be used in the mental ray API.

Enumerator
kLightType_Origin	Same as miLIGHT_ORIGIN in the mental ray API.
kLightType_Directional	Same as miLIGHT_DIRECTION in the mental ray API.
kLightType_DirectionalWithOrigin	Same as miLIGHT_DIRECTION with miLight::miLIGHT_DIRECTION in the mental ray API.
kLightType_Spot	Same as miLIGHT_SPOT in the mental ray API.

                    {
         kLightType_Origin,
         kLightType_Directional,
         kLightType_DirectionalWithOrigin,
         kLightType_Spot
     };

enum AreaType

Identifies the type of area light to be created.

miTYPE_OBJECT is not yet supported.

Enumerator
kAreaType_None	Same as miLIGHT_NONE in the mental ray API.
kAreaType_Rectangle	Same as miLIGHT_RECTANGLE in the mental ray API.
kAreaType_Disc	Same as miLIGHT_DISC in the mental ray API.
kAreaType_Sphere	Same as miLIGHT_SPHERE in the mental ray API.
kAreaType_Cylinder	Same as miLIGHT_CYLINDER in the mental ray API.
kAreaType_User	Same as miLIGHT_USER in the mental ray API.

                   {
         kAreaType_None,
         kAreaType_Rectangle,
         kAreaType_Disc,
         kAreaType_Sphere,
         kAreaType_Cylinder,
         kAreaType_User
     };

Member Function Documentation

static CoreExport Interface_ID GetInterfaceID ( )

static

Returns the interface ID of this class.

static CoreExport imrLightTranslation* GetInterface ( InterfaceServer & iserver )

static

Queries a pointer to this class from an interface server.

Returns: A valid pointer to an instance of this class if the given interface server derives from it; NULL otherwise.

virtual Texmap* GetLightShader ( INode & node )

pure virtual

Return the light and emitter shaders to be used for this light.

These methods will usually return one of:

An instance to a mental ray shader Texmap (i.e. a Texmap* to an actual mental ray shader, which implements imrShader*). Such an instance can be created by iterating through the list of Texmap plugins loaded by 3ds Max, and looking for the internal name that matches with the shader definition.
An instance to a Texmap that implements imrShaderTranslation. This is usually preferable as it allows the plugin developer to implement custom translation for the shader.
Parameters

[in] node - The light node for which this shader is created, in case the shader has dependencies on that node.

Returns
The light and photon emitter shaders to be used with this light; the photon emitter shader may be NULL if the light does not support photon emission.

virtual Texmap* GetPhotonEmitterShader ( INode & node )

pure virtual

virtual bool HasCustomFlux ( INode & node )

pure virtual

Used by the translator to determine whether this light calculates its own flux.

If this returns false, the translator attempts to calculate the flux based on the light type, its intensity and other parameters. If this returns true, GetFlux() will be used to retrieve the flux.

virtual float GetFlux	(	INode &	node,
		imrTranslation &	translationInterface,
		TimeValue	t,
		Interval &	valid
	)

pure virtual

Returns the flux to be used with this light for GI and caustics.

If HasCustomFlux() returns true and GetPhotonEmitterShader() returns non-null, then this method needs to return a valid flux value. Otherwise, this method should simply return 0. The flux is used to calculate the energy used with GI and caustic, in lumen. The formula is: energy = PI * (flux * globalEnergyMultiplier * lightColor * globalLightLevel) / meterScale / physicalScale

For point lights, the flux is calculated as: intensity_in_candelas * solid_angle_in_steradians, IF the intensity is constant.
For point lights with non-constant intensity (e.g. spotlights with falloff), the flux is an integration of the intensity (in candelas) over the sphere.

For directional lights, the flux is: intensity_in_lux * area_covered_by_directional_light, and the directional light must shoot photons for and only for that area.

Parameters

[in]	node	- The light node with which this light is associated.
[in]	translationInterface	- The interface for the mental ray translator.
[in]	t	- The time value at which the flux is to be calculated.
[in,out]	valid	- The validity interval of the light. The validity interval of the flux calculation should be INTERSECTED with the incoming interval.

Returns: The flux to be used with this light.

virtual LightType GetLightType	(	TimeValue	t,
		Interval &	validity
	)

pure virtual

Returns the type of light to be created in mental ray.

Parameters

[in]	t	- The time value for which the value is queried.
[in]	validity	- The validity interval of the value is to be intersected with this interval.

virtual AreaType GetAreaType	(	TimeValue	t,
		Interval &	validity
	)

pure virtual

Returns the type of area light to be created in mental ray.

Parameters

[in]	t	- The time value for which the value is queried.
[in]	validity	- The validity interval of the value is to be intersected with this interval.

virtual void GetAreaPrimitive	(	AreaPrimitive &	areaPrimitive,
		TimeValue	t,
		Interval &	validity
	)

pure virtual

Returns the description of the area primitive to be created in mental ray.

Will only be called if the area light type is different than "none". Implement an empty methods if the light is not an area light.

Parameters

[in]	t	- The time value for which the value is queried.
[in]	validity	- The validity interval of the value is to be intersected with this interval.

virtual short GetAreaSamples	(	TimeValue	t,
		Interval &	validity
	)

pure virtual

Returns the number of area samples to be used for this area light.

The number of samples is equivalent to miLight::samples_u * miLight::samples_v. If this light is not an area light, return 0.

Parameters

[in]	t	- The time value for which the value is queried.
[in]	validity	- The validity interval of the value is to be intersected with this interval.

virtual short GetAreaLowSamples	(	TimeValue	t,
		Interval &	validity
	)

pure virtual

Returns the number of area samples to be used once the trance depth given in "low_level is reached.

This value is equivalent to miLight::low_samples_u * miLight::low_samples_v. Return 0 if this is not an area light.

Parameters

[in]	t	- The time value for which the value is queried.
[in]	validity	- The validity interval of the value is to be intersected with this interval.

virtual short GetAreaLowLevel	(	TimeValue	t,
		Interval &	validity
	)

pure virtual

Returns the trace depth level at which the number of area samples is changed to "low_samples".

Return 0 to disable this feature and always use "samples". Return 0 if this is not an area light.

Parameters

[in]	t	- The time value for which the value is queried.
[in]	validity	- The validity interval of the value is to be intersected with this interval.

virtual bool GetAreaVisible	(	TimeValue	t,
		Interval &	validity
	)

pure virtual

Returns whether this area light is visible.

Return false if this is not an area light.

Parameters

[in]	t	- The time value for which the value is queried.
[in]	validity	- The validity interval of the value is to be intersected with this interval.

imrLightTranslation Class Reference

Class Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Member Function Documentation