toolColor

toolColor — Simple handling and storage of RGBA colours.

Synopsis

#define             TOOL_COLOR_MASK_A
#define             TOOL_COLOR_MASK_B
#define             TOOL_COLOR_MASK_G
#define             TOOL_COLOR_MASK_R
#define             TOOL_COLOR_MASK_RGBA
struct              ToolColor;
ToolColor *         tool_color_addColor                 (ToolColor *color);
ToolColor *         tool_color_addFloatRGBA             (float rgba[4],
                                                         int *position);
ToolColor *         tool_color_addIntRGBA               (int rgba[4]);
void                tool_color_convertHSLtoRGB          (float *rgb,
                                                         float *hsl);
void                tool_color_convertHSVtoRGB          (float *rgb,
                                                         float *hsv);
void                tool_color_convertRGBtoHSL          (float *hsl,
                                                         float *rgb);
void                tool_color_copy                     (ToolColor *color,
                                                         ToolColor *color_old);
gboolean            tool_color_equal                    (ToolColor *color1,
                                                         ToolColor *color2);
void                tool_color_freeAll                  (void);
int                 tool_color_getByColor               (ToolColor *color);
ToolColor *         tool_color_getById                  (int num);
ToolColor *         tool_color_getByValues              (int *pos,
                                                         float red,
                                                         float green,
                                                         float blue,
                                                         float alpha);
ToolColor *         tool_color_getLastStored            (void);
GList *             tool_color_getStoredColors          (void);
ToolColor *         tool_color_new                      (float rgba[4]);
const ToolColor *   tool_color_new_bright               (guint id);

Object Hierarchy

  GBoxed
   +----ToolColor

Description

This file defines a basic structure to store colours (not using the GDK one beca use V_Sim core should not rely on GDK and GTK): ToolColor. Several transformations are possible on a colour, going from and to RGB encoding. Use tool_color_convertHSVtoRGB() and tool_color_convertHSLtoRGB() to do that.

This file gives also the capability to store known colours in a list. Use methods such as tool_color_addColor() or tool_color_addFloatRGBA(). Them, one can access to stored colours, using tool_color_getByValues() or tool_color_getByColor().

Details

TOOL_COLOR_MASK_A

#define TOOL_COLOR_MASK_A (1 << 3)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to the alpha channel.


TOOL_COLOR_MASK_B

#define TOOL_COLOR_MASK_B (1 << 2)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to blue.


TOOL_COLOR_MASK_G

#define TOOL_COLOR_MASK_G (1 << 1)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to green.


TOOL_COLOR_MASK_R

#define TOOL_COLOR_MASK_R (1 << 0)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to red.


TOOL_COLOR_MASK_RGBA

#define TOOL_COLOR_MASK_RGBA (15)

This value can be used to create a mask for methods that require one for reading rgb color array. This value is a shortcut for TOOL_COLOR_MASK_R | TOOL_COLOR_MASK_G | TOOL_COLOR_MASK_B.


struct ToolColor

struct ToolColor {
  float rgba[4];
  gpointer userData;
};

A structure to store colors.

float rgba[4];

the coding of color in Red, Green, Blue, Alpha format, floating point numbers between 0 and 1 ;

gpointer userData;

a pointer to store some data (should be used with care).

tool_color_addColor ()

ToolColor *         tool_color_addColor                 (ToolColor *color);

This method copies color informations from color to the list of stored colors.

color :

a ToolColor.

Returns :

the newly created ToolColor. [transfer none]

tool_color_addFloatRGBA ()

ToolColor *         tool_color_addFloatRGBA             (float rgba[4],
                                                         int *position);

This method adds a new color in the list of stored colors with the given values. If it already exits it returns the pointer of that color.

rgba :

four values between 0. and 1. that represent [Red, Green, Blue, Alpha] ;

position :

an int pointer to store the position of the returned colour. [out caller-allocates][allow-none]

Returns :

a newly created ToolColor or the already existing one. [transfer none]

tool_color_addIntRGBA ()

ToolColor *         tool_color_addIntRGBA               (int rgba[4]);

This method adds a new color in the list of stored colors with the given values.

rgba :

four values between 0 and 255 that represent [Red, Green, Blue, Alpha].

Returns :

a newly created ToolColor or the already existing one. [transfer none]

tool_color_convertHSLtoRGB ()

void                tool_color_convertHSLtoRGB          (float *rgb,
                                                         float *hsl);

This methods convert a HSL color to a RGB one.

rgb :

an allocated 3 elements array to receive the RGB values ;

hsl :

a 3 elements array to retrieve the HSL values from.

tool_color_convertHSVtoRGB ()

void                tool_color_convertHSVtoRGB          (float *rgb,
                                                         float *hsv);

This methods convert a HSV color to a RGB one.

rgb :

an allocated 3 elements array to receive the RGB values ;

hsv :

a 3 elements array to retrieve the HSV values from.

tool_color_convertRGBtoHSL ()

void                tool_color_convertRGBtoHSL          (float *hsl,
                                                         float *rgb);

Convert a RGB colour into a HSL one.

hsl :

three float to store the HSL value ;

rgb :

three floats giving the RGB values.

tool_color_copy ()

void                tool_color_copy                     (ToolColor *color,
                                                         ToolColor *color_old);

This method copies all values from color_old to color.

color :

an allocated ToolColor object to receive values ;

color_old :

a ToolColor to read the values from.

tool_color_equal ()

gboolean            tool_color_equal                    (ToolColor *color1,
                                                         ToolColor *color2);

Test if the two colours are the same.

color1 :

a ToolColor ;

color2 :

an other ToolColor.

Returns :

TRUE if the rgba attributes are the same.

tool_color_freeAll ()

void                tool_color_freeAll                  (void);

Remove all previously stored colours.


tool_color_getByColor ()

int                 tool_color_getByColor               (ToolColor *color);

This function retrieves the number (begining at 0) of the specified color.

color :

a pointer to a stored color.

Returns :

the position of the specified color or -1 if not found.

tool_color_getById ()

ToolColor *         tool_color_getById                  (int num);

This function retrieves the nth stored color. Number 0, is the last added color.

num :

an integer (>0).

Returns :

the corresponding color, or NULL if none has been found. [transfer none]

tool_color_getByValues ()

ToolColor *         tool_color_getByValues              (int *pos,
                                                         float red,
                                                         float green,
                                                         float blue,
                                                         float alpha);

This method is used to look for a specific color in the stored list. The argument pos is -1 if nothing is found or stores the position (beginning at 0) of the found color.

pos :

an allocated int to store the position of the found color ;. [out caller-allocates]

red :

a value between 0. and 1. ;

green :

a value between 0. and 1. ;

blue :

a value between 0. and 1. ;

alpha :

a value between 0. and 1..

Returns :

the found color, or NULL if none exists. [transfer none]

tool_color_getLastStored ()

ToolColor *         tool_color_getLastStored            (void);

This method is typiccally called after a client has catched the colorNewAvailable signal.

Returns :

the last added color, NULL if no color exists. [transfer none]

tool_color_getStoredColors ()

GList *             tool_color_getStoredColors          (void);

Use this method to get a pointeur to the list of stored colors.

Returns :

a GList pointer to the stored colors. [transfer none][element-type ToolColor]

tool_color_new ()

ToolColor *         tool_color_new                      (float rgba[4]);

Create a new color with initial values given as arguments.

rgba :

four values between 0. and 1. that represent [Red, Green, Blue, Alpha].

Returns :

a new allocated ToolColor (use g_free() to free it). [transfer none]

tool_color_new_bright ()

const ToolColor *   tool_color_new_bright               (guint id);

V_Sim has a list of 20 bright colors. One can get one by calling this routine. The id is taken modulo the number of available colors.

id :

an index

Returns :

a bright color. [transfer none]

Since 3.7