RenderTimeInstancingInterface Class Reference

The RenderTimeInstancingInterface allows a renderer to access an object's instancing information so that it can do efficient instancing at render-time. More...

#include <C:/adskgit/3dsmax/3dsmax/3dswin/src/maxsdk/include/Rendering/RenderTimeInstancing.h>

Inheritance diagram for RenderTimeInstancingInterface:

Classes
class	Iterator

Public Member Functions
Setup, update and release
virtual void	UpdateInstanceData (TimeValue t, Interval &valid, MotionBlurInfo &mbinfo, const View &view, const TSTR &plugin)=0
	Make sure that the instancing data is up-to-date.
virtual void	ReleaseInstanceData ()=0
	Release the instancing data.
Interface_ID	GetID () override
	Get this interface's ID.
Getting data channels
These are methods that can be used to obtain the list of data channels on the object. Known data channels can also be requested by name.
virtual MaxSDK::Array< ChannelInfo >	GetChannels () const =0
	Returns a list of data channels.
virtual ChannelID	GetChannelID (const TSTR &name, TypeID type) const =0
	Utility method to get the ChannelID of a known data channel.
Getting the actual things to be instanced (the sources)
virtual size_t	GetNumInstanceSources () const =0
	Get the number of sources.
virtual const RenderInstanceSource *	GetRenderInstanceSource (size_t index) const =0
	Get the nth source.
Iterator	begin () const
	Retrieve the begin() iterator. Allows using a for (auto x : y) loop.
Iterator	end () const
	Retrieve the end() iterator.
Public Member Functions inherited from BaseInterface
virtual UtilExport	~BaseInterface ()
	Destructor.
UtilExport BaseInterface *	GetInterface (Interface_ID id) override
virtual LifetimeType	LifetimeControl ()
virtual bool	RegisterNotifyCallback (InterfaceNotifyCallback *incb)
virtual void	UnRegisterNotifyCallback (InterfaceNotifyCallback *incb)
virtual BaseInterface *	AcquireInterface ()
virtual void	ReleaseInterface ()
virtual void	DeleteInterface ()
virtual BaseInterface *	CloneInterface (void *remapDir=nullptr)
Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor.
template<class InterfaceType>
InterfaceType *	GetTypedInterface ()

Additional Inherited Members
Public Types inherited from BaseInterface
enum	LifetimeType { noRelease , immediateRelease , wantsRelease , serverControlled }
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator.
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator.
static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary.
static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary.
static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc.

Detailed Description

The RenderTimeInstancingInterface allows a renderer to access an object's instancing information so that it can do efficient instancing at render-time.

This interface is implemented by an object and called by a renderer.

Note

It is legal for a renderer to iterate over the RenderInstanceSources and RenderInstanceTargets from multiple threads. However, the same thread should not concurrently access multiple RenderInstanceTargets at the same time. This makes it legal for the object plugin to actually reuse the memory returned by the RenderInstanceSource::GetRenderInstanceTarget() method to improve performance, as long as that memory block is kept separate per thread.

A renderer should not call GetRenderMesh() for an object that supports this interface. However, even if an object implements this interface, it should ideally still implement GetRenderMesh() to return an aggregate mesh of all instances, so that a renderer that does not support this interface will at least render something.

An instance may have custom data channels. The data channel names used by an instancer can be retrieved using the RenderTimeInstancingInterface::GetChannels() method. Each data channel has a name, a type, and a ChannelID, which is used to retrieve the actual values for each instance using the RenderInstanceTarget::GetXXX() methods.

Usage example by a renderer:

RenderTimeInstancingInterface* instancer = RenderTimeInstancingInterface::GetRenderTimeInstancingInterface(baseObject);
if (instancer)
{
    // UpdateInstanceData
    Interval valid = FOREVER;
 
    // Initialize motion blur info, which is used for two-way communication
    // between the renderer and the object. The renderer specifies what it wants
    // and the object responds with what it can actually accommodate
    MotionBlurInfo mblur(Interval(shutterOpen, shutterClose));
    instancer->UpdateInstanceData(t, valid, mblur, view, _T("myRenderer"));
 
    // Get the ChannelIDs of known data channels by using their names
    ChannelID floatChannel1  = instancer->GetChannelID(_T("myFloatChannel"),   typeFloat);
    ChannelID VectorChannel1 = instancer->GetChannelID(_T("myVectorChannel1"), typeVector);
    ChannelID VectorChannel2 = instancer->GetChannelID(_T("myVectorChannel2"), typeVector);
    ChannelID TMChannel1     = instancer->GetChannelID(_T("myTMChannel"),      typeTM);
 
    // Instancer acts as a container of sources. Loop over the sources in the instancer
    for (auto source : *instancer)
    {
        auto flags = source->GetFlags();
 
        // Get what will be instanced
        void* data = source->GetData();
        if (flags & DataFlags::df_mesh)  { ... the pointer is a mesh ... }
        if (flags & DataFlags::df_inode) { ... the data pointer is an iNode ... }
 
        // A source acts as a container of targets
        for (auto target : *source)
        {
            // Deal with known data. Will return defaults if missing
            // It is the responsibility of the caller to not call the wrong type
            float   f1  = target->GetCustomFloat(floatChannel1);
            Point3  v1  = target->GetCustomVector(vectorChannel1);
            Point3  v2  = target->GetCustomVector(vectorChannel2);
            Matrix3 tm1 = target->GetCustomVector(TMChannel1);
 
            // Instance the "source" object using info from the "target"
            // If the renderer prefers to work with velocities and spins, it should check if the object is providing such data
            // This case is not necessary if the renderer only cares about the array of transforms
            if (mblur.flags & MBFlags::mb_velocityspin)
            {
                Matrix3 tm = target->GetTM();
                Vector3    = target->GetVelocity();
                AngAxis    = target->GetSpin();
                ... instance the object accordingly ...
            }
            else // There is no velocity/spin data, so we use transforms
            {
                // Gets the array of transforms over the shutter interval
                auto tms = target->GetTMs();
                ... instance the object accordingly ...
            }
        }
 
        if ((flags & DataFlags::df_mesh) && (flags & DataFlags::df_pluginMustDelete))
        {
            ... delete the mesh ...
        }
    }
 
    // Cleanup, if any is needed
    instancer->ReleaseInstanceData();
}
else
{
    ... use GetRenderMesh() instead ...
}

Member Function Documentation

UpdateInstanceData()

virtual void UpdateInstanceData ( TimeValue t, Interval & valid, MotionBlurInfo & mbinfo, const View & view, const TSTR & plugin )

pure virtual

Make sure that the instancing data is up-to-date.

This method needs to be called by the renderer to make sure that the instancing data is up-to-date and ready to be retrieved.

Parameters

t	The time of the evaluation. Most often same as the shutter open time, if motion blur is used.
valid	Returns the validity of the returned data. For example, if FOREVER is returned it indicates to the renderer that the instances are not moving or changing at all, and could in principle be retained over multiple frames.
mbinfo	An initialized MotionBlurInfo, which upon return will contain info on how the motion data is returned. If the object will return values for velocity and spin, it should set the mb_velocityspin flag.
view	The view. This allows the object to do level-of-detail computations or camera frustum culling.
plugin	The plugin argument of this method takes the name of the plugin querying this interface, in lowercase letters. For example: _T("arnold"), _T("octane"), _T("redshift"), _T("vray"), etc. This is a somewhat arbitrary value, but by having renderers identify themselves during a query, the object can internally determine if any renderer-specific edge cases need to be processed.

See also

Struct MotionBlurInfo

ReleaseInstanceData()

virtual void ReleaseInstanceData ( )

pure virtual

Release the instancing data.

When a renderer is done with the data returned by this interface, it can call this method. If the generating plugin allocated some information, it can release it in this method.

GetID()

Interface_ID GetID ( )

inlineoverridevirtual

Get this interface's ID.

Reimplemented from BaseInterface.

{ return RENDERTIME_INSTANCING_INTERFACE; }

GetChannels()

virtual MaxSDK::Array< ChannelInfo > GetChannels ( ) const

pure virtual

Returns a list of data channels.

GetChannelID()

virtual ChannelID GetChannelID ( const TSTR & name, TypeID type ) const

pure virtual

Utility method to get the ChannelID of a known data channel.

Returns -1 if a data channel of that name and type does not exist.

GetNumInstanceSources()

virtual size_t GetNumInstanceSources ( ) const

pure virtual

Get the number of sources.

GetRenderInstanceSource()

virtual const RenderInstanceSource * GetRenderInstanceSource ( size_t index ) const

pure virtual

Get the nth source.

begin()

Iterator begin ( ) const

inline

Retrieve the begin() iterator. Allows using a for (auto x : y) loop.

{ return Iterator(this); }

end()

Iterator end ( ) const

inline

Retrieve the end() iterator.

{ return Iterator(this, GetNumInstanceSources()); }