  SP Image -> Image convertor

Unfortunately this software does NOT support for:
   1. batch processing (*.ext)
   2. TTF rendering (this may be fixed in future ;))
   3. tonns of image formats
   4. OS/2 icon and bitmap formats(!!)
   5. 1,4 bit color formats (will be fixed)
   6. writing GIFs with global palette
   7. reading "optimized" animated GIFs (will be fixed)

Fortunately this software support for:
   1. Reading: 
      - BMP: 8 bit (plain & RLE), 15,16,24,32 bit, top-bottom/bottom-top.
      - PCX: 2,4,8,24 bit. (2,4 bit converting to 8 bit on load)
      - PNG: all (16 bit R,G,B components converting to 8 on load)
      - GIF: all
      - JPG: all, except CMYK (jpeglib 6)
      - TGA: all
   2. Writing: 
      - BMP: 8 bit (plain & RLE), 15,16,24,32 bit
      - PCX: 8,24 bit
      - PNG: 8,24,32 bit,grayscale,transparent color
      - GIF: all, transparent color, multipage
      - JPG: all, grayscale
      - TGA: all, grayscale (RLE compressed by default, but only if compressed
             data is smaller than uncompressed).
   3. Converting:
      - colors everything between 8,15,16,24,32 bits per pixel
      - resize images
      - adding constant alpha channel value
   4. Script engine:
      - C/C++ like syntax
      - many internal routines: creating images, direct access to the image
        buffer, converting, drawing lines/rectangles, blitting (with alpha
        channel support) and other...
      - capable of direct import of external functions, for ex.
            /* -- */
            extern "som.dll" name "somPrintf"
            int cdecl printf( char * __format, ...);
            /* -- */

Usage: alch <destin format> <source string> <destin file> [options]
       alch -s <script file> [options] [-a script arguments] - execute script
       alch -l <source file>  - list image contents
       alch -i <source file>  - detailed image info

   destination format:
       JPG[+][P][Cfmt][I/S/F][quality] -> write JPEG (default: "JPGS75")
          '+' - optimize on
          'P' - progressive
          'Cfmt - subsampling/format: fmt = RGB,Y41,Y42
          'I'/'S'/'F' - int/fast/float DCT
          'quality'   - 1..100
       GIF[7/9][+]               -> write GIF
          '+' - append if file exist
          '9' - write GIF89a (transparent tag, default)
          '7' - write GIF87a
       BMP[B][R][O]              -> write Windows Bitmap
          'B' - top-bottom (unsupported by most image readers)
          'R' - RLE bitmap (8 bit only, full "RLE" option analogue)
          'O' - OS/2 bitmap header
          BR options can be used together.
       RLE                       -> write RLE-compressed Windows Bitmap
       PCX                       -> write PCX
       PNG                       -> write PNG
       TGA[-][s/p][b][n]         -> write Targa bitmap
          '-' - do not pack with RLE
          'p' - write complete color palette
          's' - strip color palette top (highly not recommended - only Image
                Alchemy can correctly read this!)
          'b' - top-bottom
          'n' - do not write extended header
   source string:
       name[?image_index_in_file][%[convert_to_bpp][%transparent_color_to_set]]
       note: transparent_color_to_set is not RGB, but direct color value. Use
             -t for RGB.
   options (case sensitive):
       -c=x[,y]  - convert x pictures from pos y
       -ca       - convert all pictures in library
       -m=<destin file> - mask for multiple pictures (ex. out%d.pcx)
       -x=width   - resize to width
       -y=height  - resize to height
       -t=color   - set transparent color (RGB, ex. -t=0xFF00FF)
       -bg=color  - background color (RGB) to blit image with alpha channel to
       -a=value   - add constant alpha channel value
       -t         - remove transparent color
       -q         - be quiet
       -v         - write log and script dumps
       -g         - convert image to grayscale
       -fi{v,h}   - flip before processing (vert./horz.)
       -fo{v,h}   - flip output image(s) (vert./horz.)
       -pr        - proportional resize (for only -x or -y)
       -fp        - use fixed point scaling instead of float
       -fill      - fill instead of stretch (for -x,-y)
       -r=x,y,dx,dy[,step_x,step_y,count[,in_line]] - get source image rectange
       -cc=c1,c2  - change color c1 to color c2
       -cs=dx,dy,<direction>[,fill_color] - canvas size, dir.: S,W,NE,... & C
       -dith      - use dithering then convert Truecolor to 16 bit
       -lggif     - use logical image size then read gif
       -rtpitch   - allow image data with aligned line size (actual for scripts only)
       -si=script - execute script on input image(s)
       -so=script - execute script on output image(s)
       -i=dir     - additional include directory for scripts

   examples:
      alch jpg+pcy42f95 test.bmp test.jpg
        Read test.bmp and save it as optimized progressive JPEG with
        YUV422 subsampling, float DCT and quality=95

      alch tga- test.bmp test.tga -a=0x7F
        Read test.bmp, convert it to 32 bit image with alpha channel by 
        adding alpha value =127 and save it to uncompressed TGA

      alch png test.bmp%32 test.png -t=0xFFFFFF
        Read test.bmp, convert it to 32 bit image, set transparent color
        0xFFFFFF (white) and write to test.png (note: transparent tag in
        PNG does not supported by most image editors)

      alch gif test.bmp%8 test.gif -r=0,0,16,0,16,0,16
        Read test.bmp, convert it to 8 bit image and save 16 rectangles
        with size 16,16 and top left coordinates 0,0; 0,16; 0,32; .. 0,240
        as separate pages of output GIF image.
          
      alch rle test.bmp%8 mosaic.bmp -x=1024 -pr -fill
        Read test.bmp, convert it to 8 bit image, set size of output image
        to 1024xYYY (with keeping aspect ratio), fill it by test.bmp and
        save result to RLE compressed mosaic.bmp.
          
      alch tgabn test.bmp test.tga -g
        Read test.bmp, convert it to grayscale and save to top-bottom RLE 
        compressed TGA without extended (TGA 2.0) header.
          
      alch bmp test.gif -c=2 -m=test%2.2d.bmp
        Read multipage test.gif and save first two pages to separate
        BMP files test00.bmp and test01.bmp
         
      alch bmp test.gif?2%15 -m=test%2.2d.bmp -si=advproc.scr
        Read second page of test.gif, convert it to 15 bit image (555),
        process in script advproc.scr and save results to separate BMP files
        test00.bmp, test01.bmp... (script can handle number of output images
        (add or remove some)).

   Alch mean "tiny Alchemy". If Handmade Software will ask for change this
   name, i'll do it, but i'm too lazy to find another name now ;)

Script language:
   Please, note - script language is in the permanent alpha stage ;)
   Futures:

   1. C/C++ syntax.
   2. Full C preprocessor.
   3. Operation overload support (between standard types too).
   4. Classes (limited).
   5. "with" operator (pascal analogue - with(rec) {} ).
   6. Direct import of external functions. Supported calling conventions are:
      __cdecl, __stdcall, __fastcall, __pascal, __delphi (it can emulate ICC 
      _Optlink by using some hacks).

   Bugs & imcompatibilites:
   1. Local static variables in procedures are initialized at each entrance.
   2. func(void) != func().
   3. Const does not supported (ignored now).
   4. Type compatibility can be unstable of slighlty different.
   5. C-like structure declarations is not supported:
      struct KuKu *Var;
   6. Code can be written outside of function body too. It will be executed
      duaring initialization stage (initing gloabal variables & classes).

   About supported functions (see. include/alch.h):
   1. Creating 8,15,16,24,32 bpp image
   2. Converting between those formats.
   3. Drawing rectangles (with optional alpha transparency).
   4. Blitting images (with alpha channel support).
   5. Set/remove transparency.
   6. Direct access to image data.
   7. Creating alpha channel for image.
   8. Converting to grayscale.
   9. Flipping, scaling, brightness, replace colors.
  10. Creating images with external data (by suppling pointer & pitch).
  11. Text output by using:
      - bit fonts - in BIOS format (simple array with bit data).
      - a specially prepared bitmaps with letters:
        - simple bitmap
        - bitmap with alpha channel (for ex. letters with shadow)
        - grayscale 8-bit bitmap (colored output)

Can be implemented in future:
   1. more image formats
   2. TTF support
   3. VIO image viewer (for diskette boot)
   4. more script functions
   5. batch processing
   6. full animated GIF support (even with optimizer)
   7. PM image viewer

******************************************************************************
More script doc:
   There are two common image structures: IFF & IFC.
   Second is a first without internal memory block header.
   Some functions use IFF, some IFC - do not ask why ;) Use IFF2IFC/IFC2IFF to
convert between it.

   There is 2 modes:

   1. processing script via -si/so key while converting image (images).
       images located in
         PIFC *CvtImages;
       list with
         uint   CvtCount;
       entries.
     You can call ExtendImageList() to extend list and set CvtCount to 
     another values. Images can be free via free() routine.

   2. simple script processing without any image processing.
      Also, "main" function called, if it available in script, and arguments
      for it can be passed in alch.exe command line, after -a key

      You can also can load images manually by
        ihlpcLoadPic(char *name);
      function. BUT, if you planning to change it, you must make a unique
      copy first via
        memDup(void *M);
      call. The reason for this is a strange and buggy internal cache system ;)

   There is a lack of any docs, sorry ;)
   So, read alch.h and enjoy ;) Function names are commonly self-explaning...

   How to register fonts:

   * 0;name;ttt.bmp;dX;dY;dMX;dMY;StartX;StartY;Count;FirstChar;CharCount;Color;CodePage;
     register 8bit (ONLY!!!) bitmap font ttt.bmp:
      name          - font name (for info & search)
      dX/dY         - char width/height
      dMX/dMY       - char x/y step (in bitmap)
      StartX/StartY - start pos (in bitmap)
      Count         - number of chars in one line (in bitmap)
      FirstChar     - first char ASC code
      CharCount     - numbers of chars (1..256)
      Color         - font color (info only)
      CodePage      - font codePage (info only - codepages are unsupported now)
     example:
      0;Classic;font8x16.gif;9;16;32;16;0;0;16;0;256;0xF7CE04;866

   * 1;name;pp.dat;x;y;FirstChar;CharCount;CodePage
     register bit array font pp.dat:
      name          - font name (for info & search)
      x/y           - char width/height
      FirstChar     - first char ASC code
      CharCount     - numbers of chars (1..256)
      CodePage      - font codePage (info only - codepages are unsupported now)
     example:
      1;Roman;ROMAN.FNT;8;16;0;256;866

   * 2;name;pp.tga;Size;Start;Count;Spacing;Space width;Color;CodePage
     register full alpha channel font pp.tga:
      name          - font name (for info & search)
      Size          - font height
      Start         - first char ASC code
      Count         - numbers of chars (1..256)
      Spacing       - default spacing
      Space width   - space character width
      Color         - font color (info only)
      CodePage      - font codePage (info only - codepages are unsupported now)
     example:
      2;huge64;font64.png;64;33;94;1;20;0x0000FF;437

   * 3;name;pp.gif;Size;Start;Count;Spacing;Space width;Color;CodePage
     register 256 gray level font pp.gif:
      name          - font name (for info & search)
      Size          - font height
      Start         - first char ASC code
      Count         - numbers of chars (1..256)
      Spacing       - default spacing
      Space width   - space character width
      Color         - font color (default info value, can be changed in iFntSet)
      CodePage      - font codePage (info only - codepages are unsupported now)
     example:
      3;New Gothic;newgoth24.png;24;33;94;0;10;0xFFFF00;437

   Some tips for font using:
   - iFntSet.Color can be used for types 1 & 3
   - font type 1 is monospaced by default, any other - proportional by default
     Letter width determined automatically:
     - type 0 - by image transparent color
     - type 1 - by bits
     - type 2 - by alpha channel (full transparent column == end of letter)
     - type 3 - by 0 pixel values (zero column == end of letter)
     The main problem for types 2 & 3 - fully transparent column between
     ' & ' in " ;) It must be filled with some sightly visible pixels.
     
