## toolShade toolShade — Shades are color gradients. |

## Synopsis

    struct              Shade_struct;
    typedef             Shade;
    enum                ShadeColorMode;
    enum                ShadeMode;
    Shade*              shadeNew                            (const gchar *labelUTF8,
                                                             float vectA[3],
                                                             float vectB[3],
                                                             ShadeColorMode colorMode);
    Shade*              shadeNew_fromData                   (const gchar *labelUTF8,
                                                             guint len,
                                                             float *vectCh1,
                                                             float *vectCh2,
                                                             float *vectCh3,
                                                             ShadeColorMode colorMode);
    void                shadeFree                           (Shade *shade);
    Shade*              shadeCopy                           (Shade *shade);
    gboolean            shadeCompare                        (Shade *sh1,
                                                             Shade *sh2);
    gchar*              shadeGet_label                      (Shade *shade);
    ShadeColorMode      shadeGet_colorMode                  (Shade *shade);
    gboolean            shadeSet_colorMode                  (Shade *shade,
                                                             ShadeColorMode mode);
    ShadeMode           shadeGet_mode                       (Shade *shade);
    gboolean            shadeGet_linearCoeff                (Shade *shade,
                                                             float **vectA,
                                                             float **vectB);
    gboolean            shadeSet_linearCoeff                (Shade *shade,
                                                             float coeff,
                                                             int channel,
                                                             int order);
    void                shadeGet_valueTransformedInRGB      (const Shade *shade,
                                                             float rgba[4],
                                                             float value);
    void                shadeGet_RGBFromValues              (const Shade *shade,
                                                             float rgba[4],
                                                             float values[3]);
    void                shadeDraw_legend                    (Shade *shade,
                                                             float widthVal,
                                                             float heightVal,
                                                             float minMax[2],
                                                             float *marks,
                                                             int nbMarks,
                                                             ToolMatrixScalingFlag scale);
    GList*              toolShadeListGet                    (void);
    GList*              toolShadeListAppend                 (Shade *shade);
    GList*              toolShadeBuild_presetList           (void);

## Description

This module allow V_Sim to deal with color gradients. Such a gradient is defined by a linear transformation of color space. This space can be RBG or HSV (see the enum ShadeColorMode). This linear transformation can be written [resulting color vector] = [vectB] + lambda.[vectA], where lambda denotes the input variable of the gradient (ranging from 0 to 1). Resulting color vector are clamped to [0;1] if needed.

Use `shadeNew()` to create a new shade, giving the arguments as defined above. A shade can be linked to an image to represent it, use `shadeSet_pathToImage()` to do it.

To share color gradients between modules in V_Sim, you can add new shade to the global list of stored shades using `toolShadeListAppend()` and get this list with a call to `toolShadeListGet()`.

## Details

### struct Shade_struct

    struct Shade_struct;

Opaque structure to store linear shade informations.

### Shade

    typedef struct Shade_struct Shade;

Short name to address Shade_struct objects.

### enum ShadeColorMode

    typedef enum
      {
        shade_colorModeRGB,
        shade_colorModeHSV,
        shade_nb_colorMode
      } ShadeColorMode;

Defines color mode : Red-Green-Blue or Hue-Saturation-Value.

`shade_colorModeRGB` | variation described in the shade are applied to RGB coding colors ;
`shade_colorModeHSV` | variation described in the shade are applied to HSV coding colors ;
`shade_nb_colorMode` | number of modes available.

### enum ShadeMode

    typedef enum
      {
        shade_modeLinear,
        shade_modeArray,
        shade_nb_mode
      } ShadeMode;

Defines the storage of the shade mode.

`shade_modeLinear` | all channels are defined by a linear variation Ax+B ;
`shade_modeArray` | all channels are defined by a given array of values ;
`shade_nb_mode` | the number of different shade mode.

### shadeNew ()

    Shade*              shadeNew                            (const gchar *labelUTF8,
                                                             float vectA[3],
                                                             float vectB[3],
                                                             ShadeColorMode colorMode);

Create a linear shade. Its profile is given by an AX+B formula, dealing on three channels. These channels are defined by the `colorMode` parameter. All given values are copied when the new shade is created.

`labelUTF8` : | a UTF8 string that shortly named this new shade ;
`vectA` : | an array of three floating point values ;
`vectB` : | an array of three floating point values ;
`colorMode` : | an integer that describes the color code (see ShadeColorMode enumeration).
Returns : | the newly created Shade.

### shadeNew_fromData ()

    Shade*              shadeNew_fromData                   (const gchar *labelUTF8,
                                                             guint len,
                                                             float *vectCh1,
                                                             float *vectCh2,
                                                             float *vectCh3,
                                                             ShadeColorMode colorMode);

Create a Shade from direct data for three channels. These channels are defined by the `colorMode` parameter. All given values are copied when the new shade is created.

`labelUTF8` : | a UTF8 string that shortly named this new shade ;
`len` : | the size of arguments `vectCh1`, `vectCh2` and `vectCh3` ;
`vectCh1` : | an array of floating point values for the first channel ;
`vectCh2` : | an array of floating point values for the first channel ;
`vectCh3` : | an array of floating point values for the first channel ;
`colorMode` : | an integer that describes the color code (see ShadeColorMode enumeration).
Returns : | the newly created Shade.

### shadeFree ()

    void                shadeFree                           (Shade *shade);

Free all dynamic memory from `shade` and free `shade` itself.

`shade` : | a Shade.

### shadeCopy ()

    Shade*              shadeCopy                           (Shade *shade);

Create a new shade deep copy of the first.

`shade` : | a Shade.
Returns : | a newly created shade.

### shadeCompare ()

    gboolean            shadeCompare                        (Shade *sh1,
                                                             Shade *sh2);

Compare if the two shade are identical (first, smae mode, then same values).

`sh1` : | a Shade ;
`sh2` : | a Shade.
Returns : | TRUE if `shade1` is equivalent to `shade2`.

### shadeGet_label ()

    gchar*              shadeGet_label                      (Shade *shade);

Get the name (in UTF8) of the shade.

`shade` : | a valid Shade object.
Returns : | a string naming the shade.

### shadeGet_colorMode ()

    ShadeColorMode      shadeGet_colorMode                  (Shade *shade);

Get the color mode of the shade (RGB or HSV).

`shade` : | a valid Shade object.
Returns : | the color mode.

### shadeSet_colorMode ()

    gboolean            shadeSet_colorMode                  (Shade *shade,
                                                             ShadeColorMode mode);

Change the mode of the shade, see ShadeColorMode.

`shade` : | a Shade ;
`mode` : | a new mode for the shade.
Returns : | TRUE if `mode` is different from previous `shade` mode.

### shadeGet_mode ()

    ShadeMode           shadeGet_mode                       (Shade *shade);

Get the mode of the shade (linear, array...).

`shade` : | a valid Shade object.
Returns : | the mode.

### shadeGet_linearCoeff ()

    gboolean            shadeGet_linearCoeff                (Shade *shade,
                                                             float **vectA,
                                                             float **vectB);

This methods can get the linear color transformation. The given arrays (`vectA`, `vectB`) are read-only. This method return FALSE if the `shade` is not in a shade_modeLinear state.

`shade` : | a valid Shade object ;
`vectA` : | a pointer to a floating point values array to store vect in AX+B ;
`vectB` : | a pointer to a floating point values array to store vect in AX+B.
Returns : | TRUE if `vectA`, `vectB` and `vectX` have been set correctly.

### shadeSet_linearCoeff ()

    gboolean            shadeSet_linearCoeff                (Shade *shade,
                                                             float coeff,
                                                             int channel,
                                                             int order);

Change one value `coeff` of the linear mode for the given `shade`.

`shade` : | a Shade ;
`coeff` : | a new value ;
`channel` : | either RGBA (from 0 to 3) ;
`order` : | the order in the linear approx (0 means constant and 1 is the linear coeeficient).
Returns : | TRUE if the new value changes anything.

### shadeGet_valueTransformedInRGB ()

    void                shadeGet_valueTransformedInRGB      (const Shade *shade,
                                                             float rgba[4],
                                                             float value);

Give a RGBA vector for the given value.

`shade` : | a valid Shade object ;
`rgba` : | an array of size [4] ;
`value` : | the value ranged in [0;1].

### shadeGet_RGBFromValues ()

    void                shadeGet_RGBFromValues              (const Shade *shade,
                                                             float rgba[4],
                                                             float values[3]);

Like `shadeGet_valueTransformedInRGB()` but here, the three values are applied respectivly for the Red, the Green and the Blue channel.

`shade` : | a Shade ;
`rgba` : | a location to store the result of the colour transformation ;
`values` : | inout values.

### shadeDraw_legend ()

    void                shadeDraw_legend                    (Shade *shade,
                                                             float widthVal,
                                                             float heightVal,
                                                             float minMax[2],
                                                             float *marks,
                                                             int nbMarks,
                                                             ToolMatrixScalingFlag scale);

This method calls OpenGL primitive to draw a coloured legend on the rendering surface. If `widthVal` is negative then the default value in pixel is used. If `widthVal` is smaller than 1., the width is taken as a percentage of the width of the rendering area. Finaly, if `widthVal` is larger than 1., the width of the legend in pixel is the given value. If `marks` is not NULL, some marks are set on the legend for the given values.

`shade` : | a valid Shade object ;
`widthVal` : | a floating point value ;
`heightVal` : | a floating point value ;
`minMax` : | the min & max value of the represented shaded color ;
`marks` : | an array of values bounded by `minMax` ;
`nbMarks` : | the number of elements in the `marks` array ;
`scale` : | the kind of transformation.

### toolShadeListGet ()

    GList*              toolShadeListGet                    (void);

It returns a read-only pointer to the internal shade list. Use `toolShadeListAppend()` to add new shades to this list.

Returns : | a pointer to the internal shade list.

### toolShadeListAppend ()

    GList*              toolShadeListAppend                 (Shade *shade);

Add a shape to the internal list. Use the return value or `toolShadeListGet()` method to look into this list.

`shade` : | a Shade object.
Returns : | a read-only pointer to the internal shade list.

### toolShadeBuild_presetList ()

    GList*              toolShadeBuild_presetList           (void);

Create a list of preset shades.

Returns : | a read-only pointer to the internal shade list.