Class IRenderElement
See Also: Class SpecialFX, Class PBBitmap, Class ISave, Class ILoad, List of Reference Messages, Render Elements
class IRenderElement : public SpecialFX
Description:
This class is available in release 4.0 and later only.
This is the interface that must be supported by all render elements whether they support the 3ds max renderer or some other renderer. The UI in the render dialog uses this interface exclusively to control the element.
The methods are almost all state-setting methods, with ones that are settable by the UI provided by both sets and gets. A sample plugin of a Render Element can be found in the SDK samples; \MAXSDK\SAMPLES\RENDER\RENDERELEMENTS.
Methods:
public:
Prototype:
virtual void SetEnabled(BOOL enabled)=0;
Remarks:
This method enables or disables the Render Element.
Parameters:
BOOL enabled
Set to TRUE in order to enable the Render Element. FALSE to disable it.
Prototype:
virtual BOOL IsEnabled() const = 0;
Remarks:
This method returns TRUE if the Render Element is enabled, otherwise FALSE.
Prototype:
virtual void SetFilterEnabled(BOOL filterEnabled)=0;
Remarks:
Each active render element has the option of either using the current AA filter or simple blending within the pixel. This method will set the internal filter enable to the value of parameter filterEnabled.
Parameters:
BOOL filterEnabled
Set to TRUE in order to enable. FALSE to disable it.
Prototype:
virtual BOOL IsFilterEnabled() const = 0;
Remarks:
This method returns the current state of whether the AA filter is enabled.
Parameters:
This method returns TRUE if filters for the Render Element are enabled, otherwise FALSE.
Prototype:
virtual BOOL BlendOnMultipass() const =0;
Remarks:
This method returns whether this element type should be blended during multipass effects.
When multipass camera effects such as depth of field are used in a rendering, each of the separate elements may be blended into a final bitmap like the composite color, or they may be "frozen" after the first pass. Blending is not appropriate for some elements, like z-depth. This is typically a query only, it is unlikely that this will need to be turned on & off.
Return Value:
TRUE if blending during multipass effects, otherwise FALSE.
Prototype:
virtual void SetApplyAtmosphere(BOOL applyAtmosphere)=0;
Remarks:
This method enables or disables the Apply Atmosphere flag for the Render Element.
Parameters:
BOOL applyAtmosphere
Set to TRUE in order to enable the atmospheric effects for the Render Element. FALSE to disable it.
Prototype:
virtual BOOL AtmosphereApplied() const = 0;
Remarks:
This method returns TRUE if atmospheric effects for the Render Element are enabled, otherwise FALSE.
Prototype:
virtual void SetApplyShadows(BOOL applyShadows)=0;
Remarks:
This method enables or disables the Apply Shadows flag for the Render Element.
Parameters:
BOOL applyShadows
Set to TRUE in order to enable the shadows for the Render Element. FALSE to disable it.
Prototype:
virtual BOOL ShadowsApplied() const = 0;
Remarks:
This method returns TRUE if shadows for the Render Element are enabled, otherwise FALSE.
Prototype:
virtual void SetElementName(TCHAR* newName)=0;
Remarks:
This method sets the Render Element’s name as it appears in the render dialog.
Parameters:
TCHAR* newName;
The name for the Render Element.
Prototype:
virtual const TCHAR* ElementName() const = 0;
Remarks:
This method returns a string representing the Render Element’s name as it appears in the render dialog.
Prototype:
virtual void SetPBBitmap(PBBitmap* &pPBBitmap) const = 0;
Remarks:
This method allows you to set the bitmapinfo/bitmap to use for the Render Element.
Each render element has an output bitmap. We use the pb2 style bitmap as it contains the pathname as well as the bitmap & bitmapInfo structures needed by windows. The bitmap is created by the render element manager, then held by the element until it’s not needed. These are the calls that set & get the elements bitmap.
Parameters:
PBBitmap* &pPBBitmap
The pointer to the PBBitmap reference.
Prototype:
virtual void GetPBBitmap(PBBitmap* &pPBBitmap) const = 0;
Remarks:
This method allows you to get the bitmapinfo/bitmap that is used for the Render Element.
Parameters:
PBBitmap* &pPBBitmap
The pointer to the PBBitmap reference which was retrieved.
Prototype:
virtual IRenderElementParamDlg *CreateParamDialog(IRendParams *ip);
Remarks:
Each render element may define a rollup that will be displayed in the render dialog when that element is selected. Most current render elements do not provide their own rollups, but some like z-depth and blend do. This method creates the elements parameter rollup and return it’s pointer to the system. If no rollup is supported, NULL should be returned.
Parameters:
IRendParams *ip
A pointer to the IRendParams data.
Default Implementation:
{ return NULL; }
Prototype:
virtual BOOL SetDlgThing(IRenderElementParamDlg* dlg);
Remarks:
Implement this method if you are using the ParamMap2 AUTO_UI system and the IRenderElement has secondary dialogs that don't have the IRenderElement as their 'thing'. Called once for each secondary dialog, for you to install the correct ‘thing’. This method will set the "thing" of a secondary dialog.
Parameters:
IRenderElementParamDlg* dlg
The pointer to the parameter dialog.
Return Value:
TRUE if you process the dialog, otherwise FALSE.
Default Implementation:
{ return FALSE; };
Prototype:
IOResult Save(ISave *iSave)
Remarks:
This method handles saving the plugin data. it is critical for merging that this code is called at the start of a plug-in's save and load methods. SpecialFX's base implementation saves/loads SpecialFX::name, which is used to populate the 'Merge Render Elements' dialog box. if a plugin re-implements this function, it should first call RenderElement::Save(iSave) or IRenderElement::Load(iLoad)
Parameters:
ISave *iSave
You may use this pointer to call methods of ISave to write data.
Return Value:
One of the following values: IO_OK, IO_ERROR.
Default Implementation:
{
name = ElementName();
return SpecialFX::Save(iSave);
}
Prototype:
IOResult Load(ILoad *iLoad)
Remarks:
This method handles loading the plugin data. It is critical for merging that this code is called at the start of a plug-in's save and load methods. SpecialFX's base implementation saves/loads SpecialFX::name, which is used to populate the 'Merge Render Elements' dialog box. if a plugin re-implements this function, it should first call RenderElement::Save(iSave) or IRenderElement::Load(iLoad)
Parameters:
ILoad *iLoad
You may use this pointer to call methods of ILoad to read data.
Return Value:
One of the following values: IO_OK, IO_ERROR.
Default Implementation:
{ return SpecialFX::Load(iLoad); }
Prototype:
virtual RefResult NotifyRefChanged(Interval changeInt, RefTargetHandle hTarget, PartID& partID, RefMessage message);
Remarks:
A plug-in which makes references must implement this method to receive and respond to messages broadcast by its dependents.
Parameters:
Interval changeInt
This is the interval of time over which the message is active. Currently, all plug-ins will receive FOREVER for this interval.
RefTargetHandle hTarget
This is the handle of the reference target the message was sent by. The reference maker uses this handle to know specifically which reference target sent the message.
PartID& partID
This contains information specific to the message passed in. Some messages don't use the partID at all. See the section List of Reference Messages for more information about the meaning of the partID for some common messages.
RefMessage message
The message parameters passed into this method is the specific message which needs to be handled. See List of Reference Messages.
Return Value:
The return value from this method is of type RefResult. This is usually REF_SUCCEED indicating the message was processed. Sometimes, the return value may be REF_STOP. This return value is used to stop the message from being propagated to the dependents of the item.
Default Implementation:
{ return REF_SUCCEED; }
Prototype:
SClass_ID SuperClassID();
Remarks:
This method returns the plugin’s SuperClass ID.
Default Implementation:
{ return RENDER_ELEMENT_CLASS_ID; }
Prototype:
virtual void* GetInterface(ULONG id)=0;
Remarks:
This method is being used as a general extension method in 3dw max. The Render Elements use it to get the interface for a specific renderer’s element interface. The renderer will call this method to see if an IRenderElement is compatible with it. By asking for a specific renderer interface, the element can either provide the interface, or return NULL. If NULL is returned, then this element will not be available for this renderer. Note that this strategy allows a single render element to support more than one renderer. The max default renderer iid is in \MAXSDK\INCLUDE\renderElements.h and is defined as 0xeffeeffe, accessed through MaxRenderElement::IID.
Parameters:
ULONG id
Currently this is not used and is reserved for future use.
Prototype:
virtual void ReleaseInterface(ULONG id, void *i)=0;
Remarks:
This method is not currently used. It is reserved for future use. Its purpose is for releasing an interface created with GetInterface().