Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pushfoo/octo-termlib
A terminal-like text library for XO-CHIP in assembly
https://github.com/pushfoo/octo-termlib
assembly assembly-language chip-8 octojam terminal text-rendering xo-chip
Last synced: about 1 month ago
JSON representation
A terminal-like text library for XO-CHIP in assembly
- Host: GitHub
- URL: https://github.com/pushfoo/octo-termlib
- Owner: pushfoo
- Created: 2023-11-03T01:40:01.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-03-30T04:00:02.000Z (9 months ago)
- Last Synced: 2024-10-22T23:34:16.272Z (2 months ago)
- Topics: assembly, assembly-language, chip-8, octojam, terminal, text-rendering, xo-chip
- Language: Roff
- Homepage:
- Size: 102 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# octo-termlib
[itch]: https://pushfoo.itch.io/termlib-demo
[octojam10]: https://itch.io/jam/octojam-10
[chiplet]: https://github.com/gulrak/chiplet
[octopus]: https://github.com/Timendus/chipcode/tree/main/octopus
[octo]: https://github.com/JohnEarnest/Octo
[xo-chip]: http://johnearnest.github.io/Octo/docs/XO-ChipSpecification.html
[octo-ide]: http://johnearnest.github.io/Octo/
**TL;DR**: A terminal-inspired text rendering library in [Octo][octo]
for [XO-CHIP][xo-chip].
It supports notions of foreground and background.
License TBD, but there's [an interactive demo on itch.io][itch]. This
project was initially written as an [Octojam 10][octojam10] entry.
## Quickstart
1. Save [template.8o](template.8o) or copy it into the online [Octo IDE][octo-ide]
2. Find the `Start of User code` heading
3. Replace the code between it and the `End of User Code` heading to match the following:
```
####### Start of User code #######
: main
hires
loop
clear
show-msg 0 0 message_string
v0 := key # Wait for user input before looping
again
: 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.
####### End of User Code ######
```
When you compile & run, you should see something like the following:
The exact colors depend on your current XO-CHIP color palette.
## Table of contents
1. [How big is it?](#how-big-is-it)
2. [Why build this?](#why-build-this)
3. [How does it work?](#how-does-it-work)
4. [Is it fast?](#is-it-fast)
5. [Syntax Details](#syntax-details)
6. [Design goals](#design-goals)
7. [Current limitations](#current-limitations)
8. [Inspiration](#inspiration)
## How big is it?
**TL;DR** It depends on which parts you use.
The demo built with `make demo-rom` takes up 1408 bytes.
Most of that is the default character set found in:
1. [src/default_font_data.8o](src/default_font_data.8o)
2. [src/default_font_stringmodes.8o](src/default_font_data.8o)
You can override this data before importing [src/render_core.8o](src/render_core.8o)
as described in [docs/style_conventions.8o](docs/style_conventions.md#includes--overrides).
If you define a character set with different contents or structure,
you may also have override the following:
1. `show-msg` before importing `render_core.8o`
2. Any character handlers you use from `render_impl.8o` before importing it
## 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](https://github.com/pushfoo/Fontknife), another project
of mine
3. To learn about text formatting and rendering on low-resource and
retro platforms
Bash's color escapes are not the tool I was looking for:
1. Bash-style color escapes are hard to read:
| Bash-style escape | octo-termlib syntax |
|----------------------------------|-------------------------------|
| `\e[37mLight gray foreground\]` | `^F1Light gray foreground^D` |
| `\e[41mRed background\]` | `^B2Red background^D` |
| `\e[41m\e[37Both colors\]\]` | `^B2^F3Both colors^D` |
2. [Octo\'s `:stringmode` macro](https://johnearnest.github.io/Octo/docs/Manual.html#strings)
does not support `\e`
3. Substituting another escaped character would make them harder to
read
4. The substituted codes would end up using even more space than they
already do.
5. Processing them would be harder to implement in Octo.
## 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 TERM 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
```
The result:
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 second screen shows off the full range of color combinations by
using the following syntax:
```console
: 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**: Fast enough for most use cases with plenty of room for
optimizations.
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 become 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:
| Name | Escape code | Action(s) |
|----------------|-------------|---------------------------------------------------------------------------------------------|
| **D**efaults | `^D` |
- Set `bg_color` to `0` invisble.
- Set `fg_color` to `3` (Full color)
|
| **B**ackground | `^BN` | Set the draw plane(s) for the flat character used to color the background layer |
| **F**oreground | `^FN` | Set the draw plane(s) for the foreground layer. |
### As Regex
**TL;DR**: There are interactive regex playgrounds linked below.
| Regex Flavor | Regex101 Link | Rough expression |
|------------------------|-------------------------------------------|----------------------------------------|
| ECMAScript/JavaScript | [Try it](https://regex101.com/r/0366WB/) | `/(\^(?[A-Z])(?\d?)+)/` |
| Python | [Try it](https://regex101.com/r/4upDdM/) | `r'\^(?P[A-Z])(?P\d)?'` |
## 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.
| Current Implementation | Limitation |
|-----------------------------------------------------------|--------------------------------------------------------------------|
| No form of error handling in any shape | Bad input can break non-debugger status displays. |
| One message position stored at time without caching | Library best used for predictable state such as JRPG text boxes |
| Assumes monospace fonts | Unexpected character sizes will not render highlighting correctly. |
| Layer draw calls skip if their `plane` is 0 | Inconsistent timing if plane values change |
| Storing `vF` from successive draw calls is unimplemented | Can\'t detect XOR collisions while batch drawing text |
See the following to learn more:
- The [Inspiration](#inspiration) heading below
- The [XO-Chip documentation](http://johnearnest.github.io/Octo/docs/XO-ChipSpecification.html#bitplanes)
### Planned Additions
| Tentative Example | Meaning | Intended Purpose |
|--------------------------|-----------------------------------------------|-------------------------------------------|
| `text "^R5^C5example"` | Jump drawing cursor to row 5, column 5 | Replacing or deleting specific characters |
| `text "^X51^Y23example"` | Move the drawing cursor to screen pixel 51,32 | Fast kerning experimentation. |
| `text "^E3"` | XOR entire screen with pixels using `plane 3` | Change / flash colors for errors |
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](https://en.wikipedia.org/wiki/Control_character) for
communication and markup, as well as using [escape characters](https://en.wikipedia.org/wiki/Escape_character)
to indicate changes in encoding.
Since control characters are often represented with [caret notation](https://en.wikipedia.org/wiki/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 `^`.
[octo-debugger-doc]: https://johnearnest.github.io/Octo/docs/Manual.html#debugging
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][octo-debugger-doc],
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](https://github.com/Textualize/rich), a Python terminal
formatting library
- Control & drawing behaviors from specific systems:
- [Control codes used in teletext systems from same era as
CHIP-8](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#Modified_C0_control_code_sets)
- The [Varvara VM\'s dual-layer screen
device](https://wiki.xxiivv.com/site/varvara.html#screen)
- Python\'s [history of multiple string formatting
techniques](https://docs.python.org/3/tutorial/inputoutput.html#fancier-output-formatting)