Screentext - EDukeWiki

# Screentext

From EDukeWiki
(Redirected from Qstrdim)

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

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

It would not be fitting to document this command without also documenting its useful helper and companion, qstrdim, which calculates the dimensions taken up by an equivalent call to screentext.

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>

## Parameters

<width return var> and <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>, and <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.)

    setvarvar xdimminus xdim
    subvar xdimminus 1
    setvarvar ydimminus ydim
    subvar ydimminus 1
    // 0 0 xdimminus ydimminus

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

## Text Properties Bitfield

Value | Label | Description |
--- | --- | --- | ---
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
4096 | TEXT_LINEWRAP | Enable a hackish internal line wrapping feature used by some text in the executable (such as multiplayer messages) that will wrap a string back to its starting X position at the point when a character would go off the screen. This flag has no effect if any alignment flags are used or if the <block angle> is not a multiple of 512, which includes 0--perfectly horizontal or vertical.
8192 | TEXT_UPPERCASE | Force the case of all letters in the string to uppercase.
16384 | TEXT_INVERTCASE | Invert the case of the letters in the string. Combine with TEXT_UPPERCASE to produce all-lowercase output.
32768 | TEXT_IGNOREESCAPE | Palette escape sequences (^# or ^##) will have no effect. (See definequote.)
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.
131072 | TEXT_BACKWARDS | Iterate through the string backwards. (TEXT_LITERALESCAPE is highly recommended because there is not a separate pass to escape the palette sequences forwards.)
262144 | TEXT_GAMETEXTNUMHACK | 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'.
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))
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))
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)

This may be helpful in your CON files, using orvar to add bits and xorvar to remove them (but only when already set; ifvarand will allow you to check).

    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

## 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_GAMETEXTNUMHACK

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

source/lunatic/test/screentext.con

Retrieved from "http://wiki.eduke32.com/w/index.php?title=Screentext&oldid=11819"
Categories:

- EDuke32 specific commands
- Screen drawing commands