1. Welcome

IIf you are reading it might be because you’d like to learn how to use HALCA, a library developed by Bernhard Spanlang for character animation. In particular, you’d like to use it in XVR, a tool to render those animations. In such a case, you can download the tutorial files from here. This document is organised as follows:

1. Welcome

2. Basic Notions

3. Start Using Halca

4. Pipeline to import animations

5. How to use morph targets

6. Troubleshooting

This tutorial has been developed at the EVENT Lab by Joan Llobera with some input from Daniel Pérez-Marcos. A description of the HALCA library can be found at: http://www.lsi.upc.edu/~bspanlang/animation/avatarslib/doc/.

2. Basic Notions

XVR

The main functions are:
        -OnInit();
        -OnFrame();
           This includes the calls to SceneBegin() and SceneEnd(), in which the drawing functions should go.

Other functions: OnTimer, OnExit, OnDownload...

What any program has to do is:

1. Find out what characters should do

2. do it

3. show it was done

HALCA has the main functions (IT IS VERY IMPORTANT TO CONSERVE THE ORDER IN WHICH THEY ARE USED):

        -initAvatars()

This function initializes the avatars, loads the animations, etc.

There are 3 ways of executing animations. It is recommended not to mix modes. (see step 2 of the pipeline explained below),
            exeAct() This function executes an animation once.
            blendCycle() This function executes an animation in a loop
            Morph() This function executes in morph mode (see second tutorial)

To update the animations (in all 3 modes)
            Avatars.Idle()
        This function updates the positions according to the loaded animations but also with other functions, as for example SetPosition

To draw the animations (see step 3 of the pipeline below)
        skinShader.start();
        drawExtShader();
        skinShader.stop();

3. Start Using HALCA

To do this, I’ve prepared a tutorial for you. Open the folder named “my first XVR project, and notice it includes:

-FirstCharacter.s3d: the main functions in XVR
-solutions.txt

In it, you can also find:
-Common: some common functions generally used, such as mouse navigaton.
-KeyboardManager: this is used to interact with the keyboard.
-Other files such as dll, etc. that make the system work

TO DO:
Do not take care of the other files, and try hard finding the solution before you look the solutions. By now, only fill in the TO DO parts, which are 4 exercises, in order of increasing difficulty. This will show you how to load a character, add a basic animation and do a first adjustment to this movement. At the end there is also a fifth exercise to introduce you to the use of morph targets.

If in addition to these exercises you want to add your own animations and /or morph targets, there are instructions to do so below.

NOTE: start opening the .prj file in XVR...

4. Pipeline to import animations

Below is explained how to export characters and animations from 3D Studio max into XVR. The process should be attempted by anyone wanting to use the library.

1) load the 3D model in 3d max.: we have a character.

(if it is not rigged, there you go... good luck)
(if don't want to rig, you can also just create a biped without rigging, but it will not be possible to visualise that in HALCA)

2) load the animation related to it.

(or animate, or whatever you want that has as a result an animation)

 
3) export it as a cal3D animation

       -set the apropriate name sets (in edit > edit named selection sets)

        -ensure you are in FIGURE MODE

       -run the unified script export_cal3D
             (useful info: can be found at: http://www.cs.ucl.ac.uk/staff/W.Steptoe/char/char0700.html)

-xaf file is the animation
-cfg is the config

-xrf is for material (only jpeg supported, not tiff, and power 2 resolution)

       -go out from figure mode
       -export the animation

       -build the following structure:
             -in the folder of the project, create a folder named data. Put the cfg file of each character in it.
             -in the data folder, create another folder also named data, and put the rest of the files of the character in an other folder in it. It is recommended that this last folder is character specific.
                    Ensure the texture files referenced in the xrf are in this folder   (see 5.C for how the different materials are linked)

            -add to the cfg files the names of the animations you want to load
       

NOTE: to be able to export you need:

-a file called cal3d.dll in the 3dsmax8 folder

-a file called cal3d_max_exporter_DL3D.dle in 3dsmax8/stdplugs.

4) export the "furniture"

AAM format is what is preferred by XVR


5) create an XVR project with these things.

5.A)       -Download the following files from http://www.lsi.upc.edu/~bspanlang/animation/avatarslib/doc/ :
-Avatars.s3d to load the functions of the dll in XVR
-HALCAWin32.dll or HALCAX64.dll dependent if you use 32 or 64 bit windows
             -skinshDquat.sh, (Note you should change #define DQUAT_TRANSF_XVRSHADER if we use skinshDQuat.sh)


             -To obtain Common.s3d, in order to have some basic functions, including necessary things in order that the characters work well.

To be taken in account:

to draw the avatars with:
                   skinShader.start();
                    Avatars.DrawExtShader();
                    skinShader.stop();

instead of the usual
                    Avatars.Draw();

please note the import of the dlls is set in the avatars.s3d file.
Therefore, the only lines necessary are
#include "Common.s3d" //some general-use functions
#include "Avatars.s3d"

5.B) structures of data:

5.C) in onInit(), set the function to local dir (XVR engines after 147 is necessary)
Instruction:

SetLocalDir();

Inititalize the avatars (this loads the functions of the dll)
    initAvatars();

And finally addthe characters

    Avatars.addCharacter("guy1_dir","guy1.cfg");

6) Load the animations in your XVR project

Parameters: ( C_VOID, "exeAct",C_INT,C_INT,C_FLOAT,C_FLOAT);// AvatarID, AnimationID, inTime, outTime

For example:

Avatars.exeAct(0,0)

To take into consideration:

• The function: Avatars.__AddFunction( C_VOID, "exeAct",C_INT,C_INT,C_FLOAT,C_FLOAT,C_FLOAT, C_INT);

Takes as parameters: AvatarID, AnimationID, inTime, outTime (default 0), weight (how much of the animation),  lock (pose after playing)

The number of the animation (AnimationID) is the order of appearance in the .cfg file, starting from 0, or can be obtained with:

AddAnimation(The_name_of_The_animation_file.XAF);

The number of the avatar is the order of declaration, and is returned by:

Avatars.addCharacter("guy1_dir","guy1.cfg");

5. How to use Morph Targets with Avatars

This process is of a slightly more advanced level. It explains how to use morph targets within HALCA.

1) Add the meshes in the .CFG file, e.g.:

mesh=hero_head.XMF

morphtarget=hero_head_mouthOpen.XMF

morphtarget=hero_head_eyes_squint.XMF

2) Modify the SKinshTM.sh file:

2.A) Add the Vertex and values attributes for each morphtarget, e.g.

uniform float morphval0;

uniform float morphval1;

attribute vec3 vertexMorph0;

attribute vec3 vertexMorph1;

2.B) Modify the following equation to add the effects of each target morph.

vec4 pos = gl_ModelViewMatrix*weightmat*vec4((vec3(gl_Vertex)+vertexMorph0*morphval0+vertexMorph1*morphval1),1.0);

//The current morph value (stand) is given to the function

3) add a function to modify the morphs:

3.A) in main.s3d:

#define TM_TRANSF_XVRSHADER //instead of VA_TRANS

var morphval=vector(10); //up to 11 morphes

//If you want to modify the morph manually with keymanager:

function incMorphVal(i,x){

morphval[i]+=x;

}

KeyManager.addKeyFunction("m",VK_LSHIFT,true,"incMorphVal",{0,0.01},2,"Increase Morph"); //In oninit

3.B) in Drawscene();

#ifdef VA_TRANS

Avatars.Draw(0);

#else

skinshader.start();

skinshader.setParameter("morphval0",morphval[0]);

Avatars.DrawExtShader();

skinshader.stop();

#endif

Avatars.Idle();

PRINT HELP on the screen:

-------------------------

#include "HUD.s3d"

#include "IK.s3d"

function togglePrintHelp(){

KeyManager.printHelpOn=!KeyManager.printHelpOn;

}

*******+* ONINIT:
HUDinit();
KeyManager.addKeyFunction("h",0,true,"togglePrintHelp",{},0,"Print This Help");

******* ONFRAME: (at the end):
HUDdraw();

******* ONTIMER:
KeyManager.idle();

- IN HUD.s3d:
HUDvisible = true;

6. Troubleshooting

1) If you want to use Vista, pray.

        If you have a MSVCR80.dll dependency, then stop, stay calm, and look for the good side of life, because you need a new XVRCal3d dll version.

2)
if still, after that, you're going to try with Vista, or with other OS, can be useful to check you have all the dll. dependencies.
This can be done with Depends. http://www.dependencywalker.com/

For example, in Vista,
you might need to install NetFramework version 2 or 3

http://www.microsoft.com/downloads/details.aspx?FamilyID=0856eacb-4362-4b0d-8edd-aab15c5e04f5&displaylang=en