Differences

This shows you the differences between two versions of the page.

--- archive:hudlib [2017/06/12 18:36] – created korshun
+++ archive:hudlib [Unknown date] (current) – removed - external edit (Unknown date) 127.0.0.1
@@ Line 1: / Line 1: @@
-<note warning>This is an **archived** page. For up-to-date documentation, visit [[:|the front page]]</note>
-====== Hudlib ======
-Hudlib is an advanced wrapper for [[zdoom>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 ([[zdoom>SetHudSize]] and [[zdoom>SetFont]]) every time they are called. Other functions do not touch them.
-===== Examples =====
-==== Simple 2D drawing ====
-<code>
-HudSetPoint(320.0, 240.0);
-HudDrawText(1, "Hello!");
-</code>
-==== Simple 3D drawing ====
-<code>
-HudSetCameraActor(0);
-HudSetPoint3D(0.0, 0.0, 0.0);
-HudDrawText(2, "This is the center of the map!");
-</code>
-===== 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]]''
-===== Widescreen support =====
-==== Hud boundaries ====
-''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**
-<code>
-// This message will stick to the left border of the screen (with a gap), even in widescren.
-HudSetPoint(HudLeft() + 3.0, 240.0);
-</code>
-==== Hud borders ====
-''fixed HudBorderX()''
-''fixed HudBorderY()''
-Return hud borders for current virtual screen size, accounting for current **physical** aspect ratio.
-===== 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!");
-</code>
-===== State management =====
-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.
-==== HudResetState ====
-''void HudResetState()''
-Resets hudlib render state to default.
-<note>This doesn't delete any states saved with ''HudPushState''.</note>
-==== HudPushState ====
-''void HudPushState()''
-Saves the current render state to a stack.
-<note important>There is a limit on how many states can be saved. If you save more than ''ACSUTILS_HUDLIB_SAVEDSTATES'' states, you will be notified through [[.error|the error system]].</note>
-==== HudPopState ====
-''void HudPopState()''
-Restores the previous saved render state from the stack.
-==== HudClearStateStack ====
-''void HudClearStateStack()''
-Deletes all saved render states.

ACSUtils Wiki

User Tools

Site Tools

Differences

Page Tools