<     > 

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 

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

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 Crosswalk v5.0     <     >