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.