= 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. [[br]]
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. [[br]]

== Elements ==
This table lists all currently available HUD elements and gives a short description.
|| Name || Description ||
||      ||             ||
|| SpeedBar || Shows a value between 0 and 1 as a bar. Supports colouring. ||

== 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 [wiki: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 [wiki:XMLPort 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. [[br]]

=== OrxonoxOverlay ===
This is the very base class. Always derive from this and try to embrace it ;) [[br]]
It supports the following basic transformations:
 * setPosition/scroll (absolute/relative)
 * setRotation/rotate
 * setSize/scale
 * hide/show
The relative versions are implemented as [wiki:ConsoleCommand] too so you can use them in the Shell. [[br]][[br]]

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. [[br]][[br]]

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). [[br]]
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!
[wiki:ConsoleCommand 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.