For years I’ve been doing this and for years I’ve been meaning to get around to making it slicker but somehow there was never time. So the other day it rained – fit to burst – and I had a day inside with nothing else to do and this is what I ended up with.

Earlier attempts ended up in a puddle on the floor because for some reason the only links I could find to VSS command line building pointed me at VCBuild.exe, which is just a plain old mess. This time, though, I found a link to a list of command line options for devenv.exe – what you run to bring up the VS IDE – at the excelent codeproject.com and these are much more straightforward.

The process is fairly simple:

1. unload the plugin.
2. run a command line build using system()
3. copy over the dll (my build has this built in)
4. reload the plugin.
5. test
6. package

Step 2 involves a little bit of wrastling with .bat command line, um, features but really the code (at the end of this article) is quite simple. Because it’s scripted you can build entire plugin sets and package them in one go. The whole process takes only seconds because it’s self contained and it’s dead easy to stuff in some test code. You can easily slip back to the IDE when you need it and it makes working with a preferred text editor easier if that’s your bag.

There’s also the advantage that the build inherits the paths to libraries from the XSI version you’re working with. No more .bat file wrappers. Neat!

This example code is just a list of functions:

Build( solutionName, PluginName, forceRebuild ); // do the actual build.
GetConfig(); //gets the platform type (32/64)
Package( PluginName ); // package. Output name is hard coded in the example.

I stuff the plugin names in an array so I can build a bunch of them in one.

I also have a custom property I use with a dropdown list of my main projects along with build and package buttons.

And finally, I figure I might, next time it rains, get this working alongside package location. Who knows.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

var sPlugins = new Array( "TinyCurveExtrude", "TinyCap" );
var slnName = sPlugins[0];
var sPluginName = slnName + "Plugin";
 
Build( slnName, sPluginName, false );
Package( sPluginName );
 
// build the solution. doRebuild is a boolean, forces a complete compile and build if true.
//
function Build( slnName, sPluginName, doRebuild ) {
	var oPlugin = Application.Plugins( sPluginName );
	var sPluginFileName = oPlugin.FileName;
 
	if ( !oPlugin ) {
		logmessage( "Can't find plugin to unload: " + sPluginName, siError );
		return;
	}
 
	Logmessage( "Unloading Plugin " + sPluginFileName );	
	Application.UnloadPlugin( sPluginFileName );
 
	var Cmd = BuildCmdRoot( slnName );
	var sConfig = GetConfig();
 
	var sOpt = (doRebuild) ? " /rebuild " : " /build ";
 
	if ( sConfig ) {
		system( Cmd + sOpt + sConfig + " & pause" );
	} else {
		Logmessage( "Build Failed", siError );
	}
 
	LogMessage( "ReLoading Plugin: " + sPluginFileName );
	Application.LoadPlugin( sPluginFileName );
 
} 
// get the platform type, 32 or 64 bit. Release is hard coded
//
function GetConfig() {
	var sPlatform = Application.Platform;
	Logmessage( sPlatform );
 
	if ( sPlatform.match( /win64/i ) ) return "\"Release x64|x64\"";
	if ( sPlatform.match( /win32/i ) ) return "\"Release|Win32\"";
 
	Logmessage( "Unsupported Platform: " + sPlatform, siError );
	return false;
}
 
// build the devenv.ex command line
// NOTE: this is set to work on a 64 bit system. Take out the (x86) and spaces 
// for 32 bit. Cross compile works well enough but you'll need the 64 bit libs
function BuildCmdRoot( sTargetName ) {
	var slnRoot = "c:\\fatty\\DEV\\CPP";
 
	var vcVars = "call \"C:\\Program Files (x86)\\Microsoft Visual Studio 8\\VC\\vcvarsall.bat\" x86";
 
	var slnPath = slnRoot + "\\" + sTargetName + "\\" + sTargetName + ".sln"
	var Cmd = vcVars + " & devenv " + slnPath;
	return Cmd;
}
 
// Package.
// ToDo: rebuild for package location.
//
function Package( sPluginName ) {
	logmessage( "Packaging ... " );
 
	var sOutputPath = "C:/Fatty/Dev/CPP/Release"
 
	var sPlatform = Application.Platform;
 
	var oPlugin = Application.Plugins( sPluginName );
	var sPluginFileName = oPlugin.FileName;
 
	var oAddOn = Application.CreateAddon();
 
	oAddOn.AddItem( siPluginAddonItemType, oPlugin.FileName );
 
	oAddOn.DefaultInstallationPath = siUserAddonPath;
	oAddOn.SubDirectory = sPluginName;
 
	var sPluginFileName = sOutputPath + "/" + sPluginName + "_" + sPlatform + ".xsiaddon"
 
	oAddOn.Save( sPluginFileName );
 
	logmessage( "Packaged to: " + sPluginFileName  );
}

It is considered good practice to sprinkle all C++ code with asserts. But as a very brief overview a typical function might contain the following sorts of asserts:

• Confirm expected inputs (e.g. that an input string or array is not empty)
• Confirm expected situations during the algorithm (e.g. confirm that a local variable is holding a valid value)
• Confirm “post” conditions (e.g. that the algorithm did what is was supposed to)

The following is a bit of a “contrived” example, but it shows these three different types of asserts.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// Duplicate string multiple times
CString DuplicateString( int arg1, CString & arg2 ) 
{
   // confirm rules for the expected inputs
   assert( arg1 > 0 ) ;
   assert( arg2.IsEmpty ) ;
 
  CString retVal = "" ;
  for ( int i = 0 ; i < arg1 ; i++ )
  {
    retVal = retVal  + arg2 ;
 
    // Check for unexpected situation during the algorithm
    assert( !retVal.IsEmpty() ) ;
  }
 
  // Post condition
  assert( retVal.GetLength() == arg1 * arg2.GetLength() ) ;
 
  return retVal ;
}

It is not important to test things that you really really know are going to be valid, but “if in doubt” put an assert.

Asserts are an important maintenance tool, so even if there are no bugs in your code today, you can protect your code from future modifications by adding asserts. For example, your code may crash if the caller passes 0 as an argument. You may know that no caller ever does that. But some “idiot” might add a new call tomorrow that does pass 0. So, if your code includes a built-in check for that condition you might save yourself a lot of debugging and finger pointing.

Asserts and XSI SDK
The XSI C++ SDK is a perfect case for needing asserts. This is because the SDK is designed not to crash. Even if you divide by zero XSI will often catch the error and just mention that your plugin wasn’t well behaved. It is sometimes possible to crash, especially if you corrupt memory, but the overall behavior of the API is to try to keep going, no matter what.

One particular issue with this fail-safe attitude is the fact that if you have a bug you can end up working with an “invalid” object. All the methods will still work but the object won’t really be pointing to a real XSI object. So the methods won’t be doing anything. This can mean that a bug early in a program can lead to head scratching much later when you are trying to figure out why some methods seem to do nothing at all.

As a very basic example consider:

1
2

Parameter p ;
p.PutValue( 4.0 ) ;

This code does nothing at all. The variable p was never initialized to a real XSI object, so setting a value on it has no effect whatsoever.

Here is another example:

1
2
3
4
5
6
7
8
9
10
11

Null AddNullToModelAndGroup( Model & inModel,const CString& inGroupName,const CString& inNullName )
{
	Null newnull ;
	inModel.AddNull( inNullName, newnull ) ;	
 
	Group group = inModel.GetGroups().GetItem( inGroupName ) ;
 
	CStatus st = group.AddMember( newnull ) ;
 
	return newnull ;
}

Now this function is straightforward, but there is a lot that can go wrong. If you call this function but discover in later testing that the Null doesn't actually exist or wasn't added to the group then you will have to scratch your head, do some debugging or add some LogMessage calls to try to find the solution.

However my suggestion is that you should sprinkle assert calls in your code directly as you write it.

Here is the modified function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Null AddNullToModelAndGroup( Model & inModel,	const CString& inGroupName,	const CString& inNullName )
{
    assert( inModel.IsValid() ) ;
    assert( !inGroupName.IsEmpty() ) ;
    assert( !inNullName.IsEmpty() ) ;
 
    Null newnull ;
    inModel.AddNull( inNullName, newnull ) ;	
    assert( newnull.IsValid() ) ;
 
    Group group = inModel.GetGroups().GetItem( inGroupName ) ;
    assert( group.IsValid() ) ;
 
    CStatus st = group.AddMember( newnull ) ;
    assert( st.Succeeded() ) ;
 
    return newnull ;
}

Some example scenarios that these asserts will catch:

• Invalid arguments. This function will tell you right away if the caller passes empty strings or a bogus Model. If these asserts fail then you can immediately blame the calling code, rather than wondering if AddNullToModelAndGroup is wrong.
• Invalid group name. One of the most likely failures would be the case where inGroupName doesn't actually correspond to a real group. If assert( group.IsValid() ) fails we know that the model exists, we know that inGroupName is not empty, and we know that there is not group by that name.
• Failure to create the Null. If the AddNull call fails we'll know about it. Its hard to think of any reason why it would fail, given that the name is not empty, but better safe than sorry.

Here are some other typical asserts you might see in XSI C++ code:

1
2
3
4

assert( x > 0.0 && x < = 5.0 ) ;
assert( mynull.GetName() == L"MyNullName" ) ;
assert( points.GetCount() > 0 )  ;
assert( myref.IsA( siParameterID ) ) ;

Tips

• You may want to create your own assert macro, possible with a shorter name if you don't like typing a lot.
• You may also want to create macros that are shortcuts to testing CBase::IsValid and CStatus::Succeeded as these will be the most common asserts that you write.
• Another useful macro is one to test two floating point values with a "fudge" factor to ignore rounding errors.
• Asserts are not a replacement for error handling. In some cases you may need both the "debug" and the "ship" version of the code to test input arguments, log error messages or tell the XSI user that they did something wrong. Asserts are meant to test things that should "never" happen as a way of catching bugs, while error handling should cover the bad edge scenarios that "might" happen.
• You can add extra context strings to your assert, for example assert( x > 0 && "Value read inside foo is wrong" ) ;. The string will appear as part of the message box.
• If there is code that you believe is never executed, but are afraid to delete it, try putting assert( !"This should never happen. inform so and so immediately") ; inside it. If no one contacts you after testing you can be more confident to delete the code.
• If you are given complex code that you didn't write, and have to make changes to it, first add a lot of asserts that verify the assumptions that you find. Make sure these asserts are valid by testing, then start changing things. The asserts will help confirm that you really understand the code and that it wasn't actually more buggy than you might have thought.

Conclusion

This is just a very brief introduction to the concept of asserts. You can find lots more details in general (non-XSI) coding practice books (for example in "Code Complete" by Steve McConnell). Its a concept that goes beyond and particular language or program, but it is specifically useful for the XSI C++ API.

I can say this because I've been involved with a large C++ API project recently and I can confirm that using asserts was a good practice for fast debugging and quick stabilization of complex code. We added many asserts and used it to get meaningful information from testers and also quick entry into the debugger when testing our work. It's not the complete solution to everything, and we use other debugging tricks, but it should be part of any robust C++ development project.

- – - – - – - – -

If you tend to only use commands in your scripts, then I recommend this method (which only works for commands):

In your editor, find where the settings are for launching external applications via a keyboard shortcut. For Crimson Editor, you can find this in the “Tools->Conf. User Tools” menu.

Enter the command as:

C:\WINDOWS\hh.exe

And the argument as:

mk:@MSITStore:C:\Softimage\XSI_5.0\Doc\XSISDK\xsidevref.chm::/$(CurrWord).htm

Note that you’ll need to set the path to the help file so that it’s correct on your system. Also, if you’re not using Crimson Editor, then you’ll need to change where it says $(CurrWord) to the correct macro for your editor, so that it adds the currently selected word to your command argument.

Now just associate this tool with a shortcut key, e.g. F1, and you should now be able to launch the SDK help with a single key press to get instant reference for your command. As I said above, this only works for commands, since it relies on the naming convention of the compiled help.

- – - – - – - – -

If you want to have general context sensitive help that will work with any method, property, or command in your script, then you need to download KeyHH.exe from www.keyworks.net.

Once you’ve installed it, just use these settings:

Enter the command as:

C:\WINDOWS\keyhh.exe

And the argument as:

-myhelp -#klink "$(CurrWord)" C:\Softimage\XSI_5.0\Doc\XSISDK\xsidevref.chm

As mentioned above, you’ll need to change the path to work for your help file and change the $(CurrWord) macro to suit your editor.

When you launch this command, it will open the help file in Index view using the word selected in the editor. Unfortunately it doesn’t display the help page automatically, and you still need to double click the entry, but it beats the heck out of having to type it!

Most standalone text editors allow for a command line parameter to indicate which line number to position the cursor when opening a new file. By making a quick change to one of XSI’’s scripts, we can communicate this to the external editor. To make this change, follow the steps below.

(By the way, I take no responsibility if something goes wrong and you have to reinstall XSI to get everything working again!)

1. Navigate to C:\Softimage\…\Application\Commands
2. Create a backup copy of “SDKHelpers.js” and call it something like “SDKHelpers.js_backup”.
   Note: it is important to change the file extension to something other than “js” as otherwise it will try to install the same commands twice and you”ll get a conflict.
3. Navigate to line 106. It should be inside the “ShowFileForEdit_Execute” function at the line which says :
   if ( -1 != strExternalEditor.search( /%s/ ) )
4. Replace everything inside that “if” clause, i.e:

       // (Mis)use the XSIUtils.Translate() API
    // to replace a %s token in the string with the file
    // name. This gives us lots of flexibility for supporting
    // different command line options for showing an external editor

       strCmd = XSIUtils.Translate( strExternalEditor, "None", in_file ) ;
    logmessage( "Launching " + strCmd, siVerbose ) ;
    XSIUtils.LaunchProcess( strCmd, false ) ;


   With this:

       strExternalEditor = strExternalEditor.replace(/%s/,in_file);
    if ( strExternalEditor.search( /%l/ ) != -1)
    {
        strExternalEditor = strExternalEditor.replace(/%l/,in_linenum);
    }
    XSIUtils.LaunchProcess(strExternalEditor);


5. Save the file and restart XSI.

You can now use %l (that’’s a lowercase L) in the filename for your external editor to pass the line number at the correct position in the command line options. Note that the original script already allowed for a %s parameter to be passed as a location to insert the filename to edit, and we have retained that functionality.

So for example, for JEdit you would use this in the external editor setting in the Script Editor Preferences:

    c:\jedit\jedit %s +line:%l

Personally, I use Crimson Editor, and my external editor setting is:

    C:\Program Files\Crimson Editor\cedt.exe /L:%l %s

Now if a script throws an error, you can click on it and your external editor will open the file at the correct line. This should make it a lot easier to use your external editor with XSI.

Have a good Christmas break!

My workflow was to write quick run-once scripts in the script editor, use curves and nulls to be sure that everything was ok and then write the scripted operator. But, if scripting is meant to make your life easier, this case makes you change your mind a bit. So I decided to take advantage of both c++ and scripting by wrapping some simple OpenGL drawing functions and exposing them to scripting.

Since the result seems to be quite handy, I decided to make this little utility available on XSIBlog. Lionhead, the company I work for, kindly allowed me to publish it.

So here is the ScriptedSequencer, a small utility to draw vectors and rotation axis on screen.

The tool uses a JScript object to wrap some c++ registered commands, you can use this object from Python and VBScript as well.

First get an instance of the object:

1

var s = NewSequencer();

then call one of the drawing functions:

1
2

var vec = XSIMath.CreateVector3(); 
vec.Set(0, 1, 0); s.DrawVector(vec);

to erase the stack and start again use:

1

s.Flush();

All the drawings are collected by the c++ plug-in and then rendered at the right time using the GraphicSequencer, so you don’t have to care about synchronizing with the viewport’s OpenGL rendering, which means in other words that you can draw OpenGL stuff from wherever you are, run once scripts, scripted operators or compiled plug-ins at any moment.

As it is nothing more than a debugging utility it doesn’t support multiple clients, it means that every time you’ll flush the stack all the drawings drawn by every script will be flushed at once.

By typing NewSequencer().Help() you’ll get a quick help about the sequencer object and its methods.

I hope you’ll find it useful to debug your scripts!

Please note that this utility is not released by Lionhead Ltd., it is not covered by any guarantee and nobody is responsible in any way for any possible troubleshoot.

Download the ScriptedSequencer addon and a sample scene here (XSI 5.X required).

You are more than welcome to report possible bugs or give me suggestions, just drop me a line at andrea@ray-t.net.

When it comes to real-time plug-ins, XSI allows writing custom operators able to react to inputs and produce outputs, but what if the input we need is the mouse?

We haven’t got any mouse operator or event in the SDK yet, in fact all this kind of tools in XSI are emended into the core, but fortunately for us, we still have some tricks by our side to fill this gap and write our own interactive tools.

In the example bellow I’ve done a test, a custom manipulator to “sketch” the pose of a character by tracing quick strokes.

Download the example movie.

The tool is in fact a fully functional and integrated manipulator, it is done by using some windows functions to “steal” the mouse from XSI. Under XSI’s SDK workgroup directory there’s a great example about this topic: UserNormalEditing by Alain Laferriere, thanks for sharing Alain!

Then, to interact with the objects in scene I’ve used a custom display pass plug-in. For any object of interest there is an OpenGL primitive with a reference to the object in scene, OpenGL picking algorithm does the rest of the job by returning what’s under the mouse pointer.

Every time an event is fired from the mouse a refresh-viewport command is executed, at this point from the custom display pass a check occurs to get the currently picked object.

I’m thinking as next step to add the possibility of scripting all this mess ;)

I love this new plugin type!

Andrea