Screentext

From EDukeWiki
Jump to navigation Jump to search

screentext <tilenum> <x> <y> <zoom> <block angle> <character angle> <quote> <shade> <pal> <orientation> <alpha> <xspace> <yline> <xbetween> <ybetween> <text flags> <x1> <y1> <x2> <y2>

qstrdim <width return var> <height return var> <tilenum> <x> <y> <zoom> <block angle> <quote> <orientation> <xspace> <yline> <xbetween> <ybetween> <text flags> <x1> <y1> <x2> <y2>

The art of HUD text can best be accomplished using the screentext command.

qstrdim calculates the dimensions taken up by an equivalent call to screentext.

Parameters

<width return var>
<height return var>
are both gamevars to which qstrdim will assign its results
<tilenum> is the start of the font range. The most common value is STARTALPHANUM (#2822). MINIFONT (#3072) can also work. By default, these tile ranges follow ASCII order and the tile number itself points to the '!' character.
<x> X coordinate, normally ranged 0-320
<y> Y coordinate, normally ranged 0-200
<zoom> is normally 65536. (ex: 131072 is zoomed in 2X and 32768 is half-sized)
<block angle> is the angle of the entire block of text, normally 0, where 360 degrees corresponds to 2048 Build units
<character angle> is the angle of each individual character, relative to the block angle, also in Build units
<quote> is the quote to print, as defined by definequote.
<shade> is 0 normally but can be any standard shade up to 31 or 63.
<pal> can be from 0-255.
<orientation> controls the way the sprite is drawn (see entry). Note: It is recommended that you always include bit 16 so that the characters will be placed correctly.
<alpha> translucence, 0-255
<xspace> the width of the space character. Can be zero or negative.
<yline> the height of an empty line. Can be zero or negative.
<xbetween> the x-distance between characters. Can be zero or negative.
<ybetween> the y-distance between lines. Can be zero or negative.
<text flags> is a bitfield describing properties of the text block (see entry)
<x1>, <y1>, <x2>, <y2> are boundaries on the screen that define where the text may be drawn. By far the two most common set of values for these fields are:

0 0 xdim-1 ydim-1 (Covers the entire screen. Orientation bit 8 recommended.)

set X2 xdim
sub X2 1
set Y2 ydim
sub Y2 1

// 0 0 X2 Y2

windowx1 windowy1 windowx2 windowy2 (Shrinks to match the viewport.)

Notes

<x>, <y>, <xspace>, <yline>, <xbetween>, and <ybetween> are all affected by orientation flag 2048 which enables "full16" precision. For qstrdim, <width return var> and <height return var> will both return in full16 precision with orientation flag 2048.

If you are using a <zoom> other than 65536, <xspace>, <yline>, <xbetween>, and <ybetween> should be what your text would use at zoom 65536 and EDuke32 will scale them up or down for you.

qstrdim can be helpful if you are designing complex text effects.

Orientation

The following values are used by rotatesprite, rotatesprite16, rotatespritea, screentext, gametext, minitext, digitalnumber, digitalnumberz, myos and myospalx.

Exposed Value Label Description
No 1 RS_TRANS1 Translucency level one (66% opacity).
No 2 RS_AUTO Scaling on 320-200 coordinates. This is implicitly applied to all CON screen drawing commands, but including it in your bitfields is recommended for clarity and portability of your code.
No 4 RS_YFLIP Used to invert Y coordinates. Combine this bit with an angle of 1024 (using rotatesprite) and the tile will appear to have inverted X coordinates. If you want inversion for both the X and Y coordinates, simply set the angle (again, with rotatesprite) to 1024 and do not use this bit.
No 8 RS_NOCLIP Causes the sprite to be not affected by the screen size (using the + or - commands). This is usefull, for example, when displaying a status bar.
No 16 RS_TOPLEFT Forces the center of the sprite you're drawing to its top-left if set. It also ignores the x-y offset of the tile.
No 32 RS_TRANS2 Translucency level two (33% opacity). It won't work if 1 is not set.
No 64 RS_NOMASK Forces masking off if set. It discards translucency too.
No 128 RS_PERM "Permanent" tile (deprecated).
No 256 RS_ALIGN_L Align to the left (widescreen support)
No 512 RS_ALIGN_R Align to the right (widescreen support)
No 1024 RS_STRETCH Stretch to screen resolution (distorts aspect ratio; this is the behavior of rotatesprite prior to widescreen awareness)
No 2048 ROTATESPRITE_FULL16 Always interpret coordinate values as having "full" precision, bit-shifted left by 16, so that 20971520x13107200 corresponds to 320x200. See rotatesprite16.
No 4096 RS_LERP Enables interpolation of coordinates between rotatesprite calls per guniqhudid. Changes of tilenum reset interpolation.
No 8192 RS_FORCELERP Forces interpolation, even if the tilenum changes between calls.
Defines
define RS_TRANS1                        0x00000001
define RS_AUTO                          0x00000002
define RS_YFLIP                         0x00000004
define RS_NOCLIP                        0x00000008
define RS_TOPLEFT                       0x00000010
define RS_TRANS2                        0x00000020
define RS_NOMASK                        0x00000040
define RS_PERM                          0x00000080
define RS_ALIGN_L                       0x00000100
define RS_ALIGN_R                       0x00000200
define RS_STRETCH                       0x00000400
define ROTATESPRITE_FULL16              0x00000800

As with cstat, the bit values can be added together and used in combination. For example, orientation 33 (32+1) is transparency level two, and orientation 5 (4+1) is transparency level one with inverted Y coordinates.

Text flags

The following values are used with screentext and qstrdim.

Exposed Value Label Description
No 1 TEXT_XRIGHT Right-align text on the x-axis. For example, you could display text at x=320 with this flag and the string's right edge would be on the right edge of the screen.
No 2 TEXT_XCENTER Center-align text on the x-axis. For example, you could display text at x=160 with this flag and the string would be perfectly horizontally centered.
No 4 TEXT_YBOTTOM Bottom-align text on the y-axis. For example, you could display text at y=200 with this flag and the string's bottom edge would be on the bottom edge of the screen.
No 8 TEXT_YCENTER Center-align text on the y-axis. For example, you could display text at y=100 with this flag and the string would be perfectly vertically centered.
No 16 TEXT_INTERNALSPACE If you are unsure what to specify for the <xspace> parameter, this flag will allow EDuke32 to make its own determination. Don't use this unless you have no idea whatsoever. The <xspace> value will be added to the internal result.
No 32 TEXT_TILESPACE The <xspace> parameter will be determined using the width of the tile after '~'. Good for custom fonts. (NB: <xbetween> is added to spaces just like any other character.) The <xspace> value will be added to the result.
No 64 TEXT_INTERNALLINE If you are unsure what to specify for the <yline> parameter, this flag will allow EDuke32 to make its own determination. Don't use this unless you have no idea whatsoever. The <yline> value will be added to the internal result.
No 128 TEXT_TILELINE The <yline> parameter will be determined using the height of the tile after '~'. Good for custom fonts. The <yline> value will be added to the result.
No 256 TEXT_XOFFSETZERO Calculate spacing between characters from the left edge instead of the right. In other words, <xbetween> is used as a constant width for the characters in the string and the potentially variable widths of the tiles displayed in the string are ignored.
No 512 TEXT_XJUSTIFY Justify text in the X direction, using <xbetween> for the total width (since the actual distance will be calculated automatically). Compatible with TEXT_XRIGHT and TEXT_XCENTER.
No 1024 TEXT_YOFFSETZERO Calculate spacing between line from the top edge instead of the bottom. In other words, <ybetween> is used as a constant height for the lines in the string and the potentially variable heights of the tiles displayed in the string are ignored.
No 2048 TEXT_YJUSTIFY Justify text in the Y direction, using <ybetween> for the total height (since the actual distance will be calculated automatically). Compatible with TEXT_YBOTTOM and TEXT_YCENTER.
No 4096 <RESERVED> Do not use.
No 8192 TEXT_UPPERCASE Force the case of all letters in the string to uppercase.
No 16384 TEXT_INVERTCASE Invert the case of the letters in the string. Combine with TEXT_UPPERCASE to produce all-lowercase output.
No 32768 TEXT_IGNOREESCAPE Palette escape sequences (# or ##) will have no effect. (See definequote.)
No 65536 TEXT_LITERALESCAPE No parsing will be done for palette escape sequences so they will show up as actual text. This is useful if you have followed by a number that you actually want to display on the screen, such as exponentiation.
No 131072 <RESERVED> Do not use.
No 262144 TEXT_CONSTWIDTHNUMS All numerals will display as if they have a TEXT_XOFFSETZERO of the width of the '0' minus one. For the standard blue font, this value would be 8. This is useful if you have some string including a number value (such as a countdown timer) that you want to display without the place values shifting due to variable width tiles, particularly '1'.
No 524288 TEXT_DIGITALNUMBER Special tile order: starting at '0' instead of 'A'. Using this flag with quotes containing anything other than numbers may give you undefined behavior. (Recommended tile numbers: DIGITALNUM (#2472), THREEBYFIVE (#3010))
No 1048576 TEXT_BIGALPHANUM Special tile order: main menu red font. As in v1.3D, the gray font serves as the lowercase letters, so TEXT_UPPERCASE is recommended. (Recommended tile number: BIGALPHANUM (#2930))
No 2097152 TEXT_GRAYFONT Special tile order: gray font. To parallel the above flag, the red font serves as the lowercase letters, so TEXT_UPPERCASE is recommended. The primary difference compared to using the above flag with the lowercase flags is that the gray font has its own set of numerals. The red font's punctuation is still used. (Recommended tile number: #2966)
No 4194304 TEXT_NOLOCALE Text will not be translated by the localization DEF command.
No 8388608 TEXT_VARHEIGHT Alters the positioning of the text in the x and y direction, shifting it by half the size of the tile, depending on the zoom value of the text, if and only if RS_TOPLEFT is not set.
No 16777216 TEXT_CENTERCONSTWIDTH Center glyphs within their allotted region and respect xbetween between chars in constant width mode.
Defines
define TEXT_XRIGHT                      0x00000001
define TEXT_XCENTER                     0x00000002
define TEXT_YBOTTOM                     0x00000004
define TEXT_YCENTER                     0x00000008
define TEXT_INTERNALSPACE               0x00000010
define TEXT_TILESPACE                   0x00000020
define TEXT_INTERNALLINE                0x00000040
define TEXT_TILELINE                    0x00000080
define TEXT_XOFFSETZERO                 0x00000100
define TEXT_XJUSTIFY                    0x00000200
define TEXT_YOFFSETZERO                 0x00000400
define TEXT_YJUSTIFY                    0x00000800
define TEXT_LINEWRAP                    0x00001000
define TEXT_UPPERCASE                   0x00002000
define TEXT_INVERTCASE                  0x00004000
define TEXT_IGNOREESCAPE                0x00008000
define TEXT_LITERALESCAPE               0x00010000
define TEXT_BACKWARDS                   0x00020000
define TEXT_GAMETEXTNUMHACK             0x00040000
define TEXT_DIGITALNUMBER               0x00080000
define TEXT_BIGALPHANUM                 0x00100000
define TEXT_GRAYFONT                    0x00200000
define TEXT_NOLOCALE                    0x00400000
define TEXT_VARHEIGHT                   0x00800000
define TEXT_CENTERCONSTWIDTH            0x01000000

Default settings replicating other text commands

gametext

  • <tilenum>: STARTALPHANUM
  • <x>: Divided in half. The gametext command treats x=320 as the middle of the screen, while screentext operates like rotatesprite and uses x=160 as the center. (Gametext did not gain any precision; the quotient of dividing in half was always truncated, rounded down.)
  • <xspace>: 5
  • <yline>: 8
  • <xbetween>: 0
  • <ybetween>: 0
  • <text flags>: TEXT_CONSTWIDTHNUMS

minitext

  • <tilenum>: MINIFONT
  • <xspace>: 4
  • <yline>: 6
  • <xbetween>: 1
  • <ybetween>: 1
  • <text flags>: TEXT_UPPERCASE (unless your mod adds lowercase tiles to the MINIFONT set, in which case 0)

regular expression

Find: minitext +([A-Za-z0-9_]+) +([A-Za-z0-9_]+) +([A-Za-z0-9_]+) +([A-Za-z0-9_]+) +([A-Za-z0-9_]+)
Replace: screentext MINIFONT $1 $2 zoom blockangle charangle $3 $4 $5 orientation alpha 4 6 1 0 0x00002000 x1 y1 x2 y2

menutext

  • <tilenum>: BIGALPHANUM
  • <y>: decremented by 12
  • <xspace>: 5
  • <yline>: 16
  • <xbetween>: 0
  • <ybetween>: 0
  • <text flags>: TEXT_BIGALPHANUM + TEXT_UPPERCASE (+ TEXT_LITERALESCAPE if you want)

digitalnumber

  • <tilenum>: DIGITALNUM or THREEBYFIVE
  • <quote>: Use qsprintf to insert a gamevar into a quote.
  • <xspace>: 4
  • <yline>: 8
  • <xbetween>: 1
  • <ybetween>: 0
  • <text flags>: TEXT_XCENTER + TEXT_DIGITALNUMBER

Examples

screentext.con