====== Alphanumeric Display ======

The Bally Arcade provides several routines to display alphanumeric information. This section provides details about the standard and small character sets, loading alternate fonts, and the options common to all alphanumeric display routines.

===== Standard System Font =====

The Bally Arcade system font uses a subset of the standard ASCII table along with a few extended options (see [[#ASCII representation]] below). The following example displays the full standard system font characters 20H–63H (including the leading space character) using a [[system routines:screen handler#strdis|STRDIS]] call:

----

=== Example: System Font ===

{{:strdis_all.png}}


===== Alphanumeric Registers =====

The following register/argument combinations are used by all of the alphanumeric display routines.

==== C (Options) ====

Register C contains the options byte formatted as shown below:

{{:option_byte.png}}

The Enlarge Factor specifies if the character is to be enlarged in size. The table below defines the possible values for this parameter.

^ Enlarge Factor ^ Size Multiple ^ Enlarged Size of Single Pixel ^
| 00 | 1 | 1x1 |
| 01 | 2 | 2x2 |
| 10 | 4 | 4x4 |
| 11 | 8 | 8x8 |

XOR/OR WRITE causes the character to be ORed/XORed with the data 'beneath' it. These writes are performed through [[hardware:magic system|Magic memory]].

ON/OFF COLOR specifies the pixel values to translate the one-bit-per-pixel character patterns into. (All characters are stored as one-bit-per-pixel, but are written two-bits-per-pixel via the [[hardware:magic system#expander|Expander]].) For example, the value 1101 specifies that the foreground character color is 11, and the background color is 01.

----

=== Example: Enlarge Factors ===

<WRAP group>
<WRAP column third>{{:strdis_2x.png}}\\ **Enlarge Factor x2**\\ 6 lines per screen\\ 10 characters per line</WRAP>
<WRAP column third>{{:strdis_3x.png}}\\ **Enlarge Factor x4**\\ 3 lines per screen\\ 5 characters per line</WRAP>
<WRAP column third>{{:strdis_4x.png}}\\ **Enlarge Factor x8**\\ 1 line per screen\\ 2 characters per line</WRAP>
</WRAP>

<WRAP info>In the examples above, the colored pixels visible at the bottom of the screen display the contents of scratchpad RAM. They are left visible to show string display limits. Strings that overlap scratchpad RAM can overwrite the stack and cause program crashes.</WRAP>

==== DE (X-/Y-Coordinates) ====

The x- (E) and y-coordinate (D) give the address of the upper left-hand corner where the first character will appear. Upon return, these registers are updated to give the address of the character to the right (or below if no more space exists on the line), simplifying the composition of complex messages.

However, be aware that placing a character whose frame extends beyond the right edge of the screen //and// has no room to wrap to the next line will cause the character to wrap to the left edge //on the same line//. This is especially important when using the expansion option, since wrapped characters will overwrite other characters.

----

=== Example: String Wrapping ===

{{:strdis_4x_wrap.png}}

In the example above, the system attempts to display the string '012' with the 8x Enlarge Factor set. However, the character '2' is too large to fit on the line, so its right edge wraps to the left side of the display, overwriting a portion of the '0' numeral.


==== IX (Alternate Font Descriptor) ====

Register IX contains the Alternate Font Descriptor. It is required only if an alternate font is referenced in the system routine call (i.e., pre-loading IX with the alternate font address). Each character must be stored in one-bit per pixel format.

The format of the alternate font descriptor is illustrated below:

{{:alt_font_descriptor.png}}

The font base character defines the first ASCII character code in the alternate font. Codes $80–$FF are reserved for this purpose. The frame size describes the rectilinear area that encloses the character and its margin, while the x- and y-sizes describe the height and width of the characters themselves. Finally, the font pattern table is a 16-bit address pointer to the user-defined patterns.

The standard system font, for example, has 5x7-pixel characters within an 8x8-pixel frame, leaving a three-pixel margin on the right and a one-pixel margin on the bottom. The font's base ASCII character is 20H. 

----

=== Example: Frame Size vs. Pattern Size ===

{{:font_frame.png}}

In the illustration above, the alternating black and grey boxes outline the 8x8 character frames; the red pixels display eight character patterns in the system font. Note that most characters push against the upper and left borders of the frame in order to leave margins to the right and bottom. Some thinner characters like the numeral 1 have additional padding on either side.

A built-in small (3x5-pixel) character set is displayed using this facility. A word in the system [[:glossary#d|dope vector]] (FNTSML) points at a standard alternate font descriptor for this character set (located at $020D), as seen in the code snippet below:

<code z80>
; --- FNTSML: FoNT descriptor for SMaLl font
; L020D:
SMLFNT:
        DB      $A0             ; FonT BASE character
        DB      $04             ; FonT Frame X Size width
        DB      $06             ; FonT Frame Y Size height
        DB      $01             ; FonT X size of char in BYTEs
        DB      $05             ; FonT Y SIZe height in bits
        DW      SMLCHR          ; FonT Pattern Table address
</code>

The small font includes numerals 0–9, a colon (:), and a bullet icon used in //[[:Gunfight]]//. 

<wrap help>Testing shows that base character starts at B0H instead of A0H?</wrap>
----

=== Example: Small vs. Standard Character Set ===

<WRAP group>
<WRAP half column>{{:strdis_small_large.png}}\\ The FNTSML alternate font displayed atop an equivalent string in the standard system font.</WRAP>
<WRAP half column>{{:gunfight-play.png}}\\ //[[:Gunfight]]// uses FNTSML for its upper HUD, including the bullet icons.</WRAP>
</WRAP>

----

=== Example: Character Option Mixing ===

Combining character enlargement, positioning, and foreground/background colors can create interesting visual variations:

<WRAP group>
<WRAP half column>{{:text_sizes_1.png}}\\ A screen demonstrating all four Enlarge Factors options and multiple foreground/background combinations.</WRAP>
<WRAP half column>{{:text_sizes_2.png}}\\ The same example with the horizontal color boundary set near the first third of the screen.</WRAP>
</WRAP>

----
=== Example: Character Mixing in Games ===

Bally Arcade games routinely mix multiple character options and fonts:

<WRAP group>
<WRAP half column>{{:solar01.png}}\\ //Solar Conqueror// uses the 1x, 2x, and small character set in its interstitial screens.</WRAP>
<WRAP half column>{{:dodgem.png}}\\ //Dodge 'Em// uses the 1x, 4x, and small character sets for its in-game HUD.</WRAP>
</WRAP>
===== ASCII Representation =====

ASCII character codes represent all strings, with the following extensions:

  * Characters $01–$1F are interpreted as tabulation codes that cause the character display routines to skip over N character positions before writing the following characters. A $03 value inserts a 3-character tab, $0F inserts a 15-character tab, and so on.
  * Characters $20–$63 are displayed as 5x7-pixel patterns (FNTSYS) with 3 pixels of horizontal spacing and 1 pixel of vertical spacing. (Lowercase letters are not part of the standard system font.)
  * Characters $64–$7F are interpreted by [[system routines:screen handler#strdis|STRDIS]] as control codes that cause the contents of registers C, DE, and IX to be changed to the value that follows the string. This facility is useful for changing size, write mode, screen coordinates, or fonts during a single STRDIS call. See the table below for more details.
  * Characters $80–$FF are interpreted as references to a user-supplied alternate character font.

==== Control Codes ====

The following table specifies which registers are loaded for a given code as well as the order in which the new register data follows.

^ Code (hex) ^ Registers ^ Code (hex) ^ Registers ^
| 64 | C | 72 | IX,D |
| 65 | E,C | 73 | IX,E,D |
| 66 | D,C | 74 | IX,C |
| 67 | E,D,C | 75 | IX,E,C |
| 68 | NONE | 76 | IX,D,C |
| 69 | E | 77 | IX,E,D,C |
| 6A | D | 78 | IX |
| 6B | E,D | 79 | IX,E |
| 6C | C | 7A | IX,D |
| 6D | E,C | 7B | IX,E,D |
| 6E | D,C | 7C | IX,C |
| 6F | E,D,C | 7D | IX,E,C |
| 70 | IX | 7E | IX,D,C |
| 71 | IX,E | 7F | IX,E,D,C |

----

=== Example: Manipulating Control Codes ===

In the following example, inline ASCII control codes are used to alter the characters within the startup menu. In the first screen, the string address points to the string stored at MENNAM:

<code z80>
MENNAM: DB      "DISPLAY TEST", 0
</code>

In the second screen, control code 64H sends new display options to register C. In this example, each byte following the control code alters the foreground/background text colors and/or the text enlargement scale.

<code z80>
MENNAM: DB      "D",$64,$0B,"I",$64,$46,"S",$64,$0C,"P",$64,$01,"LAY TEST", 0
</code>

<WRAP group>
<WRAP half column>{{:control_code_before.png}}\\ **Standard String Display**</WRAP>
<WRAP half column>{{:control_code_after.png}}\\ **String with Inline Control Codes**</WRAP>
</WRAP>

----

[NM:31–3, 38]