C++ API Development

About the C++ API

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.

| For a complete list of available classes and their descriptions, see the C++ API Reference.

Features of the C++ API

These are a few of the C++ API features:

• Automatic Object Memory Management

• Backward Compatibility

• Error Handling

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).

Backward Compatibility

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.

| On the Linux platform, C++ API plug-ins compiled with v3.x will not work with version 4.0 until they are recompiled. The API is fully backward compatible, but we cannot provide binary compatibility because of an upgrade to our compiler. No source code changes should be required but the plug-in will still need to be recompiled. The newer version of gcc is not binary compatible with older versions. In particular the name mangling of the C++ exported symbols from the sicppsdk library has changed. The new compiler, v3.2, has standard ABI and no further binary compatibility breaks are foreseeable. The compilers for Windows have not been upgraded so no recompilation is required. If you are revisiting your existing plug-ins, consider upgrading to use some of the new version 4.0 features. For example, with a few changes to your source code C++ custom commands can now be self-installing, which will make workgroup deployment much more convenient. However these sorts of source changes are totally optional.

| 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.so
Warnings 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.

Error Handling

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.

| For more information on the CStatus class, see the C++ API Reference.

Autodesk Softimage v7.5