This chapter explains the usage of the Cal3D library step by step. The topics cover creation, modification, animation and rendering of models. Before you can start using the Cal3D library you need to include its cal3d.h header-file into your project: #include "cal3d.h" Make sure that the location of this header-file is included in the search-path of your compiler, so it is actually found while compiling. This file is very well suited to be handled as a precompiled header-file, in case your compiler supports this feature. In addition your project has to be linked to the Cal3D library code to be built properly. This requires a successfully compiled Cal3D library. See for details. As explained in the previous chapter, every model instance is based on a core model, which therefore must be created first. All the shared data, such as animations, meshes and materials, need to be loaded, and a few additional steps are necessary to finish the setup of the material handling. The creation of a core model is done by instantiating a CalCoreModel variable and call its create() function. This function takes one single argument which is a description of the core model, and has no other meaning or functionality otherwise. It is highly recommended to check for errors and act accordingly. Not only at this stage, but for all Cal3D library calls. CalCoreModel myCoreModel; if(!myCoreModel.create("my hero model type")) { // error handling ... } The next step after the creation of the core model is to load the skeleton data. Note that there can only be one skeleton per core model and it has to be loaded before any other type of data. Use the loadCoreSkeleton() function to do so. The single argument is the filename of a Cal3D skeleton file. if(!myCoreModel.loadCoreSkeleton("hero.csf")) { // error handling ... } The animation, mesh and material data can now be loaded in any order. Use the corresponding loadCoreAnimation(), loadCoreMesh() and loadCoreMaterial() function to do so. Each of them needs a filename to a Cal3D data file as argument. A unique identifier is returned which will be used in further Cal3D library calls. int idleAnimationId, walkAnimationId, limpAnimationId, waveAnimationId; idleAnimationId = myCoreModel.loadCoreAnimation("hero_idle.caf"); walkAnimationId = myCoreModel.loadCoreAnimation("hero_walk.caf"); limpAnimationId = myCoreModel.loadCoreAnimation("hero_limp.caf"); waveAnimationId = myCoreModel.loadCoreAnimation("hero_wave.caf"); if((idleAnimationId == -1) || (walkAnimationId == -1) || (limpAnimationId == -1) || (waveAnimationId == -1)) { // error handling ... } int upperBodyMeshId, lowerBodyMeshId, helmetMeshId; upperBodyMeshId = myCoreModel.loadCoreMesh("hero_upperbody.cmf"); lowerBodyMeshId = myCoreModel.loadCoreMesh("hero_lowerbody.cmf"); helmetMeshId = myCoreModel.loadCoreMesh("hero_helmet.cmf"); if((upperBodyMeshId == -1) || (lowerBodyMeshId == -1) || (helmetMeshId == -1)) { // error handling ... } int upperBodyChainmailMaterialId, upperBodyPlatemailMaterialId; int lowerBodyChainmailMaterialId, lowerBodyPlatemailMaterialId; upperBodyChainmailMaterialId = myCoreModel.loadCoreMaterial("hero_upperbody_chainmail.crf"); upperBodyPlatemailMaterialId = myCoreModel.loadCoreMaterial("hero_upperbody_platemail.crf"); lowerBodyChainmailMaterialId = myCoreModel.loadCoreMaterial("hero_lowerbody_chainmail.crf"); lowerBodyPlatemailMaterialId = myCoreModel.loadCoreMaterial("hero_lowerbody_platemail.crf"); if((upperBodyChainmailMaterialId == -1) || (upperBodyPlatemailMaterialId == -1) || (lowerBodyChainmailMaterialId == -1) || (lowerBodyPlatemailMaterialId == -1)) { // error handling ... } Depending on the type of model and the needed functionality, a few additional steps must be executed to make the material handling work properly. Textures are not handled by the Cal3D library itself, because of all the different ways they are needed and managed in the applications. However, there is flexible system in place to support the texture handling as much as possible. In every map of each material there is an identifier stored. This value is written during the exporting process, and is most likely the filename of a texture. The idea is to use this value to load the texture, and reference it afterwards through a user-defined data that can be stored in every core material map at runtime. Useful functions to get all the core materials of the core model are getCoreMaterialCount() and getCoreMaterial(). The number of maps in a core material is returned by the getMapCount() function. Access to the filename of each map is provided through getMapFilename(). User-data, such as an identifier of the loaded texture, can be stored in the core material map with help of the setMapUserData() function. It can later be retrieved by calling getUserMapData(). // load all textures and store their identifier as user-data in the corresponding core material map int materialId; for(materialId = 0; materialId < myCoreModel.getCoreMaterialCount(); materialId++) { // get the current core material CalCoreMaterial *pCoreMaterial; pCoreMaterial = myCoreModel.getCoreMaterial(materialId); // loop through all the maps of the current core material int mapId; for(mapId = 0; mapId < pCoreMaterial->getMapCount(); mapId++) { // get the filename of the map std::string strFilename; strFilename = pCoreMaterial->getMapFilename(mapId); // load the texture from the file Cal::UserData textureId; textureId = (Cal::UserData)myTextureLoadingFunction(strFilename); // store the texture id in the user data of the map pCoreMaterial->setMapUserData(mapId, textureId); } } If you want to use the built-in material management system of the Cal3D library to handle different material sets and threads, you have to initialize it accordingly. This is done by creating all material threads of the core model by calling createCoreMaterialThread() for each of them. Then, the setCoreMaterialId() is used to assign a material to a specific material thread/set pair. // create all the material threads const int UPPER_BODY_MATERIAL_THREAD = 0; const int LOWER_BODY_MATERIAL_THREAD = 1; myCoreModel.createCoreMaterialThread(UPPER_BODY_MATERIAL_THREAD); myCoreModel.createCoreMaterialThread(LOWER_BODY_MATERIAL_THREAD); // assign a material for each material thread/set pair const int CHAINMAIL_MATERIAL_SET = 0; const int PLATEMAIL_MATERIAL_SET = 1; myCoreModel.setCoreMaterialId(UPPER_BODY_MATERIAL_THREAD, CHAINMAIL_MATERIAL_SET, upperChainmailMaterialId); myCoreModel.setCoreMaterialId(UPPER_BODY_MATERIAL_THREAD, PLATEMAIL_MATERIAL_SET, upperPlatemailMaterialId); myCoreModel.setCoreMaterialId(LOWER_BODY_MATERIAL_THREAD, CHAINMAIL_MATERIAL_SET, lowerChainmailMaterialId); myCoreModel.setCoreMaterialId(LOWER_BODY_MATERIAL_THREAD, PLATEMAIL_MATERIAL_SET, lowerPlatemailMaterialId); When a core model is not needed anymore, it must be destroyed by calling the destroy() function. This will free all data and other resources. Make sure that all the model instances are already destroyed before doing so with their core model. myCoreModel.destroy(); After the initialization of a core model, an unlimited number of model instances can be created from it. Each of them has its own state, such as attached meshes, active animations or level-of-detail settings. The creation of a model instance is done by instantiating a CalModel variable and call its create() function. This function takes one single argument which is the core model it should be based on. CalModel myModel; if(!myModel.create(&myCoreModel)) { // error handling ... } There is no mesh attached to a freshly created model instance. This can be done by calling the attachMesh() function. The single argument is the identifier of the mesh, which was returned when the mesh was loaded. It is always possible to attach another mesh or detach an existing mesh. Detachment of an attached mesh can be done with the detachMesh() function. if(!myModel.attachMesh(helmetMeshId)) { // error handling ... } if(!myModel.detachMesh(helmetMeshId)) { // error handling ... } The setLodLevel() function is used to set the level-of-detail of a model instance. The single argument is a floating-point value in the range [0.0, 1.0]. The value is defined as the amount of the faces that are collapsed. A value of 0.0 will collapse as many faces as possible, whereas a value of 1.0 will set the model to full detail. Note that the Cal3D library does prevent face collapsing over a material border. This is done to avoid unattractive artifacts. Therefore, a value of 0.0 does not equal zero faces. It means that all those faces are removed which can be collapsed safely. The setLodLevel() function should only be called when a significant change in the level-of-detail occured, as it is a quite expensive process. A repetitive calling on every frame with the same value will kill the performance. myModel.setLodLevel(0.5f); A proper initialized material setup in the core model makes it possible to easily change the material set of a mesh or the whole model instance. The setMaterialSet() function, either of the CalModel or the CalMesh class, is used for this. The single argument is the new material set to use. myModel.setMaterialSet(CHAINMAIL_MATERIAL_SET); myModel.getMesh(upperBodyMeshId)->setMaterialSet(PLATEMAIL_MATERIAL_SET); There are currently two types of animations implemented in the Cal3D library: Cycles, which are repeating, looping animations. Actions, which are one-time executed animations. Note that all the available animations in a core model can be used as both animation types. There are two function calls that are used to control cycles: blendCycle() and clearCycle() of the CalMixer.helper class. blendCycle() adjusts the weight of a cyclic animation in a given amount of time. This can be used to fade in a new cycle or to modify the weight of an active cycle. The first argument is the animation identifier, which was returned when the animation was loaded. The second argument is the new weight for the cycle. The third and last argument is the delay until the given weight will be reached. This value can be used to seamlessly blend between two different cycles and to avoid abrupt motion changes. clearCycle() fades out an active cycle animation in a given amount of time. The first argument is again an animation identifier. The second argument is the delay until the animation will be at zero weight. myModel.getMixer()->clearCycle(idleAnimationId, 0.3f); myModel.getMixer()->blendCycle(walkAnimationId, 0.8f, 0.3f); myModel.getMixer()->blendCycle(limpAnimationId, 0.2f, 0.3f); The executeAction() function is used to execute an action animation. It takes the animation identifier as a first argument. The second and third arguments are the fade in and fade out delay. Actions are executed once and automatically removed afterwards. myModel.getMixer()->executeAction(waveAnimationId, 0.3f, 0.3f); To obtain a smooth motion of the models, their state needs to be updated regularly. This involves evaluating the new time and blending values for the active animations, and calculating the resulting pose of the skeleton. All this computation is done by calling the update() function. The single argument is a floating-point value holding the elapsed seconds since the last update() call. myModel.update(elapsedSeconds); To avoid graphic-API dependent code, the actual rendering of the models is not done in the Cal3D library itself. But all the necessary functions are available to make your rendering loop as simple as possible. IMPORTANT: The rendering of a model must always be enclosed by a beginRendering() and a endRendering() function call. The basic idea is to render the model by visiting all its meshes and their submeshes. Helpful functions for this are getMeshCount() and getSubmeshCount(). A call to the selectMeshSubmesh() function sets the current mesh/submesh to which all following data queries will refer to. Material properties can be retrieved by calling getAmbientColor(), getDiffuseColor(), getSpecularColor() and getShininess(). The geometric data, such as vertices, normals, texture coordinates and faces, is obtained by calling the appropriate functions and providing a sufficient sized buffer for the data to hold. These functions are getVertices(), getNormals(), getTextureCoordinates() and getFaces(). They all return the actual number of data elements written to the buffer. // get the renderer of the model CalRenderer *pCalRenderer; pCalRenderer = myModel.getRenderer(); // begin the rendering loop if(!pCalRenderer->beginRendering()) { // error handling ... } [ set the global graphic-API states here ] // get the number of meshes int meshCount; meshCount = pCalRenderer->getMeshCount(); // loop through all meshes of the model int meshId; for(meshId = 0; meshId < meshCount; meshId++) { // get the number of submeshes int submeshCount; submeshCount = pCalRenderer->getSubmeshCount(meshId); // loop through all submeshes of the mesh int submeshId; for(submeshId = 0; submeshId < submeshCount; submeshId++) { // select mesh and submesh for further data access if(pCalRenderer->selectMeshSubmesh(meshId, submeshId)) { // get the material colors unsigned char ambientColor[4], diffuseColor[4], specularColor[4]; pCalRenderer->getAmbientColor(&ambientColor[0]); pCalRenderer->getDiffuseColor(&diffuseColor[0]); pCalRenderer->getSpecularColor(&specularColor[0]); // get the material shininess factor float shininess; shininess = pCalRenderer->getShininess(); // get the transformed vertices of the submesh static float meshVertices[30000][3]; int vertexCount; vertexCount = pCalRenderer->getVertices(&meshVertices[0][0]); // get the transformed normals of the submesh static float meshNormals[30000][3]; pCalRenderer->getNormals(&meshNormals[0][0]); // get the texture coordinates of the submesh // (only for the first map as example, others can be accessed in the same way though) static float meshTextureCoordinates[30000][2]; int textureCoordinateCount; textureCoordinateCount = pCalRenderer->getTextureCoordinates(0, &meshTextureCoordinates[0][0]); // get the stored texture identifier // (only for the first map as example, others can be accessed in the same way though) Cal::UserData textureId; textureId = pCalRenderer->getMapUserData(0) [ set the material, vertex, normal and texture states in the graphic-API here ] // get the faces of the submesh static int meshFaces[50000][3]; int faceCount; faceCount = pCalRenderer->getFaces(&meshFaces[0][0]); [ render the faces with the graphic-API here ] } } } // end the rendering of the model pCalRenderer->endRendering(); When a model instance is not needed anymore, it must be destroyed by calling the destroy() function. This will free all data and other resources. myModel.destroy();