1o------------------------------------------------------------------------------o 2| | 3| cal3d fileformat description | 4| | 5| Version @VERSION@ | 6| | 7| Copyright (C) 2001, 2002, 2003 Bruno 'Beosil' Heidelberger | 8| Copyright (C) 2006 Loic Dachary <loic@gnu.org> | 9| | 10o------------------------------------------------------------------------------o 11 12o------------------------------------------------------------------------------o 13| Table of Contents | 14o------------------------------------------------------------------------------o 15 16 1 What is this document for? 17 2 cal3d skeleton file (.csf) 18 3 cal3d animation file (.caf) 19 4 cal3d mesh file (.cmf) 20 5 cal3d material file (.crf) 21 6 cal3d skeleton xml file (.xsf) 22 7 cal3d animation xml file (.xaf) 23 8 cal3d mesh xml file (.xmf) 24 9 cal3d material xml file (.xrf) 25 10 Website 26 11 Author 27 28 29o------------------------------------------------------------------------------o 30| 1 What is this document for? | 31o------------------------------------------------------------------------------o 32 33This document describes the format of the different files used in the cal3d 34character animation library version @VERSION@ 35 36******************************************************************************** 37******************************************************************************** 38******************************************************************************** 39 40 IMPORTANT: As the cal3d library is still in heavy development, the fileformats 41 described in this document will most likely become obsolete as soon as a new 42 version of the library is released. Furthermore, the fileformat itself is not 43 yet big-/little-endian independent and may contain fields that are either 44 ignored or misinterpreted by the library. 45 46******************************************************************************** 47******************************************************************************** 48******************************************************************************** 49 50 51o------------------------------------------------------------------------------o 52| 2 cal3d skeleton file (.csf) | 53o------------------------------------------------------------------------------o 54 55Stored in this file is the hierarchy of bones that composes the skeleton. 56 57 58description length type comments 59------------------------- ------ -------- ----------------------------------- 60[header] 61 magic token 4 const "CSF\0" 62 file version 4 integer 1200 63 number of bones 4 integer 64 65[first bone] 66 length of bone name 4 integer 67 bone name var string 68 translation x 4 float relative translation to parent bone 69 translation y 4 float 70 translation z 4 float 71 rotation x 4 float relative rotation to parent bone 72 rotation y 4 float stored as a quaternion 73 rotation z 4 float 74 rotation w 4 float 75 local translation x 4 float translation to bring a vertex from 76 local translation y 4 float model space into bone space 77 local translation z 4 float 78 local rotation x 4 float rotation to bring a vertex from 79 local rotation y 4 float model space into bone space 80 local rotation z 4 float 81 local rotation w 4 float 82 parent bone id 4 integer index to parent bone 83 number of children 4 integer 84 85 [first child] 86 child bone id 4 integer index to child bone 87 88 [all other children] 89 ... 90 91[all other bones] 92 ... 93 94 95o------------------------------------------------------------------------------o 96| 3 cal3d animation file (.caf) | 97o------------------------------------------------------------------------------o 98 99All the keyframes of an animation are stored in this file. They are grouped by 100tracks (one track per animated bone) and contain the time, the relative position 101and the relative rotation to the parent bone. 102 103 104description length type comments 105------------------------- ------ -------- ----------------------------------- 106[header] 107 magic token 4 const "CAF\0" 108 file version 4 integer 1200 109 duration 4 float length of animation in seconds 110 number of tracks 4 integer 111 flags 4 integer flags for tracks 112 Bit 0: 1 if compressed tracks 113 114#IF NORMAL (NOT COMPRESSED) TRACKS 115 116 [first track] 117 bone id 4 integer index to bone 118 number of keyframes 4 integer 119 120 [first keyframe] 121 time 4 float time of keyframe in seconds 122 translation x 4 float relative translation to parent bone 123 translation y 4 float 124 translation z 4 float 125 rotation x 4 float relative rotation to parent bone 126 rotation y 4 float stored as a quaternion 127 rotation z 4 float 128 rotation w 4 float 129 130 [all other keyframes] 131 ... 132 133 [all other tracks] 134 ... 135 136#ELSIF COMPRESSED TRACKS 137 138 [first track] 139 bone id 4 integer index to bone 140 number of keyframes 4 integer 141 142 minimum x 4 float minimum x value of translations 143 minimum y 4 float minimum y value of translations 144 minimum z 4 float minimum z value of translations 145 scale x 4 float scale value to apply on x translations 146 scale y 4 float scale value to apply on y translations 147 scale z 4 float scale value to apply on z translations 148 149 [first keyframe] 150 time 2 word quantized time of keyframe in seconds (0 is the start of the animation, 0xFFFF the maximum duration) 151 translation 4 integer 10 bits for translation x, 11 bits for translation y, 11 bits for translation z 152 minimum and scale values of the track have to be used to obtain the real float values 153 rotation 6 3 words compressed quaternion 154 155 [all other keyframes] 156 ... 157 158 [all other tracks] 159 ... 160 161#ENDIF 162 163o------------------------------------------------------------------------------o 164| 4 cal3d mesh file (.cmf) | 165o------------------------------------------------------------------------------o 166 167This file contains all the mesh data, such as the weighted influences of the 168bones on each vertex. The mesh is splitted into submeshes to group faces with 169the same material thread. 170 171 172description length type comments 173------------------------- ------ -------- ----------------------------------- 174[header] 175 magic token 4 const "CMF\0" 176 file version 4 integer 1200 177 number of submeshes 4 integer 178 179[first submesh] 180 material thread id 4 integer 181 number of vertices 4 integer 182 number of faces 4 integer 183 number of lod steps 4 integer number of vertices to collapse 184 number of springs 4 integer number of springs 185 number of maps 4 integer 186 187 [first vertex] 188 position x 4 float position in model space 189 position y 4 float 190 position z 4 float 191 normal x 4 float normal in model space 192 normal y 4 float 193 normal z 4 float 194 collapse id 4 integer index to vertex to collapse to 195 face collapse count 4 integer number of collapsing faces when 196 this vertex gets collapsed 197 198 [first map] 199 u coordinate 4 float map coordinates 200 v coordinate 4 float 201 202 [all other maps] 203 ... 204 205 number of influences 4 integer 206 207 [first influence] 208 bone id 4 integer index to bone 209 weight 4 float weight of influence (1.0 == 100%) 210 211 [all other influences] 212 ... 213 214 {physical property (only stored when #springs > 0 !)] 215 weight 4 float weight of vertex for cloth-/hair- 216 animation (0.0 == rigid) 217 218 [all other vertices] 219 ... 220 221 [first spring] 222 vertex id 1 4 integer index to vertex 223 vertex id 2 4 integer " 224 spring coefficient 4 float 225 idle length 4 float rest length of the spring 226 227 [all other springs] 228 ... 229 230 [first face] 231 vertex id 1 4 integer index to vertex 232 vertex id 2 4 integer " 233 vertex id 3 4 integer " 234 235 [all other faces] 236 ... 237 238[all other submeshes] 239 ... 240 241 242o------------------------------------------------------------------------------o 243| 5 cal3d material file (.crf) | 244o------------------------------------------------------------------------------o 245 246Material properties like ambient, diffuse and specular color and the shininess 247factor are stored in this file. If the material contains texture maps, the 248(file-)names of the textures are stored here too. 249 250 251description length type comments 252------------------------- ------ -------- ----------------------------------- 253[header] 254 magic token 4 const "CRF\0" 255 file version 4 integer 1200 256 ambient color red 1 byte 257 ambient color green 1 byte 258 ambient color blue 1 byte 259 ambient color alpha 1 byte 260 diffuse color red 1 byte 261 diffuse color green 1 byte 262 diffuse color blue 1 byte 263 diffuse color alpha 1 byte 264 specular color red 1 byte 265 specular color green 1 byte 266 specular color blue 1 byte 267 specular color alpha 1 byte 268 shininess 4 float 269 number of maps 4 integer 270 271 [first map] 272 length of texture name 4 integer 273 texture name var string most likely a filename 274 275 {all other maps] 276 ... 277 278o-----------------------------------------------------------------------------o 279| 6 skeleton Xml file (.xsf) | 280o-----------------------------------------------------------------------------o 281 282this is the text/Xml file format of cal3d skeleton file, 283see cal3d skeleton file (.csf) for more information 284 285<HEADER MAGIC="XFS" VERSION="900"/> 286<SKELETON NUMBONES="INT"> 287 <BONE ID="INT" NAME="STRING" NUMCHILD="INT"> 288 <TRANSLATION>FLOAT FLOAT FLOAT</TRANSLATION> 289 <ROTATION>FLOAT FLOAT FLOAT FLOAT</ROTATION> 290 <LOCALTRANSLATION>FLOAT FLOAT FLOAT</LOCALTRANSLATION> 291 <LOCALROTATION>FLOAT FLOAT FLOAT FLOAT</LOCALROTATION> 292 <PARENTID>INT</PARENTID> 293 <CHILDID>INT</CHILDID> 294 ... {all other childs} 295 </BONE> 296 ... {all other bones} 297</SKELETON> 298 299 300o-----------------------------------------------------------------------------o 301| 7 cal3d xml animation file (.xaf) | 302o-----------------------------------------------------------------------------o 303 304this is the text/Xml file format of cal3d animation file, 305see cal3d skeleton file (.csf) for more information 306 307<ANIMATION VERSION="1000" DURATION="FLOAT" NUMTRACKS="INT"> 308 <TRACK BONEID="INT" NUMKEYFRAMES="INT"> 309 <KEYFRAME TIME="FLOAT"> 310 <TRANSLATION>FLOAT FLOAT FLOAT</TRANSLATION> 311 <ROTATION>FLOAT FLOAT FLOAT FLOAT</ROTATION> 312 </KEYFRAME> 313 .... {all other keyframes} 314 </TRACK> 315 .... {all other animation} 316</ANIMATION> 317 318o-----------------------------------------------------------------------------o 319| 8 cal3d xml mesh file (.xmf) | 320o-----------------------------------------------------------------------------o 321 322this is the text/Xml file format of cal3d mesh file, 323see cal3d mesh file (.cmf) for more information 324 325<MESH VERSION="1000" NUMSUBMESH="INT"> 326 <SUBMESH MATERIAL="INT" NUMVERTICES="INT" NUMFACES="INT" NUMLODSTEPS="INT" NUMSPRINGS="INT" NUMTEXCOORDS="INT"> 327 <VERTEX ID="INT" NUMINFLUENCES="INT"> 328 <POS>FLOAT FLOAT FLOAT</POS> 329 <NORMFLOAT FLOAT FLOAT</NORM> 330 [<COLLAPSEID>INT</COLLAPSEID>] 331 [<COLLAPSECOUNT>INT</COLLAPSECOUNT>] 332 <TEXCOORD>FLOAT FLOAT</TEXCOORD> 333 ... {all the other texture coordinates} 334 <INFLUENCE ID="INT">FLOAT FLOAT FLOAT</INFLUENCE> 335 ... {all the other bone influances} 336 [<PHYSIQUE>FLOAT</PHYSIQUE>] 337 </VERTEX> 338 .... {all the other vertices} 339 <SPRING VERTEXID="INT INT" COEF="FLOAT" LENGTH ="FLOAT"/> 340 ... {all the other springs} 341 <FACE VERTEXID="INT INT INT"/> 342 ... {all the other faces} 343 </SUBMESH> 344 ... 345</MESH> 346 347o-----------------------------------------------------------------------------o 348| 9 cal3d xml material file (.xrf) | 349o-----------------------------------------------------------------------------o 350 351this is the text/Xml file format of cal3d material file, 352see cal3d material file (.crf) for more information 353 354<MATERIAL VERSION="1000" NUMMAPS="INT"> 355 <AMBIENT>FLOAT FLOAT FLOAT FLOAT</AMBIENT> 356 <DIFFUSE>FLOAT FLOAT FLOAT FLOAT</DIFFUSE> 357 <SPECULAR>FLOAT FLOAT FLOAT FLOAT</SPECULAR> 358 <SHININESS>FLOAT</SHININESS> 359 <MAP>STRING</MAP> 360 ... {all other maps} 361</MATERIAL> 362 363o-----------------------------------------------------------------------------o 364| 10 Website | 365o-----------------------------------------------------------------------------o 366 367 The official website of cal3d can be found at: http://gna.org/projects/cal3d/ 368 369 370o-----------------------------------------------------------------------------o 371| 11 Author | 372o-----------------------------------------------------------------------------o 373 374 This document was written by Bruno 'Beosil' Heidelberger. 375 the Xml format has been added by Laurent Desmecht 376 377 378o-----------------------------------------------------------------------------o 379 380 381