- Cal3D 0.11 API Reference -

Cal3D FAQ

Welcome to the Cal3D frequently asked questions list.

General Questions about Cal3D

What is Cal3D?

is a skeletal based 3D character animation library written in C++ in a way that is both platform-independent and graphics API-independent. It was originally designed to be used in a 3D client for Worldforge, but evolved into a stand-alone product which can be used in many different kinds of projects.

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.

What can I do with Cal3D?

, Cal3D is useful for putting animated 3D characters into your interactive graphical applications.

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.

What DOESN'T Cal3D do?

doesn't do graphics. The users are responsible for making a bridge between Cal3D and whatever graphics API they want to use. This includes things like loading textures, handling materials, and rendering the models to the screen.

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 Blender, 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.

Is Cal3D stable enough to use in a game?

, Cal3D is quite stable and efficient enough for a lot of games. Several published games have used Cal3D successfully.

How fast is Cal3D?

is a fairly subjective question, as Cal3D's speed is highly dependent on things not controlled by Cal3D. Developer choices like which graphics API to use can impact the speed, as well as using GPU programming languages. The complexity of the models plays a big role in this as well - not only the polygon count, but also the complexity of the underlying skeletal structure.

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 hundreds of characters at a time and reasonable framerates were achieved.

Can I use Cal3D for a commercial product?

short answer is yes. Cal3D is released under the Lesser GNU Public License (LGPL), which allows you to link in the Cal3D library for your commercial game or simulator or whatever.

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.

What operating systems does Cal3D work on?

is written to be cross-platform. It works on Windows, SGI Irix, various flavors of GNU/Linux, Mac OS X, etc.

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.

Can I use Cal3D with OpenGL / Direct3D / etc?

is designed to be independent of any graphics API such as OpenGL or DirectX. While this makes Cal3D more flexible, it does put a little more work on the users.

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.

Who else is using Cal3D?

Worldforge - http://www.worldforge.org - This is an open source project aimed at developing tools for massive-multiplayer online games. Cal3D was originally a part of Worldforge, but became a standalone tool.

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/ (no longer in their product list) - 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

Project FY - http://fysoftware.com - A game still in development featuring a 3D engine capable of handling both indoor and outdoor environments and transitioning seamlessly between them.

Poker3d - http://freshmeat.net/projects/poker3d/ - Poker 3D client and server released under the GNU GPL (pre-Alpha stage).

osgCal - http://gna.org/projects/underware - OpenSceneGraph adapter for cal3d released under the GNU GPL.

ReplicantBody - http://www.vrlab.umu.se/research/replicants/rbody.html - ReplicantBody is a character animation toolkit released under the GNU LGPL, written in C++, built upon Cal3D, ConfigScript and OpenSceneGraph.

Soya - http://oomadness.gna.org/ - Soya 3D is a high-level 3D engine for Python, designed with games in mind. Soya is written partly in Python and partly in C. Slune is a game based on Soya http://oomadness.nekeme.net/en/slune/index.html. Released under the GNU GPL.

Genecys - http://sourceforge.net/projects/genecys - Genecys is an online, multiplayer third person 3D MMORPG similar to Final Fantasy Online, or Everquest. Released under the GNU GPL.

Pok3d - http://pok3d.com/ - A 3D online poker room, released under the GNU GPL.

If you know of anyone else using Cal3D, let us know!

Can I just load my 3D Studio MAX files directly into Cal3D?

. You have to export your character to Cal3D-format files. There are many different things besides just animated figures that can be included in a 3DS file, and to make the Cal3D library sort these things out automagically would be an incredibly difficult task.

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.

Character Modeling

How do I make new characters?

is a job for an artist. Generally, one would create a mesh model of a character, create a skeletal system for it, animate it, and then export all of the pieces using the Cal3D exporters. (Skeleton, meshes, materials, and animations)

What modeling packages does Cal3D support?

currently have exporters for Blender, 3D Studio MAX and Milkshape 3D.

Blender - http://www.blender3d.org/
3D Studio MAX - http://www.discreet.com/products/3dsmax
Milkshape 3D - http://www.swissquake.ch/chumbalum-soft

How do I export a character from 3D Studio MAX to Cal3D?

. First, export the skeleton.

The remaining steps can be performed in any order:

2. Export the mesh or meshes.

3. Export the materials.

4. Export the animations.

How do I export a skeleton?

, you need to select the skeleton (and ONLY the skeleton). Then go to File->Export and select the Cal3D Skeleton exporter. You will be asked to choose from a list of bones. It's possible for each bone to appear more than once in the list, so make sure you only select each bone ONCE.

How do I export meshes?

exporting your mesh(es), make sure you've already exported your skeleton. And if your character has more than one mesh, you'll need to export each mesh separately. Be sure to select just one mesh at a time.

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.

How do I export materials?

are some tricks to this. The main thing is that the materials have to be named properly. Each material name that the character uses needs to end with a number enclosed in brackets, starting with 0 and going up.

For instance, if a character has materials for skin, shirt, face, and hat, them the materials should be named like this:

skin [0]
shirt [1]
face [2]
hat [3]

How do I export animations?

exporting your animations, make sure you've already exported your skeleton.

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.

Why does the exporter crash?

this is a result of having things selected that you shouldn't have. There can also be crashes caused by mis-named materials or failing to collapse the modifer stack before exporting.

Is there an exporter for Maya or Blender?

at OOMadness has released a GPL'd Python script that allows Blender users to export Cal3D objects. Find it here: http://oomadness.tuxfamily.org/en/blender2cal3d/index.html

There have been rumors of people working on a Cal3D exporter for Maya, but it has not been released yet.

How do I convert an IK-Solver animation in 3D Studio MAX to a keyframe animation?

do this, you need to collapse the bone trajectories. Select all of the model's bones. Open the Motion panel, and then the Trajectories tab. Click the Collapse button.

What's with these RAW image files?

to version 0.9, the textures for the Paladin sample model were contained in a RAW image file format. The current developers are not sure where they originated from, but they have (as of version 0.9) been converted to TGA files.

These old RAW files are no longer supported or necessary.

Programming

Are there Python bindings for Cal3D?

. The Py3D project has Python bindings for Cal3D. You can get them at the Py3D website:

http://www.py3d.org/pycal3d

What coordinate system does Cal3D use?

characters exported from a modeling package such as 3DSMax or Milkshape will be in the same coordinate system as the package. For instance, a model exported from MAX and loaded for use in an OpenGL application will require a -90 degree rotation about the X-axis to be converted to the OpenGL coordinate system.

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.

Why are there classes and core classes?

practical applications, there may be many different instances of a single type of character. For instance, your game might pit the hero against an army of robots. Some of these robots might look identical, and can then share data with each other rather than having a separate copy of it for each robot.

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.

Can I integrate Cal3D with a scenegraph like OSG or OpenSG?

are a few ways to get your Cal3D characters working within an application that uses a scene graph.

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:

http://gna.org/projects/underware/

Compiling Cal3D and the Exporters

What's with these missing DLL errors when I run the Cally demo?

may have gotten a message pop-up saying that the MSVCP70.dll file could not be found when trying to run the Cally demo.

The Windows binaries for the 0.11 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:

http://msdn.microsoft.com/netframework/downloads/howtoget.aspx

What do I need to compile the exporters in Windows?

order to compile the 3D Studio MAX exporter, you need the 3DSMax SDK (Software Development Kit) and the Character Studio SDK. When you install MAX and/or Character Studio, there will be an option to also install the SDKs.

For the Milkshape exporter, you need to get the Milkshape SDK, which is available separately from their website:

http://www.swissquake.ch/chumbalum-soft/ms3d/download.html

Where is the biped.h / bipexp.h / phyexp.h file?

need to have the Character Studio SDK installed, which contains these header files.

Do I need a specific version of 3D Studio MAX to use the exporters?

exporters are known to work with 3DSMax 6, and 7.
Generated at Thu Jun 29 19:04:00 2006 by The Cal3D Team with Doxygen 1.4.6