Introduction
------------

Bitmap to Source Converter is a small command line utility that opens
a 256-color .BMP file and reads in the palette data and the actual bitmap
data and then writes the bytes to a C++ source file that you can include
you own programs.  I have written several programs that use bitmaps
for the graphics, and I have long wished for some way to include the
bitmaps in the final EXE file.

Also, BMP files are strange in that the actual bitmap data starts at
the lower left hand corner and so if you tried to write it to the
screen you would find that is upside-down and inside out!!  Bitmap to
Source Converter takes care of this messy detail and the resulting array
will be corrected for writing to video memory.


Who should use this program?
----------------------------

Bitmap to source converter is for advanced C/C++ programmers that are writing
graphics programs that have the need to write directly to video memory.
Usually this will mean video game programmers because games often require
fast graphics routines and writing a bitmaps bytes directly to video
memory is the only way to accomplish this.

If you still have no idea what I'm talking about, this program is
probably not for you.  The source file generated by this program is not
a tutorial on VGA card programming.  If you are writing a program of
this type, you will know what to do with the source file.


What exactly will this program do?
----------------------------------

Bitmap to Source Converter will open a 256-color BMP file and create two
arrays of type int.  The first array will be named palette[] and is,
by default, 1,024 bytes.  The second array is named data[] and is
whatever size the bitmap being read happens to be.  The program will
also create three int variables named:

  - width  - Width of the bitmap.
  - height - Height of the bitmap.
  - size   - Total size.

This information is usually necessary for writing the bitmap to the screen.

Keep in mind that the resulting text file will be rather large in most
cases, so you might want to limit the size of the .BMP files that you
use this utility for!  By including the source file that this program
creates you eliminate the user from seeing or altering your bitmaps, but
the resulting .EXE file will be much larger.

IMPORTANT! - THE FILE BEING READ MUST BE A 256-COLOR .BMP FILE!!!
THIS PROGRAM IS DESIGNED FOR PROGRAMMERS WHO INTEND TO WRITE THE
BITMAP DIRECTLY TO VIDEO MEMORY.  THIS IS NOT INTENDED TO BE USED
WITH GRAPHICS FUNCTIONS.

PLEASE BE SURE TO COMPILE YOUR PROGRAM IN THE CORRECT MEMORY MODEL!!
I WOULD RECOMMEND THE LARGE MEMORY MODEL IF YOU AREN'T SURE!  REMEMBER
THAT THE ARRAYS CREATED CAN BE RATHER LARGE IN SIZE. THERE IS A LIMIT ON
HOW LARGE AN ARRAY CAN BE IN C, SO KEEP YOUR BITMAPS SMALL IN SIZE.
YOU MAY HAVE TO MAKE MINOR ADJUSTMENTS TO THE ARRAY TYPE DEPENDING ON
HOW LARGE THE BITMAPS ARE.  FOR EXAMPLE, CHANGING TYPE INT TO TYPE
UNSIGNED INT.


System Requirements
------------------

  - 386 or higher IBM or compatible.
  - MS-DOS 5.0 or higher.
  - C/C++ compiler


How to use the program
----------------------

Simply unzip the archive and extract the files to the directory of
your choice.

To use the program from the DOS command prompt:

  - Type bmp2cpp [path]filename
    where filename is the name of a valid 256-color .BMP file
    and an optional path may be included.

  - The program will do the rest!  The resulting file will be named
    bitmap.cpp - However, it is just a text file and you can rename 
    it to anything you like.

  - Then just include the source file in your program and define
    the variables size, width, height, data[] and palette[] as external
    and compile.

I have included a sample source file called MAIN.C which shows how you
might use the resulting source file, and TEST.BMP a small bitmap to feed
to the converter. In my example, I did not use the palette data because
the paint program I used to create the bitmap used the default
256-color palette.


License agreement
-----------------

Bitmap to Source converter is licensed as FREEWARE, and you may include
the source file generated by this program in your own programs royalty free.
You may distribute the software to anyone you choose, as long as all the
original files are included and have not been in any way altered.

The archive should contain the following files:

BMP2CPP.EXE - Command line converter
MAIN.C      - An example source of how you might use the source file.
TEST.BMP    - A 100x100 pixel 256-color .BMP file for testing.
README.TXT  - This file.
FILE_ID.DIZ - File description.

If any of the files are missing, or if others have been added, please
contact me and let me know about it.  See contact information below.

Bitmap to source converter (BMP2CPP.EXE) is protected by United
States copyright laws.

                Bitmap to Source Converter v1.1
                (C) Copyright 1997, Justin Hill
                     Licensed as FREEWARE.
                    

DISCLAIMER - The author assumes no liability for the use, or misuse of
this software.  No guarantees or warranties of any kind are either
expressed, implied, or written.


Changes and known bugs
----------------------

I made some minor changes to the type of arrays created and how the
information is displayed to the user.  Other than that, not much is
different from version 1.0.

Bugs?? - As far as I know everything works properly!  The only problem
you may encounter is if you try to create an array that is too large.
You should always check the source file to make sure that everything looks
ok before you attempt to compile it.  I would recommend keeping the
bitmaps 100x100 pixels or smaller.  If they're larger, you should probably
open them at runtime (dynamically).


Contact information
-------------------

Please feel free to report any bugs, comments, or questions that you may
have to:

  - Justin Hill
  - justin72@concentric.net

If I find that there are bugs, I will do my best to correct them and make
the new version of the program avavilable.  I hope that this utility will
help somebody out there.  :)





