Bmp2Ans Bitmap to ANSI Picture Converter------------------------------------
Version 1.00a by Mike Davenport (1996)--------------------------------------
----------------------------------------------------------------------------

[1] Intro
---------
Bmp2Ans is a completely free, public domain software package. It does
not require any fees payable to the author for continued use. This
software package is distributed as is, with no warranty from the author
nor any corporations mentioned within this document. It has been
extensively tested, and should not cause any errors on the user's
system. If it does, they are only superficial and restarting your
computer will remove them. Neither the author nor any companies
mentioned within this document may be held responsible for damages
to your system caused during the use of this program.

If you do find an error with this program, or you have any other
concern with this program, such as an option you would like to see in
future versions, please send E-Mail to one of the following addresses :

        AOL at screen name : Mike4148
        Internet : mike4148@aol.com

[2] The Concept
---------------
ANSI graphics are hard to draw. You have 16 colors and you get to draw
different little ASCII characters in order to somehow achieve the illusion
of a high resolution image, even when, at maximum size, an ANSI image is
less than one third of a normal graphic image at the same DPI. Bmp2Ans
allows you to use any utility which will draw normal graphic images to
engineer your ANSI graphics. The advantages of this are numerous;for
one, you can use fonts and various other options which are normally
enabled in a BMP editor yet which are forgotten in an ANSI editor. However,
Bmp2Ans has its limitations.

Bmp2Ans makes a very close imitation of the 256- or 16-color (Note : Bmp2Ans
does not require the standard 16-bit color table of black, blue, green, red,
magenta, etc.;it will work with other colors as well) table of the BMP file
(future versions will support 2-color bitmaps as well;16.7 mil. colors will
NOT be supported;read on for reasons why). This is not always EXACTLY right
although it is always VERY close. One big tip is to keep your colors above
100 in intensity (otherwise they may be treated as black). Remember, Bmp2Ans
has to shrink 256 or 16 colors into a palette that supports only a fixed set
of 16. Luckily, there are some shortcuts (involving the "shaded" characters,
176 (), 177() and 178()). Furthermore, different combinations of foreground
and background colors produce different levels of intensity as well.

Bmp2Ans is an extremely useful utility for BBS's, especially since the
most supported terminal emulation for the average BBS is ANSI-based. With
the further development and increasing use of RIP terminals, however,
Bmp2Ans may become obsolete in the future.

[3] Running
-----------
Bmp2Ans is a 16-bit MS-DOS program (which doesn't require MS-DOS mode in
Win95(tm);it can be run in an MS-DOS prompt). It is limited by available
memory, although it can theoretically process files up to 1MB in size.
Bmp2Ans does NOT require ANSI.SYS to be loaded, although it is needed for
viewing outside of Bmp2Ans without separate programs. Here is the
basic command line syntax :

BMP2ANS BitmapFile ANSIFile

BitmapFile is the name of the BMP file to be processed (extension
included). ANSIFile is the name of the ANSI file to be created (extension
isn't important with ANSI files, although you may want to use ANS).
That's it. Press enter after typing in this, and watch Bmp2Ans work its
magic. You may receive an error message during this phase (for a detailed
description of the error messages you may receive, page down to section 4).
Here is a sample output :

Bmp2Ans Bitmap to ANSI Picture Converter
v1.00a by Mike Davenport (1996)---------
----------------------------------------
	Width : 73
	Height : 29
	Bits-per-pixel : 8

Converting bitmap color table to ANSI table...
Done
Outputting bitmap data to ANSI data...
Done

Width is the width of the bitmap file, height is the height, and
bits-per-pixel is the bits-per-pixel (if you are unfamiliar with such a
term, the bits-per-pixel designates (in BMP files) the amount of total
colors which can be used by the file (the amount of bits needed to describe
one pixel) : 4-bit allows for 16 colors and 8-bit allows for 256-colors).
Note that if this is anything other than 8 or 4, the current version of
Bmp2Ans will display an error message.

The extended command syntax is as follows :

BMP2ANS BitmapFile ANSIFile [Cols=xxx] [ForceCRLFs] [DispColorTable]
[DispPic]

(Note that BMP2ANS is not case-sensitive. For example, NoCRLFs and noCrlfS
are interpreted the same)

[Cols=xxx]        Specifies amount of columns of the target terminal. If
                  the width of the image is this or longer, no carriage
                  return/linefeeds are inserted. By default, this is set
                  at 80.
[ForceCRLFs]      Always adds a carriage return/linefeed pair after each
                  row in the bitmap. (Not to be used with Cols=xxx)
                  By default, this is off.
[DispColorTable]  Displays the ANSI table on screen (requires a color
                  monitor) in 16x16 format. (Compare this to the bitmap's
                  palette to judge Bmp2Ans's accuracy)
                  By default, this is off. (Note : ANSI.SYS is NOT required
                  for viewing the color table or the output picture with
                  this option and DispPic.)
[DispPic]         Displays the ANSI picture while it is being converted
                  (requires a color monitor).
                  By default, this is off.

Note : The BitmapFile and ANSIFile parameters must come first (if Bmp2Ans
notices that a different parameter is first, it will display a warning
(see section 5) and continue with its processes (just in case you actually
have a bitmap file called DispPic or you want to make an ANSI file called
Cols=4, etc.).

[4] Errors
----------
Errors are situations in which Bmp2Ans cannot continue processing.
The program exits when an error occurs and returns a specific DOS
error code (Note : This code is 0 upon normal program exit).

The following table of errors is arranged in the form :
<Error>  <Error Description>  <DOS ErrorLevel>

Where <Error> is the text which you see when the error occurs in Bmp2Ans,
<Error Description> is a description of the error, and <DOS ErrorLevel>
is the error code returned to DOS upon exit.

Error                     Description                         Error Code
----------------------------------------------------------------------------
Usage :...                No (or not enough) parameters           1
                          listed
Cannot open input file    The program was unable to open          2
                          the input file;it may not exist,
                          or it may be locked
Only 4- and 8-bit bitmaps Bmp2Ans does not and will never         3
supported                 support > 8-bit bitmaps;support
                          for 2-bit bitmaps will be implemented
                          in later versions
Unable to use compressed  The bitmap file which was specified     4
(RLE) bitmaps             is either an RLE bitmap file or is
                          in the wrong format
Insufficient memory for   The program was unable to allocate      5
bitmap color table        memory for the bitmap's color table
Insufficient memory for   The program was unable to allocate      6
ANSI color table          memory for the ANSI color table
Insufficient memory for   The program was unable to allocate      7
bitmap                    memory for the bitmap data
Cannot open output file   The program was unable to create the    8
                          output file;there may not be enough
                          disk space available or it may exist
                          and be read-only

[5] Warnings
------------
Warnings are "suspicious" situations in which Bmp2Ans detects a
possible misuse of the program. However, Bmp2Ans will still continue
normal execution and will exit as if no error ocurred.

The following table is arranged in this format :
<Warning>   <Warning Description>

Where <Warning> is the text which appears on the screen, and
<Warning Description> is a brief description of the warning.

Warning                        Description
----------------------------------------------------------------------------
Warning! Usage :...            A normal parameter was either the first
                               or second argument on the command line;
                               Bmp2Ans requires the first and second
                               arguments to be the bitmap and ANSI files,
                               respectively;however, since some normal
                               parameters are legal DOS file names, it
                               only displays a warning (if the parameter
                               used is not a legal DOS file name, either
                               a "Cannot open input file" or "Cannot open
                               output file" error will occur (see section
                               4))
File is larger than xxx        (With the xxx being either the number in
columns                        the Cols= parameter (see section 3) or 80 (if
                               no Cols= was specified)
                               Bmp2Ans expects the Cols= parameter (or the
                               default 80) to be the width of the target
                               terminal. If the bitmap file is larger than
                               80 (or the number specified by Cols=) pixels
                               wide, that would force line-wrapping on the
                               terminal.

[6] The End
-----------
The full source code of Bmp2Ans is available via E-Mail. Send a request
for the source code to one of the E-Mail addresses listed at the beginning
of this document. The source code was written in Borland(r) Turbo C++(tm)
v3.0 for DOS;although it will probably be portable to other compilers. Any
portion of the source code may be used and copied or used as a basis for
another program.

Two example bitmaps, EX1.BMP (8-bit BMP2ANS logo) and EX2.BMP (another logo
of BMP2ANS in 4-bit bitmap format), have been provided with this version.
Convert them and compare the ANSI output files to the BMP files to witness
Bmp2Ans's accuracy.

----------------------------------------------------------------------------
Windows 95(Win95) is a trademark of the Microsoft Corporation;Turbo C++
is a trademark of Borland, Intl.
