Chapter

The 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 called XSICore.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:

General Errors
SOFTIMAGE|XSI FTK-specific Errors
SI_SUCCESS
SI_ERR_NONE
SI_ERR_STATUS_MSG
SI_ERR_MESSAGE_MSG
SI_ERR_WARNING_MSG
SI_ERR_ERROR_MSG
SI_ERR_MODE_MSG
SI_ERR_INTERNAL
SI_ERR_NOTYETIMPLEMENTED
SI_ERR_NOTSUPPORTED
SI_FILE_NOT_FOUND
SI_NO_AVAILABLE_DRIVER

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 :

SI_Error result = SI_SUCCESS;
 
_SI_CALL(CSIBCUtil::Open("foo"),_SI_TEXT("Opening File Failed")); 

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:

SOFTIMAGE|XSI FTK Types
C types
SI_Bool
unsigned short
SI_Byte
char
SI_Ubyte
unsigned char
SI_Short
short
SI_Ushort
unsigned short
SI_Int
int
SI_Uint
unsigned int
SI_Float
float
SI_Double
double
SI_Long
long
SI_Void
void
SI_Ulong
unsigned long

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:

SI_TinyVariant types
C types
SI_TinyVariant member
SI_VT_BOOL
SI_Bool
boolval
SI_VT_BYTE
SI_Byte
bVal
SI_VT_UBYTE
SI_UByte
ubVal
SI_VT_SHORT
SI_Short
sVal
SI_VT_USHORT
SI_UShort
usVal
SI_VT_INT
SI_Int
nVal
SI_VT_UINT
SI_UInt
unVal
SI_VT_FLOAT
SI_Float
fVal
SI_VT_DOUBLE
SI_Double
dVal
SI_VT_LONG
SI_Long
lVal
SI_VT_ULONG
SI_ULong
ulVal
SI_VT_PBOOL
SI_Bool *
p_boolval
SI_VT_PBYTE
SI_Byte *
p_bVal
SI_VT_PUBYTE
SI_Ubyte *
p_ubVal
SI_VT_PSHORT
SI_Short *
p_sVal
SI_VT_PUSHORT
SI_Ushort *
p_usVal
SI_VT_PINT
SI_Int *
p_nVal
SI_VT_PUINT
SI_Uint *
p_unVal
SI_VT_PFLOAT
SI_Float *
p_fVal
SI_VT_PDOUBLE
SI_Double *
p_dVal
SI_VT_PLONG
SI_Long *
p_lVal
SI_VT_PULONG
SI_Ulong *
p_ulVal
SI_VT_PCHAR
char *
p_cVal
SI_VT_PPCHAR
char **
pp_cVal
SI_VT_PVOID
SI_Void *
p_voidVal

Note  

When dealing with any of the following types, you can also use the numElems member to get the number of elements in the array:

  • SI_VT_PBOOL
  • SI_VT_PBYTE
  • SI_VT_PUBYTE
  • SI_VT_PSHORT
  • SI_VT_PUSHORT
  • SI_VT_PINT
  • SI_VT_PUINT
  • SI_VT_PFLOAT
  • SI_VT_PDOUBLE
  • SI_VT_PLONG
  • SI_VT_PULONG
  • SI_VT_PPCHAR

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:

 _SI_PRINTF("Hello World\n"); 

Use this instead:

 _SI_PRINTF(_SI_TEXT("Hello World\n")); 

These macros wrap string manipulation functions. See any ANSI C documentation for more details:

Macro Name
Description
_SI_STRCMP
Macro for the strcmp function
_SI_STRDUP
Macro for the strdup function
_SI_STRCPY
Macro for the strcpy function
_SI_STRCAT
Macro for the strcat function
_SI_SPRINTF
Macro for the sprintf function
_SI_STRLEN
Macro for the strlen function
_SI_PRINTF
Macro for the printf function
_SI_STRTOK
Macro for the strtok function
_SI_STRSTR
Macro for the strstr function
_SI_STRCHR
Macro for the strchr function
_SI_ATOI
Macro for the atoi function

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.

Macro Name
Description
_SI_RAND
Macro for the rand function
_SI_SQRT
Macro for the sqrt function
_SI_SQRTF
Macro for the sqrtf function
_SI_ASIN
Macro for the asin function
_SI_ASINF
Macro for the asinf function
_SI_ACOS
Macro for the acos function
_SI_ACOSF
Macro for the acosf function
_SI_FLOOR
Macro for the floor function
_SI_FLOORF
Macro for the floorf function
_SI_COS
Macro for the cos function
_SI_COSF
Macro for the cosf function
_SI_SIN
Macro for the sin function
_SI_SINF
Macro for the sinf function
_SI_TAN
Macro for the tan function
_SI_TANF
Macro for the tanf function
_SI_ATANF
Macro for the atanf function
_SI_ATAN
Macro for the atan function

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:

Functions
Descriptions
_SI_FOPEN( name, mode )
Opens a file using a file name and an access mode. The access mode can be either one of _SI_FILE_READ_TEXT (to open a file in text mode) or _SI_FILE_READ_BINARY (to open a file in binary mode). It returns _SI_FILE_NULL if the file cannot be opened. Otherwise, if successful, it returns an _SI_FILE handle.
_SI_FCLOSE(handle)
Closes a file described by the file handle.
_SI_FREAD( buffer, size, count, handle )
Reads from a file. See the fread function in the ANSI C documentation for more details.
_SI_FWRITE( buffer, size, count, handle )
Writes to a file. See the fread function in the ANSI C documentation for more details.
_SI_FPRINTF(handle, string)
Prints the string to a file.
_SI_FSEEK( handle, count, type )
Sets the file at a specific position according to these rules:
  • If type is set to _SI_FILE_SET then count is used as the offset from the beginning of the file.
  • If type is set to _SI_FILE_CUR, then count is used as the offset from the current file position.
  • If type is set to _SI_FILE_END, then count is used as a negative offset from the end of the file.
See the fseek function in the ANSI C documentation for more details.
_SI_FTELL( handle )
Returns the current position in bytes of the file. See the ftell function in the ANSI C documentation for more details.
_SI_FGETC( handle )
Gets the next character in the file. See the getc function in the ANSI C documentation for more details.
_SI_FEOF( handle )
Checks if the end of the file has been reached.
_SI_FERROR( handle )
Checks if there is an error on the file. See the ferror function in the ANSI C documentation for more details.
_SI_FFLUSH( x )
Flushes the buffered content of the file on disk. See the fflush function in the ANSI C documentation for more details.
_SI_UNGETC( character, handle )
Pushes a character back into the file. See the ungetc function in the ANSI C documentation for more details.

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)

CSIBCVector3D* pVec3D;
 
_SI_NEW(pVec3D, CSIBCVector3D());
_SI_DELETE(pVec3D); 

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:

Category
Class Name
CSIBCMatrix4x4
CSIBCQuaternion
CSIBCVector2D
CSIBCVector3D
CSIBCVector4D
CSIBCMatrix33d
CSIBCMatrix44d
CSIBCMatrixMNd
CSIBCQuaterniond
CSIBCRotationd
CSIBCRotMatd
CSIBCTransfod
CSIBCVector2Dd
CSIBCVector3Dd
CSIBCVector4Dd
CSIBCVectorwd
CSIBCXfoMatd
CSIBCColorf
CSIBCColorb
CSIBCString
CSIBCArray
Utilities
CSIBCUtil
CSIBCPixMap
CSIBCPixMapDriver
Networking
SIBCNetworkLayer
CSIBSearchPath
CSIBCNode
CSIBCUserData

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:

Floating point vector and matrix classes
Double floating point vector and matrix classes
CSIBCVector2D
CSIBCVector3D
CSIBCVector4D
CSIBCMatrix4x4
CSIBCQuaternion
CSIBCMatrix33d
CSIBCMatrix44d
CSIBCMatrixMNd
CSIBCQuaterniond
CSIBCRotationd
CSIBCRotMatd
CSIBCTransfod
CSIBCVector2Dd
CSIBCVector3Dd
CSIBCVector4Dd
CSIBCVectorwd
CSIBCXfoMatd

Tip  

For more information on vectors and matrices, see the SOFTIMAGE|XSI FTK Reference Guide.

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

Tip  

For more information on colors, see the SOFTIMAGE|XSI FTK Reference Guide.

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

Tip  

For more information on character strings, see the SOFTIMAGE|XSI FTK Reference Guide.

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.

Tip  

For more information on arrays, see the SOFTIMAGE|XSI FTK Reference Guide.

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:

Functions
Description
CSIBCSearchPath *CSIBCPixMap::GetSearchPath()
Gets the search path for textures
SI_Error CSIBCPixMap::AddDriver( CSIBCPixMapDriver * )
Registers a map driver
SI_Error CSIBCPixMap::Load( CSIBCString &, CSIBCPixMap &, SI_Bool in_ResizeToPowerOfTwo = TRUE )
SI_Error CSIBCPixMap::Load( const SI_Char *, CSIBCPixMap &, SI_Bool in_ResizeToPowerOfTwo = TRUE )
SI_Error CSIBCPixMap::Load( CSIBCString &, void *, SI_Int, CSIBCPixMap & )
SI_Error CSIBCPixMap::Load( const SI_Char *, void *, SI_Int, CSIBCPixMap & )
Loads an image into a pixmap
SI_Error CSIBCPixMap::Cleanup()
Clears the list of registered map drivers

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 under c:\dira, c:\dirb and c:\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:

void ReleaseMethod (void *in_pObjectToDelete); 
 

Note  

If you don’t need a release method for the user data, you can use the CSIBCNode::AttachUserData function with the tag name and the data pointer.

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);
}