Head-Up Display

When rendering a scene you usually want to overlay them with useful information about the player status like how fast you're going or how well your health is doing. This is basically the job of a HUD.
In Orxonox we have a base class for all HUD objects that makes life a lot easier. There is also a class to group multiple HUD elements together. More information about that can be found in the framework section.

Elements

This table lists all currently available general purpose HUD elements and gives a short description.

Name	Description
SpeedBar	Shows a value between 0 and 1 as a bar. Supports colouring.
OverlayText	Shows an arbitrary text in colour.

Framework

We like to keep things as generic as possible. So we naturally have a HUD that can be loaded per XML. In order to achieve that, every HUD element derives from OrxonoxOverlay?. This allows to configure basic parameters. Element specific values can also be loaded from XML, but have to be written by hand. To get more information about how to load with XML in Orxonox, visit this page. In short, loading an entire HUD group could look like this (incomplete example!):

<OverlayGroup name = "HUD" scale = "1, 1">

  <HUDSpeedBar
   name       = "SpeedBar1"
   size       = "0.35, 0.05"
   position   = "0.0 , 1.0 "
   value      = 0
  />

  <HUDRadar
   name          = "Radar"
   size          = "0.17, 0.17"
   position      = "0.5, 1.0"
  />

</OverlayGroup>

Pretty self-explanatory, right? The OverlayGroup represents a collection of elements that derive from OrxonoxOverlay. Such a group can be transformed with limited capabilities.

OrxonoxOverlay

This is the very base class. Always derive from this and try to embrace it
It supports the following basic transformations:

• setPosition/scroll (absolute/relative)
• setRotation/rotate
• setSize/scale
• hide/show

The relative versions are implemented as ConsoleCommand too so you can use them in the Shell.

There is something very important to notice: When changing the resolution of your screen, the OrxonoxOverlay scales with it, so relatively speaking it doesn't scale at all. This is however a problem for round objects like the HUDRadar, which get egg like. To prevent this, there is an XML parameter called 'correctAspect'. If this is set, the OrxonoxOverlay will keep the a round thing round, but the scaling will of course not anymore be exactly as you tell (an average value is computed). getActualSize() will return the real, corrected size.

The following XML parameters can be used when loading:

• size
• pickPoint (explained below)
• position
• rotation
• correctAspect
• background (background material name)

The transformation order is unfortunately fixed by the underlaying Overlay from Ogre:

• 1. Scale
• 2. Rotate
• 3. Translate

This implies that you cannot use correctAspect in any way when a rotation other than a multiple of 90° is applied (it simply gets deactivated otherwise).
About pickPoint: This parameter helps you aligning an element. The coordinate you supply here are relative to the element itself and they serve as the the reference point when setting position. Example: You want to put your element in the middle of your screen at the right border. You will have to set pickPoint to "1,0.5" and position to "1,0.5" too. In most cases the values will equal.

OverlayGroup

Very simple container that can group multiple OrxonoxOverlays to hide/show them at once. It implements the following transition methods:

• hide/show
• scale/setScale
• scroll/setScroll

setScroll only uses relative coordinates because you cannot actually position an OverlayGroup since it doesn't really have an origin at all. You have to image it only as grouping operator. That also means calling scale will scale each element for itself! ConsoleCommands: toggleVisibility, scaleGroup, scrollGroup

Screen Coordinates

The OrxonoxOverlay uses very simple screen coordinates: "0,0" is the upper left corner, "1,1" the lower right one. Any coordinate outside this system is considered valid too and will behave as expected.