AnsMap Library

AnsMap is a data structure that stores high level instructions for printing ANSI art 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.

API

• ansmap_create (width, height)

  Creates a memory ansmap sized width by height. The ansmap will have clipping turned on, and the clipping rectangle set to the full size of the ansmap. The minimum height of the ansmap must be 1 and width can't be negative.

  Returns the created ansmap.

  Examples using this: ex-drawtext, ex-sprite.

• ansmap_create_from_text (text, channel = "symbol")

  Creates a memory ansmap with the width and height big enough to exactly contain the provided "text" string parameter. The channel parameter can be either "symbol", "background", "foreground" or "decoration".

  Returns the created ansmap.

  Examples using this: ex-background, ex-hello, ex-palette, ex-sprite.

• ansmap_create_from_texts (background, symbols = "", foreground = "", decoration = "")

  Creates a memory ansmap with the width and height big enough to exactly contain the provided texts in their respective channels.

  Returns the created ansmap.

  Examples using this: ex-palette, ex-sprite.

• ansmap_to_string (ansmap)

  Returns all of the symbols contained in the given ansmap as a sequence of ANSI escape codes and UTF-8 encoded text segments.

  Examples using this: ex-background, ex-drawtext, ex-hello, ex-palette, ex-sprite.

• ansmap_get_height (ansmap)

  Returns the height of the specified ansmap.

  Examples using this: ex-sprite.

• ansmap_get_width (ansmap)

  Returns the width of the specified ansmap.

  Examples using this: ex-sprite.

• ansmap_blit (src, dst, src_x, src_y, dst_x, dst_y, width, height)

  Copies a rectangular area of the source ansmap to the destination ansmap. The src_x and src_y parameters are the top left corner of the area to copy from the source ansmap, and dst_x and dst_y are the corresponding position in the destination ansmap. This routine respects the destination clipping rectangle, and it will also clip if you try to blit from areas outside the source bitmap.

• ansmap_draw_sprite (dst, src, x, y)

  Draws a copy of the sprite ansmap onto the destination ansmap at the specified position. This is almost the same as ansmap_blit(sprite, amp, 0, 0, x, y, sprite_w, sprite_h), but it uses a masked drawing mode where transparent values are skipped, so the background image will show through the masked parts of the sprite. Transparent values are marked by a space symbol.

  Examples using this: ex-sprite.

• ansmap_channel_set_value (ansmap, channel, value, x, y)

  Writes a symbol to the specified position in the ansmap. The channel can be either "symbol", "background", "foreground" or "decoration".

• ansmap_draw_text (ansmap, text, x, y, ...styles)

  Writes the string "text" onto the ansmap at position x, y, using the specified styles (if any). The styles argument list may contain any combination of the following styles: "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "black-bg", "red-bg", "green-bg", "yellow-bg", "blue-bg", "magenta-bg", "cyan-bg", "white-bg", "bold", "hidden", "faint", "italic", "underline", "blinking", "strikethrough".

  Examples using this: ex-drawtext.

• ansmap_channel_swap (ansmap, first, second)

  Swaps the "first" and "second" channel contents of the given ansmap. The values of the "first" and "second" string parameters could be "symbol", "background", "foreground" or "decoration".

• ansmap_channel_clear (ansmap, channel)

  Clears the contents of the specified channel in the given ansmap. The channel can be either "symbol", "background", "foreground" or "decoration".

Examples

ex-hello

ansmap/examples/ex-hello.php

Lines 5 to 7 in a22750a

	$amp = ansmap_create_from_text("Hello World!");
	echo ansmap_to_string($amp);

ex-background

ansmap/examples/ex-background.php

Lines 5 to 17 in 84a2086

	$amp = ansmap_create_from_text(
	" Ww wW CC\n".
	" yyyyyyyy CC\n".
	" yyrRGGrR yy\n".
	" DDGGGGGG yy\n".
	"yyDDyyDDyyDDyyGG\n".
	"GGGGDDyyDDyy yy\n".
	" rrrrrrrrrr yy\n".
	" DD DD yy\n",
	"background"
	);
	echo ansmap_to_string($amp);

ex-sprite

ansmap/examples/ex-sprite.php

Lines 27 to 40 in f71bcb6

	$amp_screen = ansmap_create(80, 20);
	for ($y = 0; $y < ansmap_get_height($amp_screen); $y += 3) {
	$x = rand(0, ansmap_get_width($amp_screen) - 1);
	if (rand() % 2 === 0) {
	ansmap_draw_sprite($amp_screen, $amp_orc, $x, $y);
	}
	else {
	ansmap_draw_sprite($amp_screen, $amp_human, $x, $y);
	}
	}
	echo ansmap_to_string($amp_screen);

ex-drawtext

ansmap/examples/ex-drawtext.php

Lines 7 to 22 in 332b010

	ansmap_draw_text(
	$amp,
	"╔══════════════════╗\n".
	"║ ║\n".
	"║ ║\n".
	"║ ║\n".
	"║ ║\n".
	"╚══════════════════╝",
	0, 0, "blue-bg", "bold", "white"
	);
	ansmap_draw_text($amp, "B", 8, 2, "bold", "blue", "underline");
	ansmap_draw_text($amp, "S", 9, 2, "bold", "yellow", "strikethrough");
	ansmap_draw_text($amp, "O", 10, 2, "bold", "cyan", "blinking");
	ansmap_draw_text($amp, "D", 11, 2, "bold", "magenta", "italic");
	ansmap_draw_text($amp, "╌╌╌╌", 8, 3);

ex-palette

ex-palette.php

Demos

amp2ans

The amp2ans demo shows off the ansmap (AMP) file format and how such files could be converted into ANSI escape sequences for the terminal to display. In the below screenshot the file contents of mud.amp is shown. Then, that file is given as an input to the amp2ans.php script which will write the respective ANSI escape sequences into its standard output.

In the following screenshot the punisher.amp file from the demo directory has been given as an input to the amp2ans.php script.

License

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