Termlib demo

What is this?

TL;DR: An MVP of a terminal-inspired text rendering library for XO-CHIP.

See the GitHub repo for quickstart instructions and source code.

As of Octojam 10, it supports notions of foreground and background:

: message_string
    text "^B3^F2"
    text "PLANE 3 BG PLANE 2 TXT\n"
    text "^D"  # Reset the colors
    text "PLANE 0 BG PLANE 3 TXT\n"
    text "^B2" # Set BG plane to 3
    text "PLANE 2 BG PLANE 3 TXT\"
    text "\0" # \0 ends the message.
:main
    show-msg 0 0 message_string
    
    v0 := key # wait for input before the rest of the program

Please provide feedback on the syntax & future features proposed below!

Why build this?

I wanted:

1. A quickstart tool for rendering text in Octo projects
2. A configurable renderer to help restart work on Fontknife, another project of mine
3. To learn about text formatting and rendering on low-resource and retro platforms

How does it work?

TL;DR: It reads certain character combinations as formatting control instead of drawing them as sprites.

Let's use the title screen from the demo above as an example. With the library, drawing the formatted text on it consists of the following:

1. Declare the following label:

   : msg_title
      text "\n\n"
      text "^F3^B0 COLOR LIB DEMO \n"
      text "     ^F3^B2 PRESS ANY KEY ^D\n"
      text "       ^F1^B3 ALL TEXT DYNAMIC!\0"
   

2. Call the drawing routine:

   show-msg 0 0 msg_title
   # Wait for input to allow observing the text
   v0 := key
   

Every ^ starts an escape sequence which changes the drawing planes instead of rendering as text. Some set non-default colors, while others restore defaults.

The result:

The second screen shows off the full range of color combinations by using the following syntax:

: msg_all
  text "^F0^B0 0^F1^B0 1^F2^B0 2^F3^B0 3\n"
  text "^F0^B1 4^F1^B1 5^F2^B1 6^F3^B1 7\n"
  text "^F0^B2 8^F1^B2 9^F2^B210^F3^B211\n"
  text "^F0^B312^F1^B313^F2^B314^F3^B315\0"

The result:

Is it fast?

TL;DR: Yes-ish.

For maximum performance, you should follow Internet Janitor's advice on performance.

Otherwise, this library will probably be ok for getting started. The demo embedded on this page runs at 100 instructions / cycle. It will run smoothly down to 30 instructions / cycle. After that point, pauses from string parsing will grow more noticeable.

Since there is a lot of room for optimization, it is unclear what the minimum instruction / cycle will be.

Syntax Details

TL;DR: "What if Bash color escapes were better?"

The ^ character enters escape mode. To save CPU cycles and memory, there is no closing tag and no stack. Instead, effects are applied immediately. You can restore defaults by either binding them to a string to draw, or use the dedicated shortcut:

As Regex

TL;DR: There are interactive regex playgrounds linked below.

Current Limitations

TL;DR: There are a lot of brittle assumptions and no way to keep vF results.

The drawing layers imitate the concepts of other systems by using double length sprites compatible with plane 3. Font data is expected to match this standard. This is how the second screen generates all its color combinations: XO-CHIP's XOR-based allows effects like stenciling shapes out of single-color surfaces.

Despite its potential, the current implementation is currently incomplete in ways which limit its use for more demanding tasks. Some of the most important examples are outlined below.

See the following to learn more:

• The Inspiration heading below
• The XO-Chip documentation

Planned Additions

text "^R5^C5example"

text "^X51^Y23example"

text "^E3"

Future features could also include:

• Caching of rendered glyphs to speed up XOR-erasing specific parts
• Limited UI / widget features

Design goals

TL;DR: Imitate some old terminal behaviors but with quality of life improvements.

The CHIP-8 instruction set was originally designed for 1970s kit computers. This hardware was extremely limited, even when compared to the era's terminals and more some recent household appliances. For example, these kit computers:

• ran at less than 2 MHz
• came with less than 2 KB of RAM

Systems from this era made the most of their limited resources by reserving control characters for communication and markup, as well as using escape characters to indicate changes in encoding.

Since control characters are often represented with caret notation, this library re-uses it as a convenient default escape character. However, the final value is not converted to a byte literal but left as an ASCII ^.

It has numerous advantages:

1. It works with the limitations of Octo's :stringmode macros without sacrificing any clarity
2. Combining styles is far more legible:
3. It's easier to implement in Octo
4. It renders cleanly in Octo's debugger unlike unprintable byte literals
5. The resulting escapes are easier to distinguish than hex codes
6. It's easier to enter than hex codes

Aside from wasting bytes, there seem to be few downsides, especially if you are still prototyping. The ^ character seems to generally be unused in Octo projects due to poor legibility in pixel fonts, especially at the supported screen resolutions.

Inspiration

• rich, a Python terminal formatting library
• Control & drawing behaviors from specific systems:
  • Control codes used in teletext systems from same era as CHIP-8
  • The Varvara VM's dual-layer screen device
  • Python's history of multiple string formatting techniques