Overlays

Overlays permitem que elementos 2D ou 3D sejam renderizados no topo do conteúdo normal da cena para criar efeitos como heads-up displays (HUD's), sistemas de menus, painéis de status, etc. O painel de estatísticas que é exibido no OGRE é um exemplo de overlay:

Como se vê na imagem, o painel de estatísticas "FPS" e a logo do OGRE se sobrepõem a qualquer objeto da cena através de overlay.

Overlays podem conter elementos bi ou tridimensionais. Elementos bidimensionais são usados para HUD's e os tridimensionais podem ser usados para criar cockpits, o braço segurando uma arma que costumeiramente se vê em games FPS ou qualquer outro objeto 3D que se deseje renderizar no topo de todo o resto da cena visível.

Em jogos de simulação de voo, a cena do mundo exterior, fora da cabine do piloto, é atualizada constantemente, de acordo com a movimentação do avião. O cockpit pode ser renderizado como um elemento 3D que se sobrepõe ao resto da cena.

Overlays podem ser criados com o método SceneManager::createOverlay() [obs.: esse método não consta na documentação! Ver.] ou através de sua definição em um script .overlay. O uso de scripts é mais prático por que eles podem ser alterados dinamicamente (sem a necessidade de recompilar o código!).

Observe que é possível definir tantos overlays quanto se queiram: eles começam seu ciclo de vida escondidos e podem ser exibidos pela chamada ao seu método show(). Também é possível exibir múltiplos overlays simultaneamente e sua ordem de aparição (em profundidade, no eixo Z) é definida pelo método Overlay::setZOrder().

Criando elementos 2D

A classe OverlayElement abstrai os detalhes de elementos 2D que são adicionados a overlays. Todos os itens que podem ser incorporados a overlays são derivados dessa classe. É possível (e aconselhável) que usuários de OGRE definam suas próprias subclasses de OverlayElement, que forneçam seus próprios controles de usuário.

As características-chave em comum de todos os OverlayElements são propriedades como tamanho, posição, nome do material básico, etc. Subclasses estendem essas características afim de incluir propriedades mais complexas e comportamento.

Uma subclasse importante - que já vem com OGRE - da classe OverlayElement é a classe OverlayContainer. A única diferença entre as duas classes é que OverlayContainer pode conter outros OverlayElements, agrupando-os (permitindo que sejam movidos em conjunto, por exemplo)  e fornecendo a eles coordenadas de origem local para facilitar a formação do agrupamento.

Outra classe importante é OverlayManager. Sempre que uma aplicação desejar criar um elemento 2D para adicioná-lo a um overlay (ou a um container de overlays - OverlayContainer), ela deve chamar o método OverlayManager::createOverlayElement. 

O tipo do elemento que se deseja criar é indicado com uma string. A razão para tal é que isso permite que plugins adicionem novos tipos de OverlayElements que podem ser criados sem que seja necessário referenciar suas bibliotecas. 

Por exemplo, para criar um painel (uma área plana retangular que contém outros OverlayElements), você pode chamar o método OverlayManager::getSingleton().createOverlayElement("Panel", "myNewPanel");

Adicionando elementos 2D ao Overlay

Somente OverlayContainers podem ser adicionados diretamente a um Overlay. Isso por que cada level do container estabelece a Z-ordem dos elementos agrupados nele. Assim, se você aninhar muitos containers, os internos terão uma Z-ordem mais alta que os externos para assegurar que eles são exibidos corretamente. Para adicionar um elemento (como o painel criado no comando anterior) a um overlay, simplesmente chame Overlay::add2D.

Para adicionar elementos a um container, o método é OverlayContainer::addChild. Tais elementos adicionados podem ser instâncias de OverlayElement ou de OverlayContainer. Lembre-se que a posição de um elemento filho é relativa ao canto superior direito do seu pai.

Um pouco de coordenadas 2D

OGRE permite que elementos sejam posicionados e dimensionados com base em 2 sistemas de coordenadas: baseadas em pixels e coordenadas relativas.

Pixel Mode

Este modo é útil quando se deseja especificar um tamanho exato para os itens overlay e não há preocupação quanto aos itens diminuírem de tamanho na tela se a resolução for aumentada (de fato, isso geralmente é o que se deseja). 

Nesse modo, o único jeito de posicionar algo no meio ou no canto direito ou inferior da tela seguramente para qualquer resolução é com o uso das opções de alinhamento, ao passo em que no modo relativo basta utilizar as coordenadas relativas.

O pixel mode é bem simples: o topo esquerdo da tela é a coordenada (0, 0) e o canto inferior direito depende da resolução. Como mencionado anteriormente, você pode utilizar as opções de alinhamento para fazer com que as origens das coordenadas horizontal e vertical sejam canto direito ou inferior ou topo da tela se você quiser posicionar itens em pixels sem saber a resolução.

Relative Mode

Este modo é útil quando se quer que os itens do overlay tenham o mesmo tamanho na tela não importa qual seja a resolução. No modo relativo, o topo esquerdo da tela tem coordenada (0, 0) e o canto inferior direito tem coordenada (1, 1). Assim, se posicionarmos um elemento na posição (0.5, 0.5), seu canto superior esquerdo é posicionado exatamente no meio da tela, não importa em que resolução a aplicação esteja rodando.

O mesmo princípio se aplica ao dimensionamento dos itens: se você setar a largura de um item para 0.5, ele cobrirá metade da tela.

É importante observar que um elemento com dimensões (0.25, 0.25) não será um quadrado, mas sim tomará exatamente 1/16 da tela em termos de área. Isso se deve ao fato de o aspect ratio da tela ser normalmente 1.3333 : 1 (largura : altura). Se você quiser um elemento com aparência de quadrado, deverá levar em conta o aspect ratio da tela e compensá-lo usando, por exemplo, (0.1875, 0.25) em vez de (0.25, 0.25).

Transformando Overlays

Outra característica bem interessante de overlays é que eles podem rotacionar, rolar e ser escalados como um todo. Isso pode ser utilizado para zooms em menus, derrubá-los dentro ou fora da tela e outros efeitos legais. Veja Overlay::scroll, Overlay::rotate e Overlay:scale para mais informações.

Scripting Overlays e sistemas GUI

Overlays podem ser definidos em scripts. Essa funcionalidade será coberta em uma postagem futura e é explicada no manual OGRE na seção 3.4.

Overlays são projetados apenas para elementos de tela não interativos. Mesmo assim, você pode usá-los para o desenvolvimento de uma GUI grosseira. Para uma solução de desenvolvimento mais completa, o manual recomenda o uso do CEGui.