Welcome to SHAWN'S DANDY PALETTE EDITOR!

------------------------------------------------------------------------------
INTRODUCTION
------------------------------------------------------------------------------

This utility is used to make 256 color palettes for vga and svga 256 color
graphics modes.  It allows you to create dazzling palettes in a speedy, user
friendly manner.  Shawn's Dandy Palette Editor is FREEWARE, so copy it to any
one you like.  The following documentation will try to explain the palette 
editor's wonderful features, how to use them, and how to incorporate the 
results into your own works.  Please read on...

------------------------------------------------------------------------------
DISCLAIMER
------------------------------------------------------------------------------

This product is freeware and must be distributed AS-IS.  I do not take
responsibility for any kind of damage this product may cause.  It works fine 
on my computer, and I hope it works fine on yours.  You can't sue me if
anything screws up while you are using my utility.  There is no warranty or
guarantee so use at your own risk.

------------------------------------------------------------------------------
DISTRIBUTION
------------------------------------------------------------------------------

Please distribute this utility as much as you like to anyone you like.  But, 
please distribute it AS-IS.  So don't change anything in the files.  Also
if you are going to distribute this utility, the following files must
be present, in their original forms:

EDITPAL.EXE
EDITPAL.DAT
EDITPAL.TXT

If you wish to add files to the utility, please keep them seperate from the 
files shown above.

------------------------------------------------------------------------------
FEATURES
------------------------------------------------------------------------------

Shawn's Dandy Palette Editor boasts a hefty dose of fully functional palette
editing capabilities, including:

- a user friendly mouse oriented environment!
- Duel Color Editing allows you to edit two colors at once!
- RGB slide rules to create colors FAST!
- a gradient button to make colorful blends between colors!
- palette rotation!
- Save, Load, hell you can even quit!!
- a clear button to clear portions of the palette!
- Cut and paste groups of colors!
- quick access buttons including BLACK, WHITE, INVERSE, and EXCHANGE!
- increase/decrease intensity for all intents and purposes!
- As well as many others!

------------------------------------------------------------------------------
HOW TO / HELP
------------------------------------------------------------------------------

Enough boasting, let's get on with the show!

Hopefully everything is more or less self explanatory.  I will assume you have
a basic knowledge of palettes in VGA modes.  Right!

Selecting a color:
To select a color, click on the palette bar and drag the pointer to the 
appropriate color.  To select a color for Color B click the right mouse
button and click the left mouse button for Color A.  All other buttons,
slides, and arrows are activated with the left mouse button.  A pointer at
the top of the palette bar shows your location on the palette.  Also, above
the large colored box that displays the current color is a box displaying the
current color number.  It can range from 1 to 254.  On either side of this box
is an arrow which will increase or decrease the color by one.  Both Color A
and Color B work exactly the same.

Editing a color:
Once you have selected a color using either the palette bar or the arrows
beside the color's number box, you will want to edit the color.  Changing the
red, green, and blue components of the color is easy.  Three slide rules are
set beside the large color box.  Each slide rule edits a different component
specified by the letter beside the rule (R, G, or B).  The box on the other
side of the rule displays the component's intensity, which may have a value
of 0 to 63.  To change a component's intensity, drag the pointer along the
rule to increase or decrease the intensity.  Reapeat this for the other two
components, and voila!  You have created a color.

Creating a Blend:
Select a color for Color A and B.  edit the color's components to your liking,
and click the button labeled BLEND A TO B.  a smooth gradient will result
between the two selected colors.

Altering the Color Intensity:
If a color is too dark or too light, you can increase or decrease the gamma
(or brightness) of a color by clicking the fade arrows.  They are located in
a vertical manner beside the color component boxes.  click the up arrow to
increase the intensity, and click the down arrow to decrease the intensity.

Rotating the palette:
Two arrows on either side of the palette bar rotate the palette without
moving the color pointers.  Click the left arrow to rotate the palette left
and click the right arrow to rotate the palette right.  This is a neat
feature but I'm not sure when you'd use it.

Moving color groups:
Let's say you've made a beautiful gradient but it's not where you want it on
the palette.  You can move this gradient to a more fitting spot on the palette
by placing the color pointers at either side of the color group you want to
move.  Then hold down the Shift key and click on the color group.  Drag it to
the desired spot and let go of the mouse button and shift key.  Also, If you
want to fine-tune the placement of the color group, hold down the shift key
and click the rotate palette arrows on either side of the palette bar.  This
produces the same results.

Other useful buttons:
These buttons are found at the top of the screen.
  BLACK : sets the RGB components to 0 for the selected color.
  WHITE : sets the RGB components to 63 for the selected color.
  INVERSE : inverts the selected color's RGB components.
  XCHANGE : exchanges color A's RGB components with color B's RGB components
            without moving the color pointers.
  COL A : copies color B's RGB components to color A.
  COL B : copies color A's RGB components to color B.
  CLEAR : sets all colors between color A and color B, inclusive, to black 
          (R=0, G=0, B=0).  It is found at the bottom of the screen.

Saving a palette:
Once you have made a palette you will want to save it.  Click the SAVE button
at the bottom of the screen.  A box will appear titled SAVE.  if this is the
first time you have saved a document the file name will be NONAME.PAL.  Delete
the file name by pressing backspace and enter your palette's name.  if you
do not put a .PAL at the end of your file name the program will append one
on for you.  Press ENTER to save, or ESC to cancel.  Notice in the bottom
left corner of the screen is the current file name.  If a * appears beside
the name, it means you have not saved the palette since you changed it.

Loading a palette:
To load a palette, click the LOAD button at the bottom of the screen.  A box
will appear titled LOAD.  It lists all the files with a .PAL extension and
allows you to pick one using the up/down arrow keys.  press ENTER to select,
and ESC to cancel.

Online Help:
Click the HELP button at the bottom of the screen to get online help.
The Help button simply loads up the HELP part of this file, and allows you to 
browse it.  Three buttons line the bottom: UP, DOWN, EXIT.  I think you can 
figure them out.  Also you can use the up/down arrow keys and page up and
page down to browse.  click the EXIT button or press escape to return to 
the palette editing screen.

------------------------------------------------------------------------------
INCORPORATING THE PALETTE
-----------------------------------------------------------------------------

This part is a snap.  the palette is saved with the color's RGB components
from 0 to 255 saved in the order: R(0) G(0) B(0) R(1) G(1) B(1) R(2) G(2), etc.
to load the palette, declare an array like such:

char palette[768]; /* that was tough */

Then load it up with the following function:

int loadpalette (char name [])
{  
  FILE *fileptr;
  if ((fileptr = fopen (name, "rb")) == NULL) return(-1);
  fread (palette, sizeof (palette), 1, fileptr);
  fclose (fileptr);
  return(0);
}

After loading it from disk, you've got to tell the VGA card to use your
palette.  This code does just that:

void set_palette (void)
{
  struct REGPACK reg;
  reg.r_ax = 0X1012;
  reg.r_bx = 0;
  reg.r_cx = 256;
  reg.r_es = FP_SEG (palette);
  reg.r_dx = FP_OFF (palette);
  intr (0x10, &reg);
}

Here are the same functions in Pascal:

Var
  Palette : Array[1..768] of Byte;

Procedure LoadPalette (Name : String);

  Var
    Fp : FILE of Byte;
    ErrorCode : Integer;

  Begin
    Assign (Fp, Name);
    {$I-}
    Reset (Fp, 1);
    ErrorCode := IoResult;
    {$I+}
    If ErrorCode = 0 Then begin
      BlockRead (Fp, Palette, SizeOf (Palette));
      Close (Fp);
    End;
  End;

Procedure SetPalette;

  Var
    Reg : Registers;

  Begin
    Reg.ah := $10;
    Reg.al := $12;
    Reg.bx := 0;
    Reg.cx := 255;
    Reg.es := seg (Palette);
    Reg.dx := ofs (Palette);
    Intr ($10, Reg);
  End;

Pretty easy, eh?

------------------------------------------------------------------------------
HOW TO REACH ME
------------------------------------------------------------------------------
There are two ways to reach me: by mail, or (preferred) by e-mail.

my e-mail address is:

hotpulp@netidea.com

my mailing address is:

Shawn Betts
RR#3 S-36 C-9
Nelson, B.C. V1L 5P6
CANADA

Drop me a line, and tell me what you think.

This program is FREE, however if you see this program worthy of a donation, by
all means send me whatever you feel is fit and I will gladly accept it.  Just
mail your donations to the above address.  Check or money order is most
likely the safest.

I hope you will find this program useful.  If you do end up using it in one of
your programs I would greatly appreciate it if you gave credit to me somewhere
in the documentation.  Thanks.

Shawn Betts.
