XSIUtils.RegisterSPDL
 
 
 

XSIUtils.RegisterSPDL

Introduced

v4.0

Description

Installs a SPDL file in the Registry and optionally generates a new Preset.

WARNING: This is a low-level API and should only be used with caution because it can damage the Softimage installation.

This method associates the SPDL file with a particular "Class ID" (CLSID). Each different object in Softimage has its own Class ID. For example a Phong shader has a different CLSID than a Lambert shader. Each time a CustomProperty is created it is assigned a new, unique CLSID. However if copies of the CustomProperty are made (via cut and paste, or SceneItem.AddProperty with the Preset name) then they will all share the same CLSID. (See siObjectIdentifierType)

Each SPDL file has a reference GUID at the top of the file which tells Softimage what CLSID it is associated with. However, until the SPDL file is registered, Softimage is not aware of the SPDL file. A Custom Property can exist without a SPDL file, in which case it shows a default layout for its parameters. Most other objects must have a SPDL file to work properly, for example Custom Operators and Custom Shaders.

Only a single SPDL file can be associated with each ClassID. Hence calling this method a second time will overwrite the effects of the first call.

It is possible to generate a SPDL file for a CustomProperty using XSIUtils.WriteSPDL.

Calling this function is very similar to calling "xsi -i" with a spdl file name. However, unlike "xsi -i", the SPDL file is not duplicated. When the SPDL file and Preset are installed from an .xsiaddon file the registration is automatic. Similarly the Workgroup feature makes SPDL registration automatic. Hence in normal circumstances it is not necessary to call this method.

This method can also generate a Preset file. It is the preset which allows the object to be instantiated with calls to SceneItem.AddProperty. When a SPDL file is changed it is always recommended that the Preset file also be regenerated. The Preset file is generated in a path relative to the SPDL file location, so it is recommended that the spdl file always be located in the Application/spdl directory of the user, factory, workgroup, user addon or workgroup addon directories. Because it is possible to rename or create new presets there can be multiple presets referring to the same object.

C# Syntax

String XSIUtils.RegisterSPDL( String in_SpdlFileName, Boolean in_bGeneratePreset );

Scripting Syntax

oString = XSIUtils.RegisterSPDL( SpdlFileName, [GeneratePreset] );

Return Value

If the GeneratePreset argument is true then the return value is a String with the full path of the new Preset file.

Parameters

Parameter Type Description
SpdlFileName string Name of the SPDL file. If no path is included then Softimage expects the SPDL file to be in the [User Directory]\Application\spdl directory.
GeneratePreset boolean Whether to generate a Preset based on the SPDL file.

Default Value: false

Examples

JScript Example

// SPDL repair example
//
// This script scans for spdls and re-registers them.
// Normally it should not be necessary to run this
// script because Softimage itself performs a similar scan
// each time it starts.
//
// However it is a good example of using the FileSystemObject
// to recurse through directories and can be repurposed for
// other uses.
var g_oFSO = new ActiveXObject( "Scripting.FileSystemObject" ) ;
var g_oProgressBar = XSIUIToolkit.ProgressBar
var g_slash = "\\" ;
if ( Application.Platform != "Win32" )
{
        g_slash = "/" ;
}
SpdlRepair() ;
function SpdlRepair()
{
        var g_aSpdlList = new Array() ;
        // Use a progress bar in case it takes a long time
        // to scan the workgroup
        g_oProgressBar.maximum = 3
        g_oProgressBar.step = 1
        g_oProgressBar.visible = true
        g_oProgressBar.caption = "Processing SPDLs"
        // Scan workgroup (including workgroup addon location)
        // followed by factory addon, then user.  We don't scan the factory
        // itself because built-in spdls should not be registered with this
        // script.  Order of scanning is important because a local spdl should
        // take priority over remote spdls.
        if ( Application.InstallationPath( siWorkgroupPath ) != "" )
        {
                FindSpdls( Application.InstallationPath( siWorkgroupPath ), g_aSpdlList ) ;
        }
        // Factory addon location
        FindSpdls( Application.InstallationPath( siAddonPath ), g_aSpdlList ) ;
        // Look for local spdls
        FindSpdls( Application.InstallationPath( siUserPath ), g_aSpdlList ) ;
        g_oProgressBar.Increment() ;
        InstallSpdls( g_aSpdlList ) ;
        g_oProgressBar.Increment() ;
        Application.LogMessage( "Complete" ); 
}
// Recursively search for spdl files
function FindSpdls( in_root, io_list )
{
        g_oProgressBar.StatusText = in_root ;
        //Application.LogMessage( "Visiting " + in_root ) ;
        var oFolder = g_oFSO.GetFolder( in_root ) ;
        // Scan for spdl files in the current directory
        var oFiles = new Enumerator( oFolder.Files ) ;          
        for (;!oFiles.atEnd(); oFiles.moveNext())
        {
                var oFile = oFiles.item() ;
                var strFileName = oFile.Name ;
                var aElems = strFileName.split( "." ); 
                if ( aElems.length < 2 )
                        continue ;
                // Check the extension
                if ( aElems[aElems.length-1].toLowerCase() != "spdl" )
                        continue ;
                // Add the spdl to our list                                             
                io_list[ io_list.length ] = oFolder.Path + g_slash + strFileName ;
        }
        // Recurse into sub folders.  There are rules
// about the folders that a spdl can be stored at,
// e.g. \Application\spdl \Addons\Application\spdl
// \Addons\<subdir>\Application\spdl but
// in this case it is easier to do a brute force
// scan.  (This might cause problem if the user
// had manually copied backups of spdl files into 
// unexpected locations)
        var oSubFolders = new Enumerator( oFolder.SubFolders ) ;                
        for (;!oSubFolders.atEnd(); oSubFolders.moveNext())
        {
                var oSubFolder = oSubFolders.item() ;
                FindSpdls( oSubFolder.Path, io_list ) ;
        }               
}
function InstallSpdls( in_SpdlList )
{
        // Add each spdl to the registry
        for ( var i = 0 ; i < in_SpdlList.length ; i++ )
        {
                var bFailed = false; 
                try
                {
                        XSIUtils.RegisterSpdl( in_SpdlList[i], false ) ;                        
                        Application.LogMessage( "Registered " + in_SpdlList[i] ) ;
                }
                catch( e )
                {
                        bFailed = true ;
                }
                if ( bFailed )
                {
                        var bSpdlCheckFailed = false; 
                        try
                        {
                                // call spdl check.  (See the example with XSIUtils.LaunchProcess
                                // for a better way to call spdlcheck.)
                                system( "spdlcheck " + in_SpdlList[i] ) ;               
                        }
                        catch(e)
                        {
                                bSpdlCheckFailed = true ;
                        }
                        if ( bSpdlCheckFailed )
                        {
                                Application.LogMessage( "SPDL parsing error in " + in_SpdlList[i] + 
                                        " use spdlcheck for more info" ) ;
                        }
                        else
                        {                       
                                // This could fail for various reasons 
                                //- Current user doesn't have write access to the registry                      
                                //- missing dll for compiled shader or operator
                                //- dll dependency problem (use depends.exe to track down)
                                Application.LogMessage( "Failed to register " + in_SpdlList[i] ) ;
                        }
                }               
        }               
}

See Also

XSIUtils.UnregisterSPDL XSIUtils.WriteSPDL XSIUtils.Reload DataRepository.GetIdentifier SpdlCheck