Cuarto Tutorial: El HolaMundo más simple de ODE (con Irrlicht)

Reanudamos los tutoriales comenzando con la integración de ODE. Éste no es más que un motor de simulación física, por lo que necesitamos apoyarnos sobre un motor gráfico para visualizar dicha simulación. O dicho de otra forma, nos permite dotar de simulación física un entorno gráfico tridimensional.
Para empezar crearemos una pelota y la dejaremos caer para ver como rebota contra el suelo.

Como de costumbre, el código y los binarios se encuentran en el box: tutorial_04.zip. Hemos partido de una rápida refactorizacion en funciones del tutorial 3, dicha refactorización se encuentra también en el box bajo el nombre de tutorial_03b.zip por si el salto del tutorial 3 al 4 es algo confuso, ya que hemos duplicado el número de líneas de código al añadir ODE.
Aprovecharemos que el código está divido en funciones para realizar el análisis poco a poco.

Antes que nada, hagamos una pequeña introducción.

La idea básica es que vamos a tener por un lado un objeto poligonal esférico texturizado en Irrlicht que será nuestra pelota visible. Y por otro tendremos un objeto de colisión esférico en ODE que será nuestra pelota física y que ODE se encargará de animar en función de la gravedad configurada. Por lo tanto, la relación entre ambas librerías correrá por nuestra cuenta: crearemos ambos objetos y representaremos la pelota de Irrlicht en función de la posición en la que se encuentre la esfera física de ODE.
De esta forma conseguimos una animación física natural en nuestro entorno tridimensional totalmente automática.

Introduciendo un poco a ODE, hay que empezar dejando claro que es una librería de simulación de cuerpos rígidos, descartando otro tipo de cuerpos más complejos como elásticos, telas, fluidos, partículas, gases, etc. Al menos no de forma nativa, ya que quizás con un poco de ingenio uno puede recrear telas o la animación de algún tipo de partículas, así como simular superficies elásticas a través de la configuración de los puntos de colisión (dotando a estos con una fuerza de rebote peculiar) o incluso superficies blandas haciendo uso de los factores de corrección de la simulación permitiendo violar ligeramente el límite que una superficie de colisión impone.

Para conseguir todo esto ODE se basa en 2 tipos de objetos a los que llama "geom" y "body".
Para ODE un "geom" es el objeto geométrico que posee una forma determinada y colisiona con otros "geom". Tenemos a nuestra disposición una colección de primitivas geométricas de colisión (esfera, cilindro, plano, cubo..) para combinar a nuestro antojo, aunque de forma excepcional también podemos obtener una geometría de colisión directamente desde un modelo poligonal de malla (llamados "trimesh") a costa de un coste computacional de simulación muy alto (no recomendable).
Los "body" son aquellos objetos que se van a mover en nuestro mundo. No tienen una forma geométrica determinada (para eso ya están los "geom") pero si una masa y un centro de gravedad. Un body por lo tanto sufre el efecto de la gravedad y el de cualquier fuerza que se le aplique manualmente.

Dicho así tenemos los geoms como objetos estáticos de colisión y los body como objetos dinámicos de nuestro mundo. Entonces ¿como colisiona un body? ¿como animo un geom? La forma de trabajar con ODE es combinando ambos tipos como si de distintas características de nuestro objeto se tratara. Por ejemplo para representar los elementos que componen la escena de éste tutorial utilizaremos para el suelo un geom ya que éste nunca se va a mover, no va a ser más que un plano estático de colisión; y para recrear nuestra pelota necesitaremos por un lado un geom con forma esférica que colisione contra el suelo, y como además queremos que se mueva crearemos también un body con una masa determinada y un centro de gravedad correctamente situado. Como tanto el geom como el body van a representar nuestro mismo objeto (la pelota) deben ser vinculados para que "trabajen" al unísono, de esta forma nuestra pelota se moverá gracias a su body y colisionará gracias a su geom.

ODE define los geoms y los bodies como elementos de unas estructuras superiores sobre las que gestiona de forma óptima todos estos objetos que van a formar parte del mundo físico. Así los geoms son agrupados en los llamados "space", que son literalmente espacios de colisión: los geoms que pertenezcan a un mismo space colisionarán entre ellos (aunque la última palabra para que colisionen dos objetos la tenemos nosotros). Y por otro lado, todos los bodies cuyas nuevas posiciónes van a calcularse "simultáneamente" pertenecerán al mismo "world".

En resumen, vamos a tener geoms agrupados en spaces (que a su vez pueden contener otros space) y bodies agrupados en worlds.

El último concepto importante del universo ODE que queda por mencionar son los "joints". Un joint se puede definir como la "union" entre 2 objetos. Por ejemplo, el joint más básico es el "contac joint" que es el punto de contacto que se produce cada vez que 2 geoms colisionan. Pero la idea de los joints es mucho más avanzada ya que no solo define un punto de unión, sino como responde un objeto en relación a otro en función a unos límites de movimiento y grados de libertad que son definidos en el propio joint. De ésta forma podremos definir joints que respondan como una bisagra, como un pivote, como un pistón, etc.. Y al igual que los elementos anteriores, los joints pueden agruparse en estructuras más grandes llamadas "group joints".
Pero no nos asustemos por ahora con esto de los joints y demás que se queda grande para el tutorial que tenemos entre manos, así que vayamo al tema!


Antes de meternos con las funciones veamos la cabecera del código.

#include <irrlicht/irrlicht.h>
#include <ode/ode.h>

using namespace irr;
using namespace core;
using namespace scene;
using namespace video;
using namespace gui;

IrrlichtDevice *device;
IVideoDriver* driver;
ISceneManager* smgr;
IGUIEnvironment* guienv;
ICameraSceneNode* cameraNode;
ISceneNode* sphereNode;

dWorldID world;
dSpaceID space;
dJointGroupID contactJointGroup;
dGeomID groundGeom;
dGeomID sphereGeom;
dBodyID sphereBody;

Simplemente un par de includes son necesarios para trabajar con Irrlicht y con ODE. Todos ellos estan incluidos en el tutorial por lo que no hay que instalar nada adicional en nuestra máquina. De igual forma, para poner en marcha una aplicación ODE tan solo necesitamos enlazar con una librería, también incluida en el tutorial.
Echa un vistazo al Makefile si quieres saber como compilar una aplicación con ODE.

A continuación los ya conocidos espacios de nombres de Irrlicht, pero ¿y los de ODE?
La librería ODE, internamente, está programada en C++, pero con tal de facilitar el acceso a su interfaz, su desarrollador decidió ofrecer su API en formato C, y por ese motivo no encontramos espacios de nombres. Así que lo único que necesitamos tener en cuenta para acceder con rapidez a las funciones y tipos de ODE es saber que todas ellas comienzan por 'd'.

Tras las variables globales de Irrlicht definidas (esta vez haremos uso simplemente de un nodo esfera) encontramos las de ODE, que como hemos dicho comienzan por dXXX.
Para cualquier simulación necesitamos como mínimo un mundo, un espacio de colisiones y un grupo de joints para los puntos de contacto. Para definir nuestra pelota física necesitamos un geom y un body. Y si queremos que colisione contra el suelo, éste debe ser definido de forma explicita mediante un geom (no necesita un body ya que va a ser estático).

Demos un vistazo rápido al main.

int main()
{
 irrlicht_inicializacion();
 ode_inicializacion();
 
 irrlicht_creacion();
 ode_creacion();
 
 while( device->run() )
 {
  irrlicht_renderizacion();
  
  ode_simulacion();
  irrlicht_actualizacion();
 }
 
 irrlicht_finalizacion();
 ode_finalizacion();
 
 return 0;
}

Básicamente empezamos inicializando ambas librerías. A continuación creamos nuestros objetos irrlicht (cámara, pelota..) y nuestros objetos ODE (pelota, suelo..).
Una vez en el bucle de ejecución realizamos 3 pasos fundamentales: pintar el mundo irrlicht, dar un paso de simulación en el mundo ODE y actualizar el mundo irrlicht en función de los cálculos de ODE. En el momento que estos 3 pasos entran en ejecución constante su orden realmente es indiferente, pudiéndose colocar en cualquier otro al realizado en el tutorial.

Pasemos ahora a las funciones ODE, ya que el código Irrlicht no debería suponernos ninguna dificultad si hemos llegado hasta aquí pasando por los primeros tutoriales.

Empecemos por la inicialización.

void ode_inicializacion()
{
 dInitODE();
 world = dWorldCreate();
 space = dSimpleSpaceCreate( NULL );
 contactJointGroup = dJointGroupCreate( 0 );
 
 dWorldSetGravity( world, 0.0, -0.01, 0.0 );
}

Se inicializa ODE y creamos las estructuras mencionadas: un world para nuestro body, un space para nuestros geoms y un jointGroup para nuestros joints de contacto que se generan en el instante de la colisión.
Además aprovechamos para definir una fuerza de gravedad en el mundo. Como queremos una fuerza clásica la hemos definido sobre el eje vertical Y y negativa hacia abajo.

Una pregunta interesante es ¿a que velocidad trabaja ODE? Y la respuesta es tan sencilla como compleja: a la máxima que le permita la máquina sobre la que se ejecuta. Al igual que al render no le hemos puesto ninguna limitación y se ejecuta al máximo frames por segundo que le sea posible, nuestra simulación física va a funcionar igual haciendo el mayor número de cálculos posibles, con la diferencia que si bien en el render no tiene demasiada importancia que los FPS aumenten en una máquina más potente en el caso de la simulación nos vamos a encontrar con que ésta es más rápida o más lenta según la CPU que la ejecute, cosa que no pinta nada bien.
En próximo tutoriales veremos como conseguir tiempos de simulación constantes independientes al procesador que utilicemos, pero por ahora simplemente ajusta a mano los valores del tutorial para tu máquina si no te gustan los resultados, como por ejemplo esta fuerza de gravedad que acabamos de definir.

void ode_creacion()
{
 /* suelo */
 
 groundGeom = dCreatePlane( space, 0, 1, 0, 0 );
 
 /* pelota */
 
 sphereGeom = dCreateSphere( space, 10.0f );
 sphereBody = dBodyCreate( world );
 dGeomSetBody( sphereGeom, sphereBody );
    
 dBodySetPosition( sphereBody, 0, 100, 0 );
}

Como ya hemos comentado, creamos un geom para nuestro suelo. Los geom los creamos mediante las funciones "dCreateXXX". Dependiendo de la figura geométrica del geom elegiremos una función u otra. En este caso hemos utilizado la función del plano indicándole el space al que va a pertenecer el geom y la orientación de éste. El plano es definido directamente desde la ecuación paramétrica del mismo: a*X + b*Y + c*Z = d. Los parámetros de la función dCreatePlanet corresponden a los coeficientes "a,b,c,d", de esta forma, mediante "0,1,0,0" obtenemos un plano cuya normal se sitúa sobre el eje Y: un plano sobre los ejes XZ.

Acto seguido definimos la pelota mediante un geom esférico y un body. Como ambos elementos van a representar el mismo objeto los asociamos explicitamente.
Por último situamos la esfera en el lugar deseado. ¿dBodySetPosition ó dGeomSetPosition? Da igual, ambos están vinculados y al posicionar uno automáticamente posicionamos el otro.

Antes del extraño callback definido, veamos la función de simulación

void ode_simulacion()
{
    dSpaceCollide( space, NULL, &ode_nearCallback );
    dWorldStep( world, 0.05 );
    dJointGroupEmpty( contactJointGroup );
}

3 nuevos pasos fundamentales.
El primero detecta posibles colisiones entre todos los geoms que pertenezcan al space indicado. Y digo posibles porque el callback pasado como parámetro (puntero a función) es invocado por ODE cada vez que los objetos están muy cerca (han intersectado sus bounding boxes pero no necesariamente las geometrías han colisionado). Dentro de dicho callback detectaremos y gestionaremos las colisiones reales.
Suponiendo que dicho callback ya se ha invocado para todas las colisiones de nuestro mundo, es el momento de actualizar la posición de todos los objetos del mundo en función de lo que haya sucedido en el paso anterior. (Este es otro valor importante que debes modificar a mano si la simulación en tu ordenador es muy rápida o muy lenta).
Y por último debemos eliminar todos los joints de contacto que se encuentren en el grupo. ¿¿Mande?? Como hemos dicho, un joint es una unión entre 2 objetos, y en las colisiones se produce un joint especial de contacto para poder configurar la colisión (fricción, rebote, etc..). Estos joints se generan en el primer paso de la simulación que acabamos de ver, en el segundo se procesan y en este tercero deben ser eliminados para que los objetos sigan su curso en la siguiente iteración.
Éste es el ciclo de vida de todo joint de contacto.

Veamos ahora los entresijos del callback mencionado.

void ode_nearCallback(void *userData, dGeomID geom1, dGeomID geom2)
{
 const int maxPoints = 10;
 dContact contactPoints[maxPoints];
 int numPoints = dCollide( geom1, geom2, maxPoints, &contactPoints[0].geom, sizeof(dContact) );
 
 if (numPoints > 0)
 {
  for (int i=0; i<numPoints; i++)
  {
   contactPoints[i].surface.mode = dContactBounce;
   contactPoints[i].surface.bounce = 0.7;
   contactPoints[i].surface.bounce_vel = 0.1;
   dJointID contactJoint = dJointCreateContact( world, contactJointGroup, &contactPoints[i] );
   dJointAttach( contactJoint, dGeomGetBody(contactPoints[i].geom.g1), dGeomGetBody(contactPoints[i].geom.g2));
  }
 }
}

Recibimos los 2 geoms que están en posible colisión. Para resolver la situación invocamos dCollide: función que detectará la colisión con detalle y calculará el número de puntos en los que ambos geoms colisionan.
Si no hay colisión, sencillamente obtendremos una cantidad de 0 puntos de contacto entre ambos geoms. Pero si se ha calculado algún punto de contacto habrá que configurarlo mediante la estructura definida "dContact". En este tutorial vamos a simular una superficie elástica para conseguir que la pelota rebote, para ello debemos modificar 2 parámetros de la superficie del punto de contacto: "bounce" y "bounce_vel". Asignamos unos valores para el rebote y creamos un joint a partir de dicha configuración. Por último solo tenemos que asociar el joint creado con los dos geoms que han entrado en juego en la colisión.

void ode_finalizacion()
{
 dBodyDestroy( sphereBody );
 dGeomDestroy( sphereGeom );
 dGeomDestroy( groundGeom );
 dJointGroupDestroy( contactJointGroup );
 dSpaceDestroy( space );
 dWorldDestroy( world );
 dCloseODE();
}

Por último sencillamente liberamos uno a uno los distintos elementos que hemos ido creando en orden inverso.

Antes de finalizar, y una vez que hemos visto como funciona ODE, revisamos la función de irrlicht de actualización.

void irrlicht_actualizacion()
{
    dReal* odePosition = (dReal*)dGeomGetPosition( sphereGeom );
    vector3df newIrrlichtPosition;
    newIrrlichtPosition.set( (f32)odePosition[0], (f32)odePosition[1], (f32)odePosition[2] );
    sphereNode->setPosition( newIrrlichtPosition );
}

La pelota de Irrlicht no es más que el render final animado gracias a la física calculada por ODE, por lo tanto la posición de la pelota de Irrlicht debe ser actualizada de forma automática, y esto es gracias a esta función.
Simplemente obtenemos la posición actual del geom de la esfera de ODE (podríamos coger perfectamente la posición del body, ya que no hay diferencia como ya hemos comentado) y se la aplicamos a irrlicht. Como cada librería utiliza estructuras diferentes, sencillamente hay que transformar de una estructura a otra y aplicar al nodo esfera.