3ds Max C++ API Reference
RefEnumProc Class Referenceabstract

A callback class for ReferenceMaker::EnumRefHierarchy. More...

#include <ref.h>

+ Inheritance diagram for RefEnumProc:

Public Member Functions

virtual int proc (ReferenceMaker *rm)=0
 This method is called once for each element in the reference hierarchy. More...
 
virtual CoreExport bool CheckIfAndSetAsVisited (ReferenceMaker *rmaker)
 This method sets and checks whether a ReferenceMaker was visited. More...
 
CoreExport void BeginEnumeration (bool preventDuplicatesViaFlag=true)
 This method prepares the RefEnumProc instance for enumeration. More...
 
CoreExport void EndEnumeration ()
 This method finalizes the RefEnumProc instance after enumeration. More...
 

Protected Member Functions

CoreExport RefEnumProc ()
 
virtual CoreExport ~RefEnumProc ()
 
 RefEnumProc (const RefEnumProc &)
 
RefEnumProcoperator= (const RefEnumProc &rhs)
 

Friends

class ReferenceTarget
 

Additional Inherited Members

- Static Public Member Functions inherited from MaxHeapOperators
static UtilExport voidoperator new (size_t size)
 Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator new[] (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate arrays of objects. More...
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidaligned_malloc (size_t size, size_t alignment)
 Allocates memory on a specified alignment boundary. More...
 
static UtilExport voidaligned_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...
 

Detailed Description

A callback class for ReferenceMaker::EnumRefHierarchy.

This is the callback object for ReferenceMaker::EnumRefHierarchy. This class's proc() method is called for each element in the reference hierarchy. When enumerating indirect references, it is possible to enter an infinite recursive loop unless references are not processed more than once. The system prevents processing duplicates by either maintaining a list of all references processed, or by clearing a flag bit on all references and then testing/setting the flag bit as references are processed. In the ReferenceMaker::EnumRefHierarchy method, this object's BeginEnumeration method is called before starting an enumeration, and EndEnumeration at the end. These methods increment and decrement an internal counter. When the counter is decremented to 0, the list of visited references is cleared. This ensures that the list of visited references is maintained during recursive calls to EnumRefHierarchy, but cleared when the outer most call is exited. In some cases however, it is desirable to maintain the list of visited references across calls to EnumRefHierarchy. In these cases, call this object's BeginEnumeration method prior to the calls to EnumRefHierarchy, and EndEnumeration when done. For example:

FreeMapsRefEnum freeEnum(this);
for ( rmaker = <enum over some refmaker set> )
-- list of visited references cleared after each call
EnumRefHierarchy(rmaker, freeEnum);
versus
FreeMapsRefEnum freeEnum(this);
freeEnum.BeginEnumeration()
for ( rmaker = <enum over some refmaker set> )
-- list of visited references maintained across each call
EnumRefHierarchy(rmaker, freeEnum);
freeEnum.EndEnumeration()

Constructor & Destructor Documentation

◆ RefEnumProc() [1/2]

CoreExport RefEnumProc ( )
protected

◆ ~RefEnumProc()

virtual CoreExport ~RefEnumProc ( )
protectedvirtual

◆ RefEnumProc() [2/2]

RefEnumProc ( const RefEnumProc )
protected

Member Function Documentation

◆ operator=()

RefEnumProc& operator= ( const RefEnumProc rhs)
protected

◆ proc()

virtual int proc ( ReferenceMaker rm)
pure virtual

This method is called once for each element in the reference hierarchy.

This method is called once for each element in the reference hierarchy. The return value specifies whether continue processing the references, indirect references, and custom attributes of the refmaker; whether to skip processing of those and continue to the next element, or whether to terminate enumeration. Typically the return value will be REF_ENUM_CONTINUE.

Parameters
rm- A pointer to the reference maker to this item.
Returns
One of the following values:
  • REF_ENUM_CONTINUE: This continues the enumeration
  • REF_ENUM_HALT: This stops the enumeration.
  • REF_ENUM_SKIP: Reference Makers can hold multiple References. In certain instances you may not want to travel down all of the "branches". By returning REF_ENUM_SKIP from this method you tell the enumerator to not enumerate the current Reference Maker's references but not to halt the enumeration completely.

◆ CheckIfAndSetAsVisited()

virtual CoreExport bool CheckIfAndSetAsVisited ( ReferenceMaker rmaker)
virtual

This method sets and checks whether a ReferenceMaker was visited.

Implemented by system. This method is used to check whether a ReferenceMaker was previously visited by this callback object, and registers it as having been visited if not. This method is used to ensure we call the proc only once on each ReferenceMaker.

Parameters
rmaker- A pointer to the reference maker
Returns
Returns true of the rmaker was previously visited, false if not.

◆ BeginEnumeration()

CoreExport void BeginEnumeration ( bool  preventDuplicatesViaFlag = true)

This method prepares the RefEnumProc instance for enumeration.

Implemented by system. This method is used to initialize the RefEnumProc instance for tracking the reference makers that have been visited. Normally, you do not need to call this method as ReferenceMaker::EnumRefHierarchy calls this method prior to enumerating the specified reference maker. In some cases though, you may want to have RefEnumProc instance track the reference makers visited over multiple calls to EnumRefHierarchy. For example, you may want to call RefEnumProc::proc() on each node in a selection set, tracking the reference makers that have been visited across the entire selection set. Note that each call this method must be paired with a call to EndEnumeration.

Parameters
preventDuplicatesViaFlag- Defaults to true. With preventDuplicatesViaFlag set to true, processing of a duplicate reference is detected by requesting and clearing a flag bit on all animatables, and then testing/setting the flag bit prior to calling the proc on each reference maker. When set to false, a list of reference makers visited is maintained. If you expect to enumerate only a small number of references, this argument should be set to false. Note however that you do not know what references are held by the references you may enumerate into, so in most cases this argument should be true. Note that the setting specified here overrides the preventDuplicatesViaFlag argument setting in the EnumRefHierarchy call.
See also
ReferenceMaker::EnumRefHierarchy

◆ EndEnumeration()

CoreExport void EndEnumeration ( )

This method finalizes the RefEnumProc instance after enumeration.

Implemented by system. This method is used to finalize the RefEnumProc instance after enumeration, freeing any memory or max system resources used to track the reference makers that have been visited. This method should only, and must be, called if you called the BeginEnumeration method.

Friends And Related Function Documentation

◆ ReferenceTarget

friend class ReferenceTarget
friend