ansilove.js

A script to display ANSi and artscene related file formats on web pages
Log | Files | Refs | README | LICENSE

README.md (7481B)


      1 ## Description
      2 
      3 AnsiLove.js is a partial rewrite of [ansilove][1] and [AnsiLove-C][2] in the Javascript programming language. Unlike the original projects, AnsiLove.js enables artscene related file formats to be displayed directly on a webpage on the client-side, and supports ANSi (.ANS), PCBOARD (.PCB), BiNARY (.BIN), ADF (.ADF), iDF (.IDF), TUNDRA (.TND) and XBiN (.XB) formats.
      4 
      5 AnsiLove.js supports the majority of options found in the original set of tools.
      6 
      7 AnsiLove.js has been tested on Safari, Firefox, and Chrome. Results may vary widely on Internet Explorer browsers.
      8 
      9 ## Features
     10 
     11 - ANSi (.ANS) format support
     12 - PCBOARD (.PCB) format support
     13 - BiNARY (.BIN) format support
     14 - ADF (.ADF) format support (Artworx)
     15 - iDF (.IDF) format support (iCE Draw)
     16 - TUNDRA (.TND) format support
     17 - XBiN (.XB) format support
     18 - SAUCE (Standard Architecture for Universal Comment Extentions)
     19 - 80x25 font support
     20 - 80x50 font support
     21 - Amiga font support
     22 - iCE colors support
     23 
     24 ## Supported charsets
     25 
     26 - IBM PC (Code page 437)
     27 - Baltic (Code page 775)
     28 - Cyrillic (Code page 855)
     29 - French Canadian (Code page 863)
     30 - Greek (Code pages 737 and 869)
     31 - Hebrew (Code page 862)
     32 - Icelandic (Code page 861)
     33 - Latin-1 (Code page 850)
     34 - Latin-2 (Code page 852)
     35 - Nordic (Code page 865)
     36 - Portuguese (Code page 860)
     37 - Russian (Code page 866)
     38 - Turkish (Code page 857)
     39 - Armenian
     40 - Persian (Iran System encoding standard)
     41 
     42 ## Usage
     43 
     44     AnsiLove.render("example.bin", function (canvas, sauce) {
     45         document.body.appendChild(canvas);
     46         console.log(sauce);
     47     }, {"font": "80x25", "bits": "8", "icecolors": 0, "columns": 80, "thumbnail": 0});
     48 
     49 For extremely large files, which may silently fail on some browsers when producing a single canvas element, the `splitRender` function will produce an array of canvas elements, which can then be stacked vertically in the browser to simulate a single, contiguous display. The value of `27` in the following example is the maximum amount of text-rows in used in each element.
     50 
     51 When aligning these elements on a page there may be a small gap between each image. To correct this, simply apply the CSS style `vertical-align: bottom`, or apply it progmatically with a single line of Javascript.
     52 
     53     AnsiLove.splitRender("long_ansi.ans", function (canvases, sauce) {
     54         canvases.forEach(function (canvas) {
     55             canvas.style.verticalAlign = "bottom"; // For perfect, gap-less viewing.
     56             document.body.appendChild(canvas);
     57         });
     58         console.log(sauce);
     59     }, 27, {"bits": "8"});
     60    
     61 And for ANSImations, the animate function returns a controller object which when issued with the play() call, renders an ANSI at a pre-determined baud rate, and can be passed an additional function which is called upon completion.
     62 
     63     var controller = AnsiLove.animate("ansimation.ans", function (canvas, sauce) {
     64         document.getElementById("example").appendChild(canvas);
     65         console.log(sauce);
     66         controller.play(14400, function () {
     67             console.log("Finished!");
     68         });
     69     }, {"bits": "9"});
     70 
     71 If a function is passed after the options object of any method, then it will be called in the event that the file cannot be fetched, or if an error occured whilst attempting to interpret the file.
     72 
     73     AnsiLove.render("example.ans", function (canvas, sauce) {
     74         ...
     75     }, {}, function (message) {
     76         alert("Error: " + message);
     77     });
     78 
     79 ### PC font options: 
     80 
     81  - 80x25 (Default, code page 437)
     82  - 80x25small (small, but legible code page 437)
     83  - 80x50 (Code page 437, 80x50 mode)
     84  - armenian
     85  - baltic (Code page 775)
     86  - cyrillic (Code page 855)
     87  - french-canadian (Code page 863)
     88  - greek (Code page 737)
     89  - greek-869 (Code page 869)
     90  - hebrew (Code page 862)
     91  - icelandic (Code page 861)
     92  - latin1 (Code page 850)
     93  - latin2 (Code page 852)
     94  - nordic (Code page 865)
     95  - persian (Iran System encoding standard)
     96  - portuguese (Code page 860)
     97  - russian (Code page 866)
     98  - terminus (Terminus font)
     99  - turkish (Code page 857)
    100 
    101 ### Amiga font options:
    102  
    103  - amiga (alias to Topaz)
    104  - b-strict (Original B-Strict font)
    105  - b-struct (Original B-Struct font)
    106  - microknight (Original MicroKnight version)
    107  - microknight+ (Modified MicroKnight version)
    108  - microknightplus (alias to MicroKnight + to be used in URLs)
    109  - mosoul (Original mO’sOul font)
    110  - pot-noodle (Original P0T-NOoDLE font)
    111  - topaz (Original Topaz Kickstart 2.x version)
    112  - topaz+ (Modified Topaz Kickstart 2.x+ version)
    113  - topazplus (alias to Topaz+ to be used in URLs)
    114  - topaz500 (Original Topaz Kickstart 1.x version)
    115  - topaz500+ (Modified Topaz Kickstart 1.x version)
    116  - topaz500plus (alias to Topaz500+ to be used in URLs)
    117 
    118 
    119 ### Bits options
    120  
    121  - "8" (8-bit): Default rendering mode.
    122  - "9" (9-bit): Renders the 9th column of block characters, causing the output to look like it’s displayed in real textmode.
    123  - "ced": Renders files in black on gray, and limit the output to 78 columns (only available in ANSi loader). Used together with an Amiga font, the output will look like it is displayed on Amiga.
    124  - "workbench": Renders files using Amiga Workbench colors (only available in ANSi loader).
    125 
    126 ### iCE colors options
    127 
    128 - 0 (default, turned OFF)
    129 - 1 (turned ON)
    130 
    131 ### Columns options
    132 
    133 Used for .BIN files only. Skip this option when converting other formats. The default is set at 160.
    134 
    135 ### Thumbnail options
    136 
    137 - 0 (default, turned OFF)
    138 - 1 (1/8 scale)
    139 - 2 (1/4 scale)
    140 - 3 (1/2 scale)
    141 
    142 A thumbnail image is rendered instead of a full-size image. Does not apply when playing ansimations.
    143 
    144 ### Filetype options
    145 
    146 - ans
    147 - txt
    148 - nfo
    149 - asc
    150 - diz
    151 - ion
    152 - adf
    153 - bin
    154 - idf
    155 - pcb
    156 - tnd
    157 - xb
    158 
    159 Instead of guessing the filetype based on the name or extension of the url, the chosen rendering method can be chosen from this list by using the option `"filetype": "<type>"`. Using this method, it is possible to display the raw data contained within a file by over-riding this property with `"asc"`.
    160 
    161 ### 2x options
    162 
    163 - 0 (default, turned OFF)
    164 - 1 (turned ON)
    165 
    166 Delivers a canvas element which has double the width and height in pixels, but styled in half these amounts in CSS-pixels. This makes it suitable for display on devices with high pixel densities.
    167 
    168 ### SAUCE record
    169 
    170 As well as a canvas element, a [SAUCE][3] record is returned as a Javascript object if one is found, and follows this format:
    171 
    172     {
    173         "version": "00",
    174         "title": "Example ANSI",
    175         "author": "Joe Q. Public",
    176         "group": "Generic Ansi Group",
    177         "date": "20130922",
    178         "fileSize": 1337,
    179         "dataType": 1,
    180         "fileType": 1,
    181         "tInfo1": 80,
    182         "tInfo2": 26,
    183         "tInfo3": 0,
    184         "tInfo4": 0,
    185         "comments": ["Comment 1.", "Comment 2.", ... ],
    186         "flags": 0
    187     }
    188 
    189 It is also possible to retrieve a record for a file without generating an image by using the `sauce` function.
    190 
    191     AnsiLove.sauce("example.ans", function (sauce) {
    192         console.log(sauce);
    193     });
    194 
    195 ## License
    196 
    197 AnsiLove.js is released under the BSD 2-Clause license. See `LICENSE` file for details.
    198 
    199 ## Author
    200 
    201 AnsiLove.js was written by [Andrew Herbert](http://andyh.org) and is now
    202 maintained by [Frederic Cambus](https://www.cambus.net).
    203 
    204 ## Resources
    205 
    206 Project Homepage : [https://ansilove.github.com/ansilove.js](https://ansilove.github.com/ansilove.js)
    207 
    208 [1]: https://github.com/fcambus/ansilove
    209 [2]: https://github.com/ByteProject/AnsiLove-C
    210 [3]: http://web.archive.org/web/20120204063648/http://www.acid.org/info/sauce/sauce.htm