Hudlib is an advanced wrapper for HudMessage that supports scaling and 3D messages. It features an OpenGL-style API instead of making one function take ten parameters.

Hudlib is based around the concept of render state, a render state is a collection of all current rendering settings that are taken into account when drawing a message.

Only drawing functions actually draw stuff. All other functions only manipulate render state.

Only drawing functions change ZDoom's global message settings: SetHudSize and SetFont.

HudSetPoint(320.0, 240.0);
HudDrawText(1, "Hello!");

HudSetCameraActor(0);
HudSetPoint3D(0.0, 0.0, 0.0);
HudDrawText(2, "This is the center of the map!"); 

===== Virtual screen size =====

These functions replace ''[[zdoom>SetHudSize]]''. They work exactly the same, but hudlib needs to wrap ''SetHudSize'' for message scaling.

<note important>Virtual screen size affects the size of 3D messages.</note>

==== HudSetVirtualSize ====
''void HudSetVirtualSize(fixed width, fixed height)''

Sets the virtual screen size to the given dimensions. The default size is 640x480. This works exactly like ''[[zdoom>SetHudSize]]''.

==== HudUseRealSize ====
''void HudUseRealSize()''

Sets the virtual screen size to match the real size. This allows you to draw messages with 1:1 scale between real and virtual pixels.

==== HudUseDefaultSize ====
''void HudUseDefaultSize()''

Sets the virtual screen size to 640x480.

==== HudSetExcludeStatusBar ====
''void HudSetExcludeStatusBar(bool exclude)''

Controls whether the statusbar area should be included into the virtual screen. This corresponds to the third parameter of ''[[zdoom>SetHudSize]]''

===== 2D positioning =====

Before drawing a 2D message, you need to set its position.

==== HudSetPoint ====
''void HudSetPoint(fixed x, fixed y)''

Sets the position at which the messages will be drawn.

===== Drawing =====

==== HudDrawImage ====
''void HudDrawImage(int id, str image)''

Draws the specified image at the previously set point using the given HudMessage ID.

The point of the image that will be positioned (its origin) is determined by the image's sprite offsets.

==== HudDrawText ====
''void HudDrawText(int id, str text)''

Draws the specified text at the previously set point using the given HudMessage ID.

The point of the text message that will positioned (its origin) is determined by ''HudSetTextOrigin''.

===== Scaling =====

==== HudSetScale ====
''void HudSetScale(fixed scale)''

Sets the message scale.

Default: 1.0.
==== HudSetScaleXY ====
''void HudSetScaleXY(fixed scaleX, fixed scaleY)''

Sets the horizontal and vertical scale.

==== HudSetInvScale ====
''void HudSetInvScale(fixed invScale)''

Sets the message scale from a 1 / scale value.

<note>1 / scale = distance</note>

==== HudSetInvScaleXY ====
''void HudSetInvScaleXY(fixed invScaleX, fixed invScaleY)''

Sets the horizontal and vertical scale from 1 / scale values.

===== Fading =====

Default message stay time is unlimited.

==== HudSetAppearTime ====
''void HudSetAppearTime(fixed time)''

Sets the duration of the fade-in animation of the message in seconds. 0 means that messages will appear instantly.

Default: 0.

<note important>When drawing text in typeon mode, this functions sets the appear time **per letter**. It will take appearTime * numLetters seconds to fully draw the message.</note>

==== HudSetStayTime ====
''void HudSetStayTime(fixed time)''

Sets the amount of time to wait between appearing and disappearing. 0 means that the disappearing animation will start instantly after the appear animation. ''HUD_STAYTIME_UNLIMITED'' means that the message will stay until removed by another HudMessage with the same id.

Default: ''HUD_STAYTIME_UNLIMITED''.

<note important>Messages with ''HUD_STAYTIME_UNLIMITED'' will only stay for 9 hours, because this greatly simplifies the implementation.</note>

==== HudSetDisappearTime ====
''void HudSetDisappearTime(fixed time)''

Sets the duration of the fade-in animation of the message in seconds. 0 means that messages will disappear instantly.

Default: 0.

===== Translucency =====

<note important>Translucent HudMessages are not supported in Zandronum.</note>

==== HudSetBlendStyle ====
''void HudSetBlendStyle(int blendStyle)''

Sets the blending style of the message. Available blending styles:

  * ''HUD_BLENDSTYLE_NORMAL'' -- normal alpha blending
  * ''HUD_BLENDSTYLE_ADDITIVE'' -- additive blending

Default: ''HUD_BLENDSTYLE_NORMAL''.

==== HudSetAlpha ====
''void HudSetAlpha(fixed alpha)''

Sets the alpha of the message.

Default: 1.0.

===== Text settings =====

==== HudSetFont ====
''void HudSetFont(str font)''

Sets the font to use when drawing text.

Default: SMALLFONT.

==== HudSetCenterText ====
''void HudSetCenterText(bool center)''

If set to true, centers the text in the box before drawing. Otherwise, justifies it to the left edge of the box.

==== HudSetTextColor ====
''void HudSetTextColor(int color)''

Sets the font color to use when drawing text. For the list of available colors see [[zdoom>HudMessage]].

==== HudSetTextColorString ====
''void HudSetTextColorString(str colorName)''

Sets the font color to use when drawing text. The color must be one the colors defined in the [[zdoom>TEXTCOLO]] lump.

==== HudSetTextTypeOn ====
''void HudSetTextTypeOn(bool typeOn)''

If set to the, the text will use a typeon appear animation instead of a fade-in animation.

<note important>''HudSetAppearTime'' sets the appear time **per-letter** when typeon animation is used.</note>

==== HudSetTextOrigin ====
''void HudSetTextOrigin(fixed originX, fixed originY)''

Set the origin point of the text box.

Available X origins:

  * ''HUD_TEXTORIGIN_CENTER'' -- center
  * ''HUD_TEXTORIGIN_LEFT'' -- left
  * ''HUD_TEXTORIGIN_RIGHT'' -- right

Available Y origins:

  * ''HUD_TEXTORIGIN_CENTER'' -- center
  * ''HUD_TEXTORIGIN_BOTTOM'' -- bottom
  * ''HUD_TEXTORIGIN_TOP'' -- top

==== HudSetTextOriginX ====
''void HudSetTextOriginX(fixed originX)''

Sets the X origin point of the text box only.

==== HudSetTextOriginY ====
''void HudSetTextOriginY(fixed originY)''

Sets the Y origin point of the text box only.

==== HudSetLogMessage ====
''void HudSetLogMessage(bool log)''

If set to true, the message will be logged to console.

==== HudSetWordWrap ====
''void HudSetWordWrap(bool wrap)''

If set to true, the message will be word-wrapped if it touches the right boundary of the screen.

<note>Don't use this with 3D messages.</note>

===== Visibility =====

==== HudSetShowToEveryone ====
''void HudSetShowToEveryone(bool showToEveryone)''

If set to true, the message will be shown to everyone, and not just to the activator. This setting toggles between ''[[zdoom>HudMessage]]'' and ''[[zdoom>HudMessageBold]]'' in hudlib.

==== HudSetLayer ====
''void HudSetLayer(int layer)''

Sets the layer of the message.

FIXME This setting is present only for completeness. Please insert a description of what it actually does. FIXME

==== HudSetShowIn3DView ====
''void HudSetShowIn3DView(bool showIn3DView)''

Hudlib equivalent of the HUDMSG_NOTWITH3DVIEW flag.

FIXME This setting is present only for completeness. Please insert a description of what it actually does. FIXME

==== HudSetShowOnFullAutomap ====
''void HudSetShowOnFullAutomap(bool showOnFullAutomap)''

Hudlib equivalent of the HUDMSG_NOTWITHFULLMAP flag.

FIXME This setting is present only for completeness. Please insert a description of what it actually does. FIXME

==== HudSetShowOnOverlayAutomap ====
''void HudSetShowOnOverlayAutomap(bool showOnOverlayAutomap)''

Hudlib equivalent of the HUDMSG_NOTWITHOVERLAYMAP flag.

FIXME This setting is present only for completeness. Please insert a description of what it actually does. FIXME

===== 3D Camera position =====

==== HudSetCameraPosition ====
''void HudSetCameraPosition(fixed x, fixed y, fixed z)''

Sets the position of the camera from which 3D messages will be viewed.

Default: (0, 0, 0).

==== HudSetCameraAngles ====
''void HudSetCameraAngles(fixed angle, fixed pitch)''

Sets the direction of the camera through which 3D messages will be viewed. The direction is specified as a pair of angles.

Default: (0, 0).

<note important>Remember that actor pitch in ZDoom is inverted.</note>

<note tip>If you want to do ''HudSetCameraAngles(GetActorAngle(tid), -GetActorPitch(tid))'', use ''HudSetCameraActor(tid)'' instead.</note>

==== HudSetCameraActor ====
''void HudSetCameraActor(int tid)''

Reads the actor's position and direction and automatically sets up the camera using the functions above.

==== HudSetCameraActorAdvanced ====
''void HudSetCameraActor(int tid, int flags)''

Same as ''HudSetCameraActor'', but with flags to turn off various features:
  * ''HUD_CAMERAACTOR_NOPOSITION'' -- do not set the camera's position
  * ''HUD_CAMERAACTOR_NOPREDICTION'' -- do not take the actor's velocity into account when setting the camera position.
  * ''HUD_CAMERAACTOR_NODIRECTION'' -- do not set the direction of the camera based on the actor's angle and pitch
  * ''HUD_CAMERAACTOR_NOVIEWHEIGHT'' -- do not take into account the view height of the actor when setting the camera's position.

===== 3D Message position =====

==== HudSetPoint3D ====
''void HudSetPoint3D(fixed x, fixed y, fixed z)''

Sets the point at which the 3D message will be drawn. The next message drawn will be 3D.

Default: none.

==== HudSet2DOffset ====
''void HudSet2DOffset(fixed x, fixed y)''

Sets the 2D offset of the 3D message relative to the projected point.

Default: (0, 0).

===== 3D Projection =====

==== HudSetProjectionMode ====
''void HudSetProjectionMode(int mode)''

Sets the method to use when projecting 3D points to the screen.

Available modes are:
  * ''HUD_PROJECTION_AUTO'' -- use Y-shearing projection in Software renderer and true 3D projection in OpenGL (renderer is determined using ''IsOpenGL()'').
  * ''HUD_PROJECTION_YSHEARING'' -- always use Y-shearing projection
  * ''HUD_PROJECTION_3D'' -- always use true 3D projection

===== 3D Distance =====

==== HudSetAutoDistanceScale ====
''void HudSetAutoDistanceScale(bool autoDistanceScale)''

If enabled, the message will be automatically scaled based on distance to the camera plane.

Default: true.

==== HudGetDistance ====
''fixed HudGetDistance()''

Returns the distance from the 3D point to the camera plane. Note that this is **not** the the distance between the camera and the point.

Returns negative distances if the point is behind the camera.

**Example**

<code>
if (HudGetDistance() > 256.0)
    HudDrawText("*");
else
    HudDrawText("Shoot here!");

You can save and retrieve hudlib states using these functions. The maximum amount of saved states is configured through #define ACSUTILS_HUDLIB_SAVEDSTATES in your project's ACSUtils settings.

void HudResetState()

Resets hudlib render state to default.

void HudPushState()

Saves the current render state to a stack.

void HudPopState()

Restores the previous saved render state from the stack.

void HudClearStateStack()

Deletes all saved render states.