====== HUD Library State ======

[[HUD Library]] has a lot of settings telling it how to draw messages. It stores them in current **state**. 

This state can be reset to default using [[functions:HudResetState]]. It can be saved and restored using [[functions:HudPushState]] and [[functions:HudPopState]] respectively.

===== 2D drawing =====
These settings apply to 2D drawing only.

==== 2D position =====

The current 2D point in the [[HUD coordinate system]] to draw the message at.

**Default:** x=0.0 y=0.0

Manipulated by [[functions:HudSetPoint]].
----
==== Virtual screen size ====
The width and height of the [[HUD coordinate system]].

<note important>This width and height is stored **in HUD Library**. [[zdoom>SetHudSize]] is **not** a replacement for [[functions:HudSetVirtualSize]], because HUD Library needs to overwrite actual SetHudSize dimensions to implement scaling.</note>

<note important>Virtual screen size is specified using fixed-point numbers. The restriction on integers in [[zdoom>SetHudSize]] is completely arbitrary.</note>

<note important>Virtual screen size affects 3D message size. IF [[#auto distance scale]] is enabled, the scale of 3D messages will match that of 2D ones at 128 units from the camera plane. If it's disabled, 3D messages will look just like 2D ones at this virtual screen size.</note>

**Default:** 640x480

Manipulated by [[functions:HudSetVirtualSize]].
----
==== Exclude status bar ====
Whether to exclude status bar from [[HUD coordinate system]]. This is equivalent to the third argument to [[zdoom>SetHudSize]].

**Default:** false

Manipulated by [[functions:HudSetExcludeStatusBar]].
----

===== General appearance =====
These settings affect **all** messages drawn through HUD Library.
==== 2D/3D mode =====
Whether to draw in 2D or 3D mode.

**Default:** 2D mode.

Manipulated by:
  * [[functions:HudSetPoint]] (switches to 2D mode)
  * [[functions:HudSetPoint3D]] (switches to 3D mode)

----
==== Scale ====
Current X and Y scale of the message to draw.

**Default:** x=1.0 y=1.0

Manipulated by:
  * [[functions:HudSetScale]]
  * [[functions:HudSetScaleXY]]
  * [[functions:HudSetInvScale]]
  * [[functions:HudSetInvScaleXY]]

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

----
==== Show to everyone ====
Whether to use [[zdoom>HudMessage]] or [[zdoom>HudMessageBold]].

**Default:** false (use HudMessage)

Manipulated by [[functions:HudSetShowToEveryone]].
----
==== Appearance time ====
Duration of fade-in animation in seconds. 0 disables fade-in animation and makes the message appear instantly.

<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>

**Default:** 0.0

Manipulated by [[functions:HudSetAppearTime]].
----
==== Stay time ====
For how long the message stays after the end of fade-in and before the beginning fade-out (in seconds). 

**Default:** HUD_STAYTIME_FOREVER.

Manipulated by [[functions:HudSetStayTime]].
----
==== Disappearance time ====
Duration of fade-out animation in seconds. 0 disables fade-out animation and makes the message disappear instantly.

**Default:** 0.0

Manipulated by [[functions:HudSetDisappearTime]].
----
==== Blend style ====
Which blend style to use for the message. Can be one of the following:
  * HUD_BLENDSTYLE_NORMAL -- normal translucency
  * HUD_BLENDSTYLE_ADDITIVE -- additive translucency

**Default:** HUD_BLENDSTYLE_NORMAL (makes messages with alpha = 1.0 opaque).

Manipulated by [[functions:HudSetBlendStyle]].
----
==== Alpha ====
The alpha (opaqueness) of the message.

**Default:** 1.0

Manipulated by [[functions:HudSetAlpha]].
----

==== Show in 3D view ====
Whether to show the message in 3D game view. If false, applies [[zdoom>HudMessage#Type_flags|HUDMSG_NOTWITH3DVIEW]] flag to the message.

**Default:** true

Manipulated by: [[functions:HudSetShowIn3DView]].
----

==== Show on overlay automap ====
Whether to show the message when overlay automap is enabled. If false, applies [[zdoom>HudMessage#Type_flags|HUDMSG_NOTWITHOVERLAYMAP]] flag to the message.

**Default:** true

Manipulated by: [[functions:HudSetShowOnOverlayAutomap]].
----

==== Show on full automap ====
Whether to show the message in full automap mode. If false, applies [[zdoom>HudMessage#Type_flags|HUDMSG_NOTWITHFULLMAP]] flag to the message.

**Default:** true

Manipulated by: [[functions:HudSetShowOnFullAutomap]].
----



==== HUD layer ====
Which [[zdoom>HudMessage#HUD_layers|HUD layer]] to draw the message at. Uses HUDMSG_LAYER_* constants from ZDoom.

**Default:** HUDMSG_LAYER_OVERHUD

Manipulated by: [[functions:HudSetLayer]].
----
===== Text drawing =====
These settings apply only to [[functions:HudDrawText]], not to [[functions:HudDrawImage]].

==== Text font ====
The font to draw the text with.

**Default:** "SMALLFONT"

Manipulayed by [[functions:HudSetTextFont]].
----
==== Text color ====
Default text color to use in absence of any color codes. 

**Default:** apply no recoloring to original font.

<note important>Note that this differs from ZDoom default of red color.</note>

Manipulated by:
  * [[functions:HudSetTextColor]]
  * [[functions:HudSetTextColorString]].

<note tip>Use ''HudSetTextColor(CR_UNTRANSLATED)'' to reset back to default.</note>

----
==== Type-on ====
Whether to make appearance animation use type-on effect instead of fade-in.

<note important>Appear time is time per-letter when typeon animation is used.</note>

**Default:** false

Manipulated by [[functions:HudSetTextTypeOn]].
----
==== Word wrap ====
Whether to enable word wrap when the message goes off the right edge of the screen.

**Default:** false

Manipulated by [[functions:HudSetWordWrap]].
----

==== Text origin ====
Which point of the text box to position.

Horizontal origin can be one of:
  * HUD_TEXTORIGIN_LEFT
  * HUD_TEXTORIGIN_CENTER
  * HUD_TEXTORIGIN_RIGHT

Vertical origin can be one of:
  * HUD_TEXTORIGIN_TOP
  * HUD_TEXTORIGIN_CENTER
  * HUD_TEXTORIGIN_BOTTOM

**Default:** HUD_TEXTORIGIN_CENTER HUD_TEXTORIGIN_CENTER

Manipulated by:
  * [[functions:HudSetTextOrigin]]
  * [[functions:HudSetTextOriginX]]
  * [[functions:HudSetTextOriginY]]

----

==== Center text ====
Whether to center multiline text in the box.

**Default:** false

Manipulated by [[functions:HudSetCenterText]].

----
==== Logging ====
Whether to log the text of the message to the console using [[zdoom>HudMessage|HUDMSG_LOG]] flag.

**Default:** false

Manipulated by [[functions::HudSetLogMessage]]
----
===== 3D drawing =====
These settings apply to 3D drawing only.

==== 3D position ====
The current 3D point to draw the message at.

**Default:** x=0.0 y=0.0 z=0.0

Manipulated by [[functions:HudSetPoint3D]].
----
==== Camera position ====
The 3D position of the camera that views the 3D points.

**Default:** x=0.0 y=0.0 z=0.0

Manipulated by:
  * [[functions:HudSetCameraPosition]]
  * [[functions:HudSetCameraActor]]
  * [[functions:HudSetCameraActorAdvanced]]

----
==== Camera direction ====
The direction of the camera that views the 3D points.

**Default:** along the world X axis.

Manipulated by:
  * [[functions:HudSetCameraAngles]]
  * [[functions:HudSetCameraActor]]
  * [[functions:HudSetCameraActorAdvanced]]

----
==== 2D offset ====
A 2D offset to shift the message on screen by.

**Default:** x=0.0 y=0.0

Manipulated by [[functions:HudSet2DOffset]].

----
==== Projection mode ====
3D projection mode to convert 3D coordinates to 2D. Can be one of the following:

  * HUD_PROJECTION_AUTO -- use true 3D projection if [[functions:IsOpenGL]] returns true and Y-shearing projection otherwise.
  * HUD_PROJECTION_3D -- true 3D projection.
  * HUD_PROJECTION_YSHEARING -- a 3D projection with Y-shearing like in software renderer.

**Default:** HUD_PROJECTION_AUTO

Manipulated by [[functions:HudSetProjectionMode]].

----
==== Auto distance scale ====
Whether to multiply the scale of the message by a factor to make it change size with distance.

**Default:** true

Manipulated by [[functions:HudSetAutoDistanceScale]].