ChapterThe dotXSI Core API
This chapter describes the fundamental services provided by the Core API. These services include general macros, types and base classes. The header files are located under
h\Core
and the library file is calledXSICore.lib
.The following topics are presented here:
About Error Checking
Error checking types use the same error codes as the SOFTIMAGE|XSI SDK. The error type is called SI_Error and can have the following values:
Use the _SI_CALL macro to validate and handle errors. Using the _SI_CALL macro requires a variable called result of type SI_Error in the current function scope. The _SI_CALL macro also requires a string value indicating debug information in case the function fails.
For example :
Basic Data Types
Several types are available in the SOFTIMAGE|XSI FTK for cross-platform compatibility. It is highly recommended that you use them as much as possible to ensure that the code is portable to other platforms.
This is the mapping of SOFTIMAGE|XSI FTK types:
How Does dotXSI Deal with Variant Types?
The SOFTIMAGE|XSI FTK uses a simplified version of the Windows VARIANT type called SI_TinyVariant.
You can set the variantType member of SI_TinyVariant to the following types:
![]()
When dealing with any of the following types, you can also use the numElems member to get the number of elements in the array:
Macros
The SOFTIMAGE|XSI FTK provides a number of helpful macros which fall under the these categories:
String Manipulation Wrappers
Some macros can facilitate writing cross-platform code using string functions. _SI_TEXT is used to wrap string constants so that it is compatible with both Unicode and ANSI code. For example, rather than use the following code:
Use this instead:
These macros wrap string manipulation functions. See any ANSI C documentation for more details:
Since the XSI Viewer does not have a console to output to, the XSI Viewer redirects the output of the _SI_PRINTF macro to a log file which you can find under the launch directory for the XSI Viewer application. You use your own log file by using the CSIBCUtil::Open and CSIBCutil::Close functions.
Example (String Manipulation)
SI_Error result = SI_SUCCESS; _SI_CALL(CSIBCUtil::Open("foo"),_SI_TEXT("Opening File Failed")); if (result == SI_SUCCESS) { _SI_PRINTF(_SI_TEXT(“Hello World\n”); } _SI_CALL(CSIBCutil::Close(), _SI_TEXT(“Closing file”));Math Function Wrappers
These macros wrap common math functions. See any ANSI C documentation for more details.
File Access (I/O) Wrappers
Since file systems may differ from platform to platform, some macros are also provided to facilitate file access. _SI_FILE is the XSI Viewer file handle. It is used by all file access macros. See any ANSI C documentation for more details.
These are the wrapped file access functions:
Example (File Access)
Here is an example of reading 10 bytes from a file called "foo"
_SI_FILE filePtr; SI_Byte buffer[10]; filePtr = _SI_Open(_SI_TEXT("foo"), _SI_FILE_READ_BINARY); if(filePtr != _SI_FILE_NULL) { _SI_FREAD(buffer,sizeof(SI_Byte), 10, filePtr); _SI_FCLOSE(filePtr); }Memory Allocation
Some macros facilitate memory allocation and error checking. These include:
Example (Memory Allocation)
Exported Functions
You can use the XSIEXPORT macro to export functions. This macro maps to
__desclspec(dllexport)
when the _XSI_PLUGIN_ macro is defined.Base Classes
The SOFTIMAGE|XSI FTK uses platform-independent data structures to represent basic types. They are C++ classes that encapsulate the following types of data:
Vectors and Matrices
The SOFTIMAGE|XSI FTK has base classes that implement 2D, 3D and 4D vectors. It also provides classes that implement 4 x 4 matrices and quaternions. These classes implement the most widely-used operations on vectors and matrices, such as the basic operators (+, -, dot product, cross product). Some useful methods are also implemented for matrices to extract scaling, rotation and translation information from a transformation matrix:
Colors
The SOFTIMAGE|XSI FTK has base classes that implement colors. There are two classes that implement the same thing:
The only difference is that CSIBCColorb represents color components as byte values (0-255) and CSIBCColorf represents color components as float values (0.0 - 1.0).
Character strings
Normal strings are implemented by the CSIBCString class. Several functions and methods are also provided to manipulate these strings (concatenation, duplication, copy etc.).
Collections (Arrays)
Most arrays in the SOFTIMAGE|XSI FTK are implemented using the CSIBCArray class template. This class implements functions that are important for arrays, such as getting the number of components, dynamically allocating the array, resizing, etc.
Images
Pixel maps are images used by textures. Pixel maps have basic image manipulation functions. They are implemented by the CSIBCPixMap class. Several image loaders can also be implemented and plugged in. Image loaders are implemented by subclassing the CSIBCPixMapDriver class. Additionally, search paths can be added to give multiple paths for loading images. Here are some useful loading functions:
Example (Image Classes)
This is an example of adding a new image loader in the host application:
// Load the Image File format drivers #include <CSIILPPMFileDriver.h> #include <CSIILPICFileDriver.h> // Add ppm drivers CSIBCPixMap::AddDriver( CSIILPPMFileDriver::Driver() ); // Add Softimage pic drivers CSIBCPixMap::AddDriver( CSIILPICFileDriver::Driver() ); //Here is an example of how to load an image in a CSIBCPixMap: //Allocate a new map _SI_NEW( pPixMap, CSIBCPixMap() ); //Load it from file CSIBCPixMap::Load( _SI_TEXT("image.ppm"), *pPixMap );
File I/O
You use search paths to locate specific files in various directories. For example, the application can suppose that a file called
foo.txt
can be located underc:\dira
,c:\dirb
andc:\dirc
. The CSIBCSearchPath class provides a way to store the possible paths where the file may be located and then search for that file in those paths.
Objects
CSIBCNode is the base class for most of the classes of the SOFTIMAGE|XSI FTK. The CSIBCNode class has the following properties:
Since a lot of classes need to be aggregated in a collection and also have an identification, they should all inherit from the CSIBCNode class. User data can be attached to CSIBCNode so that it can extend the class.
User data is implemented by the CSIBCUserData class. It comprises a tag name and a pointer to data. When the CSIBCNode is destroyed, its array of user data is also destroyed. However, it is possible to assign a release function so that each user data item is cleaned properly prior to releasing the memory for the CSIBCNode.
The release function must have the following prototype:
Example (Object Classes)
void ReleaseString(void *in_pObjectToDelete) { CSIBCString* pStr = (CSIBCString *) in_pObjectToDelete; delete pStr; } void foo() { CSIBCNode node; CSIBCUserData userData; // initialize the user data tag name userData.Name().SetText(_SI_TEXT(“userdata_tag’)); // initialize the user data’s data pointer userData.SetData((void *) new CSIBCString(_SI_TEXT(“User data content”))); // set the user data’s data release function userData.SetReleaseMethod(ReleaseString); // attach the user data to the CSIBCNode node.UserDataList().Add(&userData); }
![]()