toolColor

toolColor — Simple handling and storage of RGBA colours.

Functions

Types and Values

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

Functions

tool_color_new ()

ToolColor *
tool_color_new (const float rgba[4]);

Create a new color with initial values given as arguments.

Parameters

rgba

four values between 0. and

  1. that represent [Red, Green, Blue, Alpha].

[in][array fixed-size=4]

Returns

a new allocated ToolColor (use g_free() to free it).

[transfer full]


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.

Parameters

id

an index

 

Returns

a bright color.

[transfer none]

Since: 3.7


tool_color_equal ()

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

Test if the two colours are the same.

Parameters

color1

a ToolColor ;

 

color2

an other ToolColor.

 

Returns

TRUE if the rgba attributes are the same.


tool_color_copy ()

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

This method copies all values from color_old to color .

Parameters

color

an allocated ToolColor object to receive values ;

 

color_old

a ToolColor to read the values from.

 

tool_color_getStorage ()

ToolPool *
tool_color_getStorage ();

Give access to the ToolPool instance storing all the colors.

Returns

a ToolPool object.

[transfer none]

Since: 3.8


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.

Parameters

pos

an allocated int to store the position of the found color ;.

[out caller-allocates][allow-none]

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

ToolColor *
tool_color_addFloatRGBA (const 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.

Parameters

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.

Parameters

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

const ToolColor *
tool_color_fromStr (const gchar *str,
                    int *pos);

This method parse str with the format RRGGBB or RRGGBBAA to create a ToolColor. This color is added to the pool, see tool_color_getStorage().

Parameters

str

a string.

 

pos

a location.

[out caller-allocates][allow-none]

Returns

a corresponding ToolColor, creating it if necessary.

[transfer none]

Since: 3.8


tool_color_asStr ()

const gchar *
tool_color_asStr (ToolColor *color);

Gives a string representation of color . The string is computed at each call.

Parameters

color

a ToolColor object.

 

Returns

a string representing color .

Since: 3.8


tool_color_fromName ()

const ToolColor *
tool_color_fromName (const gchar *name,
                     int *pos);

Parse a name like 'black' and generate a colour. This color is added to the pool, see tool_color_getStorage().

Parameters

name

a string.

 

pos

a location.

[out caller-allocates][allow-none]

Returns

a corresponding ToolColor, creating it if necessary.

[transfer none]

Since: 3.8


tool_color_invertRGBA ()

void
tool_color_invertRGBA (float inv[4],
                       const float rgba[4]);

Invert the colour on the stack.

Parameters

inv

a location to store the inverted colour.

 

rgba

a colour defined in RGBA.

 

Since: 3.8


tool_color_convertHSVtoRGB ()

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

This methods convert a HSV color to a RGB one.

Parameters

rgb

an allocated 3 elements array to receive the RGB values ;

 

hsv

a 3 elements array to retrieve the HSV values from.

 

tool_color_convertHSLtoRGB ()

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

This methods convert a HSL color to a RGB one.

Parameters

rgb

an allocated 3 elements array to receive the RGB values ;

 

hsl

a 3 elements array to retrieve the HSL values from.

 

tool_color_convertRGBtoHSL ()

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

Convert a RGB colour into a HSL one.

Parameters

hsl

three float to store the HSL value ;

 

rgb

three floats giving the RGB values.

 

Types and Values

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_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_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_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_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];
  gchar repr[10];
  gpointer userData;
};

A structure to store colors. repr is not set before tool_color_asStr() is called. Any changes in rgba are not transfered to repr and tool_color_asStr() should be called again.

Members

float rgba[4];

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

 

gchar repr[10];

store the representation of the colour as "rrggbbaa".

 

gpointer userData;

unused.

 

enum ToolMaterialIds

This enum is used to address the OpenGL parameters for light rendering.

Members

TOOL_MATERIAL_AMB

the ambient identifier ;

 

TOOL_MATERIAL_DIF

the diffuse identifier ;

 

TOOL_MATERIAL_SHI

the shiningness identifier ;

 

TOOL_MATERIAL_SPE

the specular identifier ;

 

TOOL_MATERIAL_EMI

the emissivity identifier ;

 

TOOL_MATERIAL_N_VALUES

number of used material identifiers.