Hudlib

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.

Virtual screen size

These functions replace SetHudSize. They work exactly the same, but hudlib needs to wrap SetHudSize for message scaling.

Virtual screen size affects the size of 3D messages.

HudSetVirtualSize

void HudSetVirtualSize(fixed width, fixed height)

Sets the virtual screen size to the given dimensions. The default size is 640×480. This works exactly like 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 640×480.

HudSetExcludeStatusBar

void HudSetExcludeStatusBar(bool exclude)

Controls whether the statusbar area should be included into the virtual screen. This corresponds to the third parameter of 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.

1 / scale = distance

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.

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.

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.

Messages with HUD_STAYTIME_UNLIMITED will only stay for 9 hours, because this greatly simplifies the implementation.

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

Translucent HudMessages are not supported in Zandronum.

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

HudSetAppearTime sets the appear time per-letter when typeon animation is used.

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.

Don't use this with 3D messages.

Visibility

HudSetShowToEveryone

void HudSetShowToEveryone(bool showToEveryone)

If set to true, the message will be shown to everyone, and not just to the activator. This settings toggles between HudMessage and HudMessageBold in hudlib.

HudSetLayer

void HudSetLayer(int layer)

Sets the layer of the message.

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

HudSetShowIn3DView

void HudSetShowIn3DView(bool showIn3DView)

Hudlib equivalent of the HUDMSG_NOTWITH3DVIEW flag.

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

HudSetShowOnFullAutomap

void HudSetShowOnFullAutomap(bool showOnFullAutomap)

Hudlib equivalent of the HUDMSG_NOTWITHFULLMAP flag.

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

HudSetShowOnOverlayAutomap

void HudSetShowOnOverlayAutomap(bool showOnOverlayAutomap)

Hudlib equivalent of the HUDMSG_NOTWITHOVERLAYMAP flag.

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

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

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

Example

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

State management

HudResetState

void HudResetState()

Resets hudlib render state to default.

This doesn't delete any states saved with HudPushState.

HudPushState

void HudPushState()

Saves the current render state to a stack.

There is a limit on how many states can be saved. If you save too many states, you will be notified through the error system.

HudPopState

void HudPopState()

Restores the previous saved render state from the stack.

HudClearStateStack

void HudClearStateStack()

Deletes all saved render states.