Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 222 lines (157 sloc) 14.696 kb
511ae14 @ByteProject added markdown read me
ByteProject authored
1 # AnsiLove.framework
2
198c55f @ByteProject now THIS is what I call good documentation
ByteProject authored
3 This is a Cocoa framework for rendering ANSi art. It uses a modified version of [Frederic Cambus'](http://www.cambus.net) awesome [AnsiLove](http://ansilove.sourceforge.net) as library. Note that the AnsiLove.framework creates PNG images from ANSi source files, any generated output will be read-only.
511ae14 @ByteProject added markdown read me
ByteProject authored
4
5 # Features
6
68c8e49 @ByteProject added hint revealing this meant to be an ARC framework
ByteProject authored
7 - Automatic Reference Counting (ARC)
198c55f @ByteProject now THIS is what I call good documentation
ByteProject authored
8 - Mac App Store conform
511ae14 @ByteProject added markdown read me
ByteProject authored
9 - ANSi (.ANS) format support
10 - PCBOARD (.PCB) format support
11 - BiNARY (.BIN) format support
12 - ADF (.ADF) format support (Artworx)
13 - iDF (.IDF) format support (iCE Draw)
14 - TUNDRA (.TND) format support [details](http://tundradraw.sourceforge.net)
15 - XBiN (.XB) format support [details](http://www.acid.org/info/xbin/xbin.htm)
16 - Small output file size (4-bit PNG)
17 - SAUCE (Standard Architecture for Universal Comment Extentions)
18 - 80x25 font support
19 - 80x50 font support
20 - Amiga font support
21 - iCE colors support
22
23 # Charsets
24
25 IBM PC (Code page 437), Baltic (Code page 775), Cyrillic (Code page 855), French Canadian (Code page 863), Greek (Code pages 737 and 869), Hebrew (Code page 862), Icelandic (Code page 861), Latin-1 (Code page 850), Latin-2 (Code page 852), Nordic (Code page 865), Portuguese (Code page 860), Russian (Code page 866), Turkish (Code page 857), Armenian (unofficial), Persian / Iran system encoding (unofficial)
26
198c55f @ByteProject now THIS is what I call good documentation
ByteProject authored
27 # Documentation
28
29 Let's talk about using this framework in your own projects. First of all, you have to download the sources and compile the framework. You need at least Mac OS X Lion and Xcode 4.2 for this purpose. The project contains two build targets, the framework itself and a test app `AnsiLoveGUI`, the latter is optional. Select `AnsiLoveGUI` from the Schemes dropdown in Xcode if you desire to compile that one too. The test app is a good example of implementing the AnsiLove.framework, it does not contain much code and what you find there is well commented. So `AnsiLoveGUI` might be your first place to play with the framework after studying this documentation. Basically this is an ARC framework. As far as I can estimate it will compile just fine with Garbace Collector enabled, though the test app is a pure ARC project. As mentioned on top of this page, AnsiLove.framework uses [AnsiLove](http://ansilove.sourceforge.net) as library, a special variant I modified to create what we got here on top of it. If you know me, you know also that when releasing open source code, I'm doing this under the BSD-license or the MIT-license. Not this time. AnsiLove.framework is GPL-licensed (Version 3), that's because [AnsiLove](http://ansilove.sourceforge.net) is GPL-licensed too. While it's fine to use the framework in projects with compatible open source licenses (e.g. modified BSD, MIT, Apache), it may not be suitable for commercial products.
30
31 ## Adding the framework to your projects
32
33 Place the compiled framework in a folder inside your project, I recommend creating a `frameworks` folder, if not existing. In Xcode go to the File menu and select `Add Files to "MyProject"`, select the AnsiLove.framework you just dropped in the `frameworks` folder and then drag the framework to the other frameworks in your project hierarchy. The last steps are pretty easy:
34
35 - In the project navigator, select your project
36 - Select your target
37 - Select the `Build Phases` tab
38 - Open `Link Binaries With Libraries` expander
39 - Click the `+` button and select AnsiLove.framework
40 - Hit `Add Build Phase` at the bottom
41 - Add a `Copy Files` build phase with `frameworks` as destination
42 - Once again select AnsiLove.framework
43
44 Now AnsiLove.framework is properly linked to your target and will be added to compiled binaries.
45
46 ## Implementing the framework in your own sources
47
48 Go to the header of the class you want to use the framework with. Import the framework like this:
49
50 #import <Ansilove/AnsiLove.h>
51
52 To transform any ANSi source file into a beautiful PNG image, there is only one method you need to know:
53
54 + (void)createPNGFromAnsiSource:(NSString *)inputFile
55 outputFile:(NSString *)outputFile
56 columns:(NSString *)columns
57 font:(NSString *)font
58 bits:(NSString *)bits
59 iceColors:(NSString *)iceColors
60
61 You can call said method like this:
62
63 [ALAnsiGenerator createPNGFromAnsiSource:self.myInputFile
64 outputFile:self.myOutputFile
65 columns:self.myColumns
66 font:self.myFont
67 bits:self.myBits
68 iceColors:self.myIceColors];
69
70 That's basically it. Keep in mind that ALAnsiGenerator needs all it's flags as `NSString` instances. You can work internally with numeric types like `NSInteger` or `BOOL` but you need to convert them to strings before you pass these values to ALAnsiGenerator. For example, the iceColors flag (I'm going to explain all flags in detail below) can only be 0 or 1, so it's perfect to have that as `BOOL` type in your app. I did this in `AnsiLoveGUI` as well. To pass this value to ALAnsiGenerator you can do it something like this:
71
72 NSString *iceColors;
73 BOOL shouldUseIceColors;
74
75 if (shouldUseIceColors == NO) {
76 self.iceColors = @"0";
77 }
78 else {
79 self.iceColors = @"1";
80 }
81
82 Note that all flags except `inputFile` are optional. You can either decide to pass `nil` to flags you don't need (AnsiLove.framework will then work with it's default values) or you just pass empty strings like:
83
84 self.myFontString = @"";
85
86 The AnsiLove.framework will silently consume `nil` and empty string values but it will rely on it's built-in defaults in both cases. Clever? I think so, too. Now that you know the basics, let's head over to the details. The `createPNGFromAnsiSource:` seems like a pretty simple method but in fact it's so damn powerful if you know how to deal with the flags and that is what I'm going to teach you now.
87
88 ## (NSString *)inputFile
89
90 The only necessary flag you need to pass to ALAnsiGenerator. Well, that's logic. If there is no input file, what should be the output? I see you get it. Here is an example for a proper `inputFile` string:
91
92 /Users/Stefan/Desktop/MyAnsiArtwork.ans
93
94 Note that all supported file extensions like `.ans` or `.xb` are detected automatically. I recommend treating this string case-sensitive. As you can see, that string explicitly needs to contain the path and the file name. That's pretty cool because it means you can work either with `NSStrings` or `NSURLs` internally. Just keep in mind that any `NSURL` needs to be converted to a string before passing to ALAnsiGenerator. NSURL has a method called `absoluteString` that can be used for easy conversion.
95
96 NSURL *myURL;
97 NSString *urlString = [myURL absoluteString];
98
99 But the AnsiLove.framework can do even more at this point, it will resolve a tilde in any provided `inputFile` string instance without a problem. So let's have a look at the proper `inputFile` string again, this would be the same:
100
101 ~/Desktop/MyAnsiArtwork.ans
102
103 Simple, elegant, comfortable, just working. That's what Cocoa is all about.
104
105 ## (NSString *)outputFile
106
107 Formatting of the `outputFile` string is identical to the `inputFile` string. There is only one difference: `outputFile` is optional. If you don't set this flag, the framework will use the same path / file name you passed as `inputFile` string, but it will add .PNG as suffix. If you plan to output your PNG into a different directory and / or under a different filename, then of course you have to set this flag.
108
109 ## (NSString *)columns
110
111 `columns` are only for ANSi source files with `.bin` extension and even for those files optional. In most cases conversion will work fine if you don't set this flag, the default value is `160` then. So please pass `columns` only to .bin files and only if you exactly know what you're doing. A KITTEN MAY DIE SOMEWHERE.
112
113 ## (NSString *)font
114
115 The AnsiLove.framework generates the most accurate rendering of ANSi sources you've ever seen on a modern computer. Not aiming, it does. That's a fact. It comes with two font families both originating from the golden age of ANSi artists. These font families are `PC` and `AMIGA`, the latter restricted to 8-bit only. Let's have a look at the flags you can pass as `font` string.
116
117 `PC` fonts can be (all case-sensitive):
118
119 - `80x25` (code page 437)
120 - `80x50` (code page 437, 80x50 mode)
121 - `armenian`
122 - `baltic` (code page 775)
123 - `cyrillic` (code page 855)
124 - `french-canadian` (code page 863)
125 - `greek` (code page 737)
126 - `greek-869` (code page 869)
127 - `hebrew` (code page 862)
128 - `icelandic` (Code page 861)
129 - `latin1` (code page 850)
130 - `latin2` (code page 852)
131 - `nordic` (code page 865)
132 - `persian` (Iran System encoding standard)
133 - `portuguese` (Code page 860)
134 - `russian` (code page 866)
135 - `turkish` (code page 857)
136
137 `AMIGA` fonts can be (all case-sensitive):
138
139 - `amiga` (alias to Topaz)
140 - `b-strict` (Original B-Strict font)
141 - `b-struct` (Original B-Struct font)
142 - `microknight` (Original MicroKnight version)
143 - `microknightplus` (Modified MicroKnight version)
144 - `mosoul` (Original mO'sOul font)
145 - `pot-noodle` (Original P0T-NOoDLE font)
146 - `topaz` (Original Topaz Kickstart 2.x version)
147 - `topazplus` (Modified Topaz Kickstart 2.x+ version)
148 - `topaz500` (Original Topaz Kickstart 1.x version)
149 - `topaz500plus` (Modified Topaz Kickstart 1.x version)
150
151 If you don't set the `font` flag by either passing `nil` or an empty string to ALAnsiGenerator, the AnsiLove.framework will generate the PNG with `80x25`, which is the default `font` value.
152
153 ## (NSString *)bits
154
155 Bits can be (all case-sensitive):
156
157 - `8` (8-bit)
158 - `9` (9-bit)
159 - `ced`
160 - `transparent`
161 - `workbench`
162
163 Now what's this all about you may ask? I will tell you.
164
165 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.
166
167 Setting the bits 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.
168
169 Setting the bits to `workbench` will cause the input file to be rendered using Amiga Workbench colors (only available for `.ans` files).
170
171 Settings the bits to `transparent` will produce output files with transparent background (only available for `.ans` files).
172
173 ## (NSString *)iceColors
174
175 As I have already written above, `iceColors` can only be `0` or `1`. All other string values for `iceColors` will be silently consumed and thankfully ignored. Setting `iceColors` to `1` will enable them. On the opposite `0` means that that `iceColors` are disabled, which is the default value. So if you don't want to enable them, there's no need to pass a value to ALAnsiGenerator. To understand how to handle this flag you need to know more about iCE colors. So what IS iCE colors? Are we talking about something that renders my ANSi source in an alternative color scheme? Well, yes and no, but more no than yes. Huh? Okay, I'll explain. When an ANSi source was created using iCE color codes, 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. But now the important part: when the ANSi source does not make specific use of iCE colors, you should NOT set this flag. The file could look pretty weird in normal mode. So in most cases it's fine to leave this flag alone.
176
177 ## Supported options for each file type
178
179 Now that you know about the different flags, you may also want to have a simple overview of which file type supports which flag. No problem, here you are:
180
2b688b2 @ByteProject cosmetically change, table not displayed properly
ByteProject authored
181 ___________________________________________
182 | | | | | |
183 | | columns | font | bits | icecolors |
184 |_____|_________|_______|_______|___________|
185 | | | | | |
186 | ANS | | X | X | X |
187 |_____|_________|_______|_______|___________|
188 | | | | | |
189 | PCB | | X | X | X |
190 |_____|_________|_______|_______|___________|
191 | | | | | |
192 | BIN | X | X | X | X |
193 |_____|_________|_______|_______|___________|
194 | | | | | |
195 | ADF | | | | |
196 |_____|_________|_______|_______|___________|
197 | | | | | |
198 | IDF | | | | |
199 |_____|_________|_______|_______|___________|
200 | | | | | |
201 | TND | | X | X | |
202 |_____|_________|_______|_______|___________|
203 | | | | | |
204 | XB | | | | |
205 |_____|_________|_______|_______|___________|
198c55f @ByteProject now THIS is what I call good documentation
ByteProject authored
206
207 # Last Words
208
209 Even though the AnsiLove.framework works well, I suggest you visit this repo now and then. It's very likely I'm adding new stuff to it. The AnsiLove.framwork was created with the vision of implementing it into one of my own apps, most of you know [Ascension](http://byteproject.net/ascension) already. On the other hand, [AnsiLove](http://ansilove.sourceforge.net) itself is work in progress, too. So if [Frederic](http://www.cambus.net) adds new features to [AnsiLove](http://ansilove.sourceforge.net) I'm going to implement those changes to the underlying library of the AnsiLove.framework, is that fine with you? I know it is.
210
211 # Credits
212
213 I bow to [Frederic Cambus](http://www.cambus.net). Without his passion and his work on [AnsiLove](http://ansilove.sourceforge.net) this framework would never have been possible. He spent countless hours and years with coding and testing. I, for one, adapted his work and created a Cocoa layer on top of it, which took me effectively three days in it's inital form. So first of all: don't thank me, please thank [Frederic](http://www.cambus.net) and if you find the AnsiLove.framework useful please consider making a donation to [AnsiLove](http://ansilove.sourceforge.net).
214
215 Thanks fly out to the all you people around the world that are downloading [Ascension](http://byteproject.net/ascension) more than hundred times a day since I released it. You guys are the reason I did this.
216
217 Also, cheers to all the great ASCII / ANSi artists around the world. You are the artscene. You keep alive what was not meant to die years ago. YOU ROCK!
218
219 # License
511ae14 @ByteProject added markdown read me
ByteProject authored
220
198c55f @ByteProject now THIS is what I call good documentation
ByteProject authored
221 The framework is released under the [GNU General Public License Version 3](http://www.gnu.org/licenses/gpl-3.0.html).
Something went wrong with that request. Please try again.