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
  1. Launch Microsoft Visual C++.
  2. Select File > New and click on the Projects tab.


  3. Select Win32 Console Application from the list of project types, type name for your project in the Project name text box, and click OK.
  4. The Win32 Console Application window appears.



  5. Select the An empty project option and click Finish.
  6. The New Project Information window appears.



  7. Click OK.
  8. 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
  1. From the Project menu in Visual C++, choose Settings.
  2. The Project Settings window appears.

  3. Choose All Configurations from the Settings for drop-down box.


  4. Click the C/C++ tab and choose Code Generation from the Category drop-down box.


  5. Choose Multithreaded DLL from the Use run-time library drop-down box.
  6. Choose Preprocessor from the Category drop-down box.


  7. Type __XSI_APPLICATION_, XSI_STATIC_LINK in the Preprocessor definitions text box.
  8. Type %XSIFTK_ROOT%\export\h\Ftk in the Additional include directories text box.
  9. Click the Link tab and choose General from the Category drop-down box.


  10. Type the name you want to use for the final executable or library file in the Output file name text box, and click OK.
  11. Add and %XSIFTK_ROOT%\export\lib\XSIFTK.lib to the Object/library modules text box.
  12. 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 rebuild 

About 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:

	SI_Ambience {
		0.200000, 
		0.200000, 
		0.200000, 
	} 

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:

	SI_Ambience
	{
		<red>, 
		<green>, 
		<blue>,
	} 

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.

Tip  

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.

Tip  

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.

Note  

SOFTIMAGE|3D does not support any of the version 3.5 or 3.6 dotXSI templates.

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  
 

<dataFieldType>
Description
BOOLEAN
8-bit value. Possible values are 0=FALSE and 1=TRUE.
BYTE
8-bit value
SHORT
16-bit value
INTEGER
32-bit value
float
32-bit IEEE float
STRING
0 terminated string
ARRAY <type>
Specifies an array of one of the above types. For example: ARRAY INTEGER

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"
BOOLEAN 

The 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:

VERTEX_BEND_TAG
2
"Bend Amount"
FLOAT
"Weight"
ARRAY FLOAT 

The internal C representation of this user data would look like this:

typedef struct
{
	float fBendAmount;
	int iNbWeights;
	float *pWeights;
} 

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

<effectName>
Name of the custom effect as it appears in SOFTIMAGE|3D (e.g., "ModelNote", not “ModelNote.v2”). The name is case sensitive.
<nbParameters>
Number of effect parameters. This is the number of symbols declared in the _SYMBOL section of the effect .cus file.
<ParameterName>
Symbol name (case-sensitive) from the _SYMBOL section of the .cus file.
<type>
The type of the effect parameter:
  • BOOLEAN (for effect parameters connected to check boxes and radio buttons)
  • FLOAT (for parameters connected to text boxes)
  • STRING (for parameters connected to text boxes)
  • INTEGER (for parameters connected to text boxes)
Parameters connected to pulldown menus, RGBA color sliders, and list boxes (text views) are not supported.

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:

Chase
2
"spdPrp" FLOAT
"spdCns" FLOAT