Public Member Functions

Renderer Class Reference

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


Search for all occurrences

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:
Inheritance graph
[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]

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]

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]

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]

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]

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]

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]

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

virtual int GetAAFilterSupport ( ) [inline, virtual]
{ return 0; } // point sample, no reconstruction filter
virtual bool SupportsTexureBaking ( ) [inline, virtual]

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]

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]

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]

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]

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]

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]
{ return RenderPresetsMapCategoryToIndex( const_cast<const MCHAR*>(category));}
virtual int RenderPresetsPreSave ( ITargetedIO root,
BitArray  saveCategories 
) [inline, virtual]

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]

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]

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]

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 Renderer Renderer Renderer Renderer Renderer Renderer Renderer Renderer Renderer
Renderer Renderer Renderer Renderer Renderer Renderer Renderer Renderer Renderer Renderer