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 printing with the user specified maximum line width parameter.

• Inline style markers: In rich text printing, style information can be embedded into the source text at the location where the style needs to be applied.

• 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.

The AMP file format

LibAMP uses a unique file format that is easily readable by humans, allowing for convenient image editing using a standard text editor with a fixed-width font. The recommended file extension for AMP files is .amp.

An AMP file is divided into layers, with the first layer dedicated to text content and required to be present, even if it has zero height (indicating no text to be printed on the ansmap). Subsequent layers are optional and contain style markers such as foreground color, background color, and text decoration specifications. Each style marker occupying the same cell must be represented by a different layer.

A valid AMP file begins with Unicode box-drawing characters ╔ and ═. The number of ═ characters following the first character determines the width of the ansmap. The sequence is terminated by ╗.

Subsequent lines must start with ║, ╠, or ╚. If a line starts with ║, the count of ║ characters at the beginning of subsequent lines determines the height of that layer. The layer with the greatest height defines the ansmap's overall height.

If a line starts with ║, it must be followed by Unicode characters equal to the ansmap's width, then another ║. This sequence defines the contents of one row in a given layer. Lines starting with ╠ indicate the end of a layer and the start of a new one if followed by ═ characters equal to the ansmap's width and a ╣. Lines starting with ╚ mark the end of a layer and the end of the AMP file if followed by ═ characters equal to the ansmap's width and a ╝.

Here is an example of the contents of ansiart.amp and its resulting ANSI escape sequences displayed in the terminal:

The letters and symbols in the second and third box in the example above serve as style markers for the cells in the first box. Each style marker applies to a single cell, and their effects can be combined by using multiple style layers. The position of a style marker on the first layer is determined by its placement when the style layer is superimposed on the first layer.

For the key of style markers, please refer to the ExRich example as it includes the list of available style markers and their definitions.

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: creating and viewing. The following sections provide a brief overview of each.

Creating 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 are amp_init() and amp_print_text(). The initialization function is necessary to specify the image resolution and data buffer. The text printing 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.

Viewing 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 resulting ANSI escape code sequences that the terminal can render. If nullptr is used for the memory location, the output will be written to the standard output of the program.

Examples

To compile all the examples, run the make command in the examples directory.

ExUnicode

The exunicode example demonstrates the library's ability to represent unicode glyphs on the ansmap. In addition, it features text wrapping.

libamp/examples/src/exunicode.c

Lines 21 to 36 in ce0207e

	amp_print_text(
	&amp, 0, 0, AMP_BG_BLUE|AMP_FG_WHITE, 0, AMP_ALIGN_LEFT,
	"╔═════════════╗\n"
	"║ ║\n"
	"║ ║\n"
	"║ ║\n"
	"║ ║\n"
	"║ ║\n"
	"╚═════════════╝\n"
	""
	);
	amp_print_text(
	&amp, 1, 1, AMP_FG_YELLOW|AMP_BG_NAVY, amp_get_width(&amp) - 3,
	AMP_ALIGN_LEFT, "In this example, we also see text wrapping in action."
	);

ExRich

The exrich example prints the list of available rich text markers with the respective text samples.

libamp/examples/src/exrich.c

Lines 29 to 41 in ce0207e

	ssize_t written = amp_snprint_rich_textf(
	&amp, 0, 0, 0, 0, AMP_ALIGN_LEFT, buf, sizeof(buf),
	" {{%s → {%ssample{X (%s)", row.glyph, row.glyph, row.name
	);
	if (written < (ssize_t) sizeof(buf) && written >= 0) {
	amp_to_ans(&amp, nullptr, 0); // Write to stdout.
	amp_clear(&amp);
	if (n++ % 2) {
	amp_stdout("\n", 1);
	}
	}

ExEncode

The exencode program generates rich text on an ansmap, displays the result in the terminal, and exports the ansmap image as an AMP document, which is also displayed in the terminal.

libamp/examples/src/exencode.c

Lines 15 to 25 in ce0207e

	amp_print_rich_text(
	&amp, amp_get_width(&amp) / 2, 0, AMP_STYLE_NONE, 0, AMP_ALIGN_CENTER,
	"{Nnavy background{X, {rred foreground{x, {/italic{x, {/{?faint italic"
	);
	// Write to stdout.
	amp_to_ans(&amp, nullptr, 0);
	const char *comment = "\n\nConverted to a plaintext AMP container:\n";
	amp_stdout(comment, strlen(comment));
	amp_encode(&amp, AMP_FLATTEN|AMP_DEFLATE, nullptr, 0);

ExDecode

The exdecode example demonstrates how the human-readable AMP documents can be imported from memory.

libamp/examples/src/exdecode.c

Lines 7 to 40 in ce0207e

	static const char doc[] =
	"╔════════════════╗\n"
	"╠════════════════╣\n"
	"║ WS SW AA║\n"
	"║ OOOOOOOO AA║\n"
	"║ OOMRLLMR OO║\n"
	"║ CCLLLLLL OO║\n"
	"║OOCCOOCCOOCCOOLL║\n"
	"║LLLLCCOOCCOO OO║\n"
	"║ MMMMMMMMMM OO║\n"
	"║ CC CC OO║\n"
	"╚════════════════╝";
	uint32_t w, h;
	size_t data_size = amp_doc_parse_size(doc, sizeof(doc), &w, &h);
	uint8_t *data = nullptr;
	if (data_size) {
	data = malloc(data_size);
	if (data) {
	struct amp_type amp;
	if (amp_init(&amp, w, h, data, data_size) <= data_size) {
	if (amp_decode(&amp, doc, sizeof(doc))) {
	amp_to_ans(&amp, nullptr, 0);
	amp_stdout("\n", 1);
	}
	else error_message = "amp_decode: parse error\n";
	}
	else error_message = "amp_init: not enough memory provided\n";
	}
	else error_message = "malloc: allocation failed\n";
	}
	else error_message = "amp_parse_size: parse error\n";

ExAmpFile

The exampfile example is very similar to ExDecode. The only difference is that instead of deserializing a hardcoded AMP document, the program loads a user specified AMP file from the file system.

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 ce0207e

	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 ce0207e

	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));
	free(buffer);
	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_print_glyph(
	&amp, x, y,
	random_uint64(), // Let's enable random styles.
	glyph
	);
	}
	}

ExTiles

The extiles example shows how to fill a canvas with tiles from a different ansmap image.

libamp/examples/src/extiles.c

Lines 111 to 133 in ce0207e

	for (long y=0; y<dungeon_h; ++y) {
	for (long x=0; x<dungeon_w; ++x) {
	uint8_t tile_index = dungeon[d][y][x];
	if (!tile_index) {
	continue;
	}
	tile_index--;
	uint8_t tile_w = 8;
	uint8_t tile_h = 4;
	long tile_from_x = tile_w * tile_index + tile_index;
	long tile_from_y = 0;
	long tile_to_x = tile_w * x;
	long tile_to_y = tile_h * y;
	amp_draw_ansmap_region(
	canvas, tile_to_x, tile_to_y,
	tiles, tile_from_x, tile_from_y, tile_w, tile_h
	);
	}
	}

API

• Colors

  • amp_map_rgb (red, green, blue) → struct amp_color_type
  • amp_unmap_rgb (color, &red, &green, &blue)
  • amp_lookup_color (color index) → struct amp_color_type

• Ansmap creation

  • amp_calc_size (width, height) → size_t
  • amp_init (&ansmap, width, height, &data, data size) → size_t

• Ansmap properties

  • amp_get_palette (&ansmap) → AMP_PALETTE
  • amp_get_width (&ansmap) → uint32_t
  • amp_get_height (&ansmap) → uint32_t
  • amp_get_glyph (&ansmap, x, y) → const char *
  • amp_get_style (&ansmap, x, y) → AMP_STYLE
  • amp_get_bg_color (&ansmap, x, y) → struct amp_color_type
  • amp_get_fg_color (&ansmap, x, y) → struct amp_color_type

• Printing operations

  • amp_clear (&ansmap)
  • amp_print_glyph (&ansmap, x, y, style, &string)
  • amp_print_line (&ansmap, x, y, style, alignment, &string)
  • amp_snprint_linef (&amp, x, y, style, align, &buf, buf size, &fmt, ...) → ssize_t
  • amp_print_text (&ansmap, x, y, style, max width, alignment, &string) → size_t
  • amp_snprint_textf (&amp, x, y, style, max width, align, &buf, buf size, &fmt, ...) → ssize_t
  • amp_print_rich_text (&ansmap, x, y, style, max width, alignment, &string) → size_t
  • amp_snprint_rich_textf (&amp, x, y, style, max width, align, &buf, buf size, &fmt, ...) → ssize_t
  • amp_put_glyph (&ansmap, x, y, &string) → const char *
  • amp_put_style (&ansmap, x, y, style) → bool
  • amp_set_bg_color (&ansmap, x, y, color) → bool
  • amp_set_fg_color (&ansmap, x, y, color) → bool
  • amp_draw_ansmap (&dst_amp, dst_x, dst_y, &src_amp) → void
  • amp_draw_ansmap_region (&dst_amp, dst_x, dst_y, &src_amp, src_x, src_y, width, height) → void

• Image I/O

  • amp_set_palette (&ansmap, palette)
  • amp_to_ans (&ansmap, &data, data size) → ssize_t
  • amp_row_to_ans (&ansmap, y, &data, data size) → ssize_t
  • amp_clip_to_ans (&ansmap, x, y, width, &data, data size) → ssize_t
  • amp_doc_parse_size (&data, data size, &width, &height) → size_t
  • amp_decode (&ansmap, &data, data size) → size_t
  • amp_encode (&ansmap, settings, &data, data size) → ssize_t
  • amp_stdout (&string, string size) → ssize_t

Colors

amp_map_rgb

libamp/amp.h

Lines 329 to 336 in ce0207e

	static inline struct amp_rgb_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 338 to 346 in ce0207e

	static inline void amp_unmap_rgb(
	struct amp_rgb_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 348 to 353 in ce0207e

	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.
	);

Ansmap creation

amp_calc_size

libamp/amp.h

Lines 127 to 133 in ce0207e

	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 135 to 146 in ce0207e

	static inline size_t amp_init(
	struct amp_type * ansmap,
	uint32_t ansmap_width,
	uint32_t ansmap_height,
	void * canvas_data,
	size_t canvas_data_size
	// Initializes the given ansmap data structure. If the canvas data array 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, exunicode, exmultiline, ex24bit, exmemory

Ansmap properties

amp_get_palette

libamp/amp.h

Lines 391 to 394 in ce0207e

	static inline AMP_PALETTE amp_get_palette(
	const struct amp_type * ansmap
	// Returns the palette of the given ansmap image.
	);

amp_get_width

libamp/amp.h

Lines 381 to 384 in ce0207e

	static inline uint32_t amp_get_width(
	const struct amp_type * ansmap
	// Returns the width of the given ansmap image.
	);

amp_get_height

libamp/amp.h

Lines 386 to 389 in ce0207e

	static inline uint32_t amp_get_height(
	const struct amp_type * ansmap
	// Returns the height of the given ansmap image.
	);

amp_get_glyph

libamp/amp.h

Lines 248 to 256 in ce0207e

	static inline const char * amp_get_glyph(
	const struct amp_type * ansmap,
	long glyph_x,
	long glyph_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_get_style

libamp/amp.h

Lines 270 to 276 in ce0207e

	static inline AMP_STYLE amp_get_style(
	const struct amp_type * ansmap,
	long style_x,
	long style_y
	// Returns the style bits of a glyph on the ansmap from the given position.
	);

amp_get_bg_color

libamp/amp.h

Lines 289 to 296 in ce0207e

	static inline struct amp_rgb_type amp_get_bg_color(
	struct amp_type * ansmap,
	long cell_x,
	long cell_y
	// Returns a color data structure holding the background color information
	// of a glyph on the ansmap at the given position.
	);

amp_get_fg_color

libamp/amp.h

Lines 309 to 316 in ce0207e

	static inline struct amp_rgb_type amp_get_fg_color(
	struct amp_type * ansmap,
	long cell_x,
	long cell_y
	// Returns a color data structure holding the foreground color information
	// of a glyph on the ansmap at the given position.
	);

Printing operations

amp_clear

libamp/amp.h

Lines 148 to 151 in ce0207e

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

Examples: exrich

amp_print_glyph

libamp/amp.h

Lines 161 to 169 in ce0207e

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

Examples: exmemory

amp_print_line

libamp/amp.h

Lines 171 to 181 in ce0207e

	static inline void amp_print_line(
	struct amp_type * ansmap,
	long text_x,
	long text_y,
	AMP_STYLE text_style,
	AMP_ALIGN text_alignment,
	const char * text_str
	// Prints 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_snprint_linef

libamp/amp.h

Lines 445 to 466 in ce0207e

	static inline ssize_t amp_snprint_linef(
	struct amp_type * ansmap,
	long text_x,
	long text_y,
	AMP_STYLE text_style,
	AMP_ALIGN text_alignment,
	char * text_format_buffer,
	size_t text_format_buffer_size,
	const char * text_format,
	...
	// Prints the provided UTF-8 encoded formatted text on the ansmap. Newlines
	// and other non-printable ASCII characters will be replaced by question
	// marks. If the provided text format buffer could not fit the text after
	// formatting or if an error occurred during formatting, then nothing is
	// printed on the ansmap.
	//
	// Returns the number of bytes that would have been written into the text
	// format buffer (excluding the null byte used to end output to strings).
	// The return value of -1 indicates that an output error was encountered in
	// the underlying call to vsnprintf.
	) __attribute__((format (printf, 8, 9)));

amp_print_text

libamp/amp.h

Lines 183 to 197 in ce0207e

	static inline size_t amp_print_text(
	struct amp_type * ansmap,
	long text_x,
	long text_y,
	AMP_STYLE text_style,
	uint32_t text_max_width,
	AMP_ALIGN text_alignment,
	const char * text_str
	// Prints 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 printed.
	);

Examples: exmultiline, exunicode

amp_snprint_textf

libamp/amp.h

Lines 396 to 418 in ce0207e

	static inline ssize_t amp_snprint_textf(
	struct amp_type * ansmap,
	long text_x,
	long text_y,
	AMP_STYLE text_style,
	uint32_t text_max_width,
	AMP_ALIGN text_alignment,
	char * text_format_buffer,
	size_t text_format_buffer_size,
	const char * text_format,
	...
	// Prints the provided UTF-8 encoded formatted 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. If the provided
	// text format buffer could not fit the text after formatting or if an error
	// occurred during formatting, then nothing is printed on the ansmap.
	//
	// Returns the number of bytes that would have been written into the text
	// format buffer (excluding the null byte used to end output to strings).
	// The return value of -1 indicates that an output error was encountered in
	// the underlying call to vsnprintf.
	) __attribute__((format (printf, 9, 10)));

amp_print_rich_text

libamp/amp.h

Lines 364 to 379 in ce0207e

	static inline size_t amp_print_rich_text(
	struct amp_type * ansmap,
	long text_x,
	long text_y,
	AMP_STYLE text_style,
	uint32_t text_max_width,
	AMP_ALIGN text_alignment,
	const char * text_str
	// Prints the provided UTF-8 encoded rich text on the ansmap. Inline
	// embedded style markers are applied to the text as it is printed. 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 printed.
	);

Examples: exrich

amp_snprint_rich_textf

libamp/amp.h

Lines 420 to 443 in ce0207e

	static inline ssize_t amp_snprint_rich_textf(
	struct amp_type * ansmap,
	long text_x,
	long text_y,
	AMP_STYLE text_style,
	uint32_t text_max_width,
	AMP_ALIGN text_alignment,
	char * text_format_buffer,
	size_t text_format_buffer_size,
	const char * text_format,
	...
	// Prints the provided UTF-8 encoded formatted text on the ansmap. Inline
	// embedded style markers are applied to the text as it is printed. This
	// function wraps the line if its width exceeds the maximum allowed width.
	// If the maximum width is zero, then wrapping is disabled. If the provided
	// text format buffer could not fit the text after formatting or if an error
	// occurred during formatting, then nothing is printed on the ansmap.
	//
	// Returns the number of bytes that would have been written into the text
	// format buffer (excluding the null byte used to end output to strings).
	// The return value of -1 indicates that an output error was encountered in
	// the underlying call to vsnprintf.
	) __attribute__((format (printf, 9, 10)));

Examples: exrich

amp_put_glyph

libamp/amp.h

Lines 258 to 268 in ce0207e

	static inline const char * amp_put_glyph(
	struct amp_type * ansmap,
	long glyph_x,
	long glyph_y,
	const char * glyph
	// 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_put_style

libamp/amp.h

Lines 278 to 287 in ce0207e

	static inline bool amp_put_style(
	struct amp_type * ansmap,
	long style_x,
	long style_y,
	AMP_STYLE style
	// 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_set_bg_color

libamp/amp.h

Lines 298 to 307 in ce0207e

	static inline bool amp_set_bg_color(
	struct amp_type * ansmap,
	long cell_x,
	long cell_y,
	struct amp_rgb_type background_color
	// 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_set_fg_color

libamp/amp.h

Lines 318 to 327 in ce0207e

	static inline bool amp_set_fg_color(
	struct amp_type * ansmap,
	long cell_x,
	long cell_y,
	struct amp_rgb_type foreground_color
	// 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_draw_ansmap

libamp/amp.h

Lines 519 to 530 in ce0207e

	static inline void amp_draw_ansmap(
	struct amp_type * dst_ansmap,
	long x_on_dst_ansmap,
	long y_on_dst_ansmap,
	const struct amp_type * src_ansmap
	// Draws a copy of the source ansmap onto the destination ansmap at the
	// specified position. It uses a masked drawing mode where transparent cells
	// are skipped, so the background image will show through the masked parts
	// of the source image. Transparent cells are marked by their glyphs
	// containing either a space or an empty string, having no style specified.
	);

amp_draw_ansmap_region

libamp/amp.h

Lines 532 to 548 in ce0207e

	static inline void amp_draw_ansmap_region(
	struct amp_type * dst_ansmap,
	long x_on_dst_ansmap,
	long y_on_dst_ansmap,
	const struct amp_type * src_ansmap,
	long x_on_src_ansmap,
	long y_on_src_ansmap,
	long region_width,
	long region_height
	// Draws a copy of a region from the source ansmap onto the destination
	// ansmap at the specified position. It uses a masked drawing mode where
	// transparent cells are skipped, so the background image will show through
	// the masked parts of the source image. Transparent cells are marked by
	// their glyphs containing either a space or an empty string, having no
	// style specified.
	);

Examples: extiles

Image I/O

amp_set_palette

libamp/amp.h

Lines 153 to 159 in ce0207e

	static inline void amp_set_palette(
	struct amp_type * ansmap,
	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_to_ans

libamp/amp.h

Lines 199 to 212 in ce0207e

	static inline ssize_t amp_to_ans(
	const struct amp_type * ansmap,
	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, exunicode, exmultiline, ex24bit, exmemory

amp_row_to_ans

libamp/amp.h

Lines 214 to 228 in ce0207e

	static inline ssize_t amp_row_to_ans(
	const struct amp_type * ansmap,
	long row_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 230 to 246 in ce0207e

	static inline ssize_t amp_clip_to_ans(
	const struct amp_type * ansmap,
	long clip_x,
	long clip_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_doc_parse_size

libamp/amp.h

Lines 490 to 504 in ce0207e

	static inline size_t amp_doc_parse_size(
	const void * doc_data,
	size_t doc_data_size,
	uint32_t * amp_width,
	uint32_t * amp_height
	// Parses the provided data as an AMP document and attempts to determine the
	// size of a buffer required for the deserialization of the document. If the
	// size was found, then the width and height of the parsed ansmap are
	// written to the memory addresses specified by the width and height pointer
	// arguments respectively.
	//
	// Returns the size of the buffer required for ansmap decoding. The return
	// value of zero indicates a parsing error.
	);

Examples: exdecode

amp_decode

libamp/amp.h

Lines 506 to 517 in ce0207e

	static inline size_t amp_decode(
	struct amp_type * ansmap,
	const void * data,
	size_t data_size
	// Imports a human-readable plaintext document from the data array into the
	// referenced ansmap. If the ansmap could not fit the image, then the image
	// will be cropped to fit.
	//
	// Returns the original canvas size of the decoded ansmap. The return
	// value of zero indicates a parsing error.
	);

Examples: exdecode

amp_encode

libamp/amp.h

Lines 468 to 488 in ce0207e

	static inline ssize_t amp_encode(
	const struct amp_type * ansmap,
	AMP_SETTINGS flags,
	char * buffer,
	size_t buffer_size
	// Exports the specified ansmap as a human-readable plaintext document. The
	// file content is written into the provided buffer, given that the buffer
	// is large enough for complete storage. If the buffer pointer is a null
	// pointer, then the output will be written into the program's standard
	// output.
	//
	// AMP_SETTINGS flags:
	// * AMP_DEFLATE - Unrequired empty lines are trimmed.
	// * AMP_FLATTEN - Merge as many style layers as possible.
	//
	// Returns the number of bytes that was written or would have been written
	// (excluding the null byte used to end output to strings). If the buffer is
	// too small, then its first byte is set to zero. The return value of -1
	// indicates an error.
	);

Examples: exencode

amp_stdout

libamp/amp.h

Lines 355 to 362 in ce0207e

	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.
	);

Examples: exhello, exunicode, exmultiline, ex24bit, exmemory

License

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