Sistema de Overlays

De IberOgre

A priori puede parecer extraño dedicarle un artículo completo a gráficos 2D en una wiki sobre desarrollo de videojuegos 3D pero es absolutamente necesario. Existen muchos elementos en un videojuego que pueden representarse con mayor facilidad en dos dimensiones como la interfaz de usuario (graphical user interface o GUI) y los indicadores del jugador (heads up display o HUD). En Ogre, estos elementos bidimensionales reciben el nombre de overlays y en este texto aprenderemos lo básico para comprenderlos, crearlos y poder gestionarlos.

Requisitos previos

El sistema de overlays de Ogre es relativamente sencillo y los requisitos previos no son demasiado elevados. No obstante, nos basaremos en varios de los artículos de IberOgre para trabajar, por tanto es recomendable que los domines con carácter previo.

• Gestión de recursos: los overlays funcionan como un tipo de recurso más dentro de Ogre. Para comprender los mecanismos que nos permiten cargar overlays deberás conocer la forma en la que gestiona Ogre los recursos de forma general.
• Materiales: algunos elementos del sistema de overlays utilizan materiales para ser renderizados de cierta manera. Hablaremos de materiales suponiendo que el lector los conoce con cierta profundidad, te recomendamos acudir a dicho artículo en primer lugar.
• Manejo básico de OIS: el ejemplo final de este artículo será interactivo así que debes saber cómo funciona la biblioteca de gestión de entrada OIS.

Conceptos básicos

Ejemplo de HUD en el videojuego Free Padel

El nombre overlay significa que se posiciona ("lay") encima del resto ("over") y resume perfectamente su funcionamiento básico. Los overlays son elementos bidimensionales que se renderizan encima del resto de la escena 3D. Internamente no son más que grupos de quads (cuatro vértices) con materiales asociados que se muestran de frente a la cámara en todo momento. Los overlays se agrupan en una cola de renderizado especial la cual se renderiza en último lugar y, por ello quedan superpuestos sobre el resto de elementos.

Tipos

De forma general, existen dos tipos de overlays:

• Gestionados: aquellos que definimos mediante scrips de extensión .overlay similares a los de sistemas de partículas o materiales. Normalmente son utilizados para mostrar texto fijo y sencillo.
• No gestionados: este tipo engloba cualquier overlay utilizado para GUIs o HUDs con funcionalidades interactivas.

No interactivos

Interfaz interactiva en un juego de estrategia en tiempo real

El sistema de overlays de Ogre sólo ofrece el apartado del renderizado, recuerda que Ogre no es un completo motor de videojuegos. Esto implica que nuestros overlays no tendrán capacidades interactivas de forma inmediata, no podremos hacer click sobre ellos, arrastrarlos o interactuar de cualquier manera. Si bien es cierto que podemos combinar OIS con los overlays, si deseamos llegar más allá de sencillos paneles mínimamente interactivos, lo mejor es recurrir a una biblioteca específica.

CEGUI es una biblioteca libre que ofrece un completo sistema para construir y manejar interfaces. Es completamente independiente del motor de renderizado por lo que puedes utilizarlo con Ogre, DirectX, OpenGL y potencialmente otros sistemas. Además, tampoco depende de ningún sistema de entrada e integrarlo con OIS es bastante trivial. No obstante, en este artículo sólo nos centraremos en los overlays.

Estructura de los Overlays

En esta sección conoceremos las clases que intervienen en el sistema de overlays de Ogre así como la estructura de los mismos. Más adelante, haremos un completo recorrido por las propiedades de todos los elementos disponibles para que puedas construir tus propios paneles ajustándose a tus necesidades.

Como puedes ver en el esquema que aparece más abajo, un overlay es simplemente una jerarquía de contenedores y elementos de texto dispuestos en un espacio bidimensional con respecto a la pantalla. En la raíz de la jerarquía siempre debe encontrarse un contenedor y los elementos de texto siempre han de ser nodos hoja. Por otra parte, un contenedor puede tener cualquier número de hijos ya sean otros contenedores o texto.

Estructura de un overlay en Ogre

Clases implicadas

HUD en la demos oficiales de Ogre

Nos disponemos a listar las clases implicadas en los overlays de Ogre a modo de presentación, con el objetivo de que el lector cree un mapa mental del funcionamiento del sistema.

• OverlayManager: clase hija de ResourceManager encargada de gestionar los recursos de tipo overlay. A través de dicha clase, podremos cargar paneles a través de scripts .overlay.
• OverlayElement: clase abstracta que modela todos los elementos que forman los overlays, ya sean paneles o texto.
  • OverlayContainer: clase hija de OverlayElement que modela de forma genérica los contenedores de los paneles.
    • PanelOverlayElement: clase especializada que funciona como un contenedor pero posibilita la inclusión de materiales.
    • BorderPanelOverlayElement: especialización de PanelOverlayElement que añade una textura adicional para emplear bordes. Resulta útil cuando el panel es demasiado grande o puede variar de tamaño, tendríamos una textura basada en tiles para el interior mientras el borde es independiente.
  • TextAreaOverlayElement: elemento sobre el que podemos renderizar texto con una fuente determinada.

Los elementos de texto utilizan fuentes para renderizar el texto y, por tanto, necesitamos conocer las clases implicadas en la gestión de tipografías en Ogre. Más adelante aprenderemos a definir fuentes y cargarlas en nuestra aplicación.

• Font: clase hija de Resource encargada de modelar un recurso de tipo fuente.
• FontManager: gestor de recursos para el tipo fuente. Carga la definición de cada fuente de scripts de extensión .fontdef los cuales indican el fichero .ttf a utilizar, el tamaño y otras opciones adicionales.

Scripts

Como hemos mencionado anteriormente, los overlays pueden definirse en sripts de texto plano con extensión .overlay. En esta sección vamos a tomar una primera aproximación a la sintaxis de dichos scripts. Para ello simplemente nos limitaremos a traducir el diagrama que ilustraba la estructura de los overlays para poderlo utilizar en Ogre. Posiblemente no comprendas todas las propiedades pero en las secciones posteriores las repasaremos todas.

OverlayEjemplo
{
	zorder 100
 
	container Panel(OverlayContainerA)
	{
		metrix_mode pixels
		left 0
		top 0
		width 800
		height 600
 
		container Panel(OverlayContainerB)
		{
			metrix_mode pixels
			top 0
			right 0
			width 400
			height 300
 
			element textArea(TextAreaOverlayElementA)
			{
				metrics_mode relative
				left 0
				top 0.6
				width 1.0
				height 0.4
 
				font_name ubuntu
				char_height 0.5
				colour 1.0 0.0 0.0
				caption Hola muy buenas
			}
		}
 
		container Panel(OverlayContainerC)
		{
			metrix_mode pixels
			top 0
			right 0
			width 400
			height 300
 
			element textArea(TextAreaOverlayElementB)
			{
				metrics_mode relative
				left 0
				top 0.6
				width 1.0
				height 0.4
 
				font_name ubuntu
				char_height 0.5
				colour 0.0 1.0 0.0
				caption Espero que te esté gustando este artículo
			}
		}
 
		container Panel(OverlayContainerD)
		{
			metrix_mode relative
			left 0
			top 0.6
			width 1.0
			height 0.4
 
			element TextArea(TextAreaOverlayElementC)
			{
				metrics_mode pixels
				left 0
				top 0
				width 800
				height 200
 
				font_name ubuntu
				char_height 0.5
				colour 0.0 0.0 1.0
				caption Estás aprendiendo a usar los overlays
			}
		}
 
 
	}
}

Tal y como puede observarse, vamos anidando contenedores unos dentro de otros hasta que colocamos un elemento de texto. Los elementos siempre deben ser nodos hoja mientras que el nodo raíz siempre debe ser un contenedor.

Propiedades generales

Iremos mostrando las propiedades de los elementos que forman un overlay en forma de tabla. Citamos nombre de la propiedad, formato en el que se especifican los valores (sin los ángulos "<>", claro está) y una breve descripción de la utilidad de dicho atributo. En esta primera tabla vemos la única propiedad que encontramos en el nivel más general del script de un overlay, la profundidad.

Como vimos en el ejemplo inicial, un overlay siempre comienza de la misma manera:

OverlayPrueba2
{
	zorder 500
 
	...
}

Propiedades de elementos y contenedores

Las siguientes propiedades se pueden aplicar tanto a elementos sencillos (texto) como a contenedores ya que se refieren a sus dimensiones, posicionamiento y material asociado.

En el siguiente ejemplo trabajamos con un sencillo panel para mostrar las propiedades generales:

OverlayPrueba3
{
	...
 
	container Panel(Panel1)
	{
		metrix_mode relative
		left 0.2
		top 0.4
		width 1.0
		height 0.4
		material panelInactivo
	}
 
	...
}

Propiedades de contenedores

A continuación se listan dos grupos de propiedades relacionadas con los contenedores.

Panel (PanelOverlayElement)

Este primer grupo engloba propiedades disponibles en todos los contenedores de tipo Panel.

En el siguiente ejemplo utilizamos las propiedades específicas de los paneles.

OverlayPrueba4
{
	...
 
	container Panel(Panel1)
	{
		metrix_mode pixels
		left 200
		top 325
		width 400
		height 75
		material metal
		tiling 0 3 3
	}
 
	...
}

BorderPanel (BorderPanelOverlayElement)

Los contenedores de tipo BorderPanel cuentan con las propiedades de los paneles sencillos además de las que aparecen en la siguiente tabla:

En el siguiente ejemplo nos limitaremos a añadir la propiedad border_size de los paneles con borde.

OverlayPrueba4
{
	...
 
	container BorderPanel(borderPanel1)
	{
		metrix_mode pixels
		left 100
		top 75
		width 230
		height 76
		material brillo
		tiling 0 3 3
		border_size 5 10 5 10
	}
 
	...
}

Propiedades de áreas de texto

Las propiedades correspondientes a las áreas de texto son bastante sencillas. Simplemente especificamos el nombre de la fuente y varios parámetros relacionados con tamaño y color.

Las propiedades de las áreas de texto son bastante intuitivas y muy fáciles de entender, a continuación mostramos un ejemplo.

OverlayPrueba6
{
	...
 
	element TextArea(texto1)
	{
		metrix_mode pixels
		left 100
		top 20
		height 40
		width 60
		caption Esto es una prueba de propiedades de elementos
 
		font_name ogreFont
		colour_top 1.0 0.4 0.0
		colout_top 0.4 1.0 0.0
	}
 
	...
}

Fuentes

Textura con todos los glifos para una fuente

Las fuentes en Ogre son un tipo de recurso utilizado para texturizar elementos de la clase TextAreaOverlayElement aunque tienen más aplicaciones. Existen dos tipos de fuentes, las que cargamos a partir de ficheros .ttf (truetype) y las que cuyos glifos se colocan directamente en una imagen. Para el primer tipo, Ogre necesita un tiempo de procesamiento mayor ya que debe generar automáticamente los glifos. No obstante, para el usuario es más cómodo y rápido utilizar fuentes truetype que diseñar una plantilla con todos los glifos. Por esta razón, es común utilizar fuentes truetype durante el desarrollo y cambiar a plantillas de glifos en una textura cuando el juego pasa a producción.

Con el objetivo de reducir la complejidad, en IberOgre emplearemos fuentes truetype libres para los ejemplos. La forma en la que Ogre renderiza los glifos de las fuentes viene definida por scripts de extensión .fontdef. El nombre de la fuente que utilizamos en los elementos de texto no hace referencia al fichero ttf sino al nombre que le asignamos en el script fontdef. Cuando utilizamos una fuente en un área de texto debemos asegurarnos que el recurso fuente está disponible en el sistema o bien porque esté en el mismo grupo de recursos o bien porque ha sido cargado de forma manual.

En primer lugar, listaremos las propiedades de los scripts fontdef en una tabla similar a la de los overlays para después ofrecer un ejemplo práctico.

A continuación, un ejemplo de un script .fontdef en el que definimos una fuente truetype llamada "ubuntu".

ubuntu
{
	type truetype
	source ubuntu.ttf
	size 20
	resolution 96
	antialias_colour false
}

Si deseáis más información sobre las propiedades y sintaxis acerca de los scripts de overlays y fuentes, podéis consultar la traducción del manual oficial de Ogre.

Creación y gestión de Overlays

En esta sección aprenderemos a cargar desde código C++ nuestros overlays descritos en forma de scrips, los mostraremos, ocultaremos y modificaremos algunos de sus atributos. Ogre permite crear scripts desde cero a través de código, probablemente utilizando los mismos métodos a los que Ogre recurre tras procesar los scripts .overlay. No obstante, eso puede ser una mala idea ya que, una sencilla modificación de un atributo para darle una mejor apariencia, implicaría una recompilación del módulo afectado y un enlazado posterior. Cuando el código de nuestra aplicación crece considerablemente, es algo que conviene evitar ya que ralentiza demasiado el flujo de trabajo.

Lo mejor es definir los overlays desde scripts y modificar atributos puntuales desde el código siempre que sea extrictamente necesario.

Carga de Overlays

Los overlays utilizan recursos de tipo material y fuente entre sus atributos. Esto implica que debemos asegurarnos que dichos recursos estén disponibles antes de tratar de mostrar un overlay. Para recuperar una referencia al overlay dentro de nuestro sistema podemos hacer uso del método getByName de la clase OverlayManager:

Ogre::Overlay* Ogre::OverlayManager::getByName(const Ogre::String& name);

• const Ogre::String& name: nombre del overlay que le asignamos en su correspondiente script. Por supuesto, este nombre debía ser único o se produciría un error en la inicialización.

Es posible que deseemos acceder a elementos concretos dentro de un overlay como paneles o áreas de texto. En tal caso deberíamos hacer uso del método getOverlayElement de la clase OverlayManager tal y como se muestra a continuación:

Ogre::OverlayElement* Ogre::OverlayManager::getOverlayElement(const Ogre::String& name, bool isTemplate = false);

• const Ogre::String& name: nombre del elemento del overlay, debe ser único en todo el sistema. No obstante, se suele utilizar el formato "nombreOverlay/nombreElemento" para evitar colisiones de nombres.
• bool isTemplate: true si el elemento es una plantilla y false en caso contrario. En IberOgre no vamos a ver las plantillas así que este atributo no nos interesa por el momento.

El método getOverlayElement devuelve un puntero a OverlayElement, la clase más generica. Si quisiéramos llamar a un método de la clase más especializada a la que pertenece el elemento nos veríamos obligados a hacer un static_cast como veremos en el ejemplo a continuación.

Es una buena idea comprobar si nuestro overlay está debidamente inicializado antes de intentar mostrarlo encima de la escena. En tal caso podríamos recurrir al método isInitialised de la clase Overlay:

bool Ogre::Overlay::isInitialised(void) const;

Una vez estemos seguros de que todo ha ido bien podemos proceder a mostrar el overlay encima de nuestra escena. Llegados a ese momento basta con llamar al método show de la clase Overlay.

void Ogre::show(void);

Vamos a incluir un ejemplo mostrando todo el proceso de carga del script, recuperación de los elementos y visualización del overlay. En primer lugar mostramos el script completo junto a una sencilla definición para el material y la fuente utilizada.

OverlayInfo
{
	zorder 300
 
	container Panel(panelInfo)
	{
		metrics_mode relative
		left 0.25
		top 0.7
		width 0.5
		height 0.2
		material panelInfoM
 
		container TextArea(texto)
		{
		    metrics_mode relative
		    left 0.05
		    top 0.05
		    width 0.90
		    height 0.2
 
		    font_name ubuntu
		    colour 0 0 0
		    caption Info general
		}
	}
}
 
...
 
ubuntu
{
	type truetype
	source ubuntu.ttf
	size 10
	resolution 96
}
 
...
 
material panelInfoM
{
    technique
    {
        pass
        {
            diffuse 1 0 0
        }
    }
}

El código encargado de cargar los elementos del overlay y mostrar el panel completo es el siguiente:

// Tomamos el overlay
Ogre::OverlayManager* gestorOverlay = Ogre::OverlayManager::getSingletonPtr();
 
// Recuperamos el overlay y sus elementos
Ogre::Overlay* overlay = gestorOverlay->getByName("OverlayInfo");
 
Ogre::PanelOverlayElement* panelInfo = static_cast<Ogre::PanelOverlayElement*>(gestorOverlay->getOverlayElement("panelInfo"));
Ogre::TextAreaOverlayElement* tituloInfo = static_cast<Ogre::TextAreaOverlayElement*>(gestorOverlay->getOverlayElement("tituloInfo"));
 
if (overlay->isInitialised())
	cout << "Overlay inicializado" << endl;
else
	cout << "Overlay no inicializado" << endl;
 
// Mostramos el overlay
overlay->show();

Gestión de Overlays

En este pequeño apartado ofreceremos algunos métodos para modificar atributos de los overlays y sus elementos una vez estén cargados e inicializados. Por supuesto, para una guía completa lo mejor es acudir a la documentación oficial de las clases implicadas (referenciada en puntos anteriores).

En primer lugar, cuando deseemos ocultar un overlay simplemente hemos de colocar una llamada al método hide de la clase Overlay.

void Ogre::Overlay::hide(void);

Si deseásemos consultar su profundidad (posición z) recurriríamos al método getZOrder de la clase Overlay:

ushort Ogre::Overlay::getZOrder(void) const;

Una vez conocido, puede que deseemos cambiar la profundidad del overlay para mostrar otro elemento por encima o por debajo del mismo. En tal caso podemos emplear el método setZOrder de la misma clase.

void Ogre::Overlay::setZOrder(ushort zorder);

• ushort zorder: nueva profundidad del overlay.

Si queremos consultar las dimensiones de un elemento, podemos hacer uso de cualquier de los siguientes métodos de la clase OverlayElement:

Real Ogre::OverlayElement::getWidth(void) const;
Real Ogre::OverlayElement::getHeight(void) const;
Real Ogre::OverlayElement::getLeft(void) const;
Real Ogre::OverlayElement::getTop(void) const;

En caso de que deseemos modificar cualquiera de estos atributos en tiempo de ejecución, emplearíamos el correspondiente entre los siguientes métodos de la misma clase:

void Ogre::OverlayElement::setWidth(Ogre::Real width);
void Ogre::OverlayElement::setHeight(Ogre::Real height);
void Ogre::OverlayElement::setLeft(Ogre::Real left);
void Ogre::OverlayElement::setTop(Ogre::Real top);

• Ogre::Real width: nuevo ancho del elemento.
• Ogre::Real height: nuevo alto del elemento.
• Ogre::Real left: nueva distancia entre el lado izquierdo y la arista izquierda del elemento.
• Ogre::Real top: nueva distancia entre la parte superior del contenedor y la arista superior del elemento.

Podemos consultar el material de un elemento a través del método getMaterialName de la clase OverlayElement:

const Ogre::String& Ogre::OverlayElement::getMaterialName(void) const;

Si lo deseamos, es posible cambiar el material de un elemento a través del método setMaterialName de la clase OverlayElement.

void Ogre::OverlayElement::setMaterialName(const Ogre::String& matName);

• const Ogre::String& matName: nombre del nuevo material para el elemento.

Es posible acceder al sistema de medida que utiliza el elemento con getMetricsMode de OverlayElement:

Ogre::GuiMetricsMode getMetricsMode(void) const;

Se nos devuelve un enumerado que puede valer Ogre::GMM_RELATIVE u Ogre::GMM_PIXELS. En caso de que queramos modificar el sistema de medidas métricas haremos uso del método setMetricsMode tal y como se indica a continuación.

void Ogre::OverlayElement::setMetricsMode(Ogre::GuiMetricsMode gmm);

• Ogre::GuiMetricsMode gmm: nuevo sistema de medidas (relativo o en píxels).

Por último, resulta muy útil poder modificar el contenido de un área de texto. Normalmente podríamos utilizar estos elementos para mostrar puntuaciones que deben varíar con respecto avanza la partida, la forma de hacerlo es con el método setCaption de la clase OverlayElement.

void Ogre::OverlayElement::setCaption(const Ogre::DisplayString& text);

• const Ogre::DisplayString& text: nuevo texto que contiene el elemento, DisplayString es un alias para el tipo que ya conocemos String.

Ejemplo

Diagrama de clases del ejemplo de overlays

Ejemplo de overlays Pequeña aplicación que crea una escena similar al ejemplo de materiales incluyendo un panel informativo

En este ejemplo resumimos todo el contenido que hemos visto relacionado con los overlays en Ogre. Partimos del ejemplo del texto Materiales y le añadimos un panel informativo. Para los detalles básicos sobre el ejemplo, lo mejor es acudir al artículo original. En el ejemplo que nos ocupa, tenemos una escena con una bola a la que podemos cambiarle la textura mediante las teclas numéricas [1-5] ambas incluídas. Además, incorporamos un panel informativo en el que mostramos el nombre de la textura actual junto a los cuadros por segundo a los que se renderiza la aplicación.

En el método configurarOverlay recuperamos los elementos del panel y realizamos la comprobación de si ha sido inicializado debidamente. En cada iteración del bucle de juego actualizamos el atributo caption del área de texto que muestra los FPS con el nuevo valor. Por su parte, cuando pulsamos una tecla y cambiamos de material, actualizamos el área de texto con el nombre del material seleccionado.

Como práctica adicional deberías probar a modificar los atributos del script del overlay para darle una apariencia diferente. Incluso podrías mostrar otro tipo de información de la escena o incluir paneles en el resto de ejemplos de IberOgre.

Es importante recordar que los plugins necesarios no se distribuyen, debes copiar o enlazar los plugins de forma manual. Como se comenta en el resto de artículos, puedes encontrar más información sobre esto en "Creación de un entorno de trabajo multiplataforma". Para este ejemplo, solamente es necesario el plugin:

• RenderSystem_GL

Captura del ejemplo de overlays en ejecución

Conclusiones

Tras haber leído, comprendido, probado y modificado los ejemplos de este texto conocerás cómo funciona el sistema de overlays de Ogre. Serás capaz de definir tus propios paneles con elementos sencillos de texto y modificarlos en tiempo de ejecución para mostrar información dentro del juego tales como puntuaciones u otros anuncios.

Te habrás dado cuenta de que se trata de un sistema complejo, poco dado a la intactividad. Está hecho para mostrar información poco elaborada, si tus necesidades son mayores, deberías estudiar la biblioteca CEGUI.