ReadMe File for
CGA2BMP.C (C) Version 1.0
CopyLeft Bill Buckels 1999
All Rights Reversed.

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

Cga2Bmp is a Graphics Utility program that is used to convert "Old
Style" 4 Color Graphics Files to Windows .BMP files. It is one of a
collection of utilities that are currently available from the author to
assist users of his educational software to customize and manage
graphics used by his programs.

This utility will allow you to convert CGA 4-color screen dump files of
either a BASIC BSAVED IMAGE (.BAS) File or a ZSOFT CGA .PCX File to a
320 x 200 x 16 color Windows .BMP File, suitable for use with Version
2.1 and greater of the WorkBook program, as well as many other programs
that accept .BMP files.

CGA2BMP provides advanced color change capabilities using the keyboard
keys [F1] through [F4], to independently change each of the 4 CGA colors
in the source image to a color from a standard 16 color VGA palette in
the target .BMP image.

This utility is visual, and allows you to see your changes before either
saving or abandoning.

Two Palettes are built in:
- PCX 16 Color Standard VGA DOS Palette
- BMP 16 Color Standard VGA Windows Palette

A third palette is also available:
- CUSTOM 16 Color User Defined Palette.

The user toggles between these by pressing the
'B' (.BMP), 'P' (.PCX), and 'C' (CUSTOM) keys.

Support is provided for the following palette file formats which you can
use to define the CUSTOM palette:

- PaintShop Pro 16 Color Palette - Ascii Text
- NeoPaint 16 Color Palette (DOS or WINDOWS) - Ascii Text
- Aldus Photostyler 16 Color Palette - Ascii Text
- Aldus Photostyler CLR Color File - Ascii Text
- GeoVu 16 Color Palette - Ascii Text
- Adobe ACT Palette File - Binary
- Alchemy GIF Contruction Set CMP File - Binary
- Microsoft RIFF Palette File - Binary

Installing Cga2Bmp
-------------------

Cga2Bmp is part of a larger collection called "WorkTools", but is
installed separately using the Cga2Bmp Archive file, Cga2Bmp.Zip.

Install Cga2Bmp by "UNZIPPING" Cga2Bmp.ZIP complete with pathnames to
the drive of your choice. If you decide to install Cga2Bmp to Drive C:,
Cga2Bmp will be installed into the directory C:\WorkTool\Cga2Bmp.

To run Cga2Bmp in DOS, type Cga2Bmp.EXE and press [Enter]. To Run
Cga2Bmp in Windows, click-on Cga2Bmp.EXE.

Getting Started
---------------

Cga2Bmp has two ways to enter an input image name; through the command
line, or via a prompt. If no command line arguments are entered, Cga2Bmp
will prompt you for your input image name, and for your palette file
name.

Prompted File Name Entry
------------------------

Enter CGA Screen FileName (Blank to Exit):
Enter Palette FileName (Blank for None) :

Command Line Usage
------------------

CGA2BMP MyCGA.PCX
CGA2BMP MyBSAVE.BAS
CGA2BMP MyCGA.PCX PaletteFile.Pal
CGA2BMP MyBSAVE.BAS PaletteFile.Pal

Commands and Navigation
-----------------------

When Cga2Bmp starts, a help screen of keyboard commands is displayed.
This help screen can be redisplayed at anytime throughout the program by
pressing the 'H' key. A summary of the keyboard commands is given below.

Press [F1] To Change CGA BLACK
Press [F2] To Change CGA CYAN
Press [F3] To Change CGA MAGENTA
Press [F4] To Change CGA WHITE
Press 'C' For Custom Palette
Press 'B' For Bmp Palette Colors
Press 'P' For Pcx Palette Colors
Press 'S' or [ENTER] to Save
Press 'Q' or [ESC] to Quit
Press 'H' For Help

What does the Cga2Bmp Package Contain?
--------------------------------------

The Cga2Bmp package comes with several practice palettes and a number of
images that you can use to try-out the program features. See "Notes on
Color Palettes" following the Licence Agreement below for more details.

See Appendix A at the end of this ReadMe for a Packing List of the
program and sample files, and source code.

Licence Agreement, Copyright and Conditions of Use
--------------------------------------------------

Cga2Bmp and its associated files are Copyrighted by their author, Bill
Buckels. Cga2Bmp is not a derivative work of any other author and is the
exclusive property of its author, Bill Buckels.

You have a royalty-free right to use, modify, reproduce and distribute
this program and its source code in any way you find useful, provided
that you agree that Bill Buckels has no warranty obligations or
liability resulting from said distribution in any way whatsoever. If you
don't agree, remove this program, its source code, and any related files
from your computer now.

The images used in Cga2Bmp were produced by Bill Buckels (the author)
and as such are the author's own expression, and a fair use of content
that is believed to be in the public domain. You may use these in any
way you find useful, provided you do not compete with Bill Buckels or
his agents, and that you agree that Bill Buckels has no warranty
obligations or liability whatsoever resulting from any associated loss
or damage.

If you redistribute the Cga2Bmp program, please distribute it in its
entirety. If you are missing files, you can download a complete version
from the internet at:

http://www.escape.ca/~bbuckels/kidstuff

Bill Buckels
589 Oxford Street
Winnipeg, Manitoba, Canada R3M 3J2

Email: bbuckels@escape.ca
WebSite: http:www.escape.ca/~bbuckels

Some Notes on Color Palettes used in CGA2BMP
--------------------------------------------

Colour palettes are files containing a series of colour definitions.

For a detailed technical description of how Cga2Bmp deals with palette
formats, especially binary ones, probably the program source code is the
best place to look.

However if you are not inclined to read such things, the summary below
should answer many if not most of your questions about using external
palette files with Cga2Bmp.

If you want to delve further into the ascii text format palettes, you
can open the various sample palettes provided with Cga2Bmp using a text
editor like Windows NotePad or Dos Edit.

Binary Formats Supported
------------------------

Adobe Colour Tables (.ACT files) are used by Photoshop in paletted
images.

GIF Construction Set (.CMP) - Color Maps are used by by Alchemy
Mindworks GIF Construction Set application.

Microsoft palette (.PAL) - Windows palettes (.PAL files) are produced by
a variety of programs. These are in RIFF format.

Text File Formats Supported
---------------------------

The PaintShop Pro Palette File Format
-------------------------------------

Paint Shop Pro Palettes (.PAL files) are created using 'Save Palette' in
the Paint Shop Program. Not sure what versions of PSP support this
format, but probably versions 1-5 is my best guess.

PaintShop Pro has consistently used a common palette file version 0100
from its early versions to the present. It only makes sense to support
this widely used palette format in Cga2Bmp.

This format consists of 2 header lines, a color count line, followed by
color specification lines in the form of RGB triples. The value range
for red, green, and blue is from 0 to 255.

The NeoPaint Palette File Format
--------------------------------

NeoPaint Palettes (.PAL files) are either created in the NeoPaint DOS
Paint Program or the NeoPaint for Windows Paint Program.

The NeoPaint DOS File Format is a "native IBM 18 bit" RGB file format
that uses RGB triple values from 0-63. This is known as a "6 bit color
value" as opposed to the "8 bit color value" that is commonly used in
today's standard 24-bit color model, including by the PaintShop Pro
palette file version 0100.

The NeoPaint DOS palettes are different from Paint Shop Pro palettes by
the fact that they use 6 bits of color information (values from 0-63)
rather than 8 bits of color (values from 0-255). (And also, they have
different header text.)

The top half of the NeoPaint for Windows palettes are the same format as
the NeoPaint for DOS palettes, and use 6 bits of color information,
preserving backward compatibility with the DOS version of NeoPaint. The
bottom half of the file follows with a "duplicate" palette of 8 bit
values, the same format for color specifications as that of a Paint Shop
Pro .PAL file, allowing a higher resolution standard of 24 bit colors.

The Aldus PhotoStyler Palette File
----------------------------------

If you have Aldus PhotoStyler Version 2.0, Palettes (.PAL files) can be
found in the Photostyler palettes subdirectory. This subdirectory
contains sample files that you can load into the Color Palette. Choose
Load Palette... from the tool-drawer menu.

These are virtually the same format as Paint Shop Pro or Neo Paint, but
are not interchangeable, because of minor differences. Photostyler also
provides color files (.CLR files) that are stored under the Photostyler
colors subdirectory. These include "spreads" and other interesting
collections of assorted colors that are virtually the same format as the
Photostyler palette files, but usually with less colors. Both file types
are handled by Cga2Bmp.

The GeoVu Palette File Format
-----------------------------

GeoVu Palettes were originally used by a GeoPhysics application called
GeoVu and have been adopted for use in CGA2BMP because they are easy for
the user to create "by hand".

"Natural Color Names" are allowed for destination colors in our
interpretation of these, so the user can map the CGA colors more easily,
and partial palette files are accepted, which means that if the user
only wants to change 1 color and combine it with the default colors, all
they need to do is type-in a single line.

As said previously, GeoVu is a GeoPhysical Data Browser application
distributed by the National Geophysical Data Center. The GeoVu
application supports a separate palette file format with a .pal
extension. This file is a ascii text file. Each line in the ascii text
file is a color specification.

The color specification is a line of four values separated by spaces: an
index, red, green, and blue. The value range for red, green, and blue is
from 0 to 255.

An example of a GeoVu color palette:

0 0 0 0
1 0 0 170
2 0 170 0
3 0 170 170
4 170 0 0
5 170 0 170
6 170 170 0
7 170 170 170
8 85 85 85
9 85 85 255
10 85 255 85
11 85 255 255
12 255 85 85
13 255 85 255
14 255 255 85
15 255 255 255

Data Access Technologies and SoftWare Applications Team
Solid Earth Geophysics Division, E/GC1
National Geophysical Data Center
325 Broadway
Boulder, CO 80303
(303) 497-6472
Internet Mail: geovu@ngdc.noaa.gov
Web Home: http://www.ngdc.noaa.gov/seg/dataswat/

How The GeoVu Palette Format is Used by Cga2Bmp.Exe
---------------------------------------------------

The GeoVu Palette format can be used in Cga2Bmp as noted above. As a
matter of fact, the RGB values in the palette noted above are the
initial default palette values that are used by Cga2bmp.

The problem with creating this entire file "by hand", however, is that
it requires too much typing, so Cga2Bmp also allows some variations of
this file format that are more "user friendly":

You can create the palette file with RGB values for only the color
indexes that you wish to change and Cga2Bmp will add only those colors
that you have changed to the existing 16 color custom VGA palette.

However, even that is too much work, because you still need to know how
the CGA Colors map to the initial VGA Colors inside of the Cga2Bmp
program. (They are not 1,2,3,4.) See the following for the actual
default initial color mapping used by Cga2Bmp:

CGA Color    Cga2Bmp Index Number   Initial Color    RGB
---------    --------------------   -------------    ---
BLACK        0                      BLACK            0 0 0
CYAN         9                      LBLUE            85 85 255
MAGENTA      12                     LRED             255 85 85
WHITE        15                     BWHITE           255 255 255

To make the process of specifying a color value simpler, Cga2Bmp will
allow you to use "natural language" to point your RGB values to the
correct initial VGA indexes for the color area of the CGA image that you
are converting.

For Example, the following two palettes are equivalent

Palette 1.

0 0 0 0
9 85 85 255
12 255 85 85
15 255 255 255

Palette 2.

BLACK 0 0 0
CYAN 85 85 255
MAGENTA 255 85 85
WHITE 255 255 255

If This is Too Hard
-------------------

If you have read through all of this, and you are now saying to
yourself, "This is way too much work...", that is fine, because Cga2Bmp
works well without the use of external palette files.

And as previously noted, commercially generated palette files including
the PaintShop Pro and NeoPaint Palette Files are also both supported,
for those who want custom colors but don't want to bother typing.

Appendix A - Packing List
-------------------------

Program Files
-------------

\WORKTOOL\CGA2BMP\CGA2BMP.EXE
\WORKTOOL\CGA2BMP\README.TXT
\WORKTOOL\CGA2BMP\FILE_ID.DIZ

Sample CGA Images
-----------------

\WORKTOOL\CGA2BMP\BEAR1.PCX
\WORKTOOL\CGA2BMP\BEAR2.PCX
\WORKTOOL\CGA2BMP\BEAR3.PCX
\WORKTOOL\CGA2BMP\CHURCH.BAS

Palette Files
-------------

GeoVu - Cga2Bmp Text Palette Files
----------------------------------

\WORKTOOL\CGA2BMP\GEOBLUE.PAL
\WORKTOOL\CGA2BMP\GEOGRAY.PAL

PaintShop Pro Text Palette Files
--------------------------------

\WORKTOOL\CGA2BMP\JASC16.PAL
\WORKTOOL\CGA2BMP\JASCBLUE.PAL
\WORKTOOL\CGA2BMP\JASCGRN.PAL
\WORKTOOL\CGA2BMP\JASCRED.PAL
\WORKTOOL\CGA2BMP\JASCWIN.PAL

NeoPaint (DOS and WINDOWS) Text Palette Files
---------------------------------------------

\WORKTOOL\CGA2BMP\NEO16.PAL
\WORKTOOL\CGA2BMP\NEOWIN16.PAL

Aldus PhotoStyler Text Files
----------------------------

\WORKTOOL\CGA2BMP\ALDUSWIN.PAL
\WORKTOOL\CGA2BMP\GOLD.CLR

Binary Palette Files
--------------------

\WORKTOOL\CGA2BMP\WINDOWS.ACT
\WORKTOOL\CGA2BMP\WINDOWS.CMP
\WORKTOOL\CGA2BMP\WINDOWS.PAL

Source Code
-----------

\WORKTOOL\CGA2BMP\SRC\CGA2BMP.C
\WORKTOOL\CGA2BMP\SRC\CGA2BMP.MAK

End of ReadMe
