Special Issues with Conversion between Softimage and SI|3D

Some templates contain data that is specific to either SI|3D or Softimage. For example, when you convert a scene from SI|3D to the dotXSI file format, the SI_Material template appears under SI_MaterialLibrary. When you convert a scene from Softimage to the dotXSI file format, the XSI_Material template appears instead.

| SI|3D supports only version 3.0 and earlier of the dotXSI file format.

SI|3D | Softimage | Comments
SI_Angle | (no matching template) | Even though it doesn’t recognize this template, Softimage will throw an error message if the data in this template is not expressed in degrees.
SI_CoordinateSystem | (no matching template) | Softimage ignores this template.
SI_ElementUserData _<userDataTag> | (no matching template) | Softimage ignores this template.
SI_FileInfo | (none) | Softimage and SI|3D both ignore the data in the SI_FileInfo template. It is information about the dotXSI file only.
SI_Fog | (no matching template) | Softimage ignores this template.
(no matching members for pseudo root, stiffness activation, and stiffness data) | SI_IK_Joint | 3D ignores these members of this template. If a dotXSI file contains this data, SI|3D ignores it.
SI_ImageClip | (no matching template) | Softimage ignores this template.
SI_Material | XSI_Material | As of v3.5, this is no longer the default template. Use XSI_Material for Softimage data instead.
SI_PatchSurface | (no matching template) | If a dotXSI file contains this template, Softimage converts the patch to a null object.
SI_SubelementUserDataPolygon_<userDataTag> | (no matching template) | Softimage ignores this template.
SI_SubelementUserDataVertex_<userDataTag> | (no matching template) | Softimage ignores this template.
SI_Texture2D | (matching members for only imageName, mappingType, width, height) | Softimage only imports and exports the first four parameters of this template for native Softimage textures.
SI_TriStrip | (no matching template) | Softimage does not support this template.
SI_TriStripList | (no matching template) | Softimage does not support this template.
SI_UserDataFormat | (no matching template) | Softimage ignores this template.
SI_Visibility | (branch data only) | In Softimage only node information is stored.
(no matching template) | XSI_Action | 3D ignores this template.
(no matching template) | XSI_ActionClip | 3D ignores this template.
(no matching template) | XSI_Extrapolation | 3D ignores this template.
SI_Material | XSI_Material | As of v3.5, this is no longer the default template. Use XSI_Material for Softimage data instead.
(no matching template) | XSI_Mixer | 3D ignores this template.
(no matching template) | XSI_Shader | 3D ignores this template.
(no matching template) | XSI_TimeControl | 3D ignores this template.
(no matching template) | XSI_Track | 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 or SI|3D.

Formatted User Data in Softimage

Softimage supports formatted user and custom effects data. In dotXSI, this user data is stored in the XSI_UserData template.

Custom Parameters in Softimage

You can also add custom parameters to Softimage scene data contained in the dotXSI file—see XSI_CustomPSet.

Fomatted User Data SI|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

• 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 SI|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 SI|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 SI|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 SI|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

Autodesk Softimage v7.5