toolShade

toolShade — ToolShades are color gradients.

Synopsis

                    ToolShade;
enum                ToolShadeColorMode;
enum                ToolShadeMode;
struct              ToolShadeStep;
GList *             tool_shade_appendList               (ToolShade *shade,
                                                         gboolean unique);
void                tool_shade_channelToRGB             (const ToolShade *shade,
                                                         float rgba[4],
                                                         float values[3]);
gboolean            tool_shade_compare                  (ToolShade *sh1,
                                                         ToolShade *sh2);
ToolShade *         tool_shade_copy                     (ToolShade *shade);
void                tool_shade_free                     (ToolShade *shade);
ToolShadeColorMode  tool_shade_getColorMode             (ToolShade *shade);
gchar *             tool_shade_getLabel                 (ToolShade *shade);
gboolean            tool_shade_getLinearCoeff           (ToolShade *shade,
                                                         float **vectA,
                                                         float **vectB);
GList *             tool_shade_getList                  (void);
ToolShadeMode       tool_shade_getMode                  (ToolShade *shade);
ToolShade *         tool_shade_new                      (const gchar *labelUTF8,
                                                         float vectA[3],
                                                         float vectB[3],
                                                         ToolShadeColorMode colorMode);
ToolShade *         tool_shade_newFromData              (const gchar *labelUTF8,
                                                         guint len,
                                                         float *vectCh1,
                                                         float *vectCh2,
                                                         float *vectCh3,
                                                         ToolShadeColorMode colorMode);
ToolShade *         tool_shade_newFromSteps             (const gchar *labelUTF8,
                                                         GList *lst,
                                                         ToolShadeColorMode colorMode);
ToolShade *         tool_shade_newFromString            (const gchar *labelUTF8,
                                                         const gchar *descr,
                                                         ToolShadeColorMode colorMode,
                                                         GError **error);
gboolean            tool_shade_setColorMode             (ToolShade *shade,
                                                         ToolShadeColorMode mode);
gboolean            tool_shade_setLinearCoeff           (ToolShade *shade,
                                                         float coeff,
                                                         int channel,
                                                         int order);
void                tool_shade_valueToRGB               (const ToolShade *shade,
                                                         float rgba[4],
                                                         float value);

Object Hierarchy

  GBoxed
   +----ToolShade

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 ToolShadeColorMode). 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 tool_shade_new() 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 tool_shade_appendList() and get this list with a call to tool_shade_getList().

Details

ToolShade

typedef struct _ToolShade ToolShade;

Short name to address _ToolShade objects.


enum ToolShadeColorMode

typedef enum {
    TOOL_SHADE_COLOR_MODE_RGB,
    TOOL_SHADE_COLOR_MODE_HSV,
    TOOL_SHADE_COLOR_MODE_N_VALUES
} ToolShadeColorMode;

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

TOOL_SHADE_COLOR_MODE_RGB

variation described in the shade are applied to RGB coding colors ;

TOOL_SHADE_COLOR_MODE_HSV

variation described in the shade are applied to HSV coding colors ;

TOOL_SHADE_COLOR_MODE_N_VALUES

number of modes available.

enum ToolShadeMode

typedef enum {
    TOOL_SHADE_MODE_LINEAR,
    TOOL_SHADE_MODE_ARRAY,
    TOOL_SHADE_MODE_N_VALUES
} ToolShadeMode;

Defines the storage of the shade mode.

TOOL_SHADE_MODE_LINEAR

all channels are defined by a linear variation Ax+B ;

TOOL_SHADE_MODE_ARRAY

all channels are defined by a given array of values ;

TOOL_SHADE_MODE_N_VALUES

the number of different shade mode.

struct ToolShadeStep

struct ToolShadeStep {
  float index;
  float channels[3];
};

Stores a step in the definition of a shade.

float index;

a value.

float channels[3];

three values in [0;1] for RGB or HSV channels. [array fixed-size=3]

Since 3.7


tool_shade_appendList ()

GList *             tool_shade_appendList               (ToolShade *shade,
                                                         gboolean unique);

Add a shape to the internal list. Use the return value or tool_shade_getList() method to look into this list. If unique is TRUE, the internal list is read and shade is added only if it is not already existing in the list.

shade :

a ToolShade object.

unique :

a boolean.

Returns :

a read-only pointer to the internal shade list. [transfer none][element-type ToolShade*]

tool_shade_channelToRGB ()

void                tool_shade_channelToRGB             (const ToolShade *shade,
                                                         float rgba[4],
                                                         float values[3]);

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

shade :

a ToolShade ;

rgba :

a location to store the result of the colour transformation ;

values :

inout values.

tool_shade_compare ()

gboolean            tool_shade_compare                  (ToolShade *sh1,
                                                         ToolShade *sh2);

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

sh1 :

a ToolShade ;

sh2 :

a ToolShade.

Returns :

TRUE if shade1 is equivalent to shade2.

tool_shade_copy ()

ToolShade *         tool_shade_copy                     (ToolShade *shade);

Create a new shade deep copy of the first.

shade :

a ToolShade.

Returns :

a newly created shade.

tool_shade_free ()

void                tool_shade_free                     (ToolShade *shade);

Free all dynamic memory from shade and free shade itself.

shade :

a ToolShade.

tool_shade_getColorMode ()

ToolShadeColorMode  tool_shade_getColorMode             (ToolShade *shade);

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

shade :

a valid ToolShade object.

Returns :

the color mode.

tool_shade_getLabel ()

gchar *             tool_shade_getLabel                 (ToolShade *shade);

Get the name (in UTF8) of the shade.

shade :

a valid ToolShade object.

Returns :

a string naming the shade.

tool_shade_getLinearCoeff ()

gboolean            tool_shade_getLinearCoeff           (ToolShade *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 TOOL_SHADE_MODE_LINEAR state.

shade :

a valid ToolShade 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.

tool_shade_getList ()

GList *             tool_shade_getList                  (void);

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

Returns :

a pointer to the internal shade list. [transfer none][element-type ToolShade*]

tool_shade_getMode ()

ToolShadeMode       tool_shade_getMode                  (ToolShade *shade);

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

shade :

a valid ToolShade object.

Returns :

the mode.

tool_shade_new ()

ToolShade *         tool_shade_new                      (const gchar *labelUTF8,
                                                         float vectA[3],
                                                         float vectB[3],
                                                         ToolShadeColorMode 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 ToolShadeColorMode enumeration).

Returns :

the newly created ToolShade.

tool_shade_newFromData ()

ToolShade *         tool_shade_newFromData              (const gchar *labelUTF8,
                                                         guint len,
                                                         float *vectCh1,
                                                         float *vectCh2,
                                                         float *vectCh3,
                                                         ToolShadeColorMode colorMode);

Create a ToolShade 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 second channel ;

vectCh3 :

an array of floating point values for the third channel ;

colorMode :

an integer that describes the color code (see ToolShadeColorMode enumeration).

Returns :

the newly created ToolShade.

tool_shade_newFromSteps ()

ToolShade *         tool_shade_newFromSteps             (const gchar *labelUTF8,
                                                         GList *lst,
                                                         ToolShadeColorMode colorMode);

Create a ToolShade from a set of steps defining colours at given indexes. These channels are defined by the colorMode parameter. All given values are copied when the new shade is created. The values of indexes will be normalised by this call to range in [0;1]. Colour channel values must be in [0;1] for each step.

labelUTF8 :

a UTF8 string that shortly named this new shade ;

lst :

a list of color steps. [transfer none][element-type ToolShadeStep*]

colorMode :

a ToolShadeColorMode mode.

Returns :

the newly created ToolShade. [transfer full]

Since 3.7


tool_shade_newFromString ()

ToolShade *         tool_shade_newFromString            (const gchar *labelUTF8,
                                                         const gchar *descr,
                                                         ToolShadeColorMode colorMode,
                                                         GError **error);

As tool_shade_newFromSteps() routine, but it takes an unparsed string describing the steps in descr.

labelUTF8 :

a UTF8 string that shortly named this new shade ;

descr :

a string with the shade description.

colorMode :

a ToolShadeColorMode mode.

error :

a location for an error. [allow-none]

Returns :

the newly created ToolShade. [transfer full]

Since 3.7


tool_shade_setColorMode ()

gboolean            tool_shade_setColorMode             (ToolShade *shade,
                                                         ToolShadeColorMode mode);

Change the mode of the shade, see ToolShadeColorMode.

shade :

a ToolShade ;

mode :

a new mode for the shade.

Returns :

TRUE if mode is different from previous shade mode.

tool_shade_setLinearCoeff ()

gboolean            tool_shade_setLinearCoeff           (ToolShade *shade,
                                                         float coeff,
                                                         int channel,
                                                         int order);

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

shade :

a ToolShade ;

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.

tool_shade_valueToRGB ()

void                tool_shade_valueToRGB               (const ToolShade *shade,
                                                         float rgba[4],
                                                         float value);

Give a RGBA vector for the given value.

shade :

a valid ToolShade object ;

rgba :

an array of size [4] ;

value :

the value ranged in [0;1].