ICustomRenderItem Class Reference

This class is used to customize the behavior of a render item. More...

#include <ICustomRenderItem.h>

Inheritance diagram for ICustomRenderItem:

Public Member Functions
virtual void	Realize (DrawContext &drawContext)=0
	Realize() might be called once per frame. More...
virtual void	Display (DrawContext &drawContext)=0
	Display() might be called more than once per frame. More...
virtual size_t	GetPrimitiveCount () const =0
	Get the number of primitives in this render item. More...
virtual void	HitTest (HitTestContext &, DrawContext &drawContext)
	This function is called in a hit test pass. More...
virtual void	OnHit (HitTestContext &, DrawContext &)
	This function will be called when the render item is hit. More...
Public Member Functions inherited from ARefObject
GraphicsUtilityAPI	ARefObject ()
virtual GraphicsUtilityAPI long	AddRef ()
	from IRefObject, see comments in IRefObject More...
virtual GraphicsUtilityAPI long	Release ()
	decrease reference count of this object by one, if the decreased reference count equals zero, the object will be deleted. More...
GraphicsUtilityAPI IRefObject *	QueryInterface (Interface_ID classID)
	Try query an interface from the ref object using a given interface id. More...
Public Member Functions inherited from IRefObject
GraphicsUtilityAPI	IRefObject ()
virtual GraphicsUtilityAPI	~IRefObject ()
Public Member Functions inherited from BaseInterfaceServer
virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)
virtual UtilExport int	NumInterfaces () const
virtual UtilExport BaseInterface *	GetInterfaceAt (int i) const
virtual UtilExport	~BaseInterfaceServer ()
Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...
template<class InterfaceType >
InterfaceType *	GetTypedInterface ()

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...
Protected Member Functions inherited from ARefObject
virtual GraphicsUtilityAPI void	DeleteThis ()
	This function will be called when the reference count of an ARefObject equals zero. More...
virtual GraphicsUtilityAPI	~ARefObject ()
Protected Attributes inherited from BaseInterfaceServer
Tab< BaseInterface * >	interfaces

Detailed Description

This class is used to customize the behavior of a render item.

It can be set via CustormRenderItemHandle::SetImplementation. The main behavior of a render item is defined in 2 functions: Realize() and Display(). Realize() is called once per frame. It is used to prepare render data for the Display() function. To improve performance, it's recommended to build and store geometry data in this function. You should build vertex streams to at least meet material requirements in the pipeline context. Display() might be called more than once. You should follow material requirements in the pipeline context to draw the geometry. In some cases, the render item may looks different between viewports (for example, billboard). So you may build geometry dynamically in the Display() function. The vertex stream should always follow material requirements in the pipeline context.

Member Function Documentation

Realize()

virtual void Realize ( DrawContext &  drawContext )

pure virtual

Realize() might be called once per frame.

However, if the render item is culled by Max, it won't call Realize() any more. Realize() is designed to build necessary data for the Display() function. Most of the requirement and pipeline states are stored in the PiplineContext. So you should at least build vertex buffers to meet the material requirements. Since this function may be called every frame, it's better to have some cache mechanism to avoid unnecessary geometry rebuilding.

Parameters

[in]

drawContext

context of the pipeline.

Implemented in SplineConsolidationItem, SplineRenderItem, MeshEdgeConsolidationItemDX9, MeshEdgeConsolidationItemDX11, MeshEdgeRenderItem, MarkerConsolidationItem, and MarkerRenderItem.

Display()

virtual void Display ( DrawContext &  drawContext )

pure virtual

Display() might be called more than once per frame.

Users can get a virtual device or legacy graphics window from the pipeline context. It's your job to activate a material (either from the pipeline context or using a custom material), loop all passes, set the vertex format, set the vertex stream, index and call VirtualDevice::Draw()/DrawInstanced() to render geometries. Always make sure the vertex format should be same as pipeline context's material requirement (if it exists). And the vertex stream layout should meet the format.

Parameters

[in]

drawContext

context of the pipeline.

Implemented in SplineConsolidationItem, SplineRenderItem, MeshEdgeConsolidationItemDX9, MeshEdgeConsolidationItemDX11, MeshEdgeRenderItem, MarkerConsolidationItem, and MarkerRenderItem.

GetPrimitiveCount()

virtual size_t GetPrimitiveCount ( ) const

pure virtual

Get the number of primitives in this render item.

Sometimes a render item doesn't have an explicit primitive count (such as a procedure item). In these cases, returning a non-accurate count is acceptable. This primitive count is mainly used for BSP cell creation.

Returns

number of primitives in this render item.

Implemented in SplineConsolidationItem, SplineRenderItem, MeshEdgeConsolidationItemDX11, MeshEdgeRenderItem, MarkerConsolidationItem, and MarkerRenderItem.

HitTest()

virtual void HitTest ( HitTestContext &  , DrawContext &  drawContext  )

inlinevirtual

This function is called in a hit test pass.

All custom render items which use a different render code path need to implement this interface. Users can get hit test information from the HitTestContext and use the draw context to do a hardware hit test. Max uses occlusion query-based hit test. Each render node is associated with an occlusion query. So a typical approach in this HitTest() is call Display() to render the item. Max will get the render result to find out which nodes are hit.

Reimplemented in SplineRenderItem, MeshEdgeRenderItem, and MarkerRenderItem.

    {
        Display(drawContext);
    }

OnHit()

virtual void OnHit ( HitTestContext &  , DrawContext &    )

inlinevirtual

This function will be called when the render item is hit.

Some objects (like cameras) may need special operations rather than selection of the node when specific components are hit. For this scenario, write a separate render item and override the OnHit() function to do the those actions.

{}