## toolColor

toolColor — Simple handling and storage of RGBA colours.

## Synopsis

    void        initColorStorage                ();
    Color*      colorNew_floatRGBA              (float rgba[4]);
    void        colorCopy_color                 (Color *color,
                                                 Color *color_old);
    Color*      colorAdd_color                  (Color *color);
    Color*      colorAdd_floatRGBA              (float rgba[4],
                                                 int *position);
    Color*      colorAdd_intRGBA                (int rgba[4]);
    GList*      colorGet_storedColors           ();
    Color*      colorGet_lastStored             ();
    int         colorGet_byColor                (Color *color);
    Color*      colorGet_byId                   (int num);
    Color*      colorGet_byValues               (int *pos,
                                                 float red,
                                                 float green,
                                                 float blue,
                                                 float alpha);
    void        color_HSLtoRGB                  (float *rgb,
                                                 float *hsl);
    void        color_HSVtoRGB                  (float *rgb,
                                                 float *hsv);

## Description

This file defines a basic structure to store colours (not using the GDK one because V_Sim core should not rely on GDK and GTK): Color. Several transformations are possible on a colour, going from and to RGB encoding. Use `color_HSVtoRGB()` and `color_HSLtoRGB()` to do that.

This file gives also the capability to store known colours in a list. Use methods such as `colorAdd_color()` or `colorAdd_floatRGBA()`. Them, one can access to stored colours, using `colorGet_byValues()` or `colorGet_byColor()`.

## Details

### initColorStorage ()

    void        initColorStorage                ();

This method must be called once at the beginning of the program, if you want to use the color storage system.

### colorNew_floatRGBA ()

    Color*      colorNew_floatRGBA              (float rgba[4]);

Create a new color with initial values given as arguments.

`rgba` : | four values between 0. and 1. that represent [Red, Green, Blue, Alpha].
Returns : | a new allocated `Color`.

### colorCopy_color ()

    void        colorCopy_color                 (Color *color,
                                                 Color *color_old);

This method copies all values from `color_old` to `color`.

`color` : | an allocated Color object to receive values ;
`color_old` : | a Color to read the values from.

### colorAdd_color ()

    Color*      colorAdd_color                  (Color *color);

This method copies color informations from `color` to the list of stored colors.

`color` : | a `Color`.
Returns : | 0 if everything is OK.

### colorAdd_floatRGBA ()

    Color*      colorAdd_floatRGBA              (float rgba[4],
                                                 int *position);

This method adds a new color in the list of stored colors with the given values. If it already exits it returns the pointer of that color.

`rgba` : | four values between 0. and 1. that represent [Red, Green, Blue, Alpha] ;
`position` : | an int pointer to store the position off the returned colour.
Returns : | a pointer to the color.

### colorAdd_intRGBA ()

    Color*      colorAdd_intRGBA                (int rgba[4]);

This method adds a new color in the list of stored colors with the given values.

`rgba` : | four values between 0 and 255 that represent [Red, Green, Blue, Alpha].
Returns : | 0 if everything is OK.

### colorGet_storedColors ()

    GList*      colorGet_storedColors           ();

Use this method to get a pointeur to the list of stored colors.

Returns : | a GList pointer to the stored colors.

### colorGet_lastStored ()

    Color*      colorGet_lastStored             ();

This method is typiccally called after a client has catched the colorNewAvailable signal.

Returns : | the last added color, NULL if no color exists.

### colorGet_byColor ()

    int         colorGet_byColor                (Color *color);

This function retrieves the number (begining at 0) of the specified color.

`color` : | a pointer to a stored color.
Returns : | the position of the specified color or -1 if not found.

### colorGet_byId ()

    Color*      colorGet_byId                   (int num);

This function retrieves the nth stored color. Number 0, is the last added color.

`num` : | an integer (>0).
Returns : | the corresponding color, or NULL if none has been found.

### colorGet_byValues ()

    Color*      colorGet_byValues               (int *pos,
                                                 float red,
                                                 float green,
                                                 float blue,
                                                 float alpha);

This method is used to look for a specific color in the stored list. The argument `pos` is -1 if nothing is found or stores the position (beginning at 0) of the found color.

`pos` : | an allocated int to store the position of the found color ;
`red` : | a value between 0. and 1. ;
`green` : | a value between 0. and 1. ;
`blue` : | a value between 0. and 1. ;
`alpha` : | a value between 0. and 1..
Returns : | the found color, or NULL if none exists.

### color_HSLtoRGB ()

    void        color_HSLtoRGB                  (float *rgb,
                                                 float *hsl);

This methods convert a HSL color to a RGB one.

`rgb` : | an allocated 3 elements array to receive the RGB values ;
`hsl` : | a 3 elements array to retrieve the HSL values from.

### color_HSVtoRGB ()

    void        color_HSVtoRGB                  (float *rgb,
                                                 float *hsv);

This methods convert a HSV color to a RGB one.

`rgb` : | an allocated 3 elements array to receive the RGB values ;
`hsv` : | a 3 elements array to retrieve the HSV values from.