## 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]);
    gboolean            colorEqual_color                    (Color *color1,
                                                             Color *color2);
    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 beca use 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.

### colorEqual_color ()

    gboolean            colorEqual_color                    (Color *color1,
                                                             Color *color2);

Test if the two colours are the same.

`color1` : | a Color ;
`color2` : | an other Color.
Returns : | TRUE if the `rgba` attributes are the same.

### 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.