ExposureMaterialControl Class Reference

#include <expmtlControl.h>

Class Description

This is the inteface class to implement in order to support exposure controls.

See also

Class ExposureMaterialControlImp

Description:

This class is an extension to allow maxscript to determine whether a material's shaded output is to be processed by a tone operator and whether the self-illumination, reflection or refraction channels are to be inverted by the tone operator so the actual rgb values will appear in the display.

This class is added to materials that want to expose control over the results of the exposure control on the shaded output of the material. This is useful when a material knows the specific RGB value to appear in the rendered image, and does not want this color to be adjusted. For example, a material might already perform its own physically-based lighting calculations with handling for image exposure. Or, in the case of specialty "non-physical" materials, it might be inappropriate to perform exposure adjustments on the color.

You determine whether a material allows this control by asking for the interface. If the interface is present, then you can set values. This is how you ask for the interface:

ExposureMaterialControl* exp = GetExposureMaterialControl(mtl);

A material can support this interface by deriving from this class and handling the GetInterface() method as follows:

BaseInterface* GetInterface(Interface_ID id) {
  if (id == EXPOSURE_MATERIAL_CONTROL) return (ExposureMaterialControl*)(this);
  return Mtl::GetInterface(id); //If the interface ID is not recognized, call the superclass method
}

There are four properties in the interface, each with a get and a set method. Use the get method to get the current value and set to set a new value for the property.

The properties are:

• NoExposure
• InvertSelfIllum
• InvertReflect
• InvertRefract

Also, if you want your material's ExposureMaterialControl methods to be exposed to MAXScript, you can derive from ExposureMaterialControlImp.

Inheritance diagram for ExposureMaterialControl:

Public Types
enum	{   kGetNoExposureControl = 0, kSetNoExposureControl = 1, kGetInvertSelfIllum = 2, kSetInvertSelfIllum = 3,   kGetInvertReflect = 4, kSetInvertReflect = 5, kGetInvertRefract = 6, kSetInvertRefract = 7 }
Public Types inherited from BaseInterface
enum	LifetimeType { noRelease, immediateRelease, wantsRelease, serverControlled }

Public Member Functions
	ExposureMaterialControl ()
	PROP_FNS (kGetNoExposureControl, GetNoExposure, kSetNoExposureControl, SetNoExposure, TYPE_BOOL)
	PROP_FNS (kGetInvertSelfIllum, GetInvertSelfIllum, kSetInvertSelfIllum, SetInvertSelfIllum, TYPE_BOOL)
	PROP_FNS (kGetInvertReflect, GetInvertReflect, kSetInvertReflect, SetInvertReflect, TYPE_BOOL)
	PROP_FNS (kGetInvertRefract, GetInvertRefract, kSetInvertRefract, SetInvertRefract, TYPE_BOOL)
BOOL	GetNoExposure () const
virtual void	SetNoExposure (BOOL on)
BOOL	GetInvertSelfIllum () const
virtual void	SetInvertSelfIllum (BOOL on)
BOOL	GetInvertReflect () const
virtual void	SetInvertReflect (BOOL on)
BOOL	GetInvertRefract () const
virtual void	SetInvertRefract (BOOL on)
ULONG	isNoExposure () const
bool	isInvertSelfIllum () const
bool	isInvertReflect () const
bool	isInvertRefract () const
IOResult	Save (ISave *isave)
IOResult	Load (ILoad *iload)
Public Member Functions inherited from FPMixinInterface
	FPMixinInterface ()
virtual LifetimeType	LifetimeControl ()
virtual CoreExport bool	RegisterNotifyCallback (InterfaceNotifyCallback *incb)
virtual void	UnRegisterNotifyCallback (InterfaceNotifyCallback *incb)
CoreExport	~FPMixinInterface ()
virtual BaseInterface *	GetInterface (Interface_ID id)
virtual FPInterfaceDesc *	GetDescByID (Interface_ID id)
virtual Interface_ID	GetID ()
Public Member Functions inherited from FPInterface
virtual FPInterfaceDesc *	GetDesc ()=0
virtual CoreExport FPStatus	Invoke (FunctionID fid, TimeValue t=0, FPParams *params=NULL)
virtual FPStatus	Invoke (FunctionID fid, FPParams *params)
virtual CoreExport FPStatus	Invoke (FunctionID fid, TimeValue t, FPValue &result, FPParams *params=NULL)
virtual FPStatus	Invoke (FunctionID fid, FPValue &result, FPParams *params=NULL)
virtual CoreExport FunctionID	FindFn (const MCHAR *name)
virtual CoreExport BOOL	IsEnabled (FunctionID actionID)
virtual CoreExport BOOL	IsChecked (FunctionID actionID)
virtual CoreExport BOOL	IsVisible (FunctionID actionID)
virtual CoreExport FunctionID	GetIsEnabled (FunctionID actionID)
virtual CoreExport FunctionID	GetIsChecked (FunctionID actionID)
virtual CoreExport FunctionID	GetIsVisible (FunctionID actionID)
virtual ActionTable *	GetActionTable ()
virtual void	EnableActions (BOOL onOff)
Public Member Functions inherited from BaseInterface
virtual UtilExport	~BaseInterface ()
	Destructor. More...
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...

Protected Types
enum	{ DATA_CHUNK = 0x322 }

Protected Member Functions
IOResult	write (ISave *isave, bool &b)
IOResult	read (ILoad *iload, bool &b)
Protected Member Functions inherited from FPMixinInterface
	FPMixinInterface (const FPMixinInterface &rhs)
FPMixinInterface &	operator= (const FPMixinInterface &rhs)
Protected Member Functions inherited from FPInterface
virtual FPStatus	_dispatch_fn (FunctionID fid, TimeValue t, FPValue &result, FPParams *p)

Protected Attributes
bool	mNoExposure
bool	mInvertSelfIllum
bool	mInvertReflect
bool	mInvertRefract
Protected Attributes inherited from FPMixinInterface
Tab< InterfaceNotifyCallback * > *	interfaceNotifyCBs

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. 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...
Static Public Attributes inherited from FPInterface
static CoreExport FPInterfaceDesc	nullInterface

Member Enumeration Documentation

anonymous enum

Enumerator
kGetNoExposureControl
kSetNoExposureControl
kGetInvertSelfIllum
kSetInvertSelfIllum
kGetInvertReflect
kSetInvertReflect
kGetInvertRefract
kSetInvertRefract

         {
        kGetNoExposureControl = 0,
        kSetNoExposureControl = 1,
        kGetInvertSelfIllum = 2,
        kSetInvertSelfIllum = 3,
        kGetInvertReflect = 4,
        kSetInvertReflect = 5,
        kGetInvertRefract = 6,
        kSetInvertRefract = 7
    };

anonymous enum

protected

Enumerator
DATA_CHUNK

         {
        DATA_CHUNK = 0x322
    };

Constructor & Destructor Documentation

ExposureMaterialControl ( )

inline

                              :
        mNoExposure(false),
        mInvertSelfIllum(false),
        mInvertReflect(false),
        mInvertRefract(false) {}

Member Function Documentation

PROP_FNS	(	kGetNoExposureControl	,
		GetNoExposure	,
		kSetNoExposureControl	,
		SetNoExposure	,
		TYPE_BOOL
	)

PROP_FNS	(	kGetInvertSelfIllum	,
		GetInvertSelfIllum	,
		kSetInvertSelfIllum	,
		SetInvertSelfIllum	,
		TYPE_BOOL
	)

PROP_FNS	(	kGetInvertReflect	,
		GetInvertReflect	,
		kSetInvertReflect	,
		SetInvertReflect	,
		TYPE_BOOL
	)

PROP_FNS	(	kGetInvertRefract	,
		GetInvertRefract	,
		kSetInvertRefract	,
		SetInvertRefract	,
		TYPE_BOOL
	)

BOOL GetNoExposure ( ) const

inline

Remarks

Returns the NoExposure property. If this returns true, the shaded output of the material is NOT processed by the exposure control. When the property is false the shaded output is processed by the exposure control. This is useful for materials that aren't interacting with lighting that want specific RGB values to end up in the rendered image.

Returns

true if the material should NOT be processed by the exposure control.

{ return mNoExposure; }

virtual void SetNoExposure ( BOOL  on )

inlinevirtual

Remarks

Sets the NoExposure property. If this is set to true, the shaded output of the material is NOT processed by the exposure control. When the property is false the shaded output is processed by the exposure control. This is useful for materials that aren't interacting with lighting that want specific RGB values to end up in the rendered image.

Parameters

on	- if true the material should have no exposure

{ mNoExposure = on != 0; }

BOOL GetInvertSelfIllum ( ) const

inline

Remarks

Gets the InvertSelfIllum property: When this property is true, the self-illumination portion of the shaded output is converted from RGB to a physical value, so that the physical value gives the original RGB value when processed by the exposure control. When the property is false the self-illumination value is converted by multiplying by the physical scale. This is useful if the self-illumination value is a RGB value that you want preserved, but you also want lighting to interact with the material.

Returns

the value of Invert Self Illumination property

{ return mInvertSelfIllum; }

virtual void SetInvertSelfIllum ( BOOL  on )

inlinevirtual

Remarks

Sets the InvertSelfIllum property: When this property is true, the self-illumination portion of the shaded output is converted from RGB to a physical value, so that the physical value gives the original RGB value when processed by the exposure control. When the property is false the self-illumination value is converted by multiplying by the physical scale. This is useful if the self-illumination value is a RGB value that you want preserved, but you also want lighting to interact with the material.

Parameters

on	- the new value of Invert Self Illumination property

{ mInvertSelfIllum = on != 0; }

BOOL GetInvertReflect ( ) const

inline

Remarks

Gets the InvertReflect property: When this property is true, the reflection map portion of the shaded output is converted from RGB to a physical value so that the physical value gives the original RGB value when processed by the exposure control. When the property is false the reflection map value is converted by multiplying by the physical scale. This is useful if the reflection value is not being calculated by the renderer from the scene.

Returns

the state of the InvertReflect property

{ return mInvertReflect; }

virtual void SetInvertReflect ( BOOL  on )

inlinevirtual

Remarks

Sets the InvertReflect property: When this property is true, the reflection map portion of the shaded output is converted from RGB to a physical value so that the physical value gives the original RGB value when processed by the exposure control. When the property is false the reflection map value is converted by multiplying by the physical scale. This is useful if the reflection value is not being calculated by the renderer from the scene.

Parameters

on	- the new state of the InvertReflect property

{ mInvertReflect = on != 0; }

BOOL GetInvertRefract ( ) const

inline

Remarks

Gets the InvertRefract property: When this property is true, the refraction map portion of the shaded output is converted from RGB to a physical value so that the physical value gives the original RGB value when processed by the exposure control. When the property is false the refraction map value is converted by multiplying by the physical scale. This is useful if the reflection value is not being calculated by the renderer from the scene.

Returns

the state of the InvertRefract property

{ return mInvertRefract; }

virtual void SetInvertRefract ( BOOL  on )

inlinevirtual

Remarks

Sets the InvertRefract property: When this property is true, the refraction map portion of the shaded output is converted from RGB to a physical value so that the physical value gives the original RGB value when processed by the exposure control. When the property is false the refraction map value is converted by multiplying by the physical scale. This is useful if the reflection value is not being calculated by the renderer from the scene.

Parameters

on	- the new state of the InvertReflect property

{ mInvertRefract = on != 0; }

ULONG isNoExposure ( ) const

inline

{ return mNoExposure ? MTLREQ_NOEXPOSURE : 0; }

bool isInvertSelfIllum ( ) const

inline

{ return !mNoExposure & mInvertSelfIllum; }

bool isInvertReflect ( ) const

inline

{ return !mNoExposure & mInvertReflect; }

bool isInvertRefract ( ) const

inline

{ return !mNoExposure & mInvertRefract; }

IOResult Save ( ISave *  isave )

inline

Remarks

Save the plugin parameters to disk.
This is implemented by the system to save the exposure parameters, any child classes that override this function should explicitly call the parent classes Save. An example of how to do this is as follows

MyMaterial::Save(ISave* isave) {
    // Do my saving here
    isave->BeginChunk(PARENT_DATA_CHUNK);
    ExposureMaterialControl::Save(isave);
    isave->EndChunk();
}

The ExposureMaterialControl implementation is as follows

{
    isave->BeginChunk(DATA_CHUNK);
    IOResult res;
    if ((res = write(isave, mNoExposure)) == IO_OK
            && (res = write(isave, mInvertSelfIllum)) == IO_OK
            && (res = write(isave, mInvertReflect)) == IO_OK)
        res = write(isave, mInvertRefract);
    isave->EndChunk();
    return res;
}

IOResult Load ( ILoad *  iload )

inline

Remarks

Load the plugin parameters.
This is implemented by the system to load the exposure parameters, any child classes that override this function should explicitly call the parent classes Load. An example of how to do this is as follows

MyMaterial::Load(ILoad* iload) {
    IOResult res;
    USHORT id;
    while (IO_OK==(res=iload->OpenChunk())) {
        switch(id = iload->CurChunkID())  {
            // Any other data chunks need to go here too
        case PARENT_DATA_CHUNK:
            res = ExposureMaterialControl::Load(iload);
            break;
        }
        iload->CloseChunk();
        if (res!=IO_OK) 
            return res;
    }
    return IO_OK;
}

The ExposureMaterialControl implementation is as follows

{
    IOResult res;
    USHORT id;
    while (IO_OK==(res=iload->OpenChunk())) {
        switch(id = iload->CurChunkID())  {
        case DATA_CHUNK:
            if ((res = read(iload, mNoExposure)) == IO_OK
                    && (res = read(iload, mInvertSelfIllum)) == IO_OK
                    && (res = read(iload, mInvertReflect)) == IO_OK)
                res = read(iload, mInvertRefract);
            break;
        }

        iload->CloseChunk();
        if (res!=IO_OK) 
            return res;
    }
    return IO_OK;
}

IOResult write ( ISave *  isave, bool &  b  )

inlineprotected

{
    DWORD n;
    IOResult res = isave->Write(&b, sizeof(b), &n);
    if (res != IO_OK)
        return res;
    return n == sizeof(b) ? IO_OK : IO_ERROR;
}

IOResult read ( ILoad *  iload, bool &  b  )

inlineprotected

{
    DWORD n;
    IOResult res = iload->Read(&b, sizeof(b), &n);
    if (res != IO_OK)
        return res;
    return n == sizeof(b) ? IO_OK : IO_ERROR;
}

Member Data Documentation

bool mNoExposure

protected

bool mInvertSelfIllum

protected

bool mInvertReflect

protected

bool mInvertRefract

protected