TTY text console. More...

#include "config.h"
#include "types.h"
#include "string.h"
#include "maths.h"
#include "dma.h"

Defines
#define	ENABLE_ASSERT_CHECKS
	Comment out to disable asserts.
#define	str(s) xstr(s)
	Helper macro to stringify numbers.
#define	xstr(s) #s
	Helper macro.
#define	assert(condition)
	Assert a condition.
#define	ASSERT(condition) assert(condition)
	Assert a condition.
Typedefs
typedef int(*	vsprintf_t )(char buf, const char fmt, va_list args)
	Callback prototype for a vsprintf() function using va_list.
typedef int(*	vsnprintf_t )(char buf, int count, const char fmt, va_list args)
	Callback prototype for a vsnprintf() function using va_list.
Functions
int	CON_sprintf (char buf, const char fmt,...) __attribute__((format(printf
	Standard C library sprintf function.
int int	CON_snprintf (char buf, int count, const char fmt,...) __attribute__((format(printf
	Standard C library snprintf function.
int int void	CON_setVsprintf (vsprintf_t vsprintf_func)
	Register a standard vsprintf function as callback for CON_sprintf()
void	CON_setVsnprintf (vsnprintf_t vsnprintf_func)
	Register a standard vsnprintf function as callback for CON_snprintf()
void	CON_setConsoleSize (u16 left, u16 top, u16 width, u16 height)
	Set the size of the console window.
void	CON_setLineBufferSize (u16 size)
	Set the size of the character line buffer.
void	CON_setTransferMethod (TransferMethod tm)
	Set the transfer method used to upload the console tile buffer to VDP RAM.
void	CON_reset ()
	Reset the console.
void	CON_systemResetOnNextWrite ()
	Reset the system to the SGDK default state when CON_write() is called next time.
void	CON_clear ()
	Clear the console window.
void	CON_setCursorPosition (u16 x, u16 y)
	Set a new cursor position.
V2u16	CON_getCursorPosition ()
	Return the current cursor position.
int	CON_write (const char *fmt,...) __attribute__((format(printf
	Write a C-string to the console window.

Detailed Description

TTY text console.

Author:: Andreas Dietrich

Date:: 09/2022

This unit provides a simple TTY text console. Characters are written as a stream, where lines are automatically wrapped if the horizontal border of the screen is reached. When at the bottom of the screen window, the console content is moved up by one text line and a blank row is inserted.

Per default, the console occupies a standad screen of 40x28 tiles. All text attributes, such as font, palette, plane etc., are taken from SGDK text settings. Screen updates are done using DMA transfer mode (which can be changed with CON_setTransferMethod()).

One of the use cases are assert messages. To this end, the Genesis state can be automatically reset before text is displayed (see assert macro below).

Define Documentation

#define assert ( condition )

Value:

if ( !(condition) )                                                                \
    {                                                                                  \
        CON_reset();                                                                   \
        CON_systemResetOnNextWrite();                                                  \
        CON_write(__FILE__":"str(__LINE__)": Assertion \'"str(condition)"\' failed."); \
        while (TRUE);                                                                  \
    }

Assert a condition.

Parameters:

condition Expression that must evaluate to TRUE, otherwise an error error message in printed to the console. This will also reset the system to the SGDK default state.

Can be disabled by undefining ENABLE_ASSERT_CHECKS or by defining NDEBUG.

#define ASSERT ( condition ) assert(condition)

Assert a condition.

Uppercase version. Same as assert().

Function Documentation

void CON_clear ( )

Clear the console window.

This clears the console window by filling it with space characters. It is assumed that the first tile of the font is a space character. DMA settings apply here as well.

V2u16 CON_getCursorPosition ( )

Return the current cursor position.

Returns:: A 2D vector containing the current (x,y) position of the cursor, where (0,0) means the top/left corner of the console window.

void CON_reset ( )

Reset the console.

This function is a shortcut for:

CON_setConsoleSize(0, 0, 40, 28);
CON_setLineBufferSize(160);
CON_setTransferMethod(DMA);

void CON_setConsoleSize	(	u16	left,
		u16	top,
		u16	width,
		u16	height
	)

Set the size of the console window.

Parameters:

left	Position of the leftmost window column in tiles. Default is 0.
top	Position of the topmost window row in tiles. Default is 0.
width	Width of the console window in tiles. Default is 40.
height	Height of the console window in tiles. Default is 28.

If either width or height are 0 then VDP_getScreenWidth() and VDP_getScreenHeight() will be used to determine suitable default values.

void CON_setCursorPosition	(	u16	x,
		u16	y
	)

Set a new cursor position.

Parameters:

x	New cursor x position.
y	New cursor y position.

This function specifies a new column and row for the cursor. This is the position where the next character will appear when CON_write() is processed. A position of (0,0) relates to the tile in the top/left corner.

void CON_setLineBufferSize ( u16 size )

Set the size of the character line buffer.

Parameters:

size	Buffer size in bytes. This is the number of characters the buffer can hold including a terminating null-character.

Sets the size of the character buffer that is used internally to compose the formatted output string which is printed on the console.

Upon calling CON_setLineBufferSize(), the previous line buffer memory is immedieately freed. The new buffer will be allocated once the next call to CON_write() occurs.

Per default, the buffer size is set to 160 characters. Note that if only a vsprintf function is registered (see CON_setVsprintf()), the user is responsible for making sure a call to CON_write() does not exceed the line buffer. In case a vsnprintf function is registered (see CON_setVsnprintf()), it will automtically check the buffer size and prevent overflows.

void CON_setTransferMethod ( TransferMethod tm )

Set the transfer method used to upload the console tile buffer to VDP RAM.

Parameters:

tm	Transfer method. Accepted values are: CPU DMA DMA_QUEUE DMA_QUEUE_COPY

This sets the transfer method used with VDP_setTileMapDataRect(). The default value is DMA, which will cause an immediate upload. Note that when DMA_QUEUE or DMA_QUEUE_COPY is used, the user is responsible for triggering DMA upload, e.g., by calling SYS_doVBlankProcess().

void CON_setVsnprintf ( vsnprintf_t vsnprintf_func )

Register a standard vsnprintf function as callback for CON_snprintf()

Parameters:

vsnprintf_func Function pointer to a standard C library vsnprintf function

Registers a callback function that will be wrapped by CON_snprintf(). The funcion supplied needs to be a vsnprintf function that takes va_list as arguments, defined as follows:

typedef int (*vsnprintf_t)(char *buf, int count, const char *fmt, va_list args);

A possible implementation is stbsp_vsnprintf() (http://github.com/nothings/stb).

int int void CON_setVsprintf ( vsprintf_t vsprintf_func )

Register a standard vsprintf function as callback for CON_sprintf()

Parameters:

vsprintf_func Function pointer to a standard C library vsprintf function

Registers a callback function that will be wrapped by CON_sprintf(). The funcion supplied needs to be a vsprintf function that takes va_list as arguments, defined as follows:

typedef int (*vsprintf_t)(char *buf, const char *fmt, va_list args);

Possible implementations are SGDK's vsprintf() or alternatively stbsp_vsprintf() (http://github.com/nothings/stb).

int int CON_snprintf	(	char *	buf,
		int	count,
		const char *	fmt,
			...
	)

Standard C library snprintf function.

Parameters:

buf	Pointer to the buffer where the resulting C-string is stored.
count	Maximum number of bytes to be used in the buffer. The generated string has a length of at most count-1, leaving space for the additional terminating null-character.
fmt	C-string that contains the text to be written. It can optionally contain embedded format specifiers that are replaced by the values specified in subsequent additional arguments and formatted as requested. (See https://en.wikipedia.org/wiki/Printf_format_string)
...	(additional arguments) The function may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string.

Returns:: The total number of characters written is returned. This count does not include the additional null-character automatically appended at the end of the string.

Composes a string that would result from using a standard C library printf function. In case fmt includes format specifiers (beginning with %), the additional arguments are formatted and inserted in the resulting string replacing their respective specifiers.

This function is a wrapper for a vsnprintf type function. Per default no function is registered. CON_setVsnprintf() can be used to register an implementation, e.g., stbsp_vsnprintf().

int CON_sprintf	(	char *	buf,
		const char *	fmt,
			...
	)

Standard C library sprintf function.

Parameters:

buf	Pointer to the buffer where the resulting C-string is stored.
fmt	C-string that contains the text to be written. It can optionally contain embedded format specifiers that are replaced by the values specified in subsequent additional arguments and formatted as requested. (See https://en.wikipedia.org/wiki/Printf_format_string)
...	(additional arguments) The function may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string.

Returns:: The total number of characters written is returned. This count does not include the additional null-character automatically appended at the end of the string.

Composes a string that would result from using a standard C library printf function. In case fmt includes format specifiers (beginning with %), the additional arguments are formatted and inserted in the resulting string replacing their respective specifiers.

This function is a wrapper for a vsprintf type function. Per default SGDK's built-in vsprintf() is used. CON_setVsprintf() can be used to register another implementation, e.g., stbsp_vsprintf().

void CON_systemResetOnNextWrite ( )

Reset the system to the SGDK default state when CON_write() is called next time.

To reset the system the following SGDK functions will be called:

int CON_write	(	const char *	fmt,
			...
	)

Write a C-string to the console window.

Parameters:

fmt	C-string that contains the text to be written. It can optionally contain embedded format specifiers that are replaced by the values specified in subsequent additional arguments and formatted as requested. (See https://en.wikipedia.org/wiki/Printf_format_string)
...	(additional arguments) The function may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string.

Returns:: The total number of characters written is returned. This count does not include the additional null-character automatically appended at the end of the string.

This function writes a C-string into the console window where lines are automatically wrapped if the horizontal border of the screen is reached. When at the bottom of the screen window, the console content is moved up by one text line and a blank row is inserted.

Internally it uses either vsprintf or vsnprintf functions that have been registered with CON_setVsprintf() or CON_setVsnprintf(), respectively.

While processing the string, this function evaluates and executes escape control sequences. The following control characters are supported:

\b : backspace
\n : new line (line feed)
\r : carriage return
\t : horizontal tab
\v : vertical tab

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Function Documentation