## toolColor

toolColor — Simple handling and storage of RGBA colours.

## Synopsis

    #define             TOOL_COLOR_MASK_R
    #define             TOOL_COLOR_MASK_G
    #define             TOOL_COLOR_MASK_B
    #define             TOOL_COLOR_MASK_A
    #define             TOOL_COLOR_MASK_RGBA
                        ToolColor;
    ToolColor*          tool_color_new                      (float rgba[4]);
    gboolean            tool_color_equal                    (ToolColor *color1,
                                                             ToolColor *color2);
    void                tool_color_copy                     (ToolColor *color,
                                                             ToolColor *color_old);
    void                tool_color_freeAll                  (void);
    ToolColor*          tool_color_getById                  (int num);
    ToolColor*          tool_color_getLastStored            (void);
    int                 tool_color_getByColor               (ToolColor *color);
    ToolColor*          tool_color_getByValues              (int *pos,
                                                             float red,
                                                             float green,
                                                             float blue,
                                                             float alpha);
    GList*              tool_color_getStoredColors          (void);
    ToolColor*          tool_color_addColor                 (ToolColor *color);
    ToolColor*          tool_color_addFloatRGBA             (float rgba[4],
                                                             int *position);
    ToolColor*          tool_color_addIntRGBA               (int rgba[4]);
    void                tool_color_convertHSVtoRGB          (float *rgb,
                                                             float *hsv);
    void                tool_color_convertHSLtoRGB          (float *rgb,
                                                             float *hsl);
    void                tool_color_convertRGBtoHSL          (float *hsl,
                                                             float *rgb);

## 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): ToolColor. Several transformations are possible on a colour, going from and to RGB encoding. Use `tool_color_convertHSVtoRGB()` and `tool_color_convertHSLtoRGB()` to do that.

This file gives also the capability to store known colours in a list. Use methods such as `tool_color_addColor()` or `tool_color_addFloatRGBA()`. Them, one can access to stored colours, using `tool_color_getByValues()` or `tool_color_getByColor()`.

## Details

### TOOL_COLOR_MASK_R

    #define TOOL_COLOR_MASK_R (1 << 0)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to red.

### TOOL_COLOR_MASK_G

    #define TOOL_COLOR_MASK_G (1 << 1)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to green.

### TOOL_COLOR_MASK_B

    #define TOOL_COLOR_MASK_B (1 << 2)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to blue.

### TOOL_COLOR_MASK_A

    #define TOOL_COLOR_MASK_A (1 << 3)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to the alpha channel.

### TOOL_COLOR_MASK_RGBA

    #define TOOL_COLOR_MASK_RGBA (15)

This value can be used to create a mask for methods that require one for reading rgb color array. This value is a shortcut for TOOL_COLOR_MASK_R | TOOL_COLOR_MASK_G | TOOL_COLOR_MASK_B.

### ToolColor

    typedef struct {
      float rgba[4];
      gpointer userData;
    } ToolColor;

A structure to store colors.

float `rgba`[4]; | the coding of color in Red, Green, Blue, Alpha format, floating point numbers between 0 and 1 ;
gpointer `userData`; | a pointer to store some data (should be used with care).

### tool_color_new ()

    ToolColor*          tool_color_new                      (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 ToolColor (use `g_free()` to free it).. transfer none.

### tool_color_equal ()

    gboolean            tool_color_equal                    (ToolColor *color1,
                                                             ToolColor *color2);

Test if the two colours are the same.

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

### tool_color_copy ()

    void                tool_color_copy                     (ToolColor *color,
                                                             ToolColor *color_old);

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

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

### tool_color_freeAll ()

    void                tool_color_freeAll                  (void);

Remove all previously stored colours.

### tool_color_getById ()

    ToolColor*          tool_color_getById                  (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.. transfer none.

### tool_color_getLastStored ()

    ToolColor*          tool_color_getLastStored            (void);

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

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

### tool_color_getByColor ()

    int                 tool_color_getByColor               (ToolColor *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.

### tool_color_getByValues ()

    ToolColor*          tool_color_getByValues              (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 ;. out caller-allocates.
`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.. transfer none.

### tool_color_getStoredColors ()

    GList*              tool_color_getStoredColors          (void);

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

Returns : | a GList pointer to the stored colors.. transfer none. element-type ToolColor.

### tool_color_addColor ()

    ToolColor*          tool_color_addColor                 (ToolColor *color);

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

`color` : | a ToolColor.
Returns : | the newly created ToolColor.. transfer none.

### tool_color_addFloatRGBA ()

    ToolColor*          tool_color_addFloatRGBA             (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 of the returned colour.. out caller-allocates.
Returns : | a newly created ToolColor or the already existing one.. transfer none.

### tool_color_addIntRGBA ()

    ToolColor*          tool_color_addIntRGBA               (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 : | a newly created ToolColor or the already existing one.. transfer none.

### tool_color_convertHSVtoRGB ()

    void                tool_color_convertHSVtoRGB          (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.

### tool_color_convertHSLtoRGB ()

    void                tool_color_convertHSLtoRGB          (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.

### tool_color_convertRGBtoHSL ()

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

Convert a RGB colour into a HSL one.

`hsl` : | three float to store the HSL value ;
`rgb` : | three floats giving the RGB values.