Self-Installing Plug-ins (XSISDK)

Table of contents

Documentation

Be sure to read: Self-Installing Plug-ins (http://softimage.wiki.avid.com/sdkdocs/cus_self.htm)

New Wizard Location

In version 4.X the Custom Property and Custom Command Wizard could be found under the top Application menu.

In version 5.0 these have moved into the Plug-in Manager, and been joined by new wizards including an event wizard, toolbar wizard, empty plug-in wizard and add-on help wizard.

Reloading Self-installed Plug-in DLLs without Restarting XSI

XSI loads a Self-installed plugin dll and usually holds access to it once it has been "invoked". This means that you cannot delete and replace the .dll file if you want to install a newer compilation of the dll.

There are several workflows to avoid this problem:

  • In the plug-in manager unload your particular plugins, replace the dll, and then do an update all.
  • In the plug-in manager unload your particular plugins, replace the dll, and then use the "Load..." button to reload the dll.
  • If you are doing many updates to the same dll then consider creating two custom toolbar buttons - one with a 1 line script to unload the plugin,the other with a 1 line script to load the plugin. (See XSIApplication.LoadPlugin)
  • Right click on the DLL to Disable the "Cached" option, which will mean that XSI never holds the dll except during an actual function invocation. This can have a bad effect on performance. This is not available for plug-ins containing certain types of plugin item types, for example Graphics Sequencers (XSISDK).
  • Use the Visual Studio .Net "Apply Code Changes" feature to do trivial changes to a dll on-the-fly, without having to unload it at all.


Avoiding Absolute paths

To develop a robust plug-in that can be moved between machines or hosted on any workgroup it is necessary to avoid hardcoding absolute paths. Because Self-installed plugins are usually loaded by placing them in certain scanned directories it is usually not necessary to deal with its location as an absolute path. However often a plug-in file will use auxiliary files, for example images, html or other dlls. In this case it is recommended that the path to such auxiliary files be determine in a relative fashion compared to the location of the plug-in itself.

This approach is possible based on the use of the SIObject.OriginPath property, which returns the directory that a plug-in is located in.

For example, imagine a plugin wishes to load some images. The images are always located in a relative directory "..\..\Images".

So if the plugin is in the user directory:

C:\users\myname\Softimage\XSI_5.0\Application\Plugins\myplugin.dll

then the Images are at

C:\users\myname\Softimage\XSI_5.0\Images\

If the plugin is in a workgroup:

 \\MyServer\MyWorkgroup\Addons\myaddon\Application\Plugins\myplugin.dll

then the Images are at

\\MyServer\MyWorkgroup\Images\

And for any plug-in that might be packaged in an Addon the same file structure still applies, underneath an addon subdirectory:

 \\MyServer\MyWorkgroup\Addons\myaddon\Application\Plugins\myplugin.dll

else

 \\MyServer\MyWorkgroup\Addons\myaddon\Images

At the time of the XSILoadPlugin call the following code can determine this path:

// C++ API
XSIPLUGINCALLBACK CStatus XSILoadPlugin( XSI::PluginRegistrar& in_reg )
{
	in_reg.PutName( L"mypluginname" );

        ...Other Registration....

#ifdef unix
	CString slash(L"/") ;
#else
	CString slash(L"\\") ;
#endif

	/* Path of this plugin, e.g. C:\users\myname\Softimage\XSI_5.0\Application\Plugins\ */
	CString strPluginDir = in_reg.GetOriginPath() ;	

	// Build a path to an image directory, e.g.
	// C:\users\myname\Softimage\XSI_5.0\Application\Plugins\..\..\Images
	// which is equivalent to
	// C:\users\myname\Softimage\XSI_5.0\Images
	CString strRelativePath = strPluginDir + L".." + slash + L".." + slash + L"Images" + slash ;

	return XSI::CStatus::OK;	
}

Also, during any callback the same calculation can be performed. During callbacks the PluginRegistrar object is not available, but the Plug-in information can be found in the XSIApplication.Plugins collection (Application::GetPlugins in C++ API).

// C++ API
XSIPLUGINCALLBACK XSI::CStatus sim_bug_Execute( XSI::CRef& in_context )
{	
	Application app;

	// Find the path to this plugin via its name (must be exactly
	// as specified in the in_reg.PutName() call inside XSILoadPlugin)
	Plugin thisPlugin = app.GetPlugins().GetItem( L"mypluginname" ) ;
	CString strPluginDir = thisPlugin.GetOriginPath() ;

#ifdef unix
	CString slash(L"/") ;
#else
	CString slash(L"\\") ;
#endif

	// Build a path to an image directory, e.g.
	// C:\users\myname\Softimage\XSI_5.0\Application\Plugins\..\..\Images
	// which is equivalent to
	// C:\users\myname\Softimage\XSI_5.0\Images
	CString strRelativePath = strPluginDir + L".." + slash + L".." + slash + L"Images" + slash ;
	Application().LogMessage( strRelativePath ) ;

This code works for both Linux and Windows, which is important if you wish to develope cross-platform tools.

Note: In some production environments other approaches may be possible. For example absolute paths may be ok if there is a strict file organization policy. Or an environmental variables or "substitute drives" may be used to reference a network or local location in a safer fashion.

See also "Python Custom Modules (XSISDK)" for an example of how this concept can be extended to custom Python modules.

Mixed 32 and 64bit Workgroups

On 32 bit machines XSI cannot load dlls (or .so) compiled with a 64 bit compiler. And similarly, XSI 64bit cannot load 32bit dlls. If you wish to have a workgroup or to package an .xsiaddon that contains both flavors use the following naming scheme:

foo.32.dll  (or foo.32.so)
foo.64.dll  (or, when 64 bit XSI is available on Linux, foo.64.so)

Both files can exist in the same \Application\Plugins directory, and XSI will not attempt to load the .dll that does not match the current platform. This naming scheme avoids having error messages reported.

This page was last modified 09:45, 9 Dec 2005.
This page has been accessed 13813 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy