toolShade

toolShade — ToolShades are color gradients.

Functions

Types and Values

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.

To share color gradients between modules in V_Sim, you can find a global list of stored shades with tool_shade_getStorage(). This is a ToolPool object. Use tool_pool_add() to add a new shade to it.

Functions

tool_shade_getStorage ()

ToolPool *
tool_shade_getStorage (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]

Since: 3.8


tool_shade_getById ()

const ToolShade *
tool_shade_getById (guint id);

Convenience function calling tool_pool_getById() on the default ToolShade storage.

Parameters

id

an id.

 

Returns

a ToolShade from the pool.

Since: 3.8


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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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_free ()

void
tool_shade_free (ToolShade *shade);

Free all dynamic memory from shade and free shade itself.

Parameters

shade

a ToolShade.

 

tool_shade_copy ()

ToolShade *
tool_shade_copy (const ToolShade *shade);

Create a new shade deep copy of the first.

Parameters

shade

a ToolShade.

 

Returns

a newly created shade.


tool_shade_compare ()

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

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

Parameters

sh1

a ToolShade ;

 

sh2

a ToolShade.

 

Returns

TRUE if shade1 is equivalent to shade2 .


tool_shade_getLabel ()

gchar *
tool_shade_getLabel (ToolShade *shade);

Get the name (in UTF8) of the shade.

Parameters

shade

a valid ToolShade object.

 

Returns

a string naming the shade.


tool_shade_getColorMode ()

ToolShadeColorMode
tool_shade_getColorMode (ToolShade *shade);

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

Parameters

shade

a valid ToolShade object.

 

Returns

the color mode.


tool_shade_setColorMode ()

gboolean
tool_shade_setColorMode (ToolShade *shade,
                         ToolShadeColorMode mode);

Change the mode of the shade, see ToolShadeColorMode.

Parameters

shade

a ToolShade ;

 

mode

a new mode for the shade.

 

Returns

TRUE if mode is different from previous shade mode.


tool_shade_getMode ()

ToolShadeMode
tool_shade_getMode (ToolShade *shade);

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

Parameters

shade

a valid ToolShade object.

 

Returns

the mode.


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.

Parameters

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

Parameters

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.

Parameters

shade

a valid ToolShade object ;

 

rgba

an array of size [4] ;

 

value

the value ranged in [0;1].

 

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.

Parameters

shade

a ToolShade ;

 

rgba

a location to store the result of the colour transformation ;

 

values

inout values.

 

Types and Values

enum ToolShadeColorMode

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

Members

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

Defines the storage of the shade mode.

Members

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.

Members

float index;

a value.

 

float channels[3];

three values in [0;1] for RGB or HSV channels.

[array fixed-size=3]

Since: 3.7


ToolShade

typedef struct _ToolShade ToolShade;

Short name to address _ToolShade objects.