Class GUP
See Also: Class Interface, Class DllDir, Class BitmapManager, Class ITreeEnumProc, Class ILoad, Class ISave.
class GUP : public InterfaceServer
Description:
This class is available in release 3.0 and later only.
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 "*.gup" 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
Methods:
public:
Prototype:
GUP();
Remarks:
Constructor.
Prototype:
virtual ~GUP();
Remarks:
Destructor.
Prototype:
virtual HINSTANCE MaxInst();
Remarks:
Implemented by the System.
Returns the application instance handle of 3ds max itself.
Prototype:
virtual HWND MaxWnd();
Remarks:
Implemented by the System.
Returns the window handle of 3ds max's main window.
Prototype:
virtual DllDir* MaxDllDir();
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
Prototype:
virtual Interface* Max();
Remarks:
Implemented by the System.
Returns an interface pointer for calling methods provided by 3ds max.
Prototype:
virtual BitmapManager* Bmi();
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.
Prototype:
virtual int EnumTree(ITreeEnumProc *proc);
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.
Return Value:
Nonzero if the process was aborted by the callback (TREE_ABORT); otherwise 0.
Prototype:
virtual bool ExecuteStringScript(TCHAR *string);
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:
TCHAR *string
Points to the MAXScript command to execute.
Return Value:
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.
Prototype:
virtual bool ExecuteFileScript(TCHAR *file);
Remarks:
Implemented by the System.
This method will execute the specified MAXScript file.
Parameters:
TCHAR *file
The file name for the script file.
Return Value:
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.
Prototype:
virtual DWORD Start()=0;
Remarks:
Implemented by the Plug-In.
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.
Return Value:
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.
Prototype:
virtual void Stop()=0;
Remarks:
Implemented by the Plug-In.
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.
Prototype:
virtual DWORD Control(DWORD parameter);
Remarks:
Implemented by the Plug-In.
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.
Return Value:
The return value meaning is also defined by the plug-in.
Default Implementation:
{ return 0;}
Prototype:
virtual IOResult Save(ISave *isave);
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.
Prototype:
virtual IOResult Load(ILoad *iload);
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.