Overview
--------

   With color functions you can define a rgb value to a color index 
   from 0 to 255, or access some color indexes via color names.

   If you want to get a random color index, you may use following code:
     int color;
     color=(int)(256.*rand()/(RAND_MAX+1.));
     // now color has a random number from 0 to 255



The functions
-------------


int load_colormap(const char * arg1):
   load another colormap, replacing the former loaded one.
   A colormap defines 256 color indexes to special r,g,b values.

   (The pixels of all graphics keep the color index they had before,
    which therefore could result in another color value.
    E.g. a pixel of color index 5 had with the old colormap r,g,b=10,10,10
         and now color index is r,g,b 20,30,50, then the pixel has now
         the new color 20,30,50
   )
   
   Arguments:
    - arg1: path to colormap file
            or RGB256=default colormap
            or GREY256=grey colormap
            or NULL=same colormap as before

   Return value: 0=OK
                 -1=error

   Note: When opening the window the default colormap is loaded, you
         need not call this function.

         With vgagames are included the default colormap and a grey colormap,
         if you want to use another one, you have to create one.

         The format of a colormap file is as following:
           "color index" = "Red" "Green" "Blue" 
         where "color index" is a unique value from 0 to 255
               "Red", "Green", "Blue" are the red, green and blue
                 components of this color index as values from 0 to 63.
         e.g. for white:  1=63 63 63
              for black:  0=0 0 0
              for yellow:  123=63 63 0
         The lightest pixel color is used for RGB_WHITE.
         The darkest pixel color is used as transparent pixel (RGB_BLACK).
         The darkest pixel color next RGB_BLACK (RGB_DARK) can be used as
         a nearly black color without being transparent.

         With the program "vgag-bitmap" you can display the colormap
         of a graphic file in the format of a colormap file.
         

   Example:
     // load default colormap and adjust pixels
     if (load_colormap(RGB256)==-1) { [...error...] }
     // load self created colormap
     if (load_colormap("/path/mycolormap")==-1) { [...error...] }




void brightness(int arg1):
   reduces or increases brightness of the loaded colormap.

   Arguments:
    - arg1: value from -63 (darkest) to 62 (lightest)
            where 0 is the default (original brightness of colormap)

   Example:
     int i1;
     for (i1=0;i1>=-63;i1--) {  // make more and more darker
       brightness(i1);
       flush_window();
       wait_time(70);  // wait up to 70 ms
     }




int color_index(int arg1,int arg2):
   gets best color index of a color name

   Arguments:
    - arg1: color name as CL_-definition (see below)
    - arg2: color brightness percent: value from 0 to 100

   Return value: best color index according to loaded colormap

   Note: there are following color names:
         CL_RED             = red
         CL_REDORANGE       = red orange
         CL_ORANGE          = orange
         CL_YELLOWORANGE    = yellow orange
         CL_YELLOW          = yellow
         CL_YELLOWGREEN     = yellow green
         CL_GREEN           = green
         CL_TURQUOISEGREEN  = turquoise green
         CL_TURQUOISE       = turquoise
         CL_TURQUOISEBLUE   = turquoise blue
         CL_BLUE            = blue
         CL_BLUEVIOLET      = blue violet
         CL_VIOLET          = violet
         CL_REDVIOLET       = red violet
         CL_PINK            = pink
         CL_BROWN           = brown
         CL_WHITE           = white (same color as RGB_WHITE)
         CL_BLACK           = black (same color as RGB_BLACK)

   Example:
     int c;
     // get best color index of color name "red" at 70% brightness
     c=color_index(CL_RED,70);
     draw_pixel(NULL,0,0,c);  // draw (slightly dark) red pixel to 0,0