o------------------------------------------------------------------------------o | | | cal3d fileformat description | | | | Version @VERSION@ | | | | Copyright (C) 2001, 2002, 2003 Bruno 'Beosil' Heidelberger | | Copyright (C) 2006 Loic Dachary | | | 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 @VERSION@ ******************************************************************************** ******************************************************************************** ******************************************************************************** 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 1200 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 1200 duration 4 float length of animation in seconds number of tracks 4 integer flags 4 integer flags for tracks Bit 0: 1 if compressed tracks #IF NORMAL (NOT COMPRESSED) TRACKS [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] ... #ELSIF COMPRESSED TRACKS [first track] bone id 4 integer index to bone number of keyframes 4 integer minimum x 4 float minimum x value of translations minimum y 4 float minimum y value of translations minimum z 4 float minimum z value of translations scale x 4 float scale value to apply on x translations scale y 4 float scale value to apply on y translations scale z 4 float scale value to apply on z translations [first keyframe] time 2 word quantized time of keyframe in seconds (0 is the start of the animation, 0xFFFF the maximum duration) translation 4 integer 10 bits for translation x, 11 bits for translation y, 11 bits for translation z minimum and scale values of the track have to be used to obtain the real float values rotation 6 3 words compressed quaternion [all other keyframes] ... [all other tracks] ... #ENDIF 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 1200 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 1200 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
FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT INT INT ... {all other childs} ... {all other bones} 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 FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT .... {all other keyframes} .... {all other 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 FLOAT FLOAT FLOAT [INT] [INT] FLOAT FLOAT ... {all the other texture coordinates} FLOAT FLOAT FLOAT ... {all the other bone influances} [FLOAT] .... {all the other vertices} ... {all the other springs} ... {all the other faces} ... 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 FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT STRING ... {all other maps} o-----------------------------------------------------------------------------o | 10 Website | o-----------------------------------------------------------------------------o The official website of cal3d can be found at: http://gna.org/projects/cal3d/ 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