o------------------------------------------------------------------------------o
| |
| cal3d fileformat description |
| |
| Version 0.10.0 |
| (12. january 2005) |
| |
| Copyright (C) 2001, 2002, 2003 Bruno 'Beosil' Heidelberger |
| |
o------------------------------------------------------------------------------o
o------------------------------------------------------------------------------o
| Table of Contents |
o------------------------------------------------------------------------------o
1 What is this document for?
2 cal3d skeleton file (.csf)
3 cal3d animation file (.caf)
4 cal3d mesh file (.cmf)
5 cal3d material file (.crf)
6 cal3d skeleton xml file (.xsf)
7 cal3d animation xml file (.xaf)
8 cal3d mesh xml file (.xmf)
9 cal3d material xml file (.xrf)
10 Website
11 Author
o------------------------------------------------------------------------------o
| 1 What is this document for? |
o------------------------------------------------------------------------------o
This document describes the format of the different files used in the cal3d
character animation library version 0.10.0.
********************************************************************************
********************************************************************************
********************************************************************************
IMPORTANT: As the cal3d library is still in heavy development, the fileformats
described in this document will most likely become obsolete as soon as a new
version of the library is released. Furthermore, the fileformat itself is not
yet big-/little-endian independent and may contain fields that are either
ignored or misinterpreted by the library.
********************************************************************************
********************************************************************************
********************************************************************************
o------------------------------------------------------------------------------o
| 2 cal3d skeleton file (.csf) |
o------------------------------------------------------------------------------o
Stored in this file is the hierarchy of bones that composes the skeleton.
description length type comments
------------------------- ------ -------- -----------------------------------
[header]
magic token 4 const "CSF\0"
file version 4 integer 700
number of bones 4 integer
[first bone]
length of bone name 4 integer
bone name var string
translation x 4 float relative translation to parent bone
translation y 4 float
translation z 4 float
rotation x 4 float relative rotation to parent bone
rotation y 4 float stored as a quaternion
rotation z 4 float
rotation w 4 float
local translation x 4 float translation to bring a vertex from
local translation y 4 float model space into bone space
local translation z 4 float
local rotation x 4 float rotation to bring a vertex from
local rotation y 4 float model space into bone space
local rotation z 4 float
local rotation w 4 float
parent bone id 4 integer index to parent bone
number of children 4 integer
[first child]
child bone id 4 integer index to child bone
[all other children]
...
[all other bones]
...
o------------------------------------------------------------------------------o
| 3 cal3d animation file (.caf) |
o------------------------------------------------------------------------------o
All the keyframes of an animation are stored in this file. They are grouped by
tracks (one track per animated bone) and contain the time, the relative position
and the relative rotation to the parent bone.
description length type comments
------------------------- ------ -------- -----------------------------------
[header]
magic token 4 const "CAF\0"
file version 4 integer 700
duration 4 float length of animation in seconds
number of tracks 4 integer
[first track]
bone id 4 integer index to bone
number of keyframes 4 integer
[first keyframe]
time 4 float time of keyframe in seconds
translation x 4 float relative translation to parent bone
translation y 4 float
translation z 4 float
rotation x 4 float relative rotation to parent bone
rotation y 4 float stored as a quaternion
rotation z 4 float
rotation w 4 float
[all other keyframes]
...
[all other tracks]
...
o------------------------------------------------------------------------------o
| 4 cal3d mesh file (.cmf) |
o------------------------------------------------------------------------------o
This file contains all the mesh data, such as the weighted influences of the
bones on each vertex. The mesh is splitted into submeshes to group faces with
the same material thread.
description length type comments
------------------------- ------ -------- -----------------------------------
[header]
magic token 4 const "CMF\0"
file version 4 integer 700
number of submeshes 4 integer
[first submesh]
material thread id 4 integer
number of vertices 4 integer
number of faces 4 integer
number of lod steps 4 integer number of vertices to collapse
number of springs 4 integer number of springs
number of maps 4 integer
[first vertex]
position x 4 float position in model space
position y 4 float
position z 4 float
normal x 4 float normal in model space
normal y 4 float
normal z 4 float
collapse id 4 integer index to vertex to collapse to
face collapse count 4 integer number of collapsing faces when
this vertex gets collapsed
[first map]
u coordinate 4 float map coordinates
v coordinate 4 float
[all other maps]
...
number of influences 4 integer
[first influence]
bone id 4 integer index to bone
weight 4 float weight of influence (1.0 == 100%)
[all other influences]
...
{physical property (only stored when #springs > 0 !)]
weight 4 float weight of vertex for cloth-/hair-
animation (0.0 == rigid)
[all other vertices]
...
[first spring]
vertex id 1 4 integer index to vertex
vertex id 2 4 integer "
spring coefficient 4 float
idle length 4 float rest length of the spring
[all other springs]
...
[first face]
vertex id 1 4 integer index to vertex
vertex id 2 4 integer "
vertex id 3 4 integer "
[all other faces]
...
[all other submeshes]
...
o------------------------------------------------------------------------------o
| 5 cal3d material file (.crf) |
o------------------------------------------------------------------------------o
Material properties like ambient, diffuse and specular color and the shininess
factor are stored in this file. If the material contains texture maps, the
(file-)names of the textures are stored here too.
description length type comments
------------------------- ------ -------- -----------------------------------
[header]
magic token 4 const "CRF\0"
file version 4 integer 700
ambient color red 1 byte
ambient color green 1 byte
ambient color blue 1 byte
ambient color alpha 1 byte
diffuse color red 1 byte
diffuse color green 1 byte
diffuse color blue 1 byte
diffuse color alpha 1 byte
specular color red 1 byte
specular color green 1 byte
specular color blue 1 byte
specular color alpha 1 byte
shininess 4 float
number of maps 4 integer
[first map]
length of texture name 4 integer
texture name var string most likely a filename
{all other maps]
...
o-----------------------------------------------------------------------------o
| 6 skeleton Xml file (.xsf) |
o-----------------------------------------------------------------------------o
this is the text/Xml file format of cal3d skeleton file,
see cal3d skeleton file (.csf) for more information
<HEADER MAGIC="XFS" VERSION="900"/>
<SKELETON NUMBONES="INT">
<BONE ID="INT" NAME="STRING" NUMCHILD="INT">
<TRANSLATION>FLOAT FLOAT FLOAT</TRANSLATION>
<ROTATION>FLOAT FLOAT FLOAT FLOAT</ROTATION>
<LOCALTRANSLATION>FLOAT FLOAT FLOAT</LOCALTRANSLATION>
<LOCALROTATION>FLOAT FLOAT FLOAT FLOAT</LOCALROTATION>
<PARENTID>INT</PARENTID>
<CHILDID>INT</CHILDID>
... {all other childs}
</BONE>
... {all other bones}
</SKELETON>
o-----------------------------------------------------------------------------o
| 7 cal3d xml animation file (.xaf) |
o-----------------------------------------------------------------------------o
this is the text/Xml file format of cal3d animation file,
see cal3d skeleton file (.csf) for more information
<ANIMATION VERSION="1000" DURATION="FLOAT" NUMTRACKS="INT">
<TRACK BONEID="INT" NUMKEYFRAMES="INT">
<KEYFRAME TIME="FLOAT">
<TRANSLATION>FLOAT FLOAT FLOAT</TRANSLATION>
<ROTATION>FLOAT FLOAT FLOAT FLOAT</ROTATION>
</KEYFRAME>
.... {all other keyframes}
</TRACK>
.... {all other animation}
</ANIMATION>
o-----------------------------------------------------------------------------o
| 8 cal3d xml mesh file (.xmf) |
o-----------------------------------------------------------------------------o
this is the text/Xml file format of cal3d mesh file,
see cal3d mesh file (.cmf) for more information
<MESH VERSION="1000" NUMSUBMESH="INT">
<SUBMESH MATERIAL="INT" NUMVERTICES="INT" NUMFACES="INT" NUMLODSTEPS="INT" NUMSPRINGS="INT" NUMTEXCOORDS="INT">
<VERTEX ID="INT" NUMINFLUENCES="INT">
<POS>FLOAT FLOAT FLOAT</POS>
<NORMFLOAT FLOAT FLOAT</NORM>
[<COLLAPSEID>INT</COLLAPSEID>]
[<COLLAPSECOUNT>INT</COLLAPSECOUNT>]
<TEXCOORD>FLOAT FLOAT</TEXCOORD>
... {all the other texture coordinates}
<INFLUENCE ID="INT">FLOAT FLOAT FLOAT</INFLUENCE>
... {all the other bone influances}
[<PHYSIQUE>FLOAT</PHYSIQUE>]
</VERTEX>
.... {all the other vertices}
<SPRING VERTEXID="INT INT" COEF="FLOAT" LENGTH ="FLOAT"/>
... {all the other springs}
<FACE VERTEXID="INT INT INT"/>
... {all the other faces}
</SUBMESH>
...
</MESH>
o-----------------------------------------------------------------------------o
| 9 cal3d xml material file (.xrf) |
o-----------------------------------------------------------------------------o
this is the text/Xml file format of cal3d material file,
see cal3d material file (.crf) for more information
<MATERIAL VERSION="1000" NUMMAPS="INT">
<AMBIENT>FLOAT FLOAT FLOAT FLOAT</AMBIENT>
<DIFFUSE>FLOAT FLOAT FLOAT FLOAT</DIFFUSE>
<SPECULAR>FLOAT FLOAT FLOAT FLOAT</SPECULAR>
<SHININESS>FLOAT</SHININESS>
<MAP>STRING</MAP>
... {all other maps}
</MATERIAL>
o-----------------------------------------------------------------------------o
| 10 Website |
o-----------------------------------------------------------------------------o
The official website of cal3d can be found at: http://cal3d.sourceforge.net
o-----------------------------------------------------------------------------o
| 11 Author |
o-----------------------------------------------------------------------------o
This document was written by Bruno 'Beosil' Heidelberger.
the Xml format has been added by Laurent Desmecht
o-----------------------------------------------------------------------------o