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.

Drawing functions change ZDoom's global message settings (SetHudSize and SetFont) every time they are called. Other functions do not touch them.

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!");

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

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.

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.

void HudUseDefaultSize()

Sets the virtual screen size to 640×480.

void HudSetExcludeStatusBar(bool exclude)

Controls whether the statusbar area should be included into the virtual screen. This corresponds to the third parameter of SetHudSize

fixed HudLeft()

fixed HudRight()

fixed HudTop()

fixed HudBottom()

Return the boundaries of the screen for current virtual screen size, accounting for current physical aspect ratio. Equivalent to adding or subtracting a hud border manually.

Example

// This message will stick to the left border of the screen (with a gap), even in widescren.
HudSetPoint(HudLeft() + 3.0, 240.0);

fixed HudBorderX()

fixed HudBorderY()

Return hud borders for current virtual screen size, accounting for current physical aspect ratio.

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

void HudSetPoint(fixed x, fixed y)

Sets the position at which the messages will be drawn.

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.

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.

void HudSetScale(fixed scale)

Sets the message scale.

Default: 1.0.

void HudSetScaleXY(fixed scaleX, fixed scaleY)

Sets the horizontal and vertical scale.

void HudSetInvScale(fixed invScale)

Sets the message scale from a 1 / scale value.

void HudSetInvScaleXY(fixed invScaleX, fixed invScaleY)

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

Default message stay time is unlimited.

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.

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.

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.

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.

void HudSetAlpha(fixed alpha)

Sets the alpha of the message.

Default: 1.0.

void HudSetFont(str font)

Sets the font to use when drawing text.

Default: SMALLFONT.

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.

void HudSetTextColor(int color)

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

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.

void HudSetTextTypeOn(bool typeOn)

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

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

void HudSetTextOriginX(fixed originX)

Sets the X origin point of the text box only.

void HudSetTextOriginY(fixed originY)

Sets the Y origin point of the text box only.

void HudSetLogMessage(bool log)

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

void HudSetWordWrap(bool wrap)

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

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 HudMessage and HudMessageBold in hudlib.

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.

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.

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.

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.

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

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

void HudSetCameraActor(int tid)

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

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.

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.

void HudSet2DOffset(fixed x, fixed y)

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

Default: (0, 0).

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

void HudSetAutoDistanceScale(bool autoDistanceScale)

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

Default: true.

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

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.