NAME
====
  vg_load_colormap() - load a colormap


SYNOPSIS
========
  int vg_load_colormap(const char * clm, char * vclm, size_t vlen)


DESCRIPTION
===========
  Loads a colormap from the VgaGames-install-directory /usr/share/vgagames
  or from the local directory share/ of your game.

  As in Understanding colormap mentioned, the color of a pixel
  is defined via a color-index, which refers to an entry to the actual colormap.
  When another colormap is loaded, the color-index may reference to another
  color, which results in a global change of the colors.

  E.g. the color-index 28 refered in the first colormap to: 10 0 10,
  but in the second colormap to: 45 30 0,
  then all pixels with color-index 28 of all current bitmaps change their
  color from 10 0 10 to 45 30 0.

  The argument clm is the filename (without path) of the colormap
  to be loaded or just RGB256 for the shipped default colormap
  or GREY256 for the shipped default Grey-colormap.
  At first this file will be searched in "share/" of your game, then
  in the VgaGames-install-directory "/usr/share/vgagames".

  The argument vclm is an address to a buffer to which the function
  returns the previous loaded colormap-file for restoring purposes
  or it is just NULL.
  The function does not write more than vlen characters into vclm
  (including the trailing '\0').


RETURN VALUE
============
  If it succeeds, it returns 0.
  If an error occurs, it returns -1, giving out an error message to stderr.


SEE ALSO
========
  Index
  Understanding colormap
  vg_color_index()
  vg_brightness()