The C++ Application Programmer's Interface (API) is a library of C++ classes that gives C++ developers access to the Softimage object model. The library uses, among others, these kinds of classes:
API classes—these classes, the mutator and accessor classes, encapsulate the methods applicable to internal Softimage objects.
Core classes—these provide some general services such as the generic class (CRef) used by the API classes for accessing Softimage internal objects and arrays.
Math classes—these provide access to Softimage math library elements such as vector, matrix, transformation, rotation, and quaternion. Math classes should not be treated as API class objects because they aren't represented with reference objects and they don't need an CRef object at creation time, so you can create them freely.
These are a few of the C++ API features:
Automatic Object Memory Management
The C++ API is designed to automatically take care of object lifetime. Classes that reference objects in the scene (for example, CRef and the API classes) are lightweight and should be created on the stack as shown in the examples in this chapter. The constructor of these objects automatically increments a reference count, and the destructor automatically decrements this count. This is much easier than COM development where object lifetime needs to be explicitly controlled with calls to AddRef() and Release().
Care must be taken to avoid keeping a reference to an object that has been deleted from the scene. For example, if a plug-in maintains a reference object to a sphere in the heap, and that sphere is removed from the scene (or a different scene is opened), then the C++ API reference will be pointing to a zombie object that no longer has any valid existence in the current context of Softimage.
For normal C++ API plug-ins this is not a problem because the classes are created in a temporary fashion on the stack, and objects are only removed during the execution of a plug-in callback if the plug-in deletes the object explicitly (by calling the DeleteObj command).
API classes are wrapper classes with no virtual methods that call internal object methods. Because the polymorphism happens inside the API, these classes act like a basic API function set. This extra layer ensures that backward compatibility is preserved between versions.
If you are having any problems with .so files that will not load in Softimage we recommend that you look for unresolved symbols after running the following:
ldd -r filename.soWarnings about mainwin_init not resolved could be ignored but other errors are a sign that the .so file was compiled with an older version of Softimage. If you attempt to execute a custom command inside Softimage that is implemented in an old .so file, you will see a descriptive error message.
The C++ API uses the CStatus class with error handling. The CStatus class encapsulates status data types (Fail, Invalid Argument, Out of Memory, Access Denied, etc.) and allows you to query, set the error code and print the extended error description.
