File: README.md

package info (click to toggle)
ansilove 4.1.5-1
  • links: PTS, VCS
  • area: main
  • in suites: experimental
  • size: 320 kB
  • sloc: ansic: 773; makefile: 7
file content (299 lines) | stat: -rw-r--r-- 9,593 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
```
         _______         ___________          ___
       __\___   \_  ____/     /\   /______ ___\_/__            /\
      /    \|     \/  _ \    /--\_____    \\   /  /\          /  \
    _/      |     /    \     \      |/     /      \ \ _ _____/    \_______
    \       |_____\____/     /      /      \____  /\/                    /
     \______|      \  \_____/\______       /\   \/  \   /\NSILOVE / C   /____ _
      \     |_______\__\___ \ \    \      /  \___\__/____
       \____|        /____/\_\/\__ /     / __/___ \     /\    ____
                     \    \ \     /     /_/ __   \/    /__\__/  _/ _____ ___
                 /\   \____\/    /     //   \    /    /    /    _>/    //__/\
                /  \           _/      \   //   /    /    /     \/    / \__\/
_ _________    /    \_______ _ \___    /_______/    /   _/ \____      \  /
           \  /                 \ \___/\       \_______/\\  \  \______/\/
            \/                   \_\  \ \_______\      \ \\/ \__\     \ \
                                    \__\/        \______\/ h7/dS!\_____\/
```

# AnsiLove/C

[![Build Status][1]][2]

AnsiLove is an ANSI and ASCII art to PNG converter, allowing to convert
ANSI and artscene-related file formats into PNG images, supporting ANSI
(.ANS), PCBoard (.PCB), Binary (.BIN), Artworx (.ADF), iCE Draw (.IDF),
Tundra (.TND) and XBin (.XB) formats.

It creates size optimized 4-bit PNG files and supports SAUCE (Standard
Architecture for Universal Comment Extentions), 80x25 and 80x50 PC fonts
(including all the 14 MS-DOS charsets), Amiga fonts, and iCE colors.

This is a complete rewrite of [AnsiLove/PHP][3] in the C programming
language.

# Specs

AnsiLove/C is strictly using the `C99 standard` to achieve high
portability to all major operating systems. Supported compilers are
`GCC` and `Clang`, others may work but aren't tested. We use Linux
and OpenBSD for AnsiLove/C development.

# Why C?

There were many reasons, most notably PHP interpreter independence
and performance. A solid C foundation is just perfect for creating
libraries and it can easily be embedded into applications. We already
mentioned portability. What else? We wanted evolution. AnsiLove/C
should not be understood as a port. It takes many different approaches
(like processing binary font dumps or generating @2x Retina images),
it is overall improved and introduces new features. While results
tend to be the same, the codebase does not have much in common with
it's ancestor.

# Dependencies

AnsiLove/C uses the `CMake` build system and requires the
[libansilove][4] library and header files.

# Installing dependencies

- OpenBSD: `pkg_add -r cmake`
- NetBSD: `pkgin install cmake`
- FreeBSD: `pkg install cmake`
- macOS: `brew install cmake`
- Alpine Linux: `apk add cmake gcc make musl-dev`
- Debian / Ubuntu / Mint: `apt-get install build-essential cmake`
- Fedora: `dnf install cmake gcc make`
- Solus: `eopkg install -c system.devel`

Binary packages for `libansilove` are available on OpenBSD, NetBSD,
FreeBSD, Debian, Ubuntu, and Solus.

On other systems, `libansilove` has to be installed manually.

# Compiling

	mkdir build
	cd build
	cmake ..
	make

# Packages

Packages are available for the following operating systems:

- [OpenBSD][5]
- [NetBSD][6]
- [FreeBSD][7]
- [Debian][8]
- [Ubuntu][9]
- [openSUSE][10]
- [Solus][11]

# Features

The following formats are supported:

- .ANS - ANSi (ANSI escape sequences: ANSI X3.64 standard)
- .PCB - PCBoard Bulletin Board System (BBS) own file format
- .BIN - Binary format (raw memory copy of text mode video memory)
- .ADF - Artworx format, supporting custom character sets and palettes
- .IDF - iCE Draw format, supporting custom character sets and palettes
- .TND - [TundraDraw][12] format, supporting 24-bit color mode
- .XB - The eXtended Binary [XBin][13] format, supporting custom character sets
  and palettes

Files with custom suffix default to the ANSi renderer (e.g. ICE or CIA).

AnsiLove/C is capabable of processing:

- [SAUCE][14] records
- DOS and Amiga fonts (embedded binary dump)
- iCE colors

Even more:

- Small output file size (4-bit PNG).
- Optionally generates proper Retina @2x (and up to @8x) PNG.
- You can use custom options for adjusting output results.
- Built-in support for rendering Amiga ASCII.

# Documentation

## Synopsis

```
     ansilove [-dhiqrsv] [-b bits] [-c columns] [-f font] [-m mode] [-o file]
              [-R factor] [-t type] file
```

## Options

```
     -b bits     Set to 9 to render 9th column of block characters (default:
                 8).

     -c columns  Adjust number of columns for ANSI, BIN, and TND files.

     -d          Enable DOS aspect ratio.

     -f font     Select font for supported formats.

     -h          Show help.

     -i          Enable iCE colors.

     -m mode     Set rendering mode for ANS files. Valid options are:

                 ced     Black on gray, with 78 columns.

                 transparent
                         Render with transparent background.

                 workbench
                         Use Amiga Workbench palette.

     -o file     Specify output filename/path.

     -q          Suppress output messages (quiet).

     -r          Create Retina @2x output file.

     -R factor   Create Retina output file with custom scale factor.

     -t type     Specify input file type.

     -s          Show SAUCE record without generating output.

     -S          If available, use SAUCE info for render options (ex: width).

     -v          Show version information.
```

There are certain cases where you need to set options for proper
rendering. However, this is occasionally. Results turn out well
with the built-in defaults.

## Fonts

We dumped many fonts as binary data right into AnsiLove/C, so the
most popular typefaces for rendering ANSi / ASCII art are available
at your fingertips.

PC fonts can be (all case-sensitive):

- `80x25` Default (Code page 437)
- `80x50` 80x50 mode (Code page 437)
- `cp737` Greek (Code page 737)
- `cp775` Baltic (Code page 775)
- `cp850` Latin-1 (Code page 850)
- `cp852` Latin-2 (Code page 852)
- `cp855` Cyrillic (Code page 855)
- `cp857` Turkish (Code page 857)
- `cp860` Portuguese (Code page 860)
- `cp861` Icelandic (Code page 861)
- `cp862` Hebrew (Code page 862)
- `cp863` French Canadian (Code page 863)
- `cp865` Nordic (Code page 865)
- `cp866` Russian (Code page 866)
- `cp869` Greek (Code page 869)
- `terminus` Terminus (Modern font, code page 437)

AMIGA fonts can be (all case-sensitive):

- `amiga` (alias to Topaz)
- `microknight` (Original MicroKnight version)
- `microknight+` (Modified MicroKnight version)
- `mosoul` (Original mO'sOul font)
- `pot-noodle` (Original P0T-NOoDLE font)
- `topaz` (Original Topaz Kickstart 2.x version)
- `topaz+` (Modified Topaz Kickstart 2.x+ version)
- `topaz500` (Original Topaz Kickstart 1.x version)
- `topaz500+` (Modified Topaz Kickstart 1.x version)

## Bits

`bits` can be:

- `8` (8-bit)
- `9` (9-bit)

Setting the bits to `9` will render the 9th column of block characters,
so the output will look like it is displayed in real textmode.

## Rendering Mode

`mode` can be (all case-sensitive):

- `ced`
- `transparent`
- `workbench`

Setting the mode to `ced` will cause the input file to be rendered
in black on gray, and limit the output to 78 columns (only available
for `ANS` files). Used together with an Amiga font, the output will
look like it is displayed on Amiga.

Setting the mode to `workbench` will cause the input file to be
rendered using Amiga Workbench colors (only available for `ANS`
files).

Settings the mode to `transparent` will produce output files with
transparent background (only available for `ANS` files).

## iCE Colors

iCE colors are disabled by default, and can be enabled by specifying
the `-i` option.

When an ANSi source was created using iCE colors, it was done with
a special mode where the blinking was disabled, and you had 16
background colors available. Basically, you had the same choice for
background colors as for foreground colors, that's iCE colors.

## Columns

`columns` is only relevant for .ANS, .BIN, .PCB,  and .TND files, and
is optional. In most cases conversion will work fine if you don't set
this flag, the default value is `160` for .BIN files and `80`
otherwise.

## SAUCE records

It's fine to use AnsiLove/C as SAUCE reader without generating any
output, just set option `-s` for this purpose.

# License

AnsiLove/C is released under the BSD 2-Clause License. See the
`LICENSE` file for details.

# Authors

AnsiLove/C is developed by Stefan Vogt ([@ByteProject][15]), Brian Cassidy
([@bricas][16]) and Frederic Cambus ([@fcambus][17]).

# Resources

Project homepage: https://www.ansilove.org

GitHub: https://github.com/ansilove/ansilove

[1]: https://api.travis-ci.org/ansilove/ansilove.png?branch=master
[2]: https://travis-ci.org/ansilove/ansilove
[3]: https://www.ansilove.org
[4]: https://github.com/ansilove/libansilove
[5]: https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/graphics/ansilove
[6]: https://pkgsrc.se/graphics/ansilove
[7]: https://www.freshports.org/graphics/ansilove/
[8]: https://packages.debian.org/search?keywords=ansilove
[9]: https://packages.ubuntu.com/search?keywords=ansilove
[10]: https://software.opensuse.org/package/ansilove
[11]: https://dev.getsol.us/source/ansilove/
[12]: https://sourceforge.net/projects/tundradraw/
[13]: https://github.com/radman1/xbin
[14]: https://github.com/radman1/sauce
[15]: https://github.com/ByteProject
[16]: https://github.com/bricas
[17]: https://github.com/fcambus