GUP Class Reference

#include <gup.h>

Class Description

See also

Class Interface, Class DllDir, Class BitmapManager, Class ITreeEnumProc, Class ILoad, Class ISave.

Description:

This is the base class for the creation of Global Utility Plug-Ins.

These plug-ins work as follows: At 3ds Max startup time, before 3ds Max begins its message loop and after all its subsystems are initialized, the GUP Manager will scan the plug-in directory and load all plug-ins with the "<b>*.gup</b>" extension. One by one, the GUP Manager will call the plug-in's Start() method. At that point the plug-in would do its initialization and decide if it wants to remain loaded or if it can be discarded. As an option, it is also possible for a GUP plug-in for make 3ds Max fail and abort all together. If a plug-in wishes to remain loaded (after returning a GUPRESULT_KEEP result code from the Start() method described below), it should start a new thread for its code as there is no other call from 3ds Max.

Unlike other 3ds Max plug-ins, GUP's do not provide a user interface. If developers of GUP plug-ins desire to present an interface, they can develop a standard 3ds Max utility plug-in to do so. See Class UtilityObj. There is some sample code using this technique availalble in /MAXSDK/SAMPLES/GUP/COMSRV/MSCOM.CPP. This Utility plug-in (COMSRV.DLU) accesses the COM/DCOM plug-in and allows the user to "register" or "unregister" the COM interface. See the Advanced Topics section COM/DCOM Interface.

Plug-In Information:

Class Defined In GUP.H

Super Class ID GUP_CLASS_ID

Standard File Name Extension GUP

Extra Include File Needed None

Inheritance diagram for GUP:

Public Member Functions
GUPExport	GUP ()
virtual GUPExport	~GUP ()
virtual GUPExport HINSTANCE	MaxInst ()
virtual GUPExport HWND	MaxWnd ()
virtual GUPExport DllDir *	MaxDllDir ()
virtual GUPExport Interface *	Max ()
virtual GUPExport BitmapManager *	Bmi ()
virtual GUPExport int	EnumTree (ITreeEnumProc *proc)
virtual GUPExport bool	ExecuteStringScript (const MCHAR *string)
virtual GUPExport bool	ExecuteFileScript (const MCHAR *file)
virtual GUPExport DWORD	Start ()=0
virtual GUPExport void	Stop ()=0
virtual GUPExport DWORD_PTR	Control (DWORD parameter)
virtual GUPExport IOResult	Save (ISave *isave)
virtual GUPExport IOResult	Load (ILoad *iload)
virtual GUPExport void	DeleteThis ()=0
	Called by the system to delete instances of the plugin class. 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...

Constructor & Destructor Documentation

GUPExport GUP

(

)

Remarks

Constructor.

virtual GUPExport ~GUP ( )

virtual

Remarks

Destructor.

Member Function Documentation

virtual GUPExport HINSTANCE MaxInst ( )

virtual

Remarks

Implemented by the System.

Returns the application instance handle of 3ds Max itself.

virtual GUPExport HWND MaxWnd ( )

virtual

Remarks

Implemented by the System.

Returns the window handle of 3ds Max's main window.

virtual GUPExport DllDir* MaxDllDir ( )

virtual

Remarks

Implemented by the System.

Returns a pointer to an instance of a class which provides access to the DLL Directory. This is a list of every DLL loaded in 3ds Max

virtual GUPExport Interface* Max ( )

virtual

Remarks

Implemented by the System.

Returns an interface pointer for calling methods provided by 3ds Max.

virtual GUPExport BitmapManager* Bmi ( )

virtual

Remarks

Implemented by the System.

Returns a pointer to the bitmap manager which may be used to manage the use of bitmaps within 3ds Max.

virtual GUPExport int EnumTree ( ITreeEnumProc *  proc )

virtual

Remarks

Implemented by the System.

This may be called to enumerate every INode in the scene.

Parameters:

ITreeEnumProc *proc

This callback object is called once for each INode in the scene.

Returns

Nonzero if the process was aborted by the callback (TREE_ABORT); otherwise 0.

virtual GUPExport bool ExecuteStringScript ( const MCHAR *  string )

virtual

Remarks

Implemented by the System.

This method will execute the specified MAXScript command. If a developer needs to ask 3ds Max to do something and this "something" is not implemented within the COM interface, it is possible to send MAXScript commands through this method (and ExecuteFileScript() below). This method will execute whatever string is specified, for instance ExecuteStringScript("open \"MyScene.max"").

Parameters:

MCHAR *string

Points to the MAXScript command to execute.

Returns

TRUE indicates if the command was successfully sent to MAXScript; FALSE if it was not sent. Note that this does not reflect the success of the embedded command.

virtual GUPExport bool ExecuteFileScript ( const MCHAR *  file )

virtual

Remarks

Implemented by the System.

This method will execute the specified MAXScript file.

Parameters:

MCHAR *file

The file name for the script file.

Returns

TRUE indicates if the script was successfully sent to MAXScript; FALSE if it was not sent. Note that this does not reflect the result of the script.

virtual GUPExport DWORD Start ( )

pure virtual

Remarks

This method is called at boot time. At that point the plug-in should do its initialization and decide if it wants to remain loaded or if it can be discarded. As an option, it is also possible for a GUP plug-in for make 3ds Max fail and abort all together. Obviously this should be used with caution and plenty of documentation from the part of the developer of the plug-in. If a plug-in wishes to remain loaded (after returning a GUPRESULT_KEEP result code), it should start a new thread for its code as there is no other call from 3ds Max.

Returns

One of the following values:

GUPRESULT_KEEP

Return this to value to have the plug-in remain loaded.

GUPRESULT_NOKEEP

Return this value to discard.

GUPRESULT_ABORT

Return this value to cause 3ds Max to shut down.

virtual GUPExport void Stop ( )

pure virtual

Remarks

The Stop() method is called when 3ds Max is going down. The GUP Manager will call this methods for all GUP plug-ins that were maintained in memory right before it discards them. This method is called only for plug-ins that returned GUPRESULT_KEEP for the Start() method above.

virtual GUPExport DWORD_PTR Control ( DWORD  parameter )

inlinevirtual

Remarks

This method is an entry point for external access to GUP plug-in. For instance, Utility plug-ins can invoke their GUP plugin counterpart and have direct access to them.

Parameters:

DWORD parameter

The meaning of this parameter is defined by the plug-in.

Returns

The return value meaning is also defined by the plug-in.

Default Implementation:

{ return 0;}

{ UNUSED_PARAM(parameter); return 0;}

virtual GUPExport IOResult Save ( ISave *  isave )

virtual

Remarks

This method is called to save any data the plug-in may have into the 3ds Max file.

Parameters:

ISave *isave

An interface used for saving data.

virtual GUPExport IOResult Load ( ILoad *  iload )

virtual

Remarks

This method is called to load any data the plug-in may have from the 3ds Max file.

Parameters:

ILoad *iload

An interface used for loading data.

virtual GUPExport void DeleteThis ( )

pure virtual

Called by the system to delete instances of the plugin class.