LibAMP Readme

• Home: https://github.com/1Hyena/libamp
• Issue tracker: https://github.com/1Hyena/libamp/issues

In LibAMP, the letters AMP stand for "ANSI Map" (as in ANSI art), and the Lib prefix indicates that it is a library for the C programming language.

What is AnsMap

AnsMap (AMP) is a data structure that stores the instructions for printing ANSI art graphics to the terminal. The AnsMap Library is accompanied by a set of methods for ansmap construction and for the conversion of ansmap images to ANSI escape code sequences.

In this context, an ansmap is a digital text-based image represented as a grid of individual cells called glyphs. Each glyph stores color and style information to form a complete picture.

The AnsMap Library offers a specialized application programming interface (API) designed for creating terminal applications and games like multi-user dungeons (MUDs) and roguelikes. It includes the following features:

• Header-only: The AnsMap Library is implemented in a single header file with no dependencies other than the standard C library.

• Non-allocating: LibAMP does not involve any heap memory allocations.

• UTF8-only: The library expects UTF-8 encoding of the input text and does not attempt to detect Unicode encoding errors.

• Multi-palette: The generated ANSI escape sequences can include color codes either specific to the standard 16 color palette or to the 24 bit true color mode.

• Text wrapping: The LibAMP API allows for multiline text drawing with the user specified maximum line width parameter.

• Portable: LibAMP builds and functions on Linux. It should be relatively simple to make it run on most other platforms as long as the platform provides the C standard library.

• Permissive license: LibAMP is available under the MIT license.

Installation

Clone the repository and include the header file in your project. Compile using a C compiler (C23 or later required).

Using LibAMP

The usage of the library can be divided into two main parts: drawing and rendering. The following sections provide a brief overview of each.

Drawing ansmap images

To create an ansmap image, you can include the amp.h header file directly in your codebase. The library is implemented in a single C header file for easy integration.

The main functions to use for drawing are amp_init() and amp_draw_text(). The initialization function is necessary to specify the image resolution and data buffer. The text drawing function takes the initialized ansmap pointer as an argument and prints the desired text on it.

While the initialization of the ansmap data structure typically requires an external data buffer for storing the image state in memory, it can be omitted. If omitted, the library will try to use the limited amount of integrated memory associated with each ansmap. The amount of integrated memory is defined by the AMP_BUF_SIZE macro, which the user can define according to their needs in each compilation unit.

To determine the size of the external data buffer before initialization, the API provides the amp_calc_size() function, which takes the image resolution as its arguments.

Rendering ansmap images

To display an ansmap in the terminal, use the amp_to_ans() function. It requires a pointer to the ansmap image structure and a pointer to the memory location to copy the result. If nullptr is used for the memory location, the output will be written to the standard output of the program.

Examples

ex24bit

The ex24bit example demonstrates how to use the 24 bit true color mode when converting the ansmap into a sequence of ANSI escape codes.

libamp/examples/src/ex24bit.c

Lines 28 to 32 in 1f4544b

	draw_palette(&amp);
	amp_set_palette(&amp, AMP_PAL_24BIT); // Enable the true color mode.
	amp_to_ans(&amp, nullptr, 0); // Write to stdout.
	amp_stdout("\n", 1);

exmemory

The exmemory example shows how to allocate memory from the heap and use it for the storage of an ansmap image. It then fills the image with randomly chosen and styled printable ASCII characters.

libamp/examples/src/exmemory.c

Lines 17 to 49 in 1f4544b

	size_t buffer_size = amp_calc_size(width, height);
	uint8_t *buffer = malloc(buffer_size);
	if (!buffer) {
	static const char message[] = "malloc: allocation failed\n";
	write(2, message, strlen(message));
	return EXIT_FAILURE;
	}
	struct amp_type amp;
	if (amp_init(&amp, width, height, buffer, buffer_size) > buffer_size) {
	static const char message[] = "amp_init: not enough memory provided\n";
	write(2, message, strlen(message));
	return EXIT_FAILURE;
	}
	for (unsigned y=0; y<height; ++y) {
	for (unsigned x=0; x<width; ++x) {
	char glyph[] = {
	// Let's draw a random character.
	(char) random_uint64() % CHAR_MAX, '\0'
	};
	amp_draw_glyph(
	&amp,
	random_uint64(), // Let's enable random styles.
	x, y, glyph
	);
	}
	}
	amp_to_ans(&amp, nullptr, 0); // Write to stdout.

API

amp_calc_size

libamp/amp.h

Lines 114 to 120 in 1f4544b

	static inline size_t amp_calc_size(
	uint32_t ansmap_width,
	uint32_t ansmap_height
	// Returns the size of the data buffer needed for the initialization of an
	// ansmap with the given resolution.
	);

Examples: ex24bit, exmemory

amp_init

libamp/amp.h

Lines 122 to 133 in 1f4544b

	static inline size_t amp_init(
	struct amp_type * amp,
	uint32_t ansmap_width,
	uint32_t ansmap_height,
	void * data,
	size_t data_size
	// Initializes the given ansmap data structure. If the data buffer is not
	// big enough for the image, then the end of the image will be cut off.
	//
	// Returns the size of the data buffer needed for the given resolution.
	);

Examples: exhello, exmultiline, ex24bit, exmemory

amp_clear

libamp/amp.h

Lines 135 to 138 in 1f4544b

	static inline void amp_clear(
	struct amp_type * amp
	// Fills the ansmap with empty string glyphs and resets their style.
	);

amp_set_palette

libamp/amp.h

Lines 140 to 146 in 1f4544b

	static inline void amp_set_palette(
	struct amp_type * amp,
	AMP_PALETTE palette
	// Sets the color palette for the given ansmap. It is effective only during
	// the conversion of the ansmap into ANSI escape sequences.
	);

Examples: ex24bit

amp_draw_glyph

libamp/amp.h

Lines 148 to 156 in 1f4544b

	static inline void amp_draw_glyph(
	struct amp_type * amp,
	AMP_STYLE glyph_style,
	long glyph_x,
	long glyph_y,
	const char * glyph_str
	// Draws a single glyph on the given ansmap.
	);

Examples: exmemory

amp_draw_text

libamp/amp.h

Lines 158 to 168 in 1f4544b

	static inline void amp_draw_text(
	struct amp_type * amp,
	AMP_STYLE text_style,
	long text_x,
	long text_y,
	AMP_ALIGN text_alignment,
	const char * text_str
	// Draws the provided UTF-8 encoded text on the ansmap. Newlines and other
	// non-printable ASCII characters will be replaced by question marks.
	);

Examples: exhello

amp_draw_multiline_text

libamp/amp.h

Lines 170 to 184 in 1f4544b

	static inline size_t amp_draw_multiline_text(
	struct amp_type * amp,
	AMP_STYLE text_style,
	long text_x,
	long text_y,
	uint32_t text_max_width,
	AMP_ALIGN text_alignment,
	const char * text_str
	// Draws the provided UTF-8 encoded text on the ansmap. This function wraps
	// the line if its width exceeds the maximum allowed width. If the maximum
	// width is zero, then wrapping is disabled.
	//
	// Returns the number of lines drawn.
	);

Examples: exmultiline,

amp_to_ans

libamp/amp.h

Lines 186 to 199 in 1f4544b

	static inline ssize_t amp_to_ans(
	const struct amp_type * amp,
	char * ans_dst,
	size_t ans_dst_size
	// Converts the given ansmap into ANSI escape sequences. The escape codes
	// will be copied to the provided data buffer. If the buffer pointer is a
	// null pointer, then the output will be written into the program's standard
	// output.
	//
	// Returns the number of bytes that would have been written if the given
	// buffer was big enough. If the buffer is too small, then its first byte
	// is set to zero. The return value of -1 indicates an error.
	);

Examples: exhello, exmultiline, ex24bit, exmemory

amp_row_to_ans

libamp/amp.h

Lines 201 to 215 in 1f4544b

	static inline ssize_t amp_row_to_ans(
	const struct amp_type * amp,
	uint32_t y,
	char * ans_dst,
	size_t ans_dst_size
	// Converts one row of the given ansmap into ANSI escape sequences. The
	// escape codes will be copied to the provided data buffer. If the buffer
	// pointer is a null pointer, then the output will be written into the
	// program's standard output.
	//
	// Returns the number of bytes that would have been written if the given
	// buffer was big enough. If the buffer is too small, then its first byte
	// is set to zero. The return value of -1 indicates an error.
	);

amp_clip_to_ans

libamp/amp.h

Lines 217 to 233 in 1f4544b

	static inline ssize_t amp_clip_to_ans(
	const struct amp_type * amp,
	uint32_t x,
	uint32_t y,
	uint32_t width,
	char * ans_dst,
	size_t ans_dst_size
	// Converts a segment of a single row in the given ansmap into ANSI escape
	// sequences. The escape codes will be copied to the provided data buffer.
	// If the buffer pointer is a null pointer, then the output will be written
	// into the program's standard output.
	//
	// Returns the number of bytes that would have been written if the given
	// buffer was big enough. If the buffer is too small, then its first byte
	// is set to zero. The return value of -1 indicates an error.
	);

amp_get_glyph

libamp/amp.h

Lines 235 to 243 in 1f4544b

	static inline const char * amp_get_glyph(
	const struct amp_type * amp,
	uint32_t x,
	uint32_t y
	// Returns a pointer to the null-terminated UTF-8 encoded string of the
	// glyph on the given position of the ansmap. If the specified position is
	// not on the ansmap, then a null pointer is returned.
	);

amp_put_glyph

libamp/amp.h

Lines 245 to 255 in 1f4544b

	static inline const char * amp_put_glyph(
	struct amp_type * amp,
	const char * glyph,
	uint32_t x,
	uint32_t y
	// Overwrites a single glyph in the ansmap on the given position and returns
	// a pointer to the null-terminated UTF-8 encoded string of the new glyph.
	// If the specified position is not on the ansmap, then a null pointer is
	// returned.
	);

amp_get_style

libamp/amp.h

Lines 257 to 263 in 1f4544b

	static inline AMP_STYLE amp_get_style(
	const struct amp_type * amp,
	uint32_t x,
	uint32_t y
	// Returns the style bits of a glyph on the ansmap from the given position.
	);

amp_put_style

libamp/amp.h

Lines 265 to 274 in 1f4544b

	static inline bool amp_put_style(
	struct amp_type * amp,
	AMP_STYLE style,
	uint32_t x,
	uint32_t y
	// Sets the style of a glyph on the ansmap at the given position.
	//
	// Returns true on success and false if the position is not on the ansmap.
	);

amp_get_bg_color

libamp/amp.h

Lines 276 to 283 in 1f4544b

	static inline struct amp_color_type amp_get_bg_color(
	struct amp_type * amp,
	uint32_t x,
	uint32_t y
	// Returns a color data structure holding the background color information
	// of a glyph on the ansmap at the given position.
	);

amp_set_bg_color

libamp/amp.h

Lines 285 to 294 in 1f4544b

	static inline bool amp_set_bg_color(
	struct amp_type * amp,
	struct amp_color_type background_color,
	uint32_t x,
	uint32_t y
	// Sets the background color of a glyph on the ansmap at the given position.
	//
	// Returns true on success and false if the position is not on the ansmap.
	);

Examples: ex24bit

amp_get_fg_color

libamp/amp.h

Lines 296 to 303 in 1f4544b

	static inline struct amp_color_type amp_get_fg_color(
	struct amp_type * amp,
	uint32_t x,
	uint32_t y
	// Returns a color data structure holding the foreground color information
	// of a glyph on the ansmap at the given position.
	);

amp_set_fg_color

libamp/amp.h

Lines 305 to 314 in 1f4544b

	static inline bool amp_set_fg_color(
	struct amp_type * amp,
	struct amp_color_type foreground_color,
	uint32_t x,
	uint32_t y
	// Sets the foreground color of a glyph on the ansmap at the given position.
	//
	// Returns true on success and false if the position is not on the ansmap.
	);

amp_map_rgb

libamp/amp.h

Lines 316 to 323 in 1f4544b

	static inline struct amp_color_type amp_map_rgb(
	uint8_t red,
	uint8_t green,
	uint8_t blue
	// Returns a color data structure holding the color information given in
	// the arguments.
	);

Examples: ex24bit

amp_unmap_rgb

libamp/amp.h

Lines 325 to 333 in 1f4544b

	static inline void amp_unmap_rgb(
	struct amp_color_type color,
	uint8_t * red,
	uint8_t * green,
	uint8_t * blue
	// Copies the red, green and blue color components from the given color data
	// structure to the addresses specified in the arguments respectively.
	);

amp_lookup_color

libamp/amp.h

Lines 335 to 340 in 1f4544b

	static inline struct amp_color_type amp_lookup_color(
	AMP_COLOR color_index
	// Returns a color data structure holding the color information of the given
	// color by its index.
	);

amp_stdout

libamp/amp.h

Lines 342 to 349 in 1f4544b

	static inline ssize_t amp_stdout(
	const char * str_src,
	size_t str_src_size
	// Writes the given buffer into the program's standard output fully.
	//
	// Returns the number of bytes written or -1 to indicate an error.
	);

License

The AnsMap Library has been authored by Erich Erstu and is released under the MIT license.