Introducción a Ogre3D

Comprobando la instalación

Aunque el proceso de instalación ha sido extremadamente complejo, no está de más comprobar que todo haya ido bien. Para comprobar que Ogre se ha instalado correctamente, crearemos una instancia del objeto Root y compilaremos el código.

Primero, crearemos un fichero de texto llamado main.cpp con el siguiente código:

#include <OgreRoot.h>

int main(int argc, char argv*[]) {
   Ogre::Root* root = new Ogre::Root("config/plugins.cfg", "config/ogre.cfg", "config/ogre.log");
}

Para poder compilarlo, crearemos un sencillo makefile con el siguiente código. Crea un fichero llamado Makefile y escribe el siguiente codigo:

CXX=g++
CXXFLAGS = -std=c++11 -ggdb $(shell pkg-config --cflags OGRE OIS)
LDLIBS = $(shell pkg-config --libs OGRE OIS)

main: main.cpp

Para compilarlo, abriremos un terminal en la carpeta donde tengamos el codigo fuente y ejecutaremos:

$ make

Esto compilara nuestro codigo. Si la compilación se realizó sin problemas, procederemos a ejecutar el binario:

$ ./main

Si todo ha ido bien, la traza de inicialización de Ogre debiera mostrarse por terminal y en el fichero "config/ogre.log". Hecho esto, habremos comprobado que hemos instalado correctamente Ogre en nuestro sistema. Ahora, continuemos construyendo nuestro ejemplo.

Obteniendo recursos multimedia

En Internet podemos encontrar gran cantidad de contenido con licencia creative commons que nos permitirá trabajar libremente con él, aunque siempre hay que mirar cuidadosamente qué tipo de licencia tiene el contenido multimedia que vamos a usar y respetarla en todo momento. Para nuestro primer ejemplo, utilizaremos la mascota de Ogre3D, Sinbad. Para ello, nos iremos al repositorio del proyecto, a la carpeta Samples/Media/Packs, donde podremos encontrar mallas listas para ser usadas. Nos descargaremos el pack llamadado Sinbad.zip. A continuación, crearemos una carpeta llamada media dentro del directorio de nuestro proyecto y descompromimos el contenido del archivo .zip allí.

Hecho esto, los siguientes pasos que nos quedan son crear un nodo y una entidad, adjuntar la entidad al nodo, así como crear un foco de luz y una cámara.

Creando nuestra escena

El siguiente paso que deberemos realizar será crear un fichero que permita saber a Ogre donde están los recursos multimedia. Dentro de la carpeta config crearemos un fichero llamado "resources.cfg" con el siguiente contenido:

[General]
FileSystem=media

Esto simplemente le indica a Ogre que dentro de la carpeta media encontrara los recursos multimedia. Pero primero hay que parsear el fichero y cargar dichos recursos.

Cargando los recursos

(...)
#include <OgreResourceGroupManager.h>
#include <OgreConfigFile.h>

void load_resources(string resources_file) {
    Ogre::ConfigFile cf;
    cf.load(resources_file);

    Ogre::ConfigFile::SectionIterator seci = cf.getSectionIterator();

    Ogre::String secName, typeName, archName;
    while (seci.hasMoreElements()) {
      secName = seci.peekNextKey();
      Ogre::ConfigFile::SettingsMultiMap *settings = seci.getNext();
      Ogre::ConfigFile::SettingsMultiMap::iterator i;
      for (i = settings->begin(); i != settings->end(); ++i) {
        typeName = i->first;
        archName = i->second;
        Ogre::ResourceGroupManager::getSingleton()
          .addResourceLocation(archName, typeName, secName);
      }
    }

    Ogre::ResourceGroupManager::getSingleton()
      .initialiseAllResourceGroups();
}

int main(int argc, char *argv[])
{
  (...)
  load_resources("config/resources.cfg");
}

La función anterior abre el fichero y lo va recorriendo buscando claves. Cada clave indica el nombre de un directorio donde hay recursos multimedia. Estos directorios los recorre en el bucle for buscando archivos de los que saca el tipo, el nombre y los registra dentro del gestor de recursos (Ogre::ResourcerGroupManager). Tras registrar todos los recursos que haya encontrado, los inicializa.

Es importante que se invoque la función load_resources(string) antes que la función check_config(Ogre::Root) en el caso en el que usemos Ogre::Overlay. Si se invoca en orden contrario, el programa compilará correctamente, pero lanzará un error de segmento.

Este paso nos permitirá utilizar los recursos multimedia en nuestra escena. Pero primero, deberemos crearemos la cámara y un foco de luz.

Creando nuestra cámara

El objeto Ogre::Camera define la cámara de la escena. Este objeto es imprescindible, pues sin él no podremos ver nada en nuestra ventana. Para ello, añadiremos el siguiente código:

(...)
#include <OgreCamera.h>

Ogre::Camera* create_camera(Ogre::Root* root) {
  Ogre::Camera* camera = root->getSceneManager("SceneManager")->createCamera("Camera");

  camera->setPosition(Ogre::Vector3(0, 160, 160));
  camera->lookAt(Ogre::Vector3(0,0,0));
  camera->setNearClipDistance(5);
  camera->setFarClipDistance(10000);


  Ogre::Viewport* viewport = root->getAutoCreatedWindow()->addViewport(camera);
  viewport->setBackgroundColour(Ogre::ColourValue(0, 0, 0));

  camera->setAspectRatio(Ogre::Real(viewport->getActualWidth()) / Ogre::Real(viewport->getActualHeight()));

  return camera;
}

int main(int argc, char *argv[]){
 (...)
  Ogre::Camera* camera = create_camera(root);
}

En esta ocasión, utilizamos el gestor de escena para crear una cámara asociada a él. Ogre permite tener mas de un gestor de escena, e ir cambiando entre ellos. Es por esta razón que hay que asociar la cámara a un gestor de escena.

El objeto Ogre::Viewport es el equivalente al frustrum de la cámara; es decir, indica la región que sera renderizada.

Una vez inicializada la cámara, es importante añadir una fuente de luz, ya que por defecto el mundo se haya en tinieblas:

void create_light(Ogre::Root* root){
  Ogre::SceneManager* manager = root->getSceneManager("SceneManager");
  manager->setShadowTechnique(Ogre::SHADOWTYPE_STENCIL_ADDITIVE);

  manager->setAmbientLight(Ogre::ColourValue(0.25, 0.25, 0.25));

  Ogre::Light* light = manager->createLight("MainLight");
  light->setPosition(20, 80, 50);
  light->setCastShadows(true);

}

int main(int argc, char *argv[])
{
  (...)
  create_light(root);
}

El método Ogre::SceneManager:setShadowTechnique(Ogre::ShadowTechnique) asigna la técnica de generación de sombras que sera usada por este gestor de escena. El tipo Ogre::ShadowTechnique es un tipo enumerado que permite seleccionar una técnica de generación de sombra.

Una vez que tenemos listo todo lo necesario para que pueda renderizarse nuestra escena, procederemos a crearla añadiendo nodos de escena.

Añadiendo nodos a nuestra escena

La forma en que Ogre desencapsula el grafo de escena y los objetos de los mismos es mediante el objeto Ogre::SceneNode. Los objeto SceneNode son los cuerpos gráficos genéricos sobre los que se realizarán las operaciones de traslación, rotación, etc. A estos nodos hay que adjuntarles un contenido, típicamente un objeto de tipo Ogre::Entity, aunque se pueden adjuntar otros tipos de objetos. Veamos el código:

(...)
#include <OgreEntity.h>
#include <OgreVector3.h>
#include <OgreMath.h>
#include <OgreMeshManager.h>

(...)
Ogre::SceneNode* get_node_by_name(Ogre::SceneManager* manager,
                                 Ogre::String node_name="") {
  Ogre::SceneNode* node;
  if (node_name.empty())
    node = manager->getRootSceneNode();
  else
    node = manager->getSceneNode(node_name);

  return node;
}

Ogre::Entity* create_entity_and_attach(Ogre::SceneManager* manager,
                                       Ogre::String name,
                                       Ogre::String mesh,
                                       Ogre::String target_node="",
                                       bool cast_shadows=true){
  Ogre::SceneNode* node = get_node_by_name(manager, target_node);
  Ogre::Entity* entity = manager->createEntity(name, mesh);
  entity->setCastShadows(cast_shadows);

  node->attachObject(entity);
  return entity;
}
Ogre::SceneNode* create_node(Ogre::SceneManager* manager,
                             Ogre::String name,
                             Ogre::String parent="") {
  Ogre::SceneNode* parent_node = get_node_by_name(manager, parent);

    return parent_node->createChildSceneNode(name);
}


Ogre::SceneNode* create_node_and_entity(Ogre::SceneManager* manager,
                                        Ogre::String name,
                                        Ogre::String mesh,
                                        Ogre::String parent="") {
  Ogre::SceneNode* node = create_node(manager, name, parent);
  Ogre::Entity* entity = create_entity_and_attach(manager, name, mesh, name);
    return node;
}

int main(int argc, char *argv[]) {
(...)
  Ogre::SceneNode* node = create_node_and_entity(scene_manager, "SinbadNode", "Sinbad.mesh");

}

Las funciones anteriores son funciones de alto nivel que encapsulan una funcionalidad relacionada con el nombre de la función. Aunque parezca mucho código, las sentencias mas importantes son:

parent_node->createChildSceneNode(name);

La sentencia anterior genera un nodo hijo cuyo nodo raíz es el nodo padre(parent_node). Esto es muy útil, ya que todas las transformaciones que sufra el padre tambien las sufrirá el hijo. De esta forma, podemos generar cuerpos compuestos y mover únicamente el nodo padre, sabiendo que los nodos hijos se moverán de igual forma.

Ogre::Entity* entity = manager->createEntity(name, mesh);

Esta sentencia crea una instancia de un objeto tipo Ogre::Mesh. La clase Ogre::Mesh almacena los datos necesarios para representar un objeto tridimensional. Dicha malla la hemos cargado anteriormente en el método load_resources(std::string).

Por último, utilizamos dos funciones muy similares para obtener la referencia a los SceneNode por su nombre:

Ogre::SceneManager::getRootSceneNode();
Ogre::SceneManager::getSceneNode(Ogre::String node_name);

El primero devuelve la referencia al nodo raíz del grafo de escena y el segundo al nodo que coincida con el nombre que se le pase por argumentos.

Por último, debemos añadir la sentencia que renderiza la escena. Para poder parar nuestra aplicación, en este documento se hará uso de la clase Ogre::WindowEventListener, que cuenta con el método WindowClosing y windowClosed. Para ello crearemos una clase y haremos que herede de Ogre::WindowEventListener:

#include <OgreWindowEventUtilities.h>

class WindowManager: public Ogre::WindowEventListener{
  Ogre::RenderWindow* window_;

public:
  bool exit;

  WindowManager(Ogre::RenderWindow* window){
    window_ = window;
    exit = false;
    Ogre::WindowEventUtilities::addWindowEventListener(window, this);
  }

  bool windowClosing(Ogre::RenderWindow* window){
    Ogre::LogManager::getSingleton().logMessage("Closing window...");
    exit = true;
    return true;
  }

  void windowClosed(Ogre::RenderWindow* window) {
    Ogre::LogManager::getSingleton().logMessage("Window closed.");
    exit = true;
  }

int main(int argc, char *argv[])
{
  (...)
  WindowManager windowManager(window);

  while(!windowManager.exit){
    root->renderOneFrame();
    Ogre::WindowEventUtilities::messagePump();
  }
}
};

La clase Ogre::WindowEventListener se encarga de gestionar todos los eventos relacionados con una ventana.

Ogre::WindowEventUtilities::addWindowEventListener(window, this);

La sentencia anterior se encarga de registrar la instancia de la clase WindowManager como gestor de todos los eventos producidos en window. Los métodos windowClosed y windowClosing se ejecutan cuando se detecta un evento de cierre de ventana; es decir, cuando se pulsa el botón de salir de la esquina superior derecha de la ventana.

Se ha añadido el bucle principal a la función principal. El método renderOneFrame indica a Ogre que debe actualizar los cuerpos gráficos de la escena, muestras que la sentencia messagePump() debe ser llamada una vez por frame, ya que actualizará todas las ventanas que hayan sido registradas.

Hecho esto, habremos terminado. Sólo faltará compilar y ejecutar nuestra aplicación. El resultado deberá ser parecido al de la siguiente figura.

El código final debe parecerse al del fichero que podremos encontrar en el repositorio de este tutorial