This is an old revision of the document!
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.
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
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
.
HUD_STAYTIME_UNLIMITED
will only stay for 9 hours, because this greatly simplifies the implementation.
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 blendingHUD_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.
HudSetAppearTime
sets the appear time per-letter when typeon animation is used.
void HudSetTextOrigin(fixed originX, fixed originY)
Set the origin point of the text box.
Available X origins:
HUD_TEXTORIGIN_CENTER
– centerHUD_TEXTORIGIN_LEFT
– leftHUD_TEXTORIGIN_RIGHT
– rightAvailable Y origins:
HUD_TEXTORIGIN_CENTER
– centerHUD_TEXTORIGIN_BOTTOM
– bottomHUD_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 settings 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 positionHUD_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 pitchHUD_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 projectionHUD_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.
HudPushState
.
void HudPushState()
Saves the current render state to a stack.
ACSUTILS_HUDLIB_SAVEDSTATES
states, you will be notified through the error system.
void HudPopState()
Restores the previous saved render state from the stack.
void HudClearStateStack()
Deletes all saved render states.