v4.0
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.
oString = XSIUtils.RegisterSPDL( SpdlFileName, [GeneratePreset] ); |
If the GeneratePreset argument is true then the return value is a String with the full path of the new Preset file.
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 |
// 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] ) ; } } } } |