How is the Softimage Object Model Different from the C++ API?

 
 
 

The C++ API is newer than the Softimage Object Model (OM) and there are still some differences between which objects are available for scripting and which classes the C++ API provides. Furthermore, in some cases where there is a corresponding C++ API class, it may not provide the full coverage yet to match its object model counterpart.

There are also some C++ API classes that have no object model counterpart because of the difference between pure C++ and ActiveX (Automation), such as the CRef class, which manages object memory and provides conversion services. In addition, some C++ API classes have not been (and may never be) implemented in the object model; for example, the GraphicSequencer and the Custom Display Host.

In addition, there is one OM object which is not used by any scripting languages, and is implemented solely for the C# language: PPGEventContext.

This section provides only a basic overview of the main differences between the two APIs. If a C++ API class provides less coverage (members) than its object model counterpart, it is not explicitly covered here. For specific information, see the C++ ReferenceC++ API Reference.

Tip

Most classes that are implemented in both APIs use the same name. For example, the class that represents a basic 3D object in Softimage is called X3DObject or X3DObject in both the object model and the C++ API. If you do not see a class in the table below, it is probably because both APIs use the same name.

The following table presents a brief overview of the differences between the classes available in the C++ API and the object model:

C++ API

Softimage Object Model

Comments

--

Addon

Useful mostly for scripting in Softimage.

--

AlignedAxisConstraint (scripting only)

Represents a AxisAligned constraint (e.g. direction constraint, position constraint).

Note

This interface is not available in the C# language.

Application

XSIApplication

Application

Only Application is provided in the C++ API, which provides some (but not all) of the functionality of these two object model classes.

CBase

--

This class is the base for all API classes in the C++ API; it's an abstract class (that is, it provides access to the API classes but you wouldn't use it directly).

CBitArray

--

Encapsulates an array of binary values represented as booleans (deals with large arrays of boolean values in a compact way).

CBoolArray

CDoubleArray

CLongArray

CStringArray

--

C++ API convenience classes that manage arrays of standard data types.

Note

While the C++ API uses these specialized type arrays, C# (which is another strongly typed language) supports System.Object arrays. Since the native C# Object class is a generic data type (similar to Variant), arrays can actually contain items of different types in C#. JScript, Python, VBScript and PerlScript do not need special array classes because they are loosely typed languages.

CClusterElementArray

CClusterPropertyElementArray

ClusterElementCollection

There is a slight difference between the two APIs: the C++ API implements two separate classes to handle the elements from Cluster and ClusterProperty classes, while the object model implements one to handle both.

CClusterPropertyBuilder

--

Provides services to accelerate the process of creating new cluster properties on a geometry.

CColor

CColorArray

CVertexColor

CVertexColorArray

Color

Represents an RGBA color. The C++ API uses a specific structure to represent the color on Triangle and TriangleVertex classes.

CColor4f

CMatrix3f

CMatrix4f

CQuaternionf

CRotationf

CVector2f

CVector3f

CVector4f

--

Special MATH classes to support ICE data types.

CComAPIHandler

--

Implements a C++ wrapper for calling automation objects (including objects implemented using the Softimage Object Model).

CGeometryAccessor

--

Provides optimized access to the data and cluster property values of a geometry mesh object.

CDataArray

CDataArray2D

CDataArray2D::Accessor

CDataArray2D< bool >::Accessor

CDataArray2DBool

CDataArrayBool

CIndexSet

CIndexSet::Iterator

CICEAttributeDataArray

CICEAttributeDataArray2D

CICEAttributeDataArrayBool

--

Support data access for custom ICENode plug-ins.

CGraphicSequencer

--

Offers several services to enable custom rendering passes in the OpenGL viewport.

--

Channel

Represents a channel for a device driver

--

Cluster_V1

ClusterProperty_V1 (scripting only)

Original version of the Cluster and ClusterProperty objects for scripting (deprecated since v1.5)

Note

These interfaces are not available in the C# language.

CMeshBuilder

CMeshBuilder::CErrorDescriptor

--

Allows you to create polygon meshes from an ordered array of vertex coordinates and polygon connections (polygon to vertices).

CNurbsCurveData

CNurbsCurveDataArray

CNurbsSurfaceData

CNurbsSurfaceDataArray

CTrimCurveData

CTrimCurveDataArray

--

Special C++ API structures to hold NURBS data retrieved with the Get() and GetTrim() methods on the NurbsCurve and NurbsSurface classes. In the object model, these data are handled by output arguments or arrays.

--

CollectionItem

Generic dispatch object for scripting most often used to represent the elements of an XSICollection

--

ConstructionHistory

Represents the operator stack for a Primitive object.

Context

ViewContext

GraphicSequencerContext

Context

The object model uses the same Context object for all plug-in types, whereas the C++ API uses specialized classes.

CRef

(pointers to specific objects)

These don't correspond exactly because the C++ API uses the CRef class to manage object references, while the object model uses explicit pointers to specific objects.

CRefArray

XSICollection (pointers to collection objects)

These are special arrays of CRef objects in the C++ API but explicit pointers to specific collection objects in the object model.

CSelectionChangeNotification

CTimeChangeNotification

CValueChangeNotification

CWindowNotification

CXSIEventSelectionData

CXSIEventTimeData

CXSIEventValueSetData

CXSIWindowChangeData

CXSIEventSelectionImpl

CXSIEventTimeImpl

CXSIEventSetValueImpl

CXSIWindowChangeImpl

--

Holds read-only information an a Custom Data Host event.

CStatus

(VBScript Err object) (JScript Error object) (Python and Perl stderr pipes) (C# System.Exception class)

Encapsulates status data types for error handling purpose. The class also exposes methods to query and set the error code. The error codes use the same values as the standard HRESULT error codes on Windows.

CString

(String as Variant type for scripting and System.String for C#)

Variable-length sequence of wide character strings (for unicode support). When specifying strings in the C++ API, the wide character constant (L"mystring") must be used.

CTime

CTimeArray

--

Utility classes for manipulating time.

CUserDataArray

--

Array of user data values represented with the CUserDataArray::Value structure type

CUV

CUVArray

UV

Represents a UV coordinate. Implemented as a structure in the C++ API.

CValue

ValueField

CValueArray

--

Special classes to provide the convenience of a loosely typed variable inside a strictly typed language like C++.

Note

C# is also strongly typed, but uses the System.Object class to represent a loosely typed variable similar to the ActiveX Variant.

CVector3

CVector3Array

CVector4

CVector4Array

CMatrix3

CMatrix4

CMatrix4

CQuaternion

CRotation

CTransformation

SIVector3

--

--

--

SIMatrix3

SIMatrix4

SIQuaternion

SIRotation

SITransformation

Softimage Math objects.

--

DataRepository

Gives access to information about the internal object database.

--

Device

DeviceCollection

Channel

These objects manage device drivers in Softimage.

Directed

DirectedObject

Base class for Camera and Light objects.

--

Environment

Manages environment variables for Softimage (only available via scripting)

Factory

XSIFactory

Allows you to create objects that are external the scene graph and helper objects.

--

FCurveEditor

Provides the context information of the Softimage FCurve editor allowing you to write custom fcurve editing scripts or plug-ins which react to user's actions in the FCurve Editor.

--

FileBrowser

Provides services to display the Softimage Browser (only available via scripting)

--

FxTree FxOperator

These objects manage the FxTree (a network of FxOperators) and its FxOperators.

--

Geometry_V1

Geometry0D

Geometry1D

Geometry2D

(scripting only)

Original version of objects representing object and subcomponent geometry for scripting (deprecated since v1.5)

Note

These interfaces are not available in the C# language.

HardwareSurface

HardwareShaderContext

CHardwareAttributeArray

GraphicDriver

--

Used for Hardware Rendering (Realtime Shaders)

ImageClip2

ImageClip

The original version of the ImageClip class in the C++ API has been replaced by ImageClip2

--

Linktab

Manages how paths are translated between Unix and NT environments using the linktab.ini file.

MATH

XSIMath

Provides basic 3D mathematics functionality as an intrinsic object in the object model and as a namespace containing the math functions in the C++ API.

ICENodeContext

ICENodeDef

--

Custom ICENode or ICENode plug-in objects.

--

ParamDef

Represents the definition of a parameter and is used in the creation of paramaters.

--

PointCloudGeometry

Represents the geometry of a point cloud (for particle simulations).

--

PPG (scripting only)

Represents an instance of a Property Page in scripting.

Note

This interface is not available in the C# language.

PPGEventContext

PPGEventContext (C# only)

Allows access to event triggers on custom properties.

Note

This interface is not available in scripting.

Project

XSIProject

Project

Only Project is provided in the C++ API, which provides some (but not all) of the functionality of these two object model classes.

RendererContext

RenderImageFragment

RendererArchiveInfo

Support objects for Custom Renderer plug-in.

Rig

--

Base class for CameraRig and LightRig objects.

--

ShaderComment

ShaderCompound

ShaderCompoundParameter

RenderTreeNode

Object Model-only interfaces supporting the Custom Shaders APIs

--

Shape

Represents primitive types for particle rendering.

--

SpotLight (scripting only)

Represents a Spot light object (but does not implement any unique methods or properties).

Note

This interface is not available in the C# language.

TriangleVertex

TrianglePoint

Represents a point on a Triangle object.

UIToolkit

XSIUIToolkit

Provides access to special user-interface utilities such as the FileBrowser and the MsgBox for both APIs. However, the object model also provides access to the ProgressBar utility.

--

UserDataItem

Convenience object for getting at individual components on a UserDataMap in the object model. Handled by UserDataMap.GetItemValue and UserDataMap.PutItemValue in the C++ API.

--

XSIDialog (scripting only)

Accesses a simple modal dialog contained a drop down list of strings. This functionality is also captured by the siControlCombo (drop-down list) control available with the PPGLayout class in both APIs.

Note

This interface is not available in the C# language.

--

XSIFileService (scripting only)

Provides access to the conversion scripting tools, ImportDotXSI and ExportDotXSI.

Note

This interface is not available in the C# language.

XSILightAttributesUD

--

Mental Ray UserData struct for Light settings.

CUtils

XSIUtils

Intrinsic object that provides general utility methods

CRigidBodyAccessor

CRigidConstraintAccessor

--

Provides optimized access to the data and property values of a rigid body dynamics or constraint object.

Note

There is a difference between how flattened contol point arrays order UVs between the object model and the C++ API. For more information, see UV Ordering.

OM Collections vs. C++ API Arrays

For the most part, wherever the object model uses collection objects, the C++ API uses a CRefArray. However, there are some cases where the C++ API uses specialized arrays. The following table indicates where these similarities occur:

Important

These specialized C++ API arrays are returned by various C++ functions, they are not meant to be created and modified in user-defined functions. If you want to add and remove arbitrary items to a collection, you must use a CRefArray instead of one of these specialized arrays. For example, to build a list of parameters use a CRefArray containing references to Parameter objects, not a CParameterRefArray.