ansilove

ANSI and ASCII art to PNG converter in C
Log | Files | Refs | README | LICENSE

README.md (9934B)


      1 ```
      2          _______         ___________          ___
      3        __\___   \_  ____/     /\   /______ ___\_/__            /\
      4       /    \|     \/  _ \    /--\_____    \\   /  /\          /  \
      5     _/      |     /    \     \      |/     /      \ \ _ _____/    \_______
      6     \       |_____\____/     /      /      \____  /\/                    /
      7      \______|      \  \_____/\______       /\   \/  \   /\NSILOVE / C   /____ _
      8       \     |_______\__\___ \ \    \      /  \___\__/____
      9        \____|        /____/\_\/\__ /     / __/___ \     /\    ____
     10                      \    \ \     /     /_/ __   \/    /__\__/  _/ _____ ___
     11                  /\   \____\/    /     //   \    /    /    /    _>/    //__/\
     12                 /  \           _/      \   //   /    /    /     \/    / \__\/
     13 _ _________    /    \_______ _ \___    /_______/    /   _/ \____      \  /
     14            \  /                 \ \___/\       \_______/\\  \  \______/\/
     15             \/                   \_\  \ \_______\      \ \\/ \__\     \ \
     16                                     \__\/        \______\/ h7/dS!\_____\/
     17 ```
     18 
     19 # AnsiLove/C
     20 
     21 AnsiLove is an ANSI and ASCII art to PNG converter, allowing to convert
     22 ANSI and artscene-related file formats into PNG images, supporting ANSI
     23 (.ANS), PCBoard (.PCB), Binary (.BIN), Artworx (.ADF), iCE Draw (.IDF),
     24 Tundra (.TND) and XBin (.XB) formats.
     25 
     26 It creates size optimized 4-bit PNG files and supports SAUCE (Standard
     27 Architecture for Universal Comment Extensions), 80x25 and 80x50 PC fonts
     28 (including all the 14 MS-DOS charsets), Amiga fonts, and iCE colors.
     29 
     30 This is a complete rewrite of [AnsiLove/PHP][1] in the C programming
     31 language.
     32 
     33 Experimental seccomp support is available for selected architectures and
     34 can be enabled by setting the `ENABLE_SECCOMP` variable to `1` when
     35 invoking CMake.
     36 
     37 # Specs
     38 
     39 AnsiLove/C is strictly using the `C99 standard` to achieve high
     40 portability to all major operating systems. Supported compilers are
     41 `GCC` and `Clang`, others may work but aren't tested. We use Linux
     42 and OpenBSD for AnsiLove/C development.
     43 
     44 # Why C?
     45 
     46 There were many reasons, most notably PHP interpreter independence
     47 and performance. A solid C foundation is just perfect for creating
     48 libraries and it can easily be embedded into applications. We already
     49 mentioned portability. What else? We wanted evolution. AnsiLove/C
     50 should not be understood as a port. It takes many different approaches
     51 (like processing binary font dumps or generating @2x Retina images),
     52 it is overall improved and introduces new features. While results
     53 tend to be the same, the codebase does not have much in common with
     54 it's ancestor.
     55 
     56 # Dependencies
     57 
     58 AnsiLove/C uses the `CMake` build system and requires the
     59 [libansilove][2] library and header files.
     60 
     61 # Installing dependencies
     62 
     63 - OpenBSD: `pkg_add -r cmake`
     64 - NetBSD: `pkgin install cmake`
     65 - FreeBSD: `pkg install cmake`
     66 - macOS: `brew install cmake`
     67 - Alpine Linux: `apk add cmake gcc make musl-dev`
     68 - Debian / Ubuntu / Mint: `apt-get install build-essential cmake`
     69 - Fedora: `dnf install cmake gcc make`
     70 - Solus: `eopkg install -c system.devel`
     71 
     72 Binary packages for `libansilove` are available on OpenBSD, NetBSD,
     73 FreeBSD, Debian, Ubuntu, and Solus.
     74 
     75 On other systems, `libansilove` has to be installed manually.
     76 
     77 # Compiling
     78 
     79 	mkdir build
     80 	cd build
     81 	cmake ..
     82 	make
     83 
     84 # Packages
     85 
     86 Packages are available for the following operating systems:
     87 
     88 - [OpenBSD][3]
     89 - [NetBSD][4]
     90 - [FreeBSD][5]
     91 - [Debian][6]
     92 - [Ubuntu][7]
     93 - [openSUSE][8]
     94 - [Solus][9]
     95 - [Gentoo][10]
     96 
     97 # Features
     98 
     99 The following formats are supported:
    100 
    101 - .ANS - ANSi (ANSI escape sequences: ANSI X3.64 standard)
    102 - .PCB - PCBoard Bulletin Board System (BBS) own file format
    103 - .BIN - Binary format (raw memory copy of text mode video memory)
    104 - .ADF - Artworx format, supporting custom character sets and palettes
    105 - .IDF - iCE Draw format, supporting custom character sets and palettes
    106 - .TND - [TundraDraw][11] format, supporting 24-bit color mode
    107 - .XB - The eXtended Binary [XBin][12] format, supporting custom character sets
    108   and palettes
    109 
    110 Files with custom suffix default to the ANSi renderer (e.g. ICE or CIA).
    111 
    112 AnsiLove/C is capable of processing:
    113 
    114 - [SAUCE][13] records
    115 - DOS and Amiga fonts (embedded binary dump)
    116 - iCE colors
    117 
    118 Even more:
    119 
    120 - Small output file size (4-bit PNG).
    121 - Optionally generates proper Retina @2x (and up to @8x) PNG.
    122 - You can use custom options for adjusting output results.
    123 - Built-in support for rendering Amiga ASCII.
    124 
    125 # Documentation
    126 
    127 ## Synopsis
    128 
    129 ```
    130      ansilove [-dhiqrsv] [-b bits] [-c columns] [-f font] [-m mode] [-o file]
    131               [-R factor] [-t type] file
    132 ```
    133 
    134 ## Options
    135 
    136 ```
    137      -b bits     Set to 9 to render 9th column of block characters (default:
    138                  8).
    139 
    140      -c columns  Adjust number of columns for ANSI, BIN, and TND files.
    141 
    142      -d          Enable DOS aspect ratio.
    143 
    144      -f font     Select font for supported formats.
    145 
    146      -h          Show help.
    147 
    148      -i          Enable iCE colors.
    149 
    150      -m mode     Set rendering mode for ANS files. Valid options are:
    151 
    152                  ced     Black on gray, with 78 columns.
    153 
    154                  transparent
    155                          Render with transparent background.
    156 
    157                  workbench
    158                          Use Amiga Workbench palette.
    159 
    160      -o file     Specify output filename/path.
    161 
    162      -q          Suppress output messages (quiet).
    163 
    164      -r          Create Retina @2x output file.
    165 
    166      -R factor   Create Retina output file with custom scale factor.
    167 
    168      -t type     Specify input file type.
    169 
    170      -s          Show SAUCE record without generating output.
    171 
    172      -S          If available, use SAUCE info for render options (ex: width).
    173 
    174      -v          Show version information.
    175 ```
    176 
    177 There are certain cases where you need to set options for proper
    178 rendering. However, this is occasionally. Results turn out well
    179 with the built-in defaults.
    180 
    181 ## Fonts
    182 
    183 We dumped many fonts as binary data right into AnsiLove/C, so the
    184 most popular typefaces for rendering ANSi / ASCII art are available
    185 at your fingertips.
    186 
    187 PC fonts can be (all case-sensitive):
    188 
    189 - `80x25` Default (Code page 437)
    190 - `80x50` 80x50 mode (Code page 437)
    191 - `cp737` Greek (Code page 737)
    192 - `cp775` Baltic (Code page 775)
    193 - `cp850` Latin-1 (Code page 850)
    194 - `cp852` Latin-2 (Code page 852)
    195 - `cp855` Cyrillic (Code page 855)
    196 - `cp857` Turkish (Code page 857)
    197 - `cp860` Portuguese (Code page 860)
    198 - `cp861` Icelandic (Code page 861)
    199 - `cp862` Hebrew (Code page 862)
    200 - `cp863` French Canadian (Code page 863)
    201 - `cp865` Nordic (Code page 865)
    202 - `cp866` Russian (Code page 866)
    203 - `cp869` Greek (Code page 869)
    204 - `terminus` Terminus (Modern font, code page 437)
    205 
    206 AMIGA fonts can be (all case-sensitive):
    207 
    208 - `amiga` (alias to Topaz)
    209 - `microknight` (Original MicroKnight version)
    210 - `microknight+` (Modified MicroKnight version)
    211 - `mosoul` (Original mO'sOul font)
    212 - `pot-noodle` (Original P0T-NOoDLE font)
    213 - `topaz` (Original Topaz Kickstart 2.x version)
    214 - `topaz+` (Modified Topaz Kickstart 2.x+ version)
    215 - `topaz500` (Original Topaz Kickstart 1.x version)
    216 - `topaz500+` (Modified Topaz Kickstart 1.x version)
    217 
    218 ## Bits
    219 
    220 `bits` can be:
    221 
    222 - `8` (8-bit)
    223 - `9` (9-bit)
    224 
    225 Setting the bits to `9` will render the 9th column of block characters,
    226 so the output will look like it is displayed in real textmode.
    227 
    228 See the "Memory Map" section of the [Monochrome Display Adapter notes][14]
    229 for more information.
    230 
    231 ## Rendering Mode
    232 
    233 `mode` can be (all case-sensitive):
    234 
    235 - `ced`
    236 - `transparent`
    237 - `workbench`
    238 
    239 Setting the mode to `ced` will cause the input file to be rendered
    240 in black on gray, and limit the output to 78 columns (only available
    241 for `ANS` files). Used together with an Amiga font, the output will
    242 look like it is displayed on Amiga.
    243 
    244 Setting the mode to `workbench` will cause the input file to be
    245 rendered using Amiga Workbench colors (only available for `ANS`
    246 files).
    247 
    248 Settings the mode to `transparent` will produce output files with
    249 transparent background (only available for `ANS` files).
    250 
    251 ## iCE Colors
    252 
    253 iCE colors are disabled by default, and can be enabled by specifying
    254 the `-i` option.
    255 
    256 When an ANSi source was created using iCE colors, it was done with
    257 a special mode where the blinking was disabled, and you had 16
    258 background colors available. Basically, you had the same choice for
    259 background colors as for foreground colors, that's iCE colors.
    260 
    261 ## Columns
    262 
    263 `columns` is only relevant for .ANS, .BIN, .PCB,  and .TND files, and
    264 is optional. In most cases conversion will work fine if you don't set
    265 this flag, the default value is `160` for .BIN files and `80`
    266 otherwise.
    267 
    268 ## SAUCE records
    269 
    270 It's fine to use AnsiLove/C as SAUCE reader without generating any
    271 output, just set option `-s` for this purpose.
    272 
    273 # Projects using Ansilove
    274 
    275 - [16colo.rs][15] - ANSI/ASCII art archive
    276 
    277 # License
    278 
    279 AnsiLove/C is released under the BSD 2-Clause license. See the
    280 `LICENSE` file for details.
    281 
    282 # Authors
    283 
    284 AnsiLove/C is developed by Stefan Vogt ([@ByteProject][16]), Brian Cassidy
    285 ([@bricas][17]) and Frederic Cambus ([@fcambus][18]).
    286 
    287 # Resources
    288 
    289 Project homepage: https://www.ansilove.org
    290 
    291 GitHub: https://github.com/ansilove/ansilove
    292 
    293 [1]: https://www.ansilove.org
    294 [2]: https://github.com/ansilove/libansilove
    295 [3]: https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/graphics/ansilove
    296 [4]: https://pkgsrc.se/graphics/ansilove
    297 [5]: https://www.freshports.org/graphics/ansilove/
    298 [6]: https://packages.debian.org/search?keywords=ansilove
    299 [7]: https://packages.ubuntu.com/search?keywords=ansilove
    300 [8]: https://software.opensuse.org/package/ansilove
    301 [9]: https://dev.getsol.us/source/ansilove/
    302 [10]: https://packages.gentoo.org/packages/media-gfx/ansilove
    303 [11]: https://sourceforge.net/projects/tundradraw/
    304 [12]: https://github.com/radman1/xbin
    305 [13]: https://github.com/radman1/sauce
    306 [14]: https://www.seasip.info/VintagePC/mda.html#memmap
    307 [15]: https://16colo.rs
    308 [16]: https://github.com/ByteProject
    309 [17]: https://github.com/bricas
    310 [18]: https://github.com/fcambus