Cal3D 0.10.0 Release Notes

The Cal3D developers are proud to release version 0.10.0 of the Open Source 3D character animation library. About 13 months after version 0.9.1 hit the road, this release is a major update and adds many new features. The list of these features is long and some minor changes are needed to convert to Cal3D 0.10.0

What's New in Cal3D 0.10.0

Cal3D core

• Create/destroy functions removed

  Previously, Cal3D used create/destroy functions for all the classes. These functions have been removed because they were redundant with constructor/destructor functions.

  Because of this, applications using Cal3D need be updated. All calls to create/destroy need to be removed and arguments of the create function need to be passed to the constructor.

• Reference counting on core objects

  Core objects (coreAnimation, coreSkeleton, coreMesh...) can be shared between several models. But with the old API it's impossible to correctly release memory. A counter has been added to each of the core objects to prevent the deletion of an object that is still used. Objects can now be shared between several coremodel correctly.

• A "stride" argument to getVertices(), getNormals() ...

  The Renderer object allows retrieving geometry data during the rendering of the model. Since 3D APIs like Direct3D have evolved and now use flexible vertex buffers, it's now easy to fill the vertex buffer directly with the new (optional) argument :

  pCalRenderer->getTangentSpaces(bumpId,&pVertex->Tangents.x,sizeof(VERTEX));

  Rem: Be careful with these functions because it can be slower.

• Modification of the XML file format

  The old XML file format wasn't legal XML. This is now fixed.

  For compatibility, the old format can still be loaded. But be careful to not try to load a new file with an old version of Cal3D

• Function to load data to the same coodinate system of the client application :

  You can use the static function CalLoader::setLoadingMode(int flags). Possible flags are LOADER_ROTATE_X_AXIS and LOADER_INVERT_V_COORD.

• Face orientation

  In previous versions of Cal3D, the face orientation wasn't always correct and for some model it was necessary to set the cull mode to none. It's now not necessary anymore.

• Loading from a byte buffer or std::istream.

  You can use the following Functions :

  static CalCoreAnimation *loadCoreAnimation(std::istream& inputStream, CalCoreSkeleton *skel=NULL);
  static CalCoreMaterial *loadCoreMaterial(std::istream& inputStream);
  static CalCoreMesh *loadCoreMesh(std::istream& inputStream);
  static CalCoreSkeleton *loadCoreSkeleton(std::istream& inputStream);
  
  static CalCoreAnimation *loadCoreAnimation(void* inputBuffer, CalCoreSkeleton *skel=NULL);
  static CalCoreMaterial *loadCoreMaterial(void* inputBuffer);
  static CalCoreMesh *loadCoreMesh(void* inputBuffer);
  static CalCoreSkeleton *loadCoreSkeleton(void* inputBuffer);
  

  Note : only binary formats are supported

• New interface for hardware vertex processing

  Since version 0.9.0 of Cal3D there was a sample to show how to use vertex shader to animate with Cal3D. In this new release, a set of functions can now be used to do this easily : the class CalHardwareModel has been added. You can look at the code source of the two new miniviewers (one OpenGL and one Direct3D) for more information. Note : the spring system needs to be disabled when using this feature.

• A time factor for animation

  A time factor allows playback of several animations at different speeds. You can use CalMixer::setTimeFactor(float timeFactor) for cycle animations or CalAnimation::setTimeFactor(float timeFactor) for action animations.

  Rem : negative time factor to allow reverse animation is supported

• CalMixer can be replaced by an application defined implementation.

  The CalMixer class is now based on an abstract class (CalAbstractMixer) from which the application can implement a different mixer. The new mixer can be registered using the CalModel::setAbstractMixer method. The mixer currently in use for a given CalModel instance can be retrieved with the CalModel::getAbstractMixer method. This addition is backward compatible.

• Animation callbacks

  The new class CalAnimationCallback and the functions :

  void CalCoreAnimation::registerCallback(CalAnimationCallback *callback,float min_interval)
  void CalCoreAnimation::removeCallback(CalAnimationCallback *callback)
  

  can be used to set functions that will be called when the animation is active.

• An option to stop a action animation at the end

  An new parameter has been added to the CalMixer::executeAction() function :

  bool CalMixer::executeAction(int id, float delayIn, float delayOut, float weightTarget, bool autoLock=false)

• Symbolic names for coreMaterial, coreMesh, coreAnimations loaded by coremodel.{h,cpp}

  A few functions have been added to provide easy access to core objects :

  int CalCoreModel::getCoreAnimationId(const std::string& strAnimationName);
  int CalCoreModel::getCoreMaterialId(const std::string& strMaterialName);
  int CalCoreModel::getCoreMeshId(const std::string& strMeshName);
  int CalCoreModel::getBoneId(const std::string& strBoneName);
  
  
• A function to rescale a core model.

  The function void CalCoreModel::scale(float factor) can be used to scale a model.

  This function directly modifies all the meshes, skeletons and animations. You can use it only before creating the CalModel. Spring systems are also disabled.

• Functions to control force of the spring system :

  The gravity vector and the force vector can now be set

  void CalSpringSystem::setGravityVector(const CalVector & vGravity);
  void CalSpringSystem::setForceVector(const CalVector & vForce);
  

  As previous version of Cal3D, the vector force is set to (0.0f, 0.5f, 0.0f) by default (to simulate some movement)

• An experimental collision system

  This new feature can be enabled with the function :

  void CalSpringSystem::setCollisionDetection(bool collision);

  Note : Bounding box calculation need to be actived for this feature. You can uncomment a few lines in Model::onRender() to test.

• A function to compute the global bounding box of the model

  The bounding box of the model can be retrieved with the CalBoundingBox & CalModel::getBoundingBox(bool precision) function

• calculateBoundingBox has been renamed to calculateBoundingBoxes.

Cal3D miniviewers

There are now six sample applications. Three new miniviewers have been added to the main distribution:

• OpenGL with vertex program : with current hardware, most of the computation can now be done directly on the graphics card. The new CalHardwareModel class is used to load the data and send it to the GPU. A vertex program is used to compute the final position of the vertices.
• Direct3D with vertex shader : the same that OpenGL with vertex program but with Direct3D.
• Direct3D bump mapping : since version 0.9.0, Cal3D supports tangent space calculations. This feature is useful to do advanced lighting effect like bump mapping.

Exporters

• Maya

  Cal3D 0.10.0 is the first version to provide a maya exporter. This version is still beta and is probably not bug-free.  Try it and let us know!

• 3D Studio Max

  The 3DSMax exporter has been improved :

• 3DS Max 7 support.
• Multi/Sub material can be selected.
• Mesh with mirroired part can be exported correctly.
• The modifier stack doesn't need to be collapsed anymore.
• A new gui in maxscript has been added.

Export_cal3D is an all-in-one export maxscript based on the 0.9.2+ 'maxscript-extended' version of the exporter plugin for Max6.

Define the objects that compose your character, specify the root bone(s), create a list of the animations segments, tune original export parameters then click Export. Additional features include automatic cal3d.cfg creation, post-export mini-viewer, animations definition and per-scene configuration.