ReadGIF Documentation ===================== ReadGIF is © Copyright 1994 by Jürgen Weinelt. Non-commercial distribution (that is, distribute freely and FOR FREE [except for reasonable media costs]) is permitted. The program "ReadGIF" and its documentation "ReadGIF.doc" must be distributed together and unchanged. Do NOT add additional files to the archive (.displayme or other nonsense). If you want to use ReadGIF as part of a commercial package, please contact me first. Usually I will not ask for more than a free copy of your package. ReadGIF may be included in CDROM distributions of freely distributable software IF, and ONLY IF I am allowed to purchase at least one copy of the CDROM for half the normal price (or cheaper, of course). Fred Fish has UNCONDITIONAL permission to include ReadGIF in his freely distributable software library, even in the CDROM version. DISCLAIMER: ReadGIF was carefully tested, but of course there could still be some bugs in it. You have been warned. If you decide to use ReadGIF and it blows up your monitor, formats your hard disk, fries your cat or does anything else that you think is nasty, that's YOUR problem. Not mine. USE AT YOUR OWN RISK. CompuServe License ------------------ "The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated." Installation ------------ Copy the executable "ReadGIF" to a directory in your search path (typically "c:"). Read the documentation (this file). Requirements ------------ * Any Amiga (tested with A4K). * A Picasso-II graphics board (tested with 2 meg version). * Lotsa RAM (depends on image resolution and depth), 4 MB should be enough even for large GIFs. * Kickstart 2.0 or better. It might run with Kickstart 1.3, but I didn't test it. Kickstart 1.3 is obsolete anyway. (Tested with KS 3.1). Features -------- * Supports the entire GIF87a standard. * Can read GIF89a as GIF87a, but ignores GIF89a-specific extensions. * Supports GIF files that contain multiple images. * Supports local color maps. * Supports interlaced GIFs. * Supports arbitrary placement of images on the screen. * Automatically goes to slide show mode when called for multiple files. * Supports (or rather, correctly ignores) GIF extension blocks. * Supports AmigaDOS file name pattern matching. Usage ----- ReadGIF F=FILE/A/M,D=DELAY/N,W=WAIT/N,C=CENTER/S,Q=QUIET/S,V=VERBOSE/S, E=ERASE/S File: List of GIF image file names or AmigaDOS name patterns. Yes, ReadGIF supports pattern matching for the file names. Delay: Time (in seconds) to wait between subsequent GIFs. If you don't specify a delay, ReadGIF will wait for a mouseclick or keypress before continuing. Note: The GIF standard specifies that the viewer program should wait for user input when a GIF file is completely processed and displayed. To get this "true GIF" behaviour, don't specify any "DELAY" value (omit the DELAY keyword entirely). Wait: Time (in seconds) to wait between subsequent images within a multiple image GIF file. If you don't specify a wait time, ReadGIF will wait for a mouseclick or keypress before continuing. Note: The GIF standard specifies that the viewer program should NOT wait at all between the images contained within one single GIF file. To get this "true GIF" behaviour, specify "WAIT=0". Note: my experience shows that for most cases, WAIT=0 or WAIT=1 seems to be the optimum. Center: If the image is smaller than the screen, force the image to be centered. This does NOT conform to the GIF standard (the image contains a position information) and may even cause SOME multi- image GIFs to look wrong (for example FAERY.GIF from Visual Fantasies). Defaults to (NOT CENTER). Quiet: Suppress all messages except error messages. Defaults to (NOT QUIET). Verbose: Display additional information (debug mode); implies (NOT QUIET). Defaults to (NOT VERBOSE). Erase: Always clear the screen between subsequent pictures. This will NOT clear the screen between subsequent images in multi-image GIF files. Background information ---------------------- ReadGIF (as well as ReadBMP) is just an initial experiment. I intend to write a generic picture viewing/editing/processing package, which will most likely be distributed as shareware. ReadGIF is basically the GIF reader part of that package, wrapped in a simple CLI/Shell interface. As one stage of the experiment, I tried to optimize ReadGIF for speed (just to find out how far/fast I could get). Most of these optimizations will be removed from the final package, because readability, portability and safety are far more important to me than speed. Currently, ReadGIF contains more than 30 % of inline assembler code, which makes the source rather hard to maintain. :-( The current version 1.249 of ReadGIF will be the last standalone version, unless someone finds a particularly nasty bug. It will also be the last version that's specifically optimized for speed; that's part of the reason why I release it. I will merge the GIF and the BMP viewer into one program next, along with some additional features. Current working title for this project is "JIV". Time of release is very uncertain, depending on the number of new features as well as the number of supported formats. :-) Seriously, I will attempt to release a version as soon as possible, even if there are not too many new features. Bugs ---- No real bugs known at the moment (there's a slight memory leak, but I *think* that's a bug in the Picasso emulation). However, there are a few potential problems in the code that I know about but (again :->) did not fix for this release: Nasty things *might* happen if you attempt to load a picture that's larger than the largest Picasso mode available. Nasty things *might* happen if you run out of memory. You have been warned. Author ------ Jürgen Weinelt Franz-Ludwig-Straße 10 97072 Würzburg Germany (If you don't know how to use Umlauts, substitute ü -> ue and ß -> ss). eMail: jow@rz.uni-wuerzburg.de (preferred) jow@hcast.franken.de jow@hcast.adsp.sub.org (possibly obsolete) IRC: jow @ #amigager Credits ------- ReadGIF is based on the CompuServe GIF87a documentation (June 15, 1987) and (part of) the GIF89a documentation (31 July 1990). The GIF-LZW decoder is based on an algorithm described in a document that was written by Steve Blackstock (I found it on an anonymous FTP server). Thanks Steve - without your description, I'd have needed at least twice as much time to write that LZW decoder. IMO, CompuServe's LZW variant suxx roxx :-). The asynchronuous IO stuff is based on an example taken from Matthias Schelers PCX datatype. The asynch IO increased the speed by at least 20 %. Thanks again! Thanks ------ Georg "Gucky" Heßmann reported bugs, suggested new features and helped with the "mouseclick/keypress"-feature. Matthias "Tron" Scheler suggested new features and provided the asynch IO source. Henning Sauer suggested new features. Todo ---- # ReadGIF really should support startup from Workbench, but I don't really need this feature, so it's relatively low on my list of priorities for now. If you feel you really can't live without it, contact me and try to convince me. :-) # ReadGIF should display a file requester when you call it without further arguments. Again, I don't really need it, so don't hold your breath unless you think blue skin looks sexy. # ReadGIF should attempt to open an Intuition screen under KS3.0 (or later versions). # ReadGIF should support AGA and possibly even ECS/OCS. History ------- 1.249 Added asynch IO, added "erase" option. 1.210 Fixed a harmless bug in the "multiple image" code. 1.209 ReadGIF used to leave behind active locks on exit. Oops. Fixed. 1.205 added AmigaDOS file name pattern matching. 1.200 enabled "deferred clear code" (untested - please somebody send me a GIF that uses this feature ;->) 1.199 enabled reading of GIF89a files. 1.196 forced clear screen between images. 1.189 fixed a bug in IDCMP handling. 1.186 added CENTER. 1.184 Added "advance on mouseclick/keypress" feature. 1.173 Fixed a bug (misunderstanding of format specification, actually) in the GIF extension handler. 1.170 Added ReadArgs support, added "quiet", "verbose", "wait", "delay". 1.152 Initial Release.