#include <IInteractiveRenderer.h>

Class Description

See also: Class InterfaceServer, Class IIRenderMgr, Class INode, Class ViewExp, Class Bitmap, Class DefaultLight, Class IRenderProgressCallback, Class Animatable, Class ActionTable

Description:: 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.

Inheritance diagram for IInteractiveRender:

Classes
class	IProgressCallback
	This class represent a callback object which can be used with an interactive renderer. Information set via RendProgressCallback::SetCurField() or RendProgressCallback::SetSceneStats() will be ignored. If a title is set via the inherited method SetTitle(), it will appear in the main status bar, but will be replaced by the 'IRenderTitle' when necessary. An interactive renderer should abort if RendProgressCallback::Progress() returns RENDPROG_ABORT. More...

Public Member Functions
virtual void	BeginSession ()=0

virtual void	EndSession ()=0

virtual void	SetOwnerWnd (HWND hOwnerWnd)=0

virtual HWND	GetOwnerWnd () const =0

virtual void	SetIIRenderMgr (IIRenderMgr *pIIRenderMgr)=0

virtual IIRenderMgr *	GetIIRenderMgr (IIRenderMgr *pIIRenderMgr) const =0

virtual void	SetBitmap (Bitmap *pDestBitmap)=0

virtual Bitmap *	GetBitmap (Bitmap *pDestBitmap) const =0

virtual void	SetSceneINode (INode *pSceneINode)=0

virtual INode *	GetSceneINode () const =0

virtual void	SetUseViewINode (bool bUseViewINode)=0

virtual bool	GetUseViewINode () const =0

virtual void	SetViewINode (INode *pViewINode)=0

virtual INode *	GetViewINode () const =0

virtual void	SetViewExp (ViewExp *pViewExp)=0

virtual ViewExp *	GetViewExp () const =0

virtual void	SetRegion (const Box2 &region)=0

virtual const Box2 &	GetRegion () const =0

virtual void	SetDefaultLights (DefaultLight *pDefLights, int numDefLights)=0

virtual const DefaultLight *	GetDefaultLights (int &numDefLights) const =0

virtual void	SetProgressCallback (IProgressCallback *pProgCB)=0

virtual const IProgressCallback *	GetProgressCallback () const =0

virtual void	Render (Bitmap *pDestBitmap)=0

virtual ULONG	GetNodeHandle (int x, int y)=0

virtual bool	GetScreenBBox (Box2 &sBBox, INode *pINode)=0

virtual ActionTableId	GetActionTableId ()=0

virtual ActionCallback *	GetActionCallback ()=0

virtual void *	GetInterface ()

virtual BOOL	IsRendering ()=0

virtual BOOL	AnyUpdatesPending ()

virtual void	AbortRender ()=0
	This method is called to abort the render operation. More...

Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)

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 UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...

static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...

static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Member Function Documentation

virtual void BeginSession ( )

pure virtual

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<IProgressCallback *>(&mImageViewerCB)

);

mIRenderInterface->BeginSession();

Consequently, BeginSession() can rely on all these local attributes being valid.

virtual void EndSession ( )

pure virtual

Remarks: This method will end an interactive rendering session and will remove all references placed on the scene.

virtual void SetOwnerWnd ( HWND hOwnerWnd )

pure virtual

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.

virtual HWND GetOwnerWnd ( ) const

pure virtual

Remarks: This method allows you to retrieve the owner window.

virtual void SetIIRenderMgr ( IIRenderMgr * pIIRenderMgr )

pure virtual

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.

virtual IIRenderMgr* GetIIRenderMgr ( IIRenderMgr * pIIRenderMgr ) const

pure virtual

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.

virtual void SetBitmap ( Bitmap * pDestBitmap )

pure virtual

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.

virtual Bitmap* GetBitmap ( Bitmap * pDestBitmap ) const

pure virtual

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.

virtual void SetSceneINode ( INode * pSceneINode )

pure virtual

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.

virtual INode* GetSceneINode ( ) const

pure virtual

Remarks: This method returns a pointer to the scene's root node.

virtual void SetUseViewINode ( bool bUseViewINode )

pure virtual

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.

virtual bool GetUseViewINode ( ) const

pure virtual

Remarks: This method returns FALSE if the ViewParams obtained from ViewExp should be used. TRUE would indicate that this is not the case.

virtual void SetViewINode ( INode * pViewINode )

pure virtual

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.

virtual INode* GetViewINode ( ) const

pure virtual

Remarks: This method returns a pointer to the view node if this is used instead of ViewExp.

virtual void SetViewExp ( ViewExp * pViewExp )

pure virtual

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.

virtual ViewExp* GetViewExp ( ) const

pure virtual

Remarks: This method returns a pointer to the ViewExp which is used for the view specification for docked windows.

virtual void SetRegion ( const Box2 & region )

pure virtual

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 &region

A reference to the rectangular area.

virtual const Box2& GetRegion ( ) const

pure virtual

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.

virtual void SetDefaultLights	(	DefaultLight *	pDefLights,
		int	numDefLights
	)

pure virtual

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.

virtual const DefaultLight* GetDefaultLights ( int & numDefLights ) const

pure virtual

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.

virtual void SetProgressCallback ( IProgressCallback * pProgCB )

pure virtual

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:: IProgressCallback *pProgCB

A pointer to the interactive rendering progress callback object.

virtual const IProgressCallback* GetProgressCallback ( ) const

pure virtual

Remarks: This method returns a pointer to the interactive rendering progress callback object.

virtual void Render ( Bitmap * pDestBitmap )

pure virtual

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.

virtual ULONG GetNodeHandle	(	int	x,
		int	y
	)

pure virtual

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.

Returns: The node handle or 0 if there is no node.

virtual bool GetScreenBBox	(	Box2 &	sBBox,
		INode *	pINode
	)

pure virtual

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.

Returns: TRUE if successful, otherwise FALSE.

virtual ActionTableId GetActionTableId ( )

pure virtual

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.

virtual ActionCallback* GetActionCallback ( )

pure virtual

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.

virtual void* GetInterface ( )

inlinevirtual

Remarks: This method provides a general extension mechanism, access to additional method interfaces.

Default Implementation:: { return NULL; }

285 { return NULL; }

NULL

#define NULL

Definition: autoptr.h:18

virtual BOOL IsRendering ( )

pure virtual

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.

virtual BOOL AnyUpdatesPending ( )

inlinevirtual

Remarks: This method returns TRUE if the renderer has not applied all pending scene updates yet, or FALSE if there are no updates pending and what is currently rendering or has been rendered is matching what the scene looks like.

If the interactive renderer has the concept of an update queue, it can return its state here. This function is used by the GetActiveShadeBitmap wait:true MaxScript function to be certain that the image being rendered is final and the complete state of the rendering. The function waits until IsRendering() AND AnyUpdatesPending() return false, and then grabs the image.

Default Implementation:: { return FALSE; }

312 { return FALSE; };

virtual void AbortRender ( )

pure virtual

This method is called to abort the render operation.

The implementation should stop the rendering process as quickly as possible and return only once the render has actually stopped rendering.

IInteractiveRender Class Reference

Class Description

Classes

Public Member Functions

Additional Inherited Members

Member Function Documentation