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)

HUD_Handle% = HUD_Create ( CameraHandle%,  [width%],  [height%],  [zOrder%] )

This command creates an empty HUD for a specified camera and returns a HUD handle. You can create and use an unlimited number of HUDs per camera.

CameraHandle%
The handle of a camera where this HUD should be attached to.

width%
The width of the camera viewport (or the screen width, if no viewports are used). If you do not specifiy this parameter, Sprite Candy will determine the HUD width automatically using ScreenWidth(). Note: when using viewports, you MUST specify the width of the viewport here.

height%
The height of the camera viewport (or the screen height, if no viewports are used). If you do not specifiy this parameter, Sprite Candy will determine the HUD height automatically using ScreenHeight(). Note: when using viewports, you MUST specify the height of the viewport here.

zOrder%
The depth order of this HUD. When not specified, a new HUD will be placed on top of existing ones. A HUDs 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 objects.

HUD_Update ( )

This command updates and renders all existing objects or animations and should be called frequently (to be placed within your main game loop). HUD_Update should be used just before UpdateWorld() or RenderWorld().

HUD_SetCameraZoom ( CameraHandle%,  zoomlevel# )

CameraHandle%
Handle of a camera that has a HUD attached to it.

zoom_level#
Float value higher or equal to 1.0, values higher than 1.0 will zoom-in the camera's viewangle. You cannot use values below 1.0 here.

zoom_value# =  HUD_GetCameraZoom ( CameraHandle% )

Returns the zoom value of the specified HUD camera (the default value is 1.0).

HUD_ChangeCamera ( HUD_Handle%,  CameraHandle%,  [width%],  [height%] )

Using this command, you can attach an existing HUD to any other camera on the fly. This is quite useful if you're using multiple cameras within your game and want to use the same HUD on all cameras.

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

CameraHandle%
Handle of a camera where this HUD should be attached to.

width%
The width of the camera viewport (or the screen width, if no viewports are used). If you do not specifiy this parameter, Sprite Candy will determine the HUD width automatically using ScreenWidth(). Note: when using viewports, you MUST specify the width of the viewport here.

height%
The height of the camera viewport (or the screen height, if no viewports are used). If you do not specifiy this parameter, Sprite Candy will determine the HUD height automatically using ScreenHeight(). Note: when using viewports, you MUST specify the height of the viewport here.

HUD_SetVisibility ( HUD_Handle%,  state% )

Use this command to show or hide complete HUDs and all attached layers. Hidden HUDs and layers will not be rendered.

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

state%

state% =  HUD_GetVisibility ( HUD_Handle% )

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

HUD_SetAlpha ( HUD_Handle%,  alpha# )

Sets the alpha (transparency) value for a complete HUD (affecting all layers and objects of this HUD). The HUD alpha value will be added to the object's individual values, so the objects will keep their individual transparencies.

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

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

alpha# =  HUD_GetAlpha ( HUD_Handle% )

Returns the current alpha (transparency) value of the specified HUD.

HUD_Move ( HUD_Handle%,  x_step#,  y_step#,  [relative%] )

Moves a HUD at a given x / y step either in absolute or relative direction.

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

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

relative%

HUD_Position ( HUD_Handle%,  x%,  y% )

Positions a HUD on an absolute screen coordinate.

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

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

HUD_Turn ( HUD_Handle%,  angle_step# )

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

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

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

HUD_SetRotation ( HUD_Handle%,  angle# )

Rotates a HUD to an absolute rotation angle.

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

angle#
Float value from 0.0 to 360.0

angle# =  HUD_GetRotation ( HUD_Handle% )

Returns the current rotation angle of a HUD.

x% =  HUD_GetX ( HUD_Handle% )

Returns the current x-position of a HUD.

y% =  HUD_GetY ( HUD_Handle% )

Returns the current y-position of a HUD.

x% | y% =  HUD_GetCorner ( HUD_Handle%,  corner%,  getY% )

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

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

corner%
Specify the corner number here:

HUD_SetScale ( HUD_Handle%,  scale_x#,  scale_y# )

Scales a HUD in vertical and horizontal direction.

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

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_GetScaleX ( HUD_Handle% )

Returns the current x-scale factor of a HUD.

scale_y# =  HUD_GetScaleY ( HUD_Handle% )

Returns the current y-scale factor of a HUD.

HUD_SwapOrder ( HUD_Handle1%,  HUD_Handle2% )

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

HUD_Handle1% , HUD_Handle2%
Handles of two HUDs, as returned by HUD_Create().

HUD_SetOrder ( HUD_Handle%,  zOrder% )

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

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

zOrder%
Integer value from 0 to ... HUDs with higher depth order values will appear in front of HUDs with a lower depth order value.

zOrder% =  HUD_GetOrder ( HUD_Handle% )

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

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

zOrder% =  HUD_ToFront ( HUD_Handle% )

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

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