Whitepaper
[ Home ] [ Sales ] [ Products ] [ Services ] [ Support ] [ Downloads ]

SoftWish is three things. SoftWish is a scripting language built as a plugin to Softimage and providing full access to Softimage's SAAPHIRE Application Programming Interface (part of Softimage's' Software Development Kit). SoftWish is a collection of utilities and libraries for scripting Softimage. SoftWish is a collection of Tools that are built upon these utilities and libraries.

SoftWish scripting can be used in a number of very different ways:

1) It can be used to implement most persistent effects without building a plugin, and to implement the functionality of channels without writing a channel driver (a persistent effect is one which remains present and active in a scene every frame). To do this one uses the SoftWish Behaviors utilities. These utilities attach scripts to objects. These scripts are then automatically evaluated each frame or whenever the object to which they are attached is modified.

2) It can be used to implement any immediate effect without building a plugin (an immediate effect is one which runs once per invocation). To do this one uses the SoftWish Console, which provides a command-line for Softimage.

3) SoftWish scripts that don’t contain any SAAPHIRE calls run outside of Softimage and can be used for vanilla scripting.

All these forms of SoftWish scripting can communicate and reuse each other's code. Before looking at each of these types of scripting more closely it is important to realize that SoftWish can only access those parts of Softimage that the SAAPHIRE applications programming interface exposes. It can't script what is not exposed. This means that not everything that one can do interactively can be scripted. For example SAAPHIRE does not expose Boolean operations, so you cant take the union or intersection of 2 models using SoftWish.

The Behaviors utilities consist of plugins for attaching code to Softimage objects, and evaluating that code each frame (or whenever the object to which the code is attached is modified). Attached code is a fast and easy way to build persistent effects without building the shareable libraries, .cus files and all the rest.

Attached code can act as expressions with runtime binding of variables. For example, one could constrain an object’s motion to always maintain a minimum distance from all other objects by moving itself and/or moving the other objects. Unlike expressions, behaviors can identify the objects they are to interact with themselves at run time (using names, chapters or any other programmatically distinguishable characteristic). Attached code can read or write files and communicate with other processes or devices. The data read or communicated can be used for any purpose including animating the element to which the code is attached. This is often easier than writing a channel driver. Attached code can use of Tk to build graphical user interface elements. Unlike Softimage dialogs these Tk widgets can be used at any time.

Since Behaviors are a part of a model they are easily portable. Just drop the model into a new scene and it’s behaviors come with it. Behaviors can also build selected function curves. Once attached code has achieved the desired behavior the code can be disabled. The behaviors animation is preserved by the generated fcurves.

The SoftWish Console is an interactive shell running as a Softimage plugin. It provides a full SoftWish interpreter and is our command line for Softimage. It updates the Softimage display after every command so you can see what you have done. If your last command scaled an object you see it change size.

SoftWish has a procedure for every routine in the Softimage SDK and supports all the data types and structures needed to communicate with the Softimage SDK. Any immediate effect you can write using C and the Softimage SDK you can write in Tcl as a SoftWish procedure. If you prefer writing in C or have existing C routines you can use Tcl wrappers to make your C routines into SoftWish procedures. These procedures can be invoked from the SoftWish Console. This gives you the functionality of an immediate effect without your having to build a plugin.

The SoftWish Console is a good development environment as well. You can watch the effect of each line of a script as you develop it, altering it or the values of any variables at any time. You can also go back and forth between Softimage itself and the script under development.

SoftWish provides a number of ways for scripts to choose Softimage elements to operate upon. The SWN library is based upon a filename paradigm. It chooses elements based upon their position in a hierarchy and their names. For example:

SWN_select+ left_hand/finger*

adds all the elements whose names begin with "finger" which are parented to an element named "left_hand" to the selected elements. The find utility uses predicates, which can be user defined, to choose elements. As an example:

find . -type Texture -name water*

uses the type and name predicates to return all the textures in a scene whose names begin with water.

The SoftWish Console benefits tremendously from the extensibility of the SoftWish core language. Tcl is extensible not just in terms of adding commands, but in terms of control structures as well. For example the SWN_do construct is such a control structure extension. It evaluates code once for each element in the current scene, whose names matches a given specification, substituting that name into the code. Using such a construct it takes only a few lines of code to animate thousands of appropriately named objects with expressions. Here is an example, which animates a deck of cards, causing each card to rise a bit more than that the card beneath it as the animation progresses:

Besides being able to create expressions, the SoftWish SW library can use expression syntax to calculate values. For example:

set d [ SW_exprValue "distance($i,$j)" ]

sets a SoftWish variable, d , to the distance between the Softimage elements tagged by i and j. Using the values of expressions saves effort and makes the Console more animator-friendly.

The SoftWish console is not limited to text. Commands entered can create graphical controls using Tk or reuse graphical controls from SoftWish tools.

SoftWish is a very capable shell scripting language. Any command that is not a SoftWish procedure or Tcl command will be tried as a program or shell command in the context of the current shell. This means that SoftWish "includes" your operating systems command line shell, and make it practical to add graphical controls to command-line driven programs. Softimage always has been a very open application, provided one was willing and able to use Unix-style scripting. SoftWish can not only construct such scripts; it can also wrap them with a graphical interface. For example the ImageConverter tool is an example of a SoftWish (Tcl/Tk) GUI wrapper to the imgconv executable supplied with Softimage.

All these types of scripting can work together.

SoftWish supports multiple interpreters within a single executable program; this is how different instances of the same effects are implemented. Since each instance has it's own interpreter there is no conflict between different instances of the same variable. All instances can communicate amongst themselves through global variables or procedures.

Interpreters within different processes on the same machine use the send command to communicate. This command evaluates a command in the context of an interpreter within the specified (different) process. The SoftWish SliderMaker effect uses this mechanism. It spawns a process external to Softimage, which creates a control (sort of a graphical midi-box control). This external process then sends any changes of the controls back to the SliderMaker effect.

Interpreters on different machines can communicate by using the send command from the Tcl-DP package. This send is much the same as the intra-machine send which is built into Tcl 8.0, except that it is IP, not process, based. This functionality could be used to implement a complex graphical control on one machine driving a Softimage session on another, or to have a Softimage model control a networked device, or to have multiple Softimage sessions interact.

All these types of scripting can reuse each other's procedures. And this means that functionality can be easily moved from one type of scripting to another. SoftWish procedures used by Behaviors or sourced from the Console can be given a .cus file to become full-fledged Softimage effects. Immediate effects, which are almost, but not quite, right for a particular purpose can be copied, edited and sourced from the Console or attached to objects as Behaviors.

Moreover SoftWish is platform independent. All SoftWish code runs without ANY changes on all platforms Softimage runs on; "code once, run everywhere".

SoftWish contains other libraries besides the SWN and SW libraries as well as other utilities besides the Behavior, Console, and find utilities mentioned above. In particular SoftWish includes a simple bounding-box based collision detector and a debugger for developing SoftWish based plugins. The debugger can be used to selectively enable a SoftWish command line just before a plugin’s entry points. This allows one to examine and set variables and step through code. Whether or not to debug a given entry point is determined by evaluating user specified SoftWish code. This means that one can break on an entry point only at specific frames or when certain relationships between Softimage elements occur.

SoftWish tools include complete source code. Besides being useful in their own right, they serve as examples of how to script and provide a source of reusable graphical controls. The tools include:

ImageConverter is a GUI wrapper for the various Softimage conversion tools. It is a good example of how to use Tcl/Tk to wrap command line executables and it is a "freebie". Because it is a pure Tcl/Tk application you don't need a license to run it.

Image File Script Editor generates Softimage texture "scripts" from all the files in a given location whose names match a pattern.  The generated texture script can be made to loop and can also be sped up or slowed down. The Image File Script Editor can also edit the sequence of textures, which have been placed on a model.

SliderMaker is a persistent effect. It builds Tk sliders, which control Softimage elements. The Tk sliders run in a process separate from Softimage (and could easily be made to run on a separate machine too). The result is very much like using a MIDI controller with channels. Slidermaker shows how to use an external process to control Softimage elements at any time and with all Softimage functionality available (unlike channels, which restrict what else you can do).  

.

UDEdit is a userdata viewer/editor. Userdata is storage, which can be used for any purpose. Most Softimage elements can have userdata and many plugins make use of it. UDEdit lets you view the elements of your scene, see which elements have userdata, and lets you view or edit that data if you wish to. UDEdit contains a nice tree-structured scene viewer as well as an editor. UDEdit also provides an example of the programmatic use of the SoftWish find utility. .

NotesPlus  is a  version of Udedit, which has been streamlined for use with Softimage's' model notes. Unlike model notes it runs on Irix as well as NT. NotesPlus can be configured to use the editor of your choice

Tcl is an interpreter that performs "on-the-fly" compilation. When a procedure is first used it gets byte compiled, so subsequent calls use the compiled code. Tcl is a full programming language but it's strength is as a "glue" language, connecting together routines and programs written in "systems" programming languages like C and Java, and providing interactive access either by command line, or by a graphical interface (constructed with the Tk extension, probably the best graphical interface builder around).

Tcl is rather like an operating system independent shell into which one may dynamically link ones own routines. As such its emphasis is on control structures, text and file handling, and code construction and evaluation rather then on data structures. Since data structures usually reside within the C or Java code, Tcl has only a limited number of data-types. SoftWish extensions are necessary to deal with the typed data, structures, arrays and function pointers used by the Softimage SDK. Doing simple things in Tcl is simple. The language scales smoothly in sense that you do not incur semantic costs for constructs you aren't using. For example local variables require no declaration at all, so a simple program has no declarations. Global variables do require a declaration (namely that they are global), so programs with multiple procedures may need declarations. Complex programs, which require dynamic scoping, must use a special uplevel construct. Note that in each case you don’t have to use, or even know about a language feature until you use it.

Thus Tcl scales from a language less difficult than Softimage expressions to multiple value function calls and self-modifying code. It is worth noting that Tcl provides an explicit eval function, so procedures can evaluate code they generate. Moreover since variables names are not automatically evaluated Lisp type macros are possible, and SoftWish includes an implementation of backquote, for easy programmatic code generation.

. Tcl is extensible, platform-independent, and extremely malleable. Tcl is also quite small, both as an executable and as a data-structure, and has been designed to work with multiple instances of it.

The basic Tcl data structure is called the interpreter. This is the environment in which code is evaluated. It consists of all variables and their bindings. Unlike most languages environments are explicit. An interpreter and its environment can be created and destroyed and different interpreters can communicate amongst themselves. Interpreters are small. This is nice because we can give each instance of an effect it’s own environment. Each instance can execute the same code and set variables with the same names, but the variables are in different interpreters so there is no conflict. This spares the bother of having to allocate an effect’s state variables outside of the effect and then pass them in, as we must do in C.

Tcl’s parent interpreters can expose functions, and hence variables, to their offspring, using a "slave alias" function (child interpreters are known as slaves). Sibling interpreters can use these functions to communicate amongst each other. Interpreters can also evaluate commands inside other related interpreters using the interp command.

Tk is a window-building, event-handling extension of Tcl. It has menus, buttons, scrollbars, listboxes, lines, boxes, images, arcs, text, lots of widgets, in fact most everything you need. And if by chance there is something you want that it doesn’t have pre-built, well, there are a number of extensions to Tk such as Tix, which is included with SoftWish. Using Tk is remarkably easy. For example, here is a Hello World program:

button .hello -command {puts stdout "Hello, World"}

This single line is the entire program. There is no compiling or linking. When typed into the interpreter this line creates a window containing a single button that prints out "Hello, World" when pushed.

SoftWish is a product of: Video Collage Inc.

Boston, MA 02130

USA

For further information:

http://www.video-collage.com website

softwish@video-collage.com email

888-VCANIM8 toll-free sales line

617-524-7835 voice

617-524-3463 fax

[ SoftWish Docs ]

copyright Video-Collage Inc.