Class IInteractiveRender
See Also: Class InterfaceServer, Class IIRenderMgr, Class INode, Class ViewExp, Class Bitmap, Class DefaultLight, Class IRenderProgressCallback, Class Animatable , Class ActionTable
class IInteractiveRender : public InterfaceServer
Description:
This class is available in release 4.0 and later only.
This is the abstract class (Interface) for a a renderer supporting interactive rendering.
With the likelihood of evolving rendering and shading techniques which are going to be markedly different from what is being used now, the 3ds max SDK provides the infrastructure to support interactive rendering. Since renderers are a plugin to 3ds max and since each renderer has a different set of resources and capabilities the interactive rendering and shading API has been made as general and independent as possible. The independence of the renderer also means that the renderer must do a fair amount of work that could be done by the system for all renderers.
Interactive rendering and shading is a separate interface which can be optionally supported by 3rd party renderers and can be obtained by using the GetInterface() method on the renderer. I_RENDER_ID is passed as the ID parameter to a renderer's implementation of Animatable::GetInterface(). The renderer returns a pointer to a class IInteractiveRender instance if it supports interactive rendering, otherwise the default implementation will return NULL, indicating that interactive rendering is not supported. This class, IInteractiveRender is defined in \MAXSDK\INCLUDE\interactiveRendering.h.
As it is, interactive renderers will reference any and all objects, as well as lights and materials in the scene that they can respond to changes from. Via the normal 3ds max notification system the interactive shader will then receive messages whenever one of these referenced objects changes and it must then decide how best to update the scene for the user.
Methods:
public:
Prototype:
virtual void BeginSession() = 0;
Remarks:
This method initiates the interactive rendering and will reference objects in the scene so the renderer receives the proper change notifications. The interactive renderer will automatically update the scene when these changes are received.
This is called when the user first invokes interactive rendering. During the begin session call, the renderer should reference any object in the scene that it can respond to changes from. There are reference manager classes in the SDK to ease this referencing in the file referenceManager.h. many of the parameters of interactive reshading are set up prior to the call to BeginSession(), here is a code snippet from the interactive rendering manager:
mIRenderInterface->SetOwnerWnd(mpIMaxBitmapViewer->GetHDisplayWindow());
mIRenderInterface->SetIIRenderMgr(this);
mIRenderInterface->SetBitmap(mpIMaxBitmapViewer->GetBitmap());
mIRenderInterface->SetSceneINode(mpInterface->GetRootNode());
mIRenderInterface->SetUseViewINode(false);
mIRenderInterface->SetViewINode(NULL);
mIRenderInterface->SetViewExp(mpViewExp);
mIRenderInterface->SetRegion(mSelectedRegion);
mIRenderInterface->SetDefaultLights(mDefaultLights, mNumDefaultLights);
mIRenderInterface->SetProgressCallback(
dynamic_cast<IRenderProgressCallback *>(&mImageViewerCB)
);
mIRenderInterface->BeginSession();
Consequently, BeginSession() can rely on all these local attributes being valid.
Prototype:
virtual void EndSession() = 0;
Remarks:
This method will end an interactive rendering session and will remove all references placed on the scene.
Prototype:
virtual void SetOwnerWnd(HWND hOwnerWnd) = 0;
Remarks:
This method allows you to set the owner window, which could come in handy if you want to pass it to the renderer if necessary. The owner HWND is supplied to the interactive renderer so that it may receive window messages for the interactive window, update the window, etc.
Parameters:
HWND hOwnerWnd
A handle to the owner window.
Prototype:
virtual HWND GetOwnerWnd() const = 0;
Remarks:
This method allows you to retrieve the owner window.
Prototype:
virtual void SetIIRenderMgr(IIRenderMgr *pIIRenderMgr) = 0;
Remarks:
This method sets a pointer to the controlling renderMgr, so that various states can be queried.
Parameters:
IIRenderMgr *pIIRenderMgr
A pointer to the controlling interactive rendering manager.
Prototype:
virtual IIRenderMgr *GetIIRenderMgr(IIRenderMgr *pIIRenderMgr) const = 0;
Remarks:
This method allows you to retrieve a pointer to the controlling interactive render manager
Parameters:
IIRenderMgr *pIIRenderMgr
A pointer to the render manager interface.
Used internally. This should always be set to NULL.
Prototype:
virtual void SetBitmap(Bitmap *pDestBitmap) = 0;
Remarks:
This method allows you to set the destination bitmap to be rendered and re-rendered to. This destination bitmap is persistent between update renderings, basically the renderer holds the bitmap and updates the screen while the manager holds the reference to the bitmap and controls its lifetime.
Parameters:
Bitmap *pDestBitmap
A pointer to the destination bitmap to set.
Prototype:
virtual Bitmap *GetBitmap(Bitmap *pDestBitmap) const = 0;
Remarks:
This method allows you to retrieve the destination bitmap that’s being redered and re-rendered to.
Parameters:
Bitmap *pDestBitmap
A pointer to the destination bitmap.
Used internally. This should always be set to NULL.
Prototype:
virtual void SetSceneINode(INode *pSceneINode) = 0;
Remarks:
This method allows you to set the scene root node. In general, the idea of interactive rendering is to start with a fixed scene and then respond to changes in that scene. This call sets the scene root node. All items stemming from this scene root that an interactive renderer can respond to changes in should be referenced.
Parameters:
INode *pSceneINode
A pointer to the scene root node.
Prototype:
virtual INode *GetSceneINode() const = 0;
Remarks:
This method returns a pointer to the scene’s root node.
Prototype:
virtual void SetUseViewINode(bool bUseViewINode) = 0;
Remarks:
This method sets whether to use the ViewINode. When a separate camera node is needed instead of ViewExp, the interactive rendering manager will set the viewINode to the interactive renderer and set UseViewINode to TRUE.
Parameters:
bool bUseViewINode
If FALSE, ViewParams obtained from ViewExp should be used.
Prototype:
virtual bool GetUseViewINode() const = 0;
Remarks:
This method returns FALSE if the ViewParams obtained from ViewExp should be used. TRUE would indicate that this is not the case.
Prototype:
virtual void SetViewINode(INode *pViewINode) = 0;
Remarks:
This method allows you to set the View INode in case a separate camera node is needed instead of ViewExp.
Parameters:
INode *pViewINode
A pointer to the view node.
Prototype:
virtual INode *GetViewINode() const = 0;
Remarks:
This method returns a pointer to the view node if this is used instead of ViewExp.
Prototype:
virtual void SetViewExp(ViewExp *pViewExp) = 0;
Remarks:
This method allows you to set the ViewExp. The ViewExp is the view specification for docked windows. The interactive renderer gets the view params out of the ViewExp.
Parameters:
ViewExp *pViewExp
A pointer to the ViewExp.
Prototype:
virtual ViewExp *GetViewExp() const = 0;
Remarks:
This method returns a pointer to the ViewExp which is used for the view specification for docked windows.
Prototype:
virtual void SetRegion(const Box2 ®ion) = 0;
Remarks:
This method allows you to set the region of the bitmap to be rendered.
There are two standard interactive modes that should be supported in all interactive renderers: region rendering and selected object rendering, and these modes should ideally work in consort if at all possible: scenes are often very complex and the plugin renderer must be able to limit complexity to increase interactivity. Note that if Box2::IsEmpty() returns TRUE, it indicates to render entire bitmap.
Parameters:
const Box2 ®ion
A reference to the rectangular area.
Prototype:
virtual const Box2 &GetRegion() const = 0;
Remarks:
This method returns the region of the bitmap to be rendered. Note that if Box2::IsEmpty() returns TRUE, it indicates to render entire bitmap.
Prototype:
virtual void SetDefaultLights(DefaultLight *pDefLights, int numDefLights) = 0;
Remarks:
This method allows you to set the default lights to be used in absence of scene lights. These lights will be used when no user specified lights are in the scene. This should be noted when the scene is traversed in begin session, and of course altered if new user lights are created.
Parameters:
DefaultLight *pDefLights
A pointer to a default light source.
int numDefLights
The number of default lights.
Prototype:
virtual const DefaultLight *GetDefaultLights(int &numDefLights) const = 0;
Remarks:
This method returns a pointer to the default lights and the number of default lights which are used in absence of scene lights.
Parameters:
int &numDefLights
The number of default lights returned.
Prototype:
virtual void SetProgressCallback(IRenderProgressCallback *pProgCB) = 0;
Remarks:
This method allows you to set an interactive rendering progress callback object.
The Progress/Abort Callback should be called by the renderer ideally about every 100 milliseconds, but the actual range varies widely. The callback allows the manager to display rendering progress and/or abort a rendering.
Parameters:
IRenderProgressCallback *pProgCB
A pointer to the interactive rendering progress callback object.
Prototype:
virtual const IRenderProgressCallback *GetProgressCallback() const = 0;
Remarks:
This method returns a pointer to the interactive rendering progress callback object.
Prototype:
virtual void Render(Bitmap *pDestBitmap) = 0;
Remarks:
This method renders the bitmap using default non-interactive rendering functionality. This is the only actual command to the interactive renderer.
Parameters:
Bitmap *pDestBitmap
The destination bitmap to render to.
Prototype:
virtual ULONG GetNodeHandle(int x, int y) = 0;
Remarks:
This method returns the closest node handle for a given bitmap pixel location. This can be implemented with an item buffer, by using ray casting, or some other method and allows the interactive rendering manager to implement object selection.
Parameters:
int x, int y
The x and y coordinate of the bitmap pixel.
Return Value:
The node handle or 0 if there is no node.
Prototype:
virtual bool GetScreenBBox(Box2& sBBox, INode *pINode) = 0;
Remarks:
This method returns the screen bounding box of the corresponding INode, so the selection box corners can be drawn.
Parameters:
Box2& sBBox
The screen bounding box.
INode *pINode
The INode for which you wish to retrieve the screen bounding box.
Return Value:
TRUE if successful, otherwise FALSE.
Prototype:
virtual ActionTableId GetActionTableId() = 0;
Remarks:
This method returns the ActionTableId for any action items the renderer may implement. This method will return 0 if none are available. Action tables are used as context sensitive command system to generate quad menus and the like from the various objects in the scene.
Prototype:
virtual ActionCallback *GetActionCallback() = 0;
Remarks:
This method returns a pointer to an ActionCallback for any action items the renderer may implement. This method will return NULL if none are available.
Prototype:
virtual void *GetInterface();
Remarks:
This method provides a general extension mechanism, access to additional method interfaces.
Default Implementation:
{ return NULL; }
Prototype:
virtual BOOL IsRendering() = 0;
Remarks:
This method returns TRUE if the renderer is currently rendering, otherwise FALSE.
When the interactive rendering manager gets a message to shut down or abort an interactive rendering, there is a potential race condition between the interactive renderer shutting down and the shutting down of the manager itself, which deletes the renderer. Since it is the renderer itself that decides when, what and how to re-render the image, it’s not clear to the manager whether a delete is safe. This method allows the manager to inquire whether the renderer is recomputing the image. To abort a rendering, the progress/abort callback must be used. When the abort is complete, IsRendering will return FALSE.