Icecache File Format
This page contains the description of the file format used for caching in XSI 7.0, version 1.00. The file extension is "icecache".
The data is not linked to any geometry type in particular, the data can be read off a polymesh for example and loaded onto This page contains the description of the file format used for caching in XSI 7.0, version 1.00. The file extension is "icecache".
The data is not linked to any geometry type in particular, the data can be read off a polymesh for example and loaded onto a pointcloud. All data-types are supported, as are single values vs. dynamic arrays.
Cache files are created on a per object and per frame basis. Each file is a zip archive, utilizing the ZLIB library to save and load directly using a zip-stream. You can create / read the files however, by zipping / unzipping the files as a second / first step. It is still recommend to create / read the files using the ZLIB library, located at http://zlib.net/.
The contents of the files are separated in three major blocks:
- file header
- attribute definitions
- data block
See the end of this document for the data type descriptions
Also, note that the Pointlocator type is supported by the ICECACHE file format, but currently is not exposed. Pointlocator data is to be treated as a binary block of data, which can be skipped when reading ICECACHE files with external tools.
| Table of contents |
Cache file contents
file header
| type | bytes | name | description |
|---|---|---|---|
| char | 8 | headerstring | the header string identifying the file ("ICECACHE") |
| ULONG | 4 | versionnumber | version number of the file format (currently 100) |
| ULONG | 4 | objecttype | the type of object (see siICENodeObjectType) |
| ULONG | 4 | pointcount | the number of points / particles |
| ULONG | 4 | edgecount | the number of edges (0 for a non-polygonmesh) |
| ULONG | 4 | polygoncount | the number of polygons (0 for a non-polygonmesh) |
| ULONG | 4 | samplecount | the number of UV samples (0 for a non-polygonmesh) |
| ULONG | 4 | attributecount | the number of attributes stored |
attribute description ( attributecount times )
In this section the attributes part of the ICECACHE file are defined. The order of the attributes has to be alphabetical (by attribute-name). This is due to a current limitation and will be fixed for future version of the file format.
| type | bytes | name | description |
|---|---|---|---|
| ULONG | 4 | namelength | number of character for the attribute name |
| char | namelength (multiple of 4) | name | the name of the attribute
(we store always a multiple of 4 characters for performance reasons) |
| DWORD | 4 | datatype | the base datatype of the attribute (see siICENodeDataType) |
| DWORD | 4 | structure | single value or dynamic array (see siICENodeStructureType) |
| DWORD | 4 | context | the context the attribute is stored in (see siICENodeContextType) |
| DWORD | 4 | objDBId | the Database ID of the object (obsolete) |
| DWORD | 4 | category | the category of the attribute ( see siICEAttributeCategory) |
If we are looking at an attribute of the datatype siICENodeDataLocation (pointlocator), the additional data is also part of the attribute description and can be skipped when reading ICECACHE files with external tools:
| type | bytes | name | description |
|---|---|---|---|
| ULONG | 4 | sizeofblock | the size of the following binary block in bytes |
| BYTE | sizeofblock | binary data block | the binary data persisting the location descriptor information (not exposed) |
attribute data
The attribute data has to be in the same order as the attribute descriptions.
The attribute data is stored as an array of values. The data is stored in chunks of 4000 elements. For each element we store a flag to determine if the chunk is a constant value, or if each element can be of a different value. Plus each value can be a dynamic array of values, depending on the structure type of the attribute. (The only exceptional attribute is the PointPosition. As it is always non-constant, it doesn't store a per-chunk flag, but just one flag prior to the whole PointPosition data chunk.) This means in the case of 8300 non-constant float elements the file contains:
| type | bytes | name | description |
|---|---|---|---|
| DWORD | 4 | isConstant | false (0) in this case |
| datatype | siICENodeDataSizeFloat * 4000 | data | one single value for each element as a chunk of 4000 |
| DWORD | 4 | isConstant | false (0) in this case |
| datatype | siICENodeDataSizeFloat * 4000 | data | one single value for each element as a chunk of 4000 |
| DWORD | 4 | isConstant | false (0) in this case |
| datatype | siICENodeDataSizeFloat * 300 | data | one single value for each element as a chunk of 300 |
There are five major cases how a chunk can be stored in the file
- Constant Single Value
This means that the value is constant for all elements, and it is a single value so we only store one single data.
- Constant Array Value
This means that as the value is constant for all elements, but it is a dynamic array, we store one array.
- Varying Single value
The value is different for all elements, so we store as many values as there are elements.
- Varying Array value
The value is different for all elements, and each one is an array so we store alot of values.
- Pointlocator binary data block
We don't store per element values, but a binary block containing the location information.
This is the contents for each case:
- attribute data ( attributecount times ) single value constant
| type | bytes | name | description |
|---|---|---|---|
| DWORD | 4 | isConstant | true (1) in this case |
| datatype | siICENodeDataSize | data | one single value |
- attribute data ( attributecount times ) array constant
| type | bytes | name | description |
|---|---|---|---|
| DWORD | 4 | isConstant | true (1) in this case |
| ULONG | 4 | arraysize | the number of elements in the array |
| datatype | siICENodeDataSize * arraysize | data | the values in the array |
- attribute data ( attributecount times ) single value varying
(the elementcount is either pointcount, edgecount, polygoncount or samplecount)
| type | bytes | name | description |
|---|---|---|---|
| DWORD | 4 | isConstant | false (0) in this case |
| datatype | siICENodeDataSize * elementcount | data | one single value for each element |
- attribute data ( attributecount times ) array varying
(the elementcount is either pointcount, edgecount, polygoncount or samplecount)
| type | bytes | name | description |
|---|---|---|---|
| DWORD | 4 | isConstant | false (0) in this case |
and then for each array (elementcount times)
| type | bytes | name | description |
|---|---|---|---|
| ULONG | 4 | arraysize | the number of elements in the array |
| datatype | siICENodeDataSize * arraysize | data | the values in the array |
- Pointlocator binary data block
| type | bytes | name | description |
|---|---|---|---|
| ULONG | 4 | sizeofblock | the size of the following binary block in bytes |
| BYTE | sizeofblock | binary data block | the binary data persisting the location descriptor information (not exposed) |
Example file description
This example contains two internal attributes of a pointcloud (pointposition, color) and one user specified one (radius).
(Note that as we are only looking at 14 points, this file is not using chunks of 4000 elements.)
| type | bytes | name | value |
|---|---|---|---|
| char | 8 | headerstring | "ICECACHE" |
| ULONG | 4 | versionnumber | 100 |
| ULONG | 4 | objecttype | 0 |
| ULONG | 4 | pointcount | 14 |
| ULONG | 4 | edgecount | 0 |
| ULONG | 4 | polygoncount | 0 |
| ULONG | 4 | samplecount | 0 |
| ULONG | 4 | attributecount | 3 |
| ULONG | 4 | namelen | 13 |
| char | 16 | name | "pointposition___" |
| DWORD | 4 | datatype | siICENodeDataVector3 (1 << 4) |
| DWORD | 4 | structure | siICENodeStructureSingle (1 << 0) |
| DWORD | 4 | context | siICENodeContextComponent0D (1 << 1) |
| DWORD | 4 | objDBId | 0 |
| DWORD | 4 | category | siICEAttributeCategoryBuiltin (1) |
| ULONG | 4 | namelen | 5 |
| char | 8 | name | "color___" |
| DWORD | 4 | datatype | siICENodeDataSizeColor4 (1 << 9) |
| DWORD | 4 | structure | siICENodeStructureSingle (1 << 0) |
| DWORD | 4 | context | siICENodeContextComponent0D (1 << 1) |
| DWORD | 4 | objDBId | 0 |
| DWORD | 4 | category | siICEAttributeCategoryBuiltin (1) |
| ULONG | 4 | namelen | 6 |
| char | 8 | name | "radius__" |
| DWORD | 4 | datatype | siICENodeDataSizeFloat (1 << 2) |
| DWORD | 4 | structure | siICENodeStructureSingle (1 << 0) |
| DWORD | 4 | context | siICENodeContextComponent0D (1 << 1) |
| DWORD | 4 | objDBId | 0 |
| DWORD | 4 | category | siICEAttributeCategoryCustom (2) |
| DWORD | 4 | isConstant | false (0) |
| float | siICENodeDataSizeVector3 * 14 | data | 14 Vectors containing 3 floats (all pointpositions) |
| DWORD | 4 | isConstant | true (1) |
| float | siICENodeDataSizeColor4 | data | as the color is constant, we only store one color (4 floats) |
| DWORD | 4 | isConstant | false (0) |
| float | siICENodeDataSizeFloat * 14 | data | 14 floats containing all radii |
Data type definitions
see the XSISDK for a description of the siICENodeStructureType, siICENodeDataType, siICENodeContextType and siICEAttributeCategory constants.
C++ type definitions
typedef unsigned long ULONG; typedef unsigned long LONG; typedef unsigned long DWORD;
siICENodeObjectType
| pointcloud | 0 |
| polygonmesh | 1 |
| nurbssurfacemesh | 2 |
| nurbscurvelist | 3 |
siICENodeDataSize
| siICENodeDataSizeBool | 4 | for siICENodeDataBool we just store one bool (encoded in a DWORD) |
| siICENodeDataSizeLong | 4 | for siICENodeDataLong we just store one LONG |
| siICENodeDataSizeFloat | 4 | for siICENodeDataFloat we just store one float |
| siICENodeDataSizeVector2 | 8 | for siICENodeDataVector2 we store 2 floats (x,y) |
| siICENodeDataSizeVector3 | 12 | for siICENodeDataVector3 we store 3 floats (x,y,z) |
| siICENodeDataSizeVector4 | 16 | for siICENodeDataVector3 we store 4 floats (x,y,z,w) |
| siICENodeDataSizeQuaternion | 16 | for siICENodeDataQuaternion we store 4 floats (w,x,y,z) |
| siICENodeDataSizeMatrix33 | 36 | for siICENodeDataMatrix33 we store 9 floats |
| siICENodeDataSizeMatrix44 | 64 | for siICENodeDataMatrix44 we store 16 floats |
| siICENodeDataSizeColor4 | 16 | for siICENodeDataColor4 we store 4 floats (r,g,b,a) |
| siICENodeDataSizeRotation3 | 16 | for siICENodeDataRotation we store 4 floats (w,x,y,z) (equivalent to quaternion) |
a pointcloud. All data-types are supported, as are single values vs. dynamic arrays.
Cache files are created on a per object and per frame basis. Each file is a zip archive, utilizing the ZLIB library to save and load directly using a zip-stream. You can create / read the files however, by zipping / unzipping the files as a second / first step. It is still recommend to create / read the files using the ZLIB library, located at http://zlib.net/.
The contents of the files are separated in three major blocks:
- file header
- attribute definitions
- data block
See the end of this document for the data type descriptions
Also, note that the Pointlocator type is supported by the ICECACHE file format, but currently is not exposed. Pointlocator data is to be treated as a binary block of data, which can be skipped when reading ICECACHE files with external tools.
Cache file contents
file header
| type | bytes | name | description |
|---|---|---|---|
| char | 8 | headerstring | the header string identifying the file ("ICECACHE") |
| ULONGLONG | 8 | versionnumber | version number of the file format (currently 100) |
| ULONGLONG | 8 | objecttype | the type of object (see siICENodeObjectType) |
| ULONGLONG | 8 | pointcount | the number of points / particles |
| ULONGLONG | 8 | edgecount | the number of edges (0 for a non-polygonmesh) |
| ULONGLONG | 8 | polygoncount | the number of polygons (0 for a non-polygonmesh) |
| ULONGLONG | 8 | samplecount | the number of UV samples (0 for a non-polygonmesh) |
| ULONG | 4 | attributecount | the number of attributes stored |
attribute description ( attributecount times )
| type | bytes | name | description |
|---|---|---|---|
| ULONG | 4 | namelength | number of character for the attribute name |
| char | namelength (multiple of 4) | name | the name of the attribute
(we store always a multiple of 4 characters for performance reasons) |
| DWORD | 4 | datatype | the base datatype of the attribute (see siICENodeDataType) |
| DWORD | 4 | structure | single value or dynamic array (see siICENodeStructureType) |
| DWORD | 4 | context | the context the attribute is stored in (see siICENodeContextType) |
| DWORD | 4 | objDBId | the Database ID of the object (obsolete) |
| DWORD | 4 | category | the category of the attribute ( see siICEAttributeCategory) |
If we are looking at an attribute of the datatype siICENodeDataLocation (pointlocator), the additional data is also part of the attribute description and can be skipped when reading ICECACHE files with external tools:
| type | bytes | name | description |
|---|---|---|---|
| ULONGLONG | 8 | sizeofblock | the size of the following binary block in bytes |
| BYTE | sizeofblock | binary data block | the binary data persisting the location descriptor information (not exposed) |
attribute data
The attribute data is stored as an array of values. There are five major cases how this data can be stored in the file
- Constant Single Value
This means that the value is constant for all elements, and it is a single value so we only store one single data.
- Constant Array Value
This means that as the value is constant for all elements, but it is a dynamic array, we store one array.
- Varying Single value
The value is different for all elements, so we store as many values as there are elements.
- Varying Array value
The value is different for all elements, and each one is an array so we store alot of values.
- Pointlocator binary data block
We don't store per element values, but a binary block containing the location information.
This is the contents for each case:
- attribute data ( attributecount times ) single value constant
| type | bytes | name | description |
|---|---|---|---|
| DWORD | 4 | isConstant | true (1) in this case |
| datatype | siICENodeDataSize | data | one single value |
- attribute data ( attributecount times ) array constant
| type | bytes | name | description |
|---|---|---|---|
| DWORD | 4 | isConstant | true (1) in this case |
| ULONGLONG | 8 | arraysize | the number of elements in the array |
| datatype | siICENodeDataSize * arraysize | data | the values in the array |
- attribute data ( attributecount times ) single value varying
(the elementcount is either pointcount, edgecount, polygoncount or samplecount)
| type | bytes | name | description |
|---|---|---|---|
| DWORD | 4 | isConstant | false (0) in this case |
| datatype | siICENodeDataSize * elementcount | data | one single value for each element |
- attribute data ( attributecount times ) array varying
(the elementcount is either pointcount, edgecount, polygoncount or samplecount)
| type | bytes | name | description |
|---|---|---|---|
| DWORD | 4 | isConstant | false (0) in this case |
and then for each array (elementcount times)
| type | bytes | name | description |
|---|---|---|---|
| ULONGLONG | 8 | arraysize | the number of elements in the array |
| datatype | siICENodeDataSize * arraysize | data | the values in the array |
- Pointlocator binary data block
| type | bytes | name | description |
|---|---|---|---|
| ULONGLONG | 8 | sizeofblock | the size of the following binary block in bytes |
| BYTE | sizeofblock | binary data block | the binary data persisting the location descriptor information (not exposed) |
Example file description
This example contains two internal attributes of a pointcloud (pointposition, color) and one user specified one (radius).
| type | bytes | name | value |
|---|---|---|---|
| char | 8 | headerstring | "ICECACHE" |
| ULONGLONG | 8 | versionnumber | 100 |
| ULONGLONG | 8 | objecttype | 0 |
| ULONGLONG | 8 | pointcount | 14 |
| ULONGLONG | 8 | edgecount | 0 |
| ULONGLONG | 8 | polygoncount | 0 |
| ULONGLONG | 8 | samplecount | 0 |
| ULONG | 4 | attributecount | 3 |
| ULONG | 4 | namelen | 13 |
| char | 16 | name | "pointposition___" |
| DWORD | 4 | datatype | siICENodeDataVector3 (1 << 4) |
| DWORD | 4 | structure | siICENodeStructureSingle (1 << 0) |
| DWORD | 4 | context | siICENodeContextComponent0D (1 << 1) |
| DWORD | 4 | objDBId | 0 |
| DWORD | 4 | category | siICEAttributeCategoryBuiltin (1) |
| ULONG | 4 | namelen | 5 |
| char | 8 | name | "color___" |
| DWORD | 4 | datatype | siICENodeDataSizeColor4 (1 << 9) |
| DWORD | 4 | structure | siICENodeStructureSingle (1 << 0) |
| DWORD | 4 | context | siICENodeContextComponent0D (1 << 1) |
| DWORD | 4 | objDBId | 0 |
| DWORD | 4 | category | siICEAttributeCategoryBuiltin (1) |
| ULONG | 4 | namelen | 6 |
| char | 8 | name | "radius__" |
| DWORD | 4 | datatype | siICENodeDataSizeFloat (1 << 2) |
| DWORD | 4 | structure | siICENodeStructureSingle (1 << 0) |
| DWORD | 4 | context | siICENodeContextComponent0D (1 << 1) |
| DWORD | 4 | objDBId | 0 |
| DWORD | 4 | category | siICEAttributeCategoryCustom (2) |
| DWORD | 4 | isConstant | false (0) |
| float | siICENodeDataSizeVector3 * 14 | data | 14 Vectors containing 3 floats (all pointpositions) |
| DWORD | 4 | isConstant | true (1) |
| float | siICENodeDataSizeColor4 | data | as the color is constant, we only store one color (4 floats) |
| DWORD | 4 | isConstant | false (0) |
| float | siICENodeDataSizeFloat * 14 | data | 14 floats containing all radii |
Data type definitions
see the XSISDK for a description of the siICENodeStructureType (http://softimage.wiki.avid.com/sdkdocs/siICENodeStructureType.htm), siICENodeDataType (http://softimage.wiki.avid.com/sdkdocs/siICENodeDataType.htm), siICENodeContextType (http://softimage.wiki.avid.com/sdkdocs/siICENodeContextType.htm) and siICEAttributeCategory (http://softimage.wiki.avid.com/sdkdocs/siICEAttributeCategory.htm) constants.
siICENodeObjectType
| pointcloud | 0 |
| polygonmesh | 1 |
| nurbssurfacemesh | 2 |
| nurbscurvelist | 3 |
siICENodeDataSize
siICENodeDataType (http://softimage.wiki.avid.com/sdkdocs/siICENodeDataType.htm)
| siICENodeDataSizeBool | 4 | for siICENodeDataBool we just store one bool (encoded in a DWORD) |
| siICENodeDataSizeLong | 4 | for siICENodeDataLong we just store one LONG |
| siICENodeDataSizeFloat | 4 | for siICENodeDataFloat we just store one float |
| siICENodeDataSizeVector2 | 8 | for siICENodeDataVector2 we store 2 floats (x,y) |
| siICENodeDataSizeVector3 | 12 | for siICENodeDataVector3 we store 3 floats (x,y,z) |
| siICENodeDataSizeVector4 | 16 | for siICENodeDataVector3 we store 4 floats (x,y,z,w) |
| siICENodeDataSizeQuaternion | 16 | for siICENodeDataQuaternion we store 4 floats (w,x,y,z) |
| siICENodeDataSizeMatrix33 | 36 | for siICENodeDataMatrix33 we store 9 floats |
| siICENodeDataSizeMatrix44 | 64 | for siICENodeDataMatrix44 we store 16 floats |
| siICENodeDataSizeColor4 | 16 | for siICENodeDataColor4 we store 4 floats (r,g,b,a) |
| siICENodeDataSizeRotation3 | 16 | for siICENodeDataRotation we store 4 floats (w,x,y,z) (equivalent to quaternion) |
