BMP2BGI: A utility to convert BMP graphic images to BGI format.
Version: 1.0
Date of Release: 6/25/91
===========================================================================

OVERVIEW:
        This utility will convert 16-Color BMP images, like the ones drawn
with MS Windows PAINT, to BGI format, so that the BGI image can be accessed
through your Borland programs.  Any image of any size can be accommodated
as long as its size does not exceed the size of your video card.  1024x768
images will not be converted if your video card can only show 640x480.  

        The BMP images must be in uncompressed format, 16-color, and not
created through OS/2.  These are the MS Windows 3.0 defaults.  A later
version of BMP2BGI will support monochrome and 256-color images.

	The advantage of this utility is that now you can use a paint program,
better than one you could create yourself, or use an already existing image.
After converting the image to BGI, you can reference it in your Turbo Pascal,
C, or C++ programs via the getimage() or putimage() functions.  I wrote this for 
Turbo-C++ programmers, but enough code is provided that you can recode it for 
Turbo Pascal.   I found this utility to be helpful for writing games, creating 
neat-o title screens, and so forth.  Granted, BGI is not the fastest nor most 
convenient of graphics system, but it's free.  Not many of us hobbyists can 
afford the SFX graphics library.

	If you like my work, consider sending me $10 for my labor.  I'd be happy
to send you the latest version on receipt of your honoria.  A nifty game w/ 
graphics that you wrote yourself can be substituted.  Send either (both if 
you're really enthusiastic, but I'd probably think you're weird--See the 
section, "About the Author.") to the address at the end of this document.  If
you use BMP2BGI in your own programming, don't worry about royalties;  I'm not 
asking any.

INSTRUCTIONS FOR USING BMP2BGI:
        BMP2BGI only works with images saved as files.  No support is made for
"Cut-out" files, i.e., those you CUT or COPIED to.  After saving your BMP image 
to a disk file, return to the DOS level, i.e.,  when you see the DOS prompt, 
type:

                           BMP2BGI FName.BMP
                
where 'FName.BMP'is the BMP file.  Next, you will see some statistics about
your file, and EITHER an error message that explains why the image couldn't
be translated OR a message that informs you that conversion will commence.
The conversion is nondestructive, i.e., your BMP file will be unchanged.

Then you will see the image on-screen, followed by black-masking as the
image is converted.  The image is saved in the file 'FName.BGI', where 'FName'
is the same 'FName' as your BMP file.  If FName.BGI already exists, it is
written over.

	To see how the image converted, a second program is included,
SHOWBGI.EXE.  This program shows how the image converted.  To run, type
the following on your DOS command line:

					SHOWBGI FName.BGI

where 'FName.BGI' is the BGI file created with BMP2BGI.  SHOWBGI is a simple
program in that it provides no error-checking, like if you entered a non-
existing file.  NOTE: YOU CAN ONLY USE SHOWBGI WITH FILES CREATED FROM
BMP2BGI.  Reason being is that I had to include some preliminary information
about the color palette at the begining of the BGI images because of
incompatibilities between Microsoft's and Borland's color palettes.  There are a 
few shareware programs that also create BGI programs, but I found that their 
file structure, similar to mine, contain preliminary information at the 
beginning of the file.  More about this in the next section "PROGRAMMING FOR BGI 
IMAGES."

PROGRAMMING FOR BGI IMAGES:
	BMP2BGI was created primarily for programmers who want to use the
Borland BGI toolkit for creating, displaying, and manipulating images they made
with a program that creates BMP images.
        If you are interested in reverse-engineering BMP2BGI, I made it easy
for you; I included all source code and project files.  NOTE: if you want to
tinker around w/ BMP2BGI: the source code is in Turbo C++ (v1.0) and you will
need to write your own fexist(char *) function that returns TRUE if a file
exists or FALSE otherwise.  Of course, you could comment out the part of the
source code that calls fexist(), as this won't affect the translation.  Also,
you will need to link two .OBJ files: EGAVGA.OBJ, which is in the \TC\BGI
directory Turbo C created when it was installed.  Also, include the .OBJ file,
EGAVGAF.OBJ, which you must create with the BGIOBJ.EXE program, also in the
\TC\BGI directory.  EGAVGAF.OBJ is a BGI driver that allocates itself from the
far heap.  I found it better to alloc from the far heap whenever I write large
programs, as most games are.  If your preference is different, or you don't
want to mess around w/ a "far" BGI driver, then amend the line 
"registerfarbgidriver()" in the file, BMP2BGI2.C.  It is not crucial that the
BGI driver be in far memory; it's just my preference.

        The BMP2BGI BGI file is not exactly pure BGI, as there is a header
before the BGI bitmap images that contains various info.  Refer to BGI.H 
(included w/ BMP2BGI) for an explanation.  IT IS IMPORTANT THAT YOUR BORLAND 
PROGRAMS USE BGI.H TO ACCESS BGI IMAGES CREATED W/ BMP2BGI.  A sample program, 
SHOWBGI.EXE, and accompanying source code is included to show you how.  Another 
file, BMP.H, is included and is necessary for BMP2BGI, but not for programs 
displaying BGI-transformed images.  BMP.H defines the file layout for BMP files.

ACKNOWLEDGEMENT:
I acknowledge Charles Petzold's informative article on BMP bitmaps as giving 
guidance if not outright variable names and BMP header structures.  If you are 
interested in the BMP file, refer to Mr.Petzold's article in PC Magazine 
(vol.10(10), pp365-370).

Included in this Zip-archive are the following files:

0. This file:
              BMP2BGI.Txt

1. Turbo C++ source code for BMP2BGI:
              bgi.h, bmp.h (Header files for BMP and BGI image files)              
              bmp2bgi.c, bmp2bgi1.c, bmp2bgi2.c, bmp2bgi3.c
              bmp2bgi.prj (The project file for BMP2BGI. Be sure to check
              			the directories listed for the supplementary 
                           files, as my programming subdirectories are probably 
                           different from yours.  Also, check the 
                           Options|Complier|Code Generation settings so as to
                           set them for your preference.  I STRONGLY recommend 
                           that you compile BMP2BGI as either a large- or huge- 
                           memory program.  The buffer for the image file data 
                           MUST be allocated from the far heap)

              
2. Turbo C++ source code for displaying BGI images created w/ BMP2BGI:
              showbgi.c, showbgi2.c
              showbgi.prj  (The project file for SHOWBGI.  Be sure to check
              			the directories listed for the supplementary 
                           files, as my programming subdirectories are probably 
                           different from yours.  Also, check the 
                           Options|Complier|Code Generation settings so as to
                           set them for your preference.  I STRONGLY recommend 
                           that you compile SHOWBGI as either a large- or huge- 
                           memory program.  The buffer for the image file data 
                           MUST be allocated from the far heap)

3. Compiled Executables if you want to use the BMP2BGI or SHOWBGI right away and
   don't want to tinker w/ reprogramming BMP2BGI.  Do check out SHOWBGI's
   algorithms so you can learn how to use BGI image files in your programs.  If
   it will help, feel free to cut-and-paste the algorithms.
              bmp2bgi.exe, showbgi.exe     
              

4. And a sample BMP file:
              test.bmp  (A 1/4th print screen from MS Windows, because I'm
		 		   unartistic.)

        
COPYRIGHTS (Because a lawyer suggested I do this):  
============================================================================

BMP.H: (c) Ziff-Davis Publishing
BMP2BGI.EXE, SHOWBGI.EXE, BMP2BGI.c..BMP2BGI3.C, BGI.H, SHOWBGI.EXE, 
        SHOWBGI.C, SHOWBGI2.C, TEST.BMP: (c) R.G.Rasulis Consulting Services
MS Windows 3.0, MS Windows Paint, BMP: (c) Microsoft, Corp.
Turbo C++, Turbo Pascal, Turbo C, BGI: (c) Borland International.
      
About the Author:
============================================================================

Richard Rasulis, Jr. is currently interning at the Milwaukee Mental Health
Complex which partially fulfilling requirements for his doctoral degree in
clinical psychology at the University of Montana.  Prior to becoming a
"gradual" student, he worked as a hacker-4-hire in Boston, MA.  Amongst his
hobbies is programming as well as conducting research on using computers
to administer psychological tests.  He is the author of several PC programs,
including scoring programs for various psychological tests.  Further, he is
conducting research in the area of maturity and psychological well-being.
He may be contacted through the various addresses:

        SnailNet: R.G.Rasulis                         PC-EXEC: Rich Rasulis
                  c/o Dep't of Psychology             GEnie: R.RASULIS
                  Milwaukee County Mental Health Complex
                  Milwaukee, WI 53226