## toolShade toolShade — Shades are color gradients. |

## Synopsis

    enum                ShadeColorMode;
    struct              Shade_struct;
    typedef             Shade;
    Shade*              shadeNew                            (const gchar *labelUTF8,
                                                             float vectA[3],
                                                             float vectB[3],
                                                             gboolean vectX[3],
                                                             ShadeColorMode colorMode);
    void                shadeDraw_legend                    (Shade *shade,
                                                             float widthVal,
                                                             float heightVal,
                                                             float minMax[2],
                                                             float *marks,
                                                             int nbMarks,
                                                             float *smin);
    ShadeColorMode      shadeGet_colorMode                  (Shade *shade);
    gboolean            shadeGet_colorTransformation        (Shade *shade,
                                                             float **vectA,
                                                             float **vectB,
                                                             gboolean **vectX);
    gchar*              shadeGet_label                      (Shade *shade);
    gchar*              shadeGet_pathToImage                (Shade *shade);
    void                shadeGet_valueTransformedInRGB      (Shade *shade,
                                                             float rgba[4],
                                                             float value);
    gboolean            shadeSet_pathToImage                (Shade *shade,
                                                             const gchar *path);

    GList*              toolShadeBuild_presetList           ();
    GList*              toolShadeListAppend                 (Shade *shade);
    GList*              toolShadeListGet                    ();

## 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. A boolean vector [vectX] can specify which color canal can be transformed.

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

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

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

### shadeNew ()

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

Shades are linear. Their profiles are 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 ;
`vectX` : | an array of three boolean values ;
`colorMode` : | an integer that describes the color code (see Shade_colorMode enumeration).
Returns : | the newly created Shade.

### shadeDraw_legend ()

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

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. If `smin` is given, the legend is drawn in log scale using the given value as secondary minimum.

`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 ;
`smin` : | a pointer to a floating point value or NULL.

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

### shadeGet_colorTransformation ()

    gboolean            shadeGet_colorTransformation        (Shade *shade,
                                                             float **vectA,
                                                             float **vectB,
                                                             gboolean **vectX);

This methods can get the linear color transformation. The given arrays (vectA, vectB and vectX) are read-only.

`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 ;
`vectX` : | a pointer to a gboolean values array to store vect in AX+B.
Returns : | TRUE if `vectA`, `vectB` and `vectX` have been set correctly.

### 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_pathToImage ()

    gchar*              shadeGet_pathToImage                (Shade *shade);

Get the path (always absolute) of an image describing the shade.

`shade` : | a valid Shade object.
Returns : | a path (absolute) or NULL if not has been set.

### shadeGet_valueTransformedInRGB ()

    void                shadeGet_valueTransformedInRGB      (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].

### shadeSet_pathToImage ()

    gboolean            shadeSet_pathToImage                (Shade *shade,
                                                             const gchar *path);

An image can be associated to the shade and its path is set with this method. If the path is not an absolute path, the real path used is the concatenation of the directory of pixmaps (cf. v_sim_pixmaps_dir in visu_basic.h) and the given path.

`shade` : | a valid Shade object ;
`path` : | a string.
Returns : | TRUE if the path has been changed.

### toolShadeBuild_presetList ()

    GList*              toolShadeBuild_presetList           ();

Create a list of preset shades.

Returns : | a read-only 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.

### toolShadeListGet ()

    GList*              toolShadeListGet                    ();

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.