PicO v1.3 Dox
-------------


INTRODUCTION:
-------------
This tool was made for optimizing crunch results on koala pictures.
Thats made possible by removing pixels that have the same colors as
the backgound color ($d021) and rearranging the color information in
the color maps. Afterwards you will need to plot colors in the unused
spots to force equal bytes follow each other. (Thats the tiresome part,
but that will also make your packer/cruncher do a better job.)
...
The size of the savefile will be the same as the loadfile.
Some editors dont use the last byte (d020/d021 color) in the koala picture.
So filesize will bet either $2710 or $2711 depending on your input file.
Your loadaddress doesn't matter as long as the filesize matches one of the above.
When saving complete pictures PicO will save files to $8000.
Alternative save methods will save to $6000.


BEFORE YOU START:
-----------------
After loading a koala picture you must make sure that $d021 has the right color.
Press CBM+K to kill all unused bits, use the $d021 color as kill bit color.
Now you can start sorting.

(Note: Killing or Sorting bits with wrong $d021 color can result in loss of 'visible' bits in bitmap.
 Reason: Killing unused bits are checked against the colors used in colormaps and the value of $d021.)


STUFF ON SCREEN:
----------------

+---------------------------+
|             D             |
|             E             |
|   ABC       FG            |
|  +---------------------+  |
|  |                     |  |
|  | H                   |  |
|  |                     |  |
|  |      Screen         |  |
|  |                     |  |
|  |                     |  |
|  |                     |  |
|  |                     |  |
|  +---------------------+  |
|     border   I            |
|                           |
+---------------------------+

A : Bit combination for sort
    1 = sort color to high nybble of Char Color (0400-07e8)
    2 = sort color to low nybble of Char Color (0400-07e8)
    3 = sort color to Ram Color (d800-dbe8)
B : Color to sort is displayed in this square.
C : Current Display mode (0-4)

D : current color for char high nybble
E : current color for char low nybble
F : current color for ram color (d800)

G : (Zoom) Cursor char position in bitmap is displayed in this square.
H : Cursor
I : X and Y position for cursor

Screen: Toggles 5 display modes. Uses $d021 as background color.

Border: Uses $d020 as border color.


SETTING MARKS:
--------------
Use the Return key to set start position, then use the cursor keys 
to set the size of the square. That square will be the area you are marking.
Sorting or killing bits will only happen inside that square.
At this point you can do three things:
1) Press Return to get into the sort color or kill bits menu.
2) Press Shift+Return to sort colors into the values displayed in (A) and (B) or
3) Press Run/Stop to disable square mark.


SORT COLOR MENU:
----------------
(Preperations: Mark an area then press Return. Then select S for Sort.)
Select the color you want to sort by pressing A-P.
Then select which nybble you want to sort this color into.


KILL UNUSUED BITS & COLORS MENU:
--------------------------------
(Preperations: Mark an area then press Return. Then select K to kill.)
Select which nybbles of the marked area to kill by pressing 1-3 (default setting is all on).
Then press return.
Next select your kill color (Best thing would be to use the $d021 color).


EDITOR KEYS:
------------
Left arrow    Display area for dump mode.
1             Display Char Color high  (high nybble of Char Color - %11110000)
2             Display Char Color low   (low nybble of Char Color - %00001111)
3             Display Ram Color (d800) (RamColor has low nybble only - %00001111)
4             Display Bitmap
* and Z       Plot color for selected bit (1-3)
Space         Sort char under cursor using top left screen options.
              In dump mode (0) spacebar will clear marked chars.
Return        Set start mark
Return        Set end mark and jump to sort area menu/kill area menu
SH+Return     If you have you have selected start mark, you can sort
              a color using the bit combination displayed in the top left corner.
              
SH+L          Load menu - Only Koala pictures can be loaded.

SH+S          Save menu - This will save all your work on the picture.
              The save menu will display "PICTURE SAVE NAME:"
              
SH+S          Alternative save mode 1 - If you have started marking an area of the 
              picture, you can save this area by pressing SHIFT+S
              The save menu will display "MARK SAVE NAME:"
              The data saved will be char area, color ram area, bitmap area.
              You need to keep track of x and y pos yourself.
              
SH+Run/Stop   Return to basic
CBM + K       Kill unused bits.
CBM + O       Copy Original picture to workram and undo buffer
CBM + U       Undo (Copy undo buffer to workram)
CBM + X       Update undo buffer (Copy workram to undo buffer - 
              Use this when you are happy with the changes)
              (Border turns red for a split second.)
A             Select all.
D             Display color info.
Run/Stop      Abort mark (Can also be used to exit all sub-menu's)
ClrHome       Cursor top left
CRSR          Move cursor
CBM+CRSR      Fast Move cursor
CTRL + 1-8    Set sort color ($00-$07)
CBM + 1-8     Set sort color ($08-$0f)
SH + 1        Set (1) sort color to Char Color high nybble
SH + 2        Set (2) sort color to Char Color low nybble
SH + 3        Set (3) sort color to Ram Color
F1            Swap color 1 with color 2 (Char high <> Char low)
F3            Swap color 2 with color 3 (Char low  <> Color ram)
F5            Swap color 3 with color 1 (Color ram <> Char high)
F7/F8         Set background color ($d021)
+/-           Set border color ($d020)
?/H/I         Help page
C             Color pick - pick color under cursor (mode 1,2 and 3 only)
Joy#2 Move    Controls the cursor.
Joy#2 Fire    Plot color for selected bit (1-3) / Plot Dump mode color (0)


ALTERNATIVE SAVE MODE:
----------------------
(See dump mode below for special saving on several marked areas.)
You can also save out a square of the picture. 
Use the Return key to set the start mark and then use the cursor keys to 
set the size of the square, when done press SHIFT+S to save. 
The save screen will pop up and the letter box should read : "MARK SAVE NAME:"
This type of save can only be done outside the DUMP mode and with the mark square on.
You need to keep track of X width and Y height yourself.
The data saved will be colors for char map, followed by colors for rom color, and at the
end is the bitmap data.


DUMP MODE - DISPLAY AREA FOR DUMP SAVE
--------------------------------------
Another special save mode.
Normally this screen is just black.
You will only want to use this mode if you want to save out selected
parts of the picture. (Or to see exactly which chars of the bitmap is unused.)
The mode for this screen is represented by the number zero '0' in spriteinfo.
Many key functions are left out when working in this mode.
What you can do here is to mark several different areas of the picture
and save it into one file. Useful for bitmap animations, or for games
which have equal graphics in several pictures - just save out the differencens 
and depack them back - and you save disk memory.
Marking several areas can be done with plotting the chars you want with Z or *,
fire button or use the square mark function.
When done press SHIFT+S to save (And you must be in the dump screen).
After pressing SHIFT+S you will see the save screen and the letter box
should read :"DUMP AREA SAVE NAME:"

The source code included ("depack.tas") can be used to depack the saved file.

Keys to use:

A             Mark all
Return        Set start mark
Return        Set end mark, then mark area with the mark on color (green)
SH+Return     Set end mark, then clear area with mark off color (black)
M             Mark area vs bits used in bitmap. Start mark must be set first.
* and Z       Plot (mark on color)
SPACEBAR      Delete (mark off color)
SHIFT+S       This will take you to the dump area save screen.
              See depack source code on how to handle a dump file.

Hint:         Press A then M. Now you will see what area of the bitmap that 
              is used in chars. Green chars are used by bitmap, the black
              chars are unused. Use it against the other 3 modes.
              
              Also remember this : The 'M' function might skip chars
              if you havent runned CBM+K on the picture. This depends on pixels
              in the bitmap having the same color as $d021. 
              Always use CBM+K the first time you start sorting a new picture.




LOAD MENU KEYS:
---------------
CRSR Up/Down  Select file
Return        Load file
Space         Load new directory
ClrHome       To the top
Run/Stop      Exit to editor

Only files with Koala picture filesize of 40 blocks will be displayed.



SAVE MENU KEYS:
---------------
Keys          Type in savename
Run/Stop      Exit to editor
Return        Save file (needs atleast one letter in filname to save)




How kill bits works:
--------------------
It takes the color of the background picture and compares it with
colors in the char color map and color ram map. If a identical color
to the background is found the routine will earase the bits of
that bit combinatinon. 
It is important that you have the correct background color selected.
You may change the background color to look for hidden bits in the bitmap,
some are hard to spot, some are not (Ie. the game Exile has a hidden message in the bitmap.)

Special sort color issue:
-------------------------
If you do a sort on black, and theres 2 or 3 black colors
in that bitmap position. 1 or 2 of the colors will turn white.
If this happens, run the kill bit routine on that area or use
the plot color function to set a color you would like.


How to get better crunch results:
---------------------------------
Char color consists of a low nybble and a high nybble, to get good
results you will need to sort those into equal byte sequences.
For instance: $89,$89,$89,$89,$89,$89....

Color Ram only uses the low nybble and is much easier to sort
for good results, again you need to sort those into equal byte sequences.
For instance: $01,$01,$01,$01,$01 ...

The sort steps:
1) Kill all unused colors with the color of the background ($d021)
   (that will make the screen easier to look at).
2) Press D to see color info.
3) Sort the color(s) most used into the Ram color.
4) Sort the char colors into equal byte sequences.
5) Kill all unused colors again - In case the special sort issue happend.
6) Use the plot color function to plot in colors in the unused colors.

Look at the files "arcticfox orie" and "arcticfox sorted" 
to see how it should be done.
If you sort it good you can save several hundred bytes, you might
not gain much on advanced bitmaps with lots of color combinations 
and pixel information.  But you WILL gain some. I always did.


crunch result:
exomizer -r "articfox orie" -o "articfox orie.exo" : 2712 bytes
exomizer -r "articfox sort" -o "articfox sort.exo" : 2087 bytes

A difference of 625 bytes, thats 3 blocks saved on a disk.

Need I say more ? :)


CREDITS:
--------
PicO(ptimzer) v1.3 (tm)
Programmed by 6R6/Nostalgia 2003-2007

Inspiration from:
Bit'n color sort (c) 1991 Spirit