This reference page is linked to from the following overview topics: Plug-in Base Classes, Writing Rendering Plug-Ins.

Detailed Description

This is the base class for any renderer plugin.

The main entry points for this class are methods Open(), Render(), and Close(). Any render operation works as follows: 1. Open() is called exactly once. 2. Render() is called zero or more times. 3. Close() is called exactly once.

See also:: Class ReferenceTarget, Class FrameRendParams, Class RendProgressCallback, Class IRendParams, Class INode, Class ViewParams, Class RendParamDlg, Class RendParams, Class DefaultLight.

Description:: This is the base class for the creation of plug-in renderers. There are five methods that need to be implemented: Open(), Render(), Close(), CreateParamDialog() and ResetParams().

In 3ds Max 2.0 and later developers must also implement ReferenceTarget::Clone() to support the new Production/Draft renderer capability.

#include <render.h>

Inheritance diagram for Renderer:

[legend]

List of all members.

Public Member Functions
SClass_ID	SuperClassID ()
	Returns the super class ID RENDERER_CLASS_ID.
virtual int	Open (INode scene, INode vnode, ViewParams viewPar, RendParams &rp, HWND hwnd, DefaultLight defaultLights=NULL, int numDefLights=0, RendProgressCallback *prog=NULL)=0
	Called once and only once per render operation; used to initialize the renderer before rendering a sequence of frames.
virtual int	Render (TimeValue t, Bitmap tobm, FrameRendParams &frp, HWND hwnd, RendProgressCallback prog=NULL, ViewParams *viewPar=NULL)=0
	Called to render a single frame.
virtual void	Close (HWND hwnd, RendProgressCallback *prog=NULL)=0
	Called once and only once per render operation; used to free any resources allocated by Open() or Render().
virtual bool	ApplyRenderEffects (TimeValue t, Bitmap *pBitmap, bool updateDisplay=true)
	This method is called to apply the render effects at the specified time value.
virtual RendParamDlg *	CreateParamDialog (IRendParams *ir, BOOL prog=FALSE)=0
	This method is called to create and return a pointer to an instance of the RendParamDlg class.
virtual void	ResetParams ()=0
	This method simply sets all the parameters to their default values.
virtual int	GetAAFilterSupport ()
virtual bool	SupportsTexureBaking ()
	Renderers which support texture baking should override this method to return true.
virtual bool	SupportsCustomRenderPresets ()
	A renderer should override this method to return true if it supports any custom preset categories beyond the standard categories.
virtual int	RenderPresetsFileVersion ()
	Return a number indicating the current version of the renderer's custom preset.
virtual BOOL	RenderPresetsIsCompatible (int version)
	Return true if the renderer can load presets of the indicated version.
virtual MCHAR *	RenderPresetsMapIndexToCategory (int catIndex)
	Returns the UI name of a supported custom category.
virtual int	RenderPresetsMapCategoryToIndex (const MCHAR *category)
	Returns the index of a supported custom category.
virtual int	RenderPresetsMapCategoryToIndex (MCHAR *category)
virtual int	RenderPresetsPreSave (ITargetedIO *root, BitArray saveCategories)
	called before a render preset is saved.
virtual int	RenderPresetsPostSave (ITargetedIO *root, BitArray loadCategories)
	called after a preset is saved.
virtual int	RenderPresetsPreLoad (ITargetedIO *root, BitArray saveCategories)
	called before a preset is loaded.
virtual int	RenderPresetsPostLoad (ITargetedIO *root, BitArray loadCategories)
	called after a preset is loaded.

Member Function Documentation

SClass_ID SuperClassID ( ) [inline, virtual]

Search for all occurrences

Returns the super class ID RENDERER_CLASS_ID.

Reimplemented from ReferenceTarget.

{return RENDERER_CLASS_ID;}

virtual int Open	(	INode *	scene,
		INode *	vnode,
		ViewParams *	viewPar,
		RendParams &	rp,
		HWND	hwnd,
		DefaultLight *	defaultLights = `NULL`,
		int	numDefLights = `0`,
		RendProgressCallback *	prog = `NULL`
	)		`[pure virtual]`

Search for all occurrences

Called once and only once per render operation; used to initialize the renderer before rendering a sequence of frames.

This gives a chance to the renderer to build any data structures which it will need in the rendering phase. If this call returns 0, then the caller is not required to call Close(), so Open() should do any necessary cleanup before returning 0.

Parameters:

[in]	scene	- The root node of the scene to render. Note: If you are rendering in the Materials Editor, you'll instead get a pointer to the INode that is in the sample slot - not the root node of the scene.
[in]	vnode	- The view node. This may be a camera, a light, or NULL.
[in]	viewPar	- View parameters for rendering orthographic or user viewports. This is used if vnode is NULL.
[in]	rp	- This class contains a set of common renderer parameters.
[in]	hwnd	- The owner window for messages.
[in]	defaultLights	- An array of default lights if there are no user created lights in the scene.
[in]	numDefLights	- Number of lights in defaultLights array.
[in]	prog	- A callback used to allow the renderer to update the progress dialog.

Returns:: Nonzero for success, zero for failure.

virtual int Render	(	TimeValue	t,
		Bitmap *	tobm,
		FrameRendParams &	frp,
		HWND	hwnd,
		RendProgressCallback *	prog = `NULL`,
		ViewParams *	viewPar = `NULL`
	)		`[pure virtual]`

Search for all occurrences

Called to render a single frame.

This may be called zero or more times, in between calls to Open() and Close(), to render a sequence of frames, at a series of time values which are not necessarily sequential.

Parameters:

[in]	t	- The time at which this frame is to be rendered.
[in]	tobm	- The bitmap to which the image is to be rendered.
[in]	frp	- A set of frame dependent parameters.
[in]	hwnd	- The owner window handle.
[in]	prog	- A callback used to allow the renderer to update the progress dialog.
[in]	viewPar	- This parameter allows one to specify a different view transformation on each render call. For example, one may render a given scene at a given time from many different viewpoints, without calling Render::Open() for each one.

Returns:: Nonzero for success, zero for failure.

virtual void Close	(	HWND	hwnd,
		RendProgressCallback *	prog = `NULL`
	)		`[pure virtual]`

Search for all occurrences

Called once and only once per render operation; used to free any resources allocated by Open() or Render().

This method needs to be called whenever Open() was called and returned a non-zero value. The renderer should free any allocated resources, returning in a state identical to the one before Open() was called.

Parameters:

[in]	hwnd	- The owner window handle.
[in]	prog	- A callback used to allow the renderer to update the progress dialog.

Returns:: Nonzero for success, zero for failure.

virtual bool ApplyRenderEffects	(	TimeValue	t,
		Bitmap *	pBitmap,
		bool	updateDisplay = `true`
	)		`[inline, virtual]`

Search for all occurrences

This method is called to apply the render effects at the specified time value.

It should be called between the Open() and Close() methods.

This can be used during a multi-pass rendering, in order to apply the render effects to the final, blended bitmap.

Parameters:

Parameters:

t	- The time to apply the render effects.
pBitmap	- Points to the bitmap.
updateDisplay	- Passing true indicates that Bitmap's display should be refreshed by the renderer; false indicates it should not be.

Returns:: Returns true if the effects were successfully applied; otherwise false.

{ return false; }

virtual RendParamDlg* CreateParamDialog	(	IRendParams *	ir,
		BOOL	prog = `FALSE`
	)		`[pure virtual]`

Search for all occurrences

This method is called to create and return a pointer to an instance of the RendParamDlg class.

The renderer can add rollup page(s) to the renderer configuration dialog using the IRendParams interface passed into this method.

Parameters:

ir	- An interface that provides methods for use in displaying parameters, for example this class has methods for adding rollup pages.
prog	- If TRUE then the rollup page should just display the parameters so the user has them for reference while rendering, they should not be editable.

Returns:: A pointer to an instance of the RendParamDlg class. This class will be deleted using RendParamDlg::DeleteThis().

virtual void ResetParams ( ) [pure virtual]

Search for all occurrences

This method simply sets all the parameters to their default values.

virtual int GetAAFilterSupport ( ) [inline, virtual]

Search for all occurrences

{ return 0; } // point sample, no reconstruction filter

virtual bool SupportsTexureBaking ( ) [inline, virtual]

Search for all occurrences

Renderers which support texture baking should override this method to return true.

It is checked when the Render to Texture dialog is opened; if the current renderer does not support texture baking, then a warning message is displayed and the user will not be able to press the Render button in the dialog.

Returns:: By default this will return false

{ return false; }

virtual bool SupportsCustomRenderPresets ( ) [inline, virtual]

Search for all occurrences

A renderer should override this method to return true if it supports any custom preset categories beyond the standard categories.

Returns:: By default this will returns false

{ return false; }

virtual int RenderPresetsFileVersion ( ) [inline, virtual]

Search for all occurrences

Return a number indicating the current version of the renderer's custom preset.

The number can be arbitrary

Returns:: By default this will return -1

{ return -1; }

virtual BOOL RenderPresetsIsCompatible ( int version ) [inline, virtual]

Search for all occurrences

Return true if the renderer can load presets of the indicated version.

Parameters:

version The version to test compatibility against

Returns:: By default this will return false.

{ return false; }

virtual MCHAR* RenderPresetsMapIndexToCategory ( int catIndex ) [inline, virtual]

Search for all occurrences

Returns the UI name of a supported custom category.

Parameters:

catIndex - The custom preset index to return the name of. catIndex will be a number between RENDER_PRESETS_CUSTOM_CATEGORY_INDEX_BEGIN and RENDER_PRESETS_CATEGORY_COUNT.

Returns:: If the ID is a supported custom category, return the name of the category to be displayed in the UI. Otherwise return NULL

{ return NULL; }

virtual int RenderPresetsMapCategoryToIndex ( const MCHAR * category ) [inline, virtual]

Search for all occurrences

Returns the index of a supported custom category.

Parameters:

category - The UI name of a custom category

Returns:: If the input is the name of a custom category supported by the renderer, return the ID number of the category. Otherwise returns 0

{ return 0; }

virtual int RenderPresetsMapCategoryToIndex ( MCHAR * category ) [inline, virtual]

Search for all occurrences

{ return RenderPresetsMapCategoryToIndex( const_cast<const MCHAR*>(category));}

virtual int RenderPresetsPreSave	(	ITargetedIO *	root,
		BitArray	saveCategories
	)		`[inline, virtual]`

Search for all occurrences

called before a render preset is saved.

For each custom category supported use root->AddSaveTarget() passing the object with the parameters for that category if the corresponding bit is set in the saveCategories, The object will be saved along with the preset.

Example Implementation:

        {
            // Iterate through all our possible custom preset indices
            for (int i = RENDER_PRESETS_CUSTOM_CATEGORY_INDEX_BEGIN; i < RENDER_PRESETS_CUSTOM_CATEGORY_INDEX_BEGIN + MY_CUSTOM_PRESET_COUNT; i++)
            {
                // Should the preset be saved?
                if (saveCategories[i])
                {
                    // p_myOptions is a class derived from ReferenceTarget that contains our options.
                    root->AddSaveTarget(i, p_myOptions);
                }
            }
        }

Parameters:

root	An instance of an ITargetedIO class to be used to save any custom presets specified
saveCategories	Species the custom preset categories to be saved

{ return -1; }

virtual int RenderPresetsPostSave	(	ITargetedIO *	root,
		BitArray	loadCategories
	)		`[inline, virtual]`

Search for all occurrences

called after a preset is saved.

No specific action is required from the renderer at this time.

See also:: RenderPresetsPreSave

{ return -1; }

virtual int RenderPresetsPreLoad	(	ITargetedIO *	root,
		BitArray	saveCategories
	)		`[inline, virtual]`

Search for all occurrences

called before a preset is loaded.

For each custom category supported, if the corresponding bit is not set in the loadCategories, use root->Store() passing the object with the parameters for that category. The object will be preserved, so the renderer can refer to it after the preset is loaded.

See also:: RenderPresetsPreSave, RenderPresetsPostLoad

Parameters:

root	An instance of an ITargetedIO class to be used to store any custom presets specified
saveCategories	Lists the custom preset categories to be loaded. Any categories not being loaded should be stored on root.

{ return -1; }

virtual int RenderPresetsPostLoad	(	ITargetedIO *	root,
		BitArray	loadCategories
	)		`[inline, virtual]`

Search for all occurrences

called after a preset is loaded.

For each custom category supported...

If the bit is set in the loadCategories: use root->GetSaveTarget() to retrieve the loaded object, and update the renderer's active parameters to match this object

If the bit is not set in the loadCategories: use root->Retrieve() to retrieve the object that was stored during pre-load. Update the renderer's active parameters to match this object. This is important in case a certain category was held in the file and loaded, but the user did not choose to load that category. In this case the renderer must restore its parameters to their former value.

See also:: RenderPresetsPreLoad

Parameters:

root	An instance of an ITargetedIO class to be used to retrieve any custom presets stored pre-load.
loadCategories	Lists the custom preset categories that have been loaded.

{ return -1; }

Renderer Class Reference

Detailed Description

Public Member Functions

Member Function Documentation