5.3. Model Instance Handling

5.3.1. Creation

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 ...
  }
        

5.3.2. Attachment and Detachment of Meshes

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 ...
  }
        

5.3.3. Level-of-Detail Control

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);
        

5.3.4. Material Control

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);
        

5.3.5. Animation Control

There are currently two types of animations implemented in the Cal3D library:

1. Cycles, which are repeating, looping animations.

2. Actions, which are one-time executed animations.

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);
        

5.3.6. State Update

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);
        

5.3.7. Rendering

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();
        

5.3.8. Destruction

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();