Intro: understanding colormap
=============================

VgaGames uses 256 colors.
You may change the colormap while your game is running, but this change
is global and changes the colors of all shown graphics.


The colormap-files

Under the VgaGames-install-directory /usr/share/vgagames
are installed default colormaps:
 - rgb256.clm
 - grey256.clm
If your game wants to use another colormap, put it into your local
subdirectory "share/" of your game. Loading a colormap with vg_load_colormap()
at first searches your local subdirectory and then the
VgaGames-install-directory.


Format of a colormap-file

A colormap-file consists of 256 lines, each of format:
  "indexnumber" = "red-value" "green-value" "blue-value"
where "indexnumber" is a number from 0 to 255
and the color-values a number from 0 to 63.
The value 63 instead of 255 seems to be a bit strange. But internally
these values are multiplied with 4, so the range is really from 0 to 252.
Each colormap-file must end with ".clm".


Accessing a color

Now every bitmap or function using colors in fact use a color-index, that is
the "indexnumber" of the current colormap-file.
When you e.g. draw a pixel with color-index 17, then the actual color is
taken from the current colormap
  with e.g.:   17=63 0 0
  which means: draw a red pixel.
If you load another colormap, which has:  17=63 63 0
then the pixel will become yellow at once.


Colormaps of bitmaps

Every bitmap file has an internal colormap, which may differ from the
current loaded colormap. When the bitmap is loaded from a file with
vg_bitmap_createfromfile(), the color-indexes of the bitmap
are converted to the current loaded colormap as good as possible.
When then a new colormap is loaded, no new conversion will be done with
already loaded bitmaps, the indexnumbers don't change, but refer now to
another color.
For example:
  bitmap b1.vga uses for indexnumber 17 a value of "63 0 0".
  The current loaded colormap doesn't have value "63 0 0", but
    28=48 5 0
  seems to be the best replacement.
  So indexnumber 17 of b1.vga becomes indexnumber 28 when loaded.
  When then another colormap is loaded,
    with e.g.:  28=34 0 49
  b1.vga's indexnumber 28 remains, but refers now to color: 34 0 49.


Colornames

Sometimes you don't want to know, which indexnumber has a certain color
and which colormap is currently loaded. You just want to draw a yellow
pixel, or a pixel as yellow as possible.
For this reason there are some predefined colornames:
==>
  CL_RED
  CL_REDORANGE
  CL_ORANGE
  CL_YELLOWORANGE
  CL_YELLOW
  CL_YELLOWGREEN
  CL_GREEN
  CL_TURQUOISEGREEN
  CL_TURQUOISE
  CL_TURQUOISEBLUE
  CL_BLUE
  CL_BLUEVIOLET
  CL_VIOLET
  CL_REDVIOLET
  CL_PINK
  CL_BROWN
  CL_WHITE
  CL_BLACK

<==
To get their actual best indexnumber, use vg_color_index().
For white and black there are also "RGB_WHITE" and "RGB_BLACK", which are
already indexnumbers, so using vg_color_index() with CL_BLACK
returns RGB_BLACK.


Transparent pixels

Pixels with color-index RGB_BLACK can be used as transparent pixels.
If you copy a bitmap to the window or another bitmap with vg_bitmap_copyto(),
then these pixels are not copied when using flag "RGB_TRANS".
- RGB_BLACK pixels have the lowest red/green/blue value, e.g. "0 0 0".
- RGB_WHITE pixels have the highest red/green/blue value, e.g. "63 63 63".
There is another indexnumber "RGB_DARK", which refers to the pixels
with the second lowest red/green/blue value, but which are never used 
as transparent pixels.


Brightness

Red is not only red. "63 0 0" is brighter than "31 0 0", but both are red.
With function vg_brightness() you can change
the brightness of the current loaded colormap.



FUNCTIONS

vg_load_colormap()
vg_color_index()
vg_brightness()

Back to Index