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

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.


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:
<== 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