AGBTTY
Simple output-only video terminal emulation for Game Boy Advance
hardware

Copyright 2003 Damian Yerrick

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.




To use this library, include it as a source file in your GBA
program's makefile.  Then call any of the following functions
or hook them into your compiler's write() implementation.


=== Functions ===

int agbtty_init(void);
Loads a 2-color font corresponding to ISO-8859-1 into the
first 4 KB of VRAM, initializes the DMG sound for beeps, calls
agbtty_set_map(4), agbtty_attr(0), and agbtty_putc('\f'), and
loads BG0CNT with appropriate settings. Does not set a palette
or change DISPCNT. Returns 0 for success.

int agbtty_init_cursor(void);
Clears out all the sprites, loads underline data into tile 1023.

int agbtty_show_cursor(int shown);
If shown is 0, hides the cursor.  Otherwise, shows an 8x8 cursor
with 16-color tile data from sprite tile 1023 in palette 0.

int agbtty_set_map(size_t nt);
Sets the base address in VRAM of the GBA map holding the display and
scrollback buffer to nt, in 2 KB units. nt must be even and less
than or equal to 30. Does not clear the screen; to do that, call
agbtty_putc('\f'). Returns 0 for success or nonzero for error.

int agbtty_putc(int c);
Writes a printable ASCII or 8-bit character to the screen or act on
the following control characters defined in the ANSI C standard:

C   ASCII ACTION
'\a' 0x07 Play a tone through GBA Sound 1.
'\b' 0x08 Move the cursor to the left one space.
'\t' 0x09 Print spaces until the horizontal location of the cursor
          is a multiple of 8.
'\n' 0x0a Set scrollback to 0 and move the cursor to the beginning
          of the next line.
'\v' 0x0b Vertical tab; treated as '\n'.
'\f' 0x0c Set scrollback to 0, clear the terminal display, and
          move the cursor to the top left corner.
'\r' 0x0d Move the cursor to the beginning of the current line.

ssize_t agbtty_write(const void *buf, size_t size);
Calls agbtty_putc() for each char in buf. Returns the number of
written bytes.

int agbtty_puts(const char *buf);
Calls agbtty_putc() for each element of null-terminated buf[].
Returns 0 for success.

int agbtty_gotoxy(unsigned int x, unsigned int y);
Moves the cursor to (x, y) on the terminal display. (x, y) should
line in (0, 0) to (29, 19) inclusive. Returns 0 for success or
nonzero for failure. If you're calling agbtty functions through
stdout, you should fflush(stdout) before calling this function.

unsigned int agbtty_textattr(unsigned int attr);
Sets the text attribute (the value OR'd with each character written)
to attr. Returns attr. Useful if your font does not start at index
0 of a pattern table or if you want to write in colors. If you're
calling agbtty functions through stdout, you should fflush(stdout)
before calling this function.

int agbtty_scrollback(size_t n_lines);
Clamps 0 <= n_lines <= 44 and then sets the scrollback distance to
n_lines. Returns 0 for success or nonzero for failure.

extern int agbtty_cur_scrollback;
Stores the current scrollback value.

