|- Cal3D 0.9 API Reference -|
What is Cal3D?
Cal3D's essentials can be boiled down to 2 parts: the C++ library and the exporter. The exporter is what you would use to take your characters (built in a 3D modeling package) and create the Cal3D-format files that the library knows how to load. The exporters are actually plug-ins for 3D modeling packages. This allows 3D artists to use the modeling tools that they're already comfortable with.
The C++ library is what you would actually use in your application, whether it's a game or a VR application. The library provides methods to load your exported files, build characters, run animations, and access the data necessary to render them with 3D graphics.
The exporters provide a bridge for users to take their characters created in a 3D modeling package to their own applications, where they will have control over the characters' actions.
Cal3D can perform animation blending. This means that you can execute multiple animations at the same time and Cal3D will blend them together smoothly. This effect is best demonstrated in the Cally Demo, where the walking, running, and strutting animations can be blended together in any ratio to get a wide variety of movement characteristics.
Cal3D also provides an automatic level-of-detail control, which allows you to scale back the number of polygons that make up your character at runtime. This can be a good performance boost when your character is farther away and the lower detail isn't noticable to the viewer.
With a little work, you can fully manipulate the individual parts of your characters. This is useful when you want to create truly dynamic motion at runtime without the aid of predefined animations. For instance, if you wanted your character's head to turn as a car goes past him, you could control the head's rotation directly to keep facing the moving car.
The source code for the Cal3D miniviewers is a good place to start, as it provides a full implementation for both OpenGL and Direct 3D graphics APIs that you can adapt for your own purposes.
Cal3D can't help you make animated models. Making a decent character will require the use of a modeling package like 3D Studio MAX, using the tools that it provides. Making a really excellent character requires a talented artist.
Cal3D doesn't load configuration files. This is a responsibility left on the users' shoulders for another degree of flexibility. And again, an example of how to do this is contained in the miniviewer examples.
Cal3D is certainly capable of operating fast enough for many practical applications and games. While we don't have an official benchmark, tests have been done in the past involving 20-30 characters at a time and reasonable framerates were achieved.
The catch, however, is that if you make changes to Cal3D and use them, you are obligated to release the source code under the same license.
Basically all you need is a decent C++ compiler with standard template library support. If you want to use the build system, you either need Visual Studio on Windows, or GNU's autotools on *nix systems.
We have several examples of our miniviewer application that can show you how to use Cal3D with various graphics APIs such as OpenGL, Direct 3D, or even shader languages.
Keep in mind that these examples only show one way how to do it; you are free to develop your own methods and techniques specific to your application.
A Tale in the Desert - http://www.atitd.com - ATITD is a very unique massive-multiplayer online roleplaying game where strategy and management take precedence over traditional combat. eGenesis used a derivative of Cal3D that they developed, which is also available on their "download" page.
Desert Rats - http://www.valusoft.com/products/desertrats.html - A WW2 action game where you fight the Nazis in northern Africa from a heavily armed jeep.
Neverending ODC - http://ne-odc.sourceforge.net - Tools to design and edit massive 3D fantasy worlds.
The Nebula Device - http://nebuladevice.sourceforge.net/cgi-bin/twiki/view/Nebula/NCal3DPackage
If you know of anyone else using Cal3D, let us know! Can I just load my 3D Studio MAX files directly into Cal3D?
Plus, you can only have a single animation stored in a 3DS file and characters will typically have a variety of animations to choose from.
How do I make new characters?
The remaining steps can be performed in any order:
2. Export the mesh or meshes.
3. Export the materials.
4. Export the animations.
Once you're got your mesh selected, go to File->Export and choose the Cal3D Mesh exporter. You will be asked to locate a skeleton file. Pick the skeleton file (.csf) that was exported based on the same character as your mesh.
For instance, if a character has materials for skin, shirt, face, and hat, them the materials should be named like this:
Once you've got your character animated, take your character out of Figure Mode, go to File->Export and choose the Cal3D Animation exporter. You'll have the option of a number of frames per second and the selection of individual keyframes to use in the animation.
Like mesh exporting, you'll be asked to find the Cal3D skeleton file (.csf) that the character is based on.
There have been rumors of people working on a Cal3D exporter for Maya, but it has not been released yet.
These old RAW files are no longer supported or necessary.
Are there Python bindings for Cal3D?
It should also be noted that Cal3D's math classes assume a left-handed rotation system. Right-handed systems are much more common, so this is not a minor detail. Think of it like this: take your right hand and point your thumb straight up while curling your fingers a bit - kind of like you're holding a coffee mug.
Your thumb is the vector axis of rotation. If you have a positive-value rotation, you will be rotating counter-clockwise about your thumb's axis. If you have a negative-value rotation, you'll be rotating clockwise.
Now do the same thing, but with your left hand. Note that your fingers now curl around clockwise. So with positive rotation values in a left-handed system, you get a clockwise rotation. This is the opposite of the right- handed system.
The core objects (skeleton, meshes, materials, bones, etc.) contain the data that will not change at runtime and can therefore be shared between multiple independent characters. The non-core classes contain data about things that frequently change, such as the animation state and mesh data. This allows the instances to share data and still be able to be animated independent of one another.
The easiest way is to simply draw your characters using OpenGL after you've drawn your scene graph. This can be inefficient, however, because you lose the culling features that the scenegraph provides. Plus you need to be very careful about the OpenGL state, which is changed by the scene graph constantly.
Most major scene graphs support draw callback functions. Using these, you can basically attach a Cal3D character to a node inside the scene graph and the character can be drawn (using your OpenGL commands) automatically as the scene graph is traversed. This approach requires a little more work, and will be different depending on the specific scene graph you're using.
If you're interested in using OpenSceneGraph, there's a Sourceforge project called osgCal that provides an adapter to put Cal3D models into OSG applications. Find it here:
What's with these missing DLL errors when I run the Cally demo?
The Windows binaries for the 0.9 version of Cal3d (and the demo) were compiled with Visual Studio .NET (VC70). Non-XP versions of Windows may not have the right C/C++ runtime DLLs that are needed.
These are available as part of Microsoft's .NET Framework package, which can be downloaded from here:
For the Milkshape exporter, you need to get the Milkshape SDK, which is available separately from their website: