Getting Started
This chapter provides information on:
Setting Up Your Development Environment in Visual C++
Setting up your development environment to work with the FTK consists of the following steps:
Changes to Project Settings in 3.6.2
The FTK no longer ships with the XSICore.lib and XSICore.dll files. You should remove these from your project settings before compiling with this version of the FTK.
About Compiling in Debug Mode
You can now compile your projects in debug mode by linking to the
%XSIFTK_ROOT%\export\lib\XSIFTKd.lib
and running the XSIFTKd.dll. We recommend that you use this library for troubleshooting your project, but do not distribute the debug version to end users.To make a new project
- Launch Microsoft Visual C++.
- Select File > New and click on the Projects tab.
- Select Win32 Console Application from the list of project types, type name for your project in the Project name text box, and click OK.
The Win32 Console Application window appears.
- Select the An empty project option and click Finish.
The New Project Information window appears.
- Click OK.
The new project workspace appears in the console window. You are now ready to set up the new project.
Changing Your Project Settings
In brief, these are the settings you need to implement:
To change your project settings to work with the FTK
- From the Project menu in Visual C++, choose Settings.
The Project Settings window appears.
- Choose All Configurations from the Settings for drop-down box.
- Click the C/C++ tab and choose Code Generation from the Category drop-down box.
- Choose Multithreaded DLL from the Use run-time library drop-down box.
- Choose Preprocessor from the Category drop-down box.
- Type
__XSI_APPLICATION_, XSI_STATIC_LINK
in the Preprocessor definitions text box.- Type
%XSIFTK_ROOT%\export\h\Ftk
in the Additional include directories text box.- Click the Link tab and choose General from the Category drop-down box.
- Type the name you want to use for the final executable or library file in the Output file name text box, and click OK.
- Add and
%XSIFTK_ROOT%\export\lib\XSIFTK.lib
to the Object/library modules text box.The Project Settings window closes and you can now create a new C++ file.
Compiling on Linux
The FTK includes two sample GNUmakefiles that you can use to create your own. They can be found in the ..\src\ directory.
Here is the XSIDump example’s GNUmakefile. For more information about what the XSIDump example does, see XSIDump: Creating a Standalone Executable to Print XSI Information:
# # Default configuration is optimized unless CFG is set to debug # ifeq "$(CFG)" "debug" DEFINES := -D_DEBUG CXXOPTS := -g else CFG := optimized DEFINES := -DNDEBUG CXXOPTS := -O2 endif # # export LD_LIBRARY_PATH in order to find symbols from linked in -lxsiftk # export LD_LIBRARY_PATH := ../../export/bin OBJDIR := obj/$(CFG) SOURCES := main.cpp OBJECTS := $(patsubst %.cpp,$(OBJDIR)/%.o,$(SOURCES)) INCLUDES := -I../../export/h/FTK DEFINES := $(DEFINES) -DXSI_STATIC_LINK -D__XSI_APPLICATION_ -D_GNU DEPLIBS := -lXSIFtk SYSLIBS := EXAMPLE := ../../export/bin/XSIDump CXXFLAGS = $(CXXOPTS) LDFLAGS = $(LDOPTS) # # Build all targets # all: $(EXAMPLE) # # Clean it and build it # rebuild: clean $(MAKE) $(EXAMPLE): $(OBJECTS) -@if [ ! -d "$(dir $@)" ]; then mkdir -p "$(dir $@)"; fi $(CXX) $(LDFLAGS) -o $@ $^ -L../../export/bin $(DEPLIBS) $(SYSLIBS) $(OBJDIR)/%.o: %.cpp -@if [ ! -d "$(dir $@)" ]; then mkdir -p "$(dir $@)"; fi $(CXX) -c -o $@ $(CXXFLAGS) $(DEFINES) $(INCLUDES) $< # # Clean it # clean: -/bin/rm -rf $(OBJDIR) $(EXAMPLE) .PHONY: clean all rebuildAbout the dotXSI Templates
This section answers questions you might have about how to use the dotXSI format:
What Is a Template?
The dotXSI file is organized into several different sections, according to functionality. For example, in version 3.6 there is a section called SI_Ambience that describes the ambient color in the XSI scene. It consists of three values (mapping to Red, Green, and Blue). Here is an example of the SI_Ambience section in a typical dotXSI file:
Each section in the dotXSI file follows a pattern, or template, so that you can know what to expect when you are trying to interact with the information in any dotXSI file. The specification for these templates are detailed in Template Reference. For example, you can find the following information in the SI_Ambience template:
How Do I Extract Information from the dotXSI File?
You can access the contents of a dotXSI file either by using the IO Layer or the Semantic Layer of the FTK. See Chapter 5: The FTK API for specific information on the tools available.
For more information on how the dotXSI file is constructed, see Chapter 6: Template Reference.
Are All Versions of the dotXSI File Format Supported?
No. FTK v3.6 only supports reading and writing of dotXSI v3.0, 3.5 and 3.6.
![]()
For more information, see Compatibility.
What Programming Environments Are Supported?
Since the dotXSI file format encoding is text-based, anything that can read text can use the text-based dotXSI files. However, the binary compressed encoding is only readable by the FTK. The functionality of the FTK is currently available as a C++ API.
![]()
As a special bonus, one of the Case Studies provides source code for an ActiveX version of a selection of the FTK functions. For more information, see ActiveX Compliance: Manipulating dotXSI Files with VBScript and JScript.
Special Issues with Conversion between XSI and 3D
Some templates contain data that is specific to either SOFTIMAGE|3D or SOFTIMAGE|XSI. For example, when you convert a scene from SOFTIMAGE|3D to the dotXSI file format, the SI_Material template appears under SI_MaterialLibrary. When you convert a scene from SOFTIMAGE|XSI to the dotXSI file format, the XSI_Material template appears instead.
SOFTIMAGE|3D SOFTIMAGE|XSI Comments (no matching template) Even though it doesn’t recognize this template, XSI will throw an error message if the data in this template is not expressed in degrees. (no matching template) XSI ignores this template. (no matching template) XSI ignores this template. (none) XSI and 3D both ignore the data in the SI_FileInfo template. It is information about the dotXSI file only. (no matching template) XSI ignores this template. (no matching members for pseudo root, stiffness activation, and stiffness data) 3D ignores these members of this template. If a dotXSI file contains this data, SOFTIMAGE|3D ignores it. (no matching template) XSI ignores this template. As of v3.5, this is no longer the default template. Use XSI_Material for XSI data instead. (no matching template) If a dotXSI file contains this template, SOFTIMAGE|XSI converts the patch to a null object. (no matching template) XSI ignores this template. (no matching template) XSI ignores this template. (matching members for only imageName, mappingType, width, height) XSI only imports and exports the first four parameters of this template for native XSI textures. (no matching template) XSI does not support this template. (no matching template) XSI does not support this template. (no matching template) XSI ignores this template. (branch data only) In SOFTIMAGE|XSI only node information is stored. (no matching template) 3D ignores this template. (no matching template) 3D ignores this template. (no matching template) 3D ignores this template. As of v3.5, this is no longer the default template. Use XSI_Material for XSI data instead. (no matching template) 3D ignores this template. (no matching template) 3D ignores this template. (no matching template) 3D ignores this template. (no matching template) 3D ignores this template.
Formatted User and Custom Data
The dotXSI file supports formatted user data and custom data. The data is stored differetnly in dotXSI depending on whether you are exporting from SOFTIMAGE|XSI or SOFTIMAGE|3D.
Formatted User Data in SOFTIMAGE|XSI
SOFTIMAGE|XSI supports formatted user and custom effects data. For information on implementing user data on SOFTIMAGE|XSI scene elements, see User Data Support for Components of the Plug-in Integration guide. For information about the XSI user data template, see XSI_UserData.
Custom Parameters in SOFTIMAGE|XSI
You can also add custom parameters to XSI scene data contained in the dotXSI file—see XSI_CustomPSet.
Fomatted User Data SOFTIMAGE|3D
By default, user data is stored as raw bytes in a dotXSI file. To store user data in a readable format, you need to define a User Data for dotXSI (UDX) file. .XSI Export and .XSI Import use UDX files to read and write formatted user data (see the SI_ElementUserData _<userDataTag>, SI_SubelementUserDataPolygon_<userDataTag>, and SI_SubelementUserDataVertex_<userDataTag> tags.
UDX File Format
<User Data Tag> // name of the user data tag <nbDataFields> // number of data fields in the group <dataFieldName> // name of the data field <dataFieldType> // type of the data field
UDX files are stored in the SI_UDX_PATH directory, which typically is %SI_LOCATION%\3D\custom\udx.
Embedding UDX in dotXSI
The SI_UserDataFormat template allows you to embed the user data formatting information in a dotXSI file. Defining the user data format in the dotXSI file allows users to exchange the dotXSI files without also having to give the UDX files.
Example: Model Rendering Properties
Suppose you want to format the user data that represents model rendering properties for a hypothetical display driver. To do this, you would write a UDX file that looks like this:
RENDERING_TAG 4 "Back Culling" BOOLEAN "Front Culling" BOOLEAN "Drawing Method" BYTE "Z-Buffer" BOOLEANThe internal C representation of this user data would look like this:
#define DRAW_POLY 0 #define DRAW_LINE 1 #define DRAW_POINT 2 typedef struct { SAA_Boolean bBackCulling; SAA_Boolean bFrontCulling; unsigned char cDrawingMethod; SAA_Boolean bZBuffer; }And the user data would be attached to the model like this:
//... RenderingProp p; // ... set rendering properties params... char buffer[7]; char *pBufPos = buffer; memcpy( (void*)&pBufPos, (void*)&p.bBackCulling, sizeof(p.bBackCulling) ); pBufPos += sizeof(p.bBackCulling); memcpy( (void*)&pBufPos, (void*)&p.bFrontCulling, sizeof(p.bFrontCulling) ); pBufPos += sizeof(p.bFrontCulling); memcpy( (void*)&pBufPos, (void*)&p.cDrawingMethod, sizeof(p.cDrawingMethod) ); pBufPos += sizeof(p.cDrawingMethod); memcpy( (void*)&pBufPos, (void*)&p.bzBuffer, sizeof(p.bzBuffer) ); pElem->SetUserData( "RENDERING_TAG", buffer, 7 );When XSI Export exports this user data, it generates the following templates given the following data: Back Culling = TRUE, Front Culling = FALSE, Drawing Method =DRAW_POLY, and Z-Buffer = TRUE.
SI_UserDataFormat RENDERING_TAG { 4; "Back Culling","BOOLEAN"; "Front Culling","BOOLEAN"; "Drawing Method","BYTE"; "Z-Buffer","BOOLEAN"; } SI_ElementUserData_RENDERING_TAG { 1, // Formatted 0, // Bigendian 1, // Back Culling 0, // Front Culling 0, // Drawing Method 1 // Z-Buffer }The unformatted user data would look like this:
SI_ElementUserData_RENDERING_TAG { 0, // Raw Byte Dump 0, // Bigendian 7, // User data length = 7 0,1,0,0,0,0,1 }In SOFTIMAGE|3D, Booleans are represented by an unsigned short; this is why the user data length is 7 and not 4.
Example: Vertex Weight Map
Suppose you want to format the user data that represents vertex weight maps for a hypothetical bend operator. To do this, you would write a UDX file that looks like this:
The internal C representation of this user data would look like this:
And the user data would be attached to the vertices like this:
//... WeightMap m; // ... set weight map params... char *buffer = NULL; int nBufferSize = sizeof(m.fBendAmount) + sizeof(m.iNbWeights ) + sizeof( float ) * m.iNbWeights; buffer = (char*)malloc( nBufferSize ); char *pBufPos = buffer; memcpy( (void*)&pBufPos, (void*)&m.fBendAmount, sizeof(m.fBendAmount) ); pBufPos += sizeof(m.fBendAmount); memcpy( (void*)&pBufPos, (void*)&m.iNbWeights, sizeof(m.iNbWeights) ); pBufPos += sizeof(m.iNbWeights); memcpy( (void*)&pBufPos, (void*)m.pWeights, sizeof( float ) * m.iNbWeights ); pVertex1->SetUserData( "RENDERING_TAG", buffer, nBufferSize, FALSE ); pVertex2->SetUserData( "RENDERING_TAG", buffer, nBufferSize, FALSE ); pVertex3->SetUserData( "RENDERING_TAG", buffer, nBufferSize, FALSE ); pVertex4->SetUserData( "RENDERING_TAG", buffer, nBufferSize, FALSE ); pVertex5->SetUserData( "RENDERING_TAG", buffer, nBufferSize, FALSE ); pVertex6->SetUserData( "RENDERING_TAG", buffer, nBufferSize, FALSE ); free( buffer );When XSI Export exports this user data, it generates the following templates given the following data:
// Bend amount = 3.0 // Weights = 0.5, 0.5, 1.0, 1.0, 0.25, 0.25 SI_UserDataFormat BEND_TAG { 2; "Bend Amount", "FLOAT"; "Weights", "ARRAY FLOAT"; } SI_SubElementUserDataVertex_BEND_TAG { 6, // Number of affected subelements 3, // index 1 5, // index 2 9, // index 3 10, // index 4 11, // index 5 12, // index 6 1, // Formatted 0, // Bigendian 3.00000, // Bend Amount 6, // Number of Weight 0.50000, // Weight 1 0.50000, // Weight 2 1.00000, // Weight 3 1.00000, // Weight 4 0.25000, // Weight 5 0.25000, // Weight 6 }The unformatted user data would look like this:
SI_SubElementUserDataVertex_BEND_TAG { 6, // Number of affected subelements 3, // index 1 5, // index 2 9, // index 3 10, // index 4 11, // index 5 12, // index 6 0, // Raw Byte Dump 0, // Bigendian 32, // User data length = 32 64,64,0,0, 0,0,0,6, 63,0,0,0, 63,0,0,0, 63,128,0,0, 63,128,0,0, 62,128,0,0, 62,128,0,0, }Custom Effects in SOFTIMAGE|3D
A persistent custom effect is stored in a template that looks like this:
<effectName> <modelName> { <nbArguments>; <Argument1>; … <ArgumentN>; <nbResults>; <Result1>; … <ResultN>; // effect parameters <paramName>, <paramValue>; // …other effect parameter name/value pairs… <paramName>, <paramValue>; }To export custom-effect data from SOFTIMAGE|3D, you need to write a UDX file for the custom effect, and put it in the directory specified by the SI_UDX_PATH environment variable (typically %SI_LOCATION%/3D/custom/udx).
UDX file format:
<effectName> <nbParameters> "<ParameterName>" <type> ...
Example
This example shows the dotXSI for the Chase effect, which animates one model to chase another model. The SI_Model template for the custom effect icon stores the effect data.
// Custom effect icon SI_Model MDL-chase1 { SI_Transform SRT-chase1 { ... } SI_Mesh MSH-chase1 { SI_Shape SHP-chase1-ORG { ... } SI_TriangleList { ... } } // Custom effect parameters Chase chase1 { 1; "sphere1"; 1; "cube1"; "spdPrp",1.000000; "spdCns",0.000000; } }The UDX file for the Chase effect:
![]()