The animation above explains what HUDs and layers are. A HUD is a 'container' that is placed in front of a camera. Then you will add one or more layers to this HUD. Each layer holds one texture (= one surface), so you can create images on a layer using the texture that has been attached to it.

You can control HUDs, layers and objects (images) seperately. So you can hide, show, move, rotate or scale a complete HUD, a seperate layer (with all its objects) only -or just a single image. Using one texture per layer keeps the surface count as low as possible -and that's no real limitation, since you can place many images on a single texture. (which is a good practice, because it minimizes the loading times and makes the use of texture space more efficient)

PERFORMANCE HINTS
Understanding the concept of layers is very important to ensure the best possible performance for your game. A layer is basically a texture surface. As you should know it is a good practice to keep the total surface count within your game as low as possible, since too many surfaces (~300 and above) will start to slow down the rendering on graphic cards.

You should try to place as many objects onto one layer, as possible. To do so, you should place all images you need on the same texture and apply this texture to the layer then. When you update a single object on a layer (by rotating, moving, etc.), only the affected object will be re-rendered. But: a layer needs to be re-rendered completely, when the vertex count of an object changes. This is the case, when you change the text of a text object, for example. So text objects that need to be updated freqcuently should always placed within a seperate layer. Placing all text objects that need to be updated on one layer together is also okay -the main goal is to avoid the re-rendering of a complete layer to update a single object only.

Layer_Handle% = HUD_CreateLayer ( HUD_Handle%,  [Font_Handle%|Texture_Handle%],  [zOrder%] )

This command creates an empty layer, attached to the specified HUD, that uses the specified font or texture. You will then be able to create objects (images, texts, etc.) on this layer using this texture. You can create unlimited layers per HUD, but you should be aware of the surface count (best to keep it as low as possible).

HUD_Handle%
Handle of a HUD as returned by HUD_Create( ).

Font_Handle% | Texture_Handle%
Handle of a font or texture loaded with HUD_LoadFont( ) or HUD_LoadImageResource( ). If no font or texture has been specified, this layer can be used to draw shapes only.

zOrder%
The depth order of this layer. When not specified, a new layer will be placed on top of existing ones. A layer's depth order can be changed at any time. Use values from 0 to ... , where higher values will place it in front and lower values will place it behind other layers.

HUD_SetLayerTexture ( Layer_Handle%,  Texture_Handle%  )

Using this command you can change a layer's texture at any time. All objects currently placed on this layer will use the specified texture then.

Layer_Handle%
Handle of a layer as created with HUD_CreateLayer( ).

Texture_Handle%
Handle of a texture loaded with HUD_LoadImageResource( ).

Texture_Handle% =  HUD_GetLayerTexture ( Layer_Handle% )

Returns the texture ID of the texture that is currently applied to this layer.

HUD_MoveLayer ( Layer_Handle%,  x_step%,  y_step%,  [relative%]  )

This command moves a complete layer with all its objects either absolute or relative to it's current rotation.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer( ).

x_step# , y_step#
The amount in pixels that the layer should be moved in x and y direction.

relative%

FALSE (default): The layer will be moved regardless of it's current rotation.

Hint: you can easily create scrolling backgrounds by moving layers. Place your images (or tiles) on the layer and shift the layer to the left, for example. After you moved the layer over a certain distance (maybe the width of a tile), reset the layer to the right, delete the leftmost image and put a new one to the right side of the layer. Of course, you can move complete HUDs, too, and move many layers at once. You can even place many layers on top of each other and move them by different speeds to achieve nice parallax scrolling effects.

HUD_PositionLayer ( Layer_Handle%,  x%,  y%,  onScreen%  )

Positions a layer on an absolute screen coordinate.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

x% , y%
The x or y screen coordinate (0 = left / top).

onScreen%

HUD_TurnLayer ( Layer_Handle%,  angle_step# )

Turns a layer at a specified angle step, counted from it's current rotation.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

angle_step#
Float value from 0.0 (no change) to 360.0 (full turn).

HUD_SetLayerRotation ( Layer_Handle%,  angle# )

Rotates a layer to an absolute rotation angle.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

angle#
Float value from 0.0 to 360.0

angle# =  HUD_GetLayerRotation ( Layer_Handle% )

Returns the current rotation angle of a layer.

x% =  HUD_GetLayerX ( Layer_Handle%,  [onScreen%]  )

Returns the current x-position of a layer.

onScreen%

y% =  HUD_GetLayerY ( Layer_Handle%,  [onScreen%]  )

Returns the current y-position of a layer.

onScreen%

x% | y% =  HUD_GetLayerCorner ( Layer_Handle%,  corner%,  getY% )

This command returns the absolute x or y screen coordinate of a layer corner or the layer's center point, which is useful if the layer has been rotated or moved, for example. So you're able to find specific screen positions at any time.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

corner%
Specify the corner number here:

HUD_SetLayerScale ( Layer_Handle%,  scale_x#,  scale_y# )

Scales a layer in vertical and horizontal direction.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

scale_x# , scale_y#
Float value, where 1.0 is the original (normal) scale, 0.5 half size and 2.0 double size, for example.

scale_x# =  HUD_GetLayerScaleX ( Layer_Handle% )

Returns the current x-scale factor of a layer.

scale_y# =  HUD_GetLayerScaleY ( Layer_Handle% )

Returns the current y-scale factor of a layer.

HUD_TFormLayerCoords (  x%,  y%  Source_Layer%,  Target_Layer%  )

Converts the x / y coordinate of a point from one layer to the coordinate system of another one. Usually, all layers share the same coordinate system (for example: 0,0 is always the upper-left corner). However, if you rotate or scale a layer, it's coordinate system will be scaled or rotated, too, so it may differ from other layers' coordinate systems. In such situations, you may want to use this command to find the same point on screen within different layers.

x% , y%
x / y coordinate of a point within the source layer.

Source_Layer% , Target_Layer%
Handles of a source- and a target layer. The specified x / y coordinate will be converted to the target layer's coordinate system.
- You can use 0 as SourceLayer to convert from absolute screen coordinates to layer coordinates.
- You can use 0 as TargetLayer to convert from layer coordinates to absolute screen coordinates.

HUD_SetLayerBlend ( Layer_Handle%,  blend_mode% )

Sets the blend mode of a complete layer (and all objects within) either to 'Alpha' (default), 'Multiply' or 'Additive'. You can use the 'Additive' mode to create bright objects like lasers, shots or explosions. To do so, simply create a layer, attach an explosion texture or anim strip to it and set it's blend mode to 3. Use this layer to create your explosions etc. then. You can change the blend mode of a layer at any time, of course.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

blend_mode%

HUD_SetLayerAlpha (  Layer_Handle%,  alpha#  )

Sets the alpha value (transparency) of the specified layer. The layer's alpha value will be added to the objects' own alpha values. This means that the layer alpha value will influence all layer objects, while the objects still keep their individual alpha settings, too.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

alpha#
A float value between 0.0 (full transparency, invisible) to 1.0 (opaque, solid).

alpha# =  HUD_GetLayerAlpha (  Layer_Handle%  )

Returns the current alpha value of a layer.

HUD_SetLayerVisibility ( Layer_Handle%,  state% )

Use this command to show or hide a complete layer and all objects within. Hidden layers will not be rendered.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

state%

state% =  HUD_GetLayerVisibility ( Layer_Handle% )

Returns TRUE if the specified layer is currently visible or FALSE if this layer has been set to hidden.

HUD_SetLayerShadow ( Layer_Handle%,  mode%,  [offset%],  [override%],  )

While you can attach a shadow to each object individually, you can also use this command to attach shadows to all objects within a layer automatically. This command attaches a shadow to all layer objects that either currently exist or will be added at a later time (you can still add or remove object shadows individually then). This command is also used to remove the shadow of all layer objects at once.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

mode%

HUD_SwapLayerOrder ( Layer_Handle1%,  Layer_Handle2% )

Swaps the depth order (display order) of two layers. Note: it doesn't make any sense to swap the depth orders of two layers that aren't attached to the same HUD. The depth order becomes important only when two or more layers are placed on top of another.

Layer_Handle1% , Layer_Handle2%
Handles of two layers, as returned by HUD_CreateLayer().

HUD_SetLayerOrder ( Layer_Handle%,  zOrder% )

Sets the depth order (display order) of a layer.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().

zOrder%
Integer value from 0 to ... Layers with higher depth order values will appear in front (on top), where layers with a lower depth order will appear behind others.

zOrder% =  HUD_GetLayerOrder ( Layer_Handle% )

Returns the current depth order value (display order) of a layer.

zOrder% =  HUD_LayerToFront ( Layer_Handle% )

Sets the z-order value (display order) of a layer automatically to display it on top of all other layers (that share the same HUD) and returns the new z-order of this layer.

Layer_Handle%
Handle of a layer as returned by HUD_CreateLayer().