cd-color: colord Reference Manual

## cd-color cd-color — Color object data functionality |

## Functions

const gchar * | cd_color_swatch_get_name ()
const CdColorLab * | cd_color_swatch_get_value ()
CdColorXYZ * | cd_color_xyz_new ()
CdColorLab * | cd_color_lab_new ()
CdColorRGB * | cd_color_rgb_new ()
CdColorYxy * | cd_color_yxy_new ()
CdColorUVW * | cd_color_uvw_new ()
CdColorSwatch * | cd_color_swatch_new ()
void | cd_color_xyz_free ()
void | cd_color_rgb_free ()
void | cd_color_lab_free ()
void | cd_color_yxy_free ()
void | cd_color_uvw_free ()
void | cd_color_swatch_free ()
CdColorXYZ * | cd_color_xyz_dup ()
CdColorLab * | cd_color_lab_dup ()
CdColorRGB * | cd_color_rgb_dup ()
CdColorYxy * | cd_color_yxy_dup ()
CdColorUVW * | cd_color_uvw_dup ()
CdColorSwatch * | cd_color_swatch_dup ()
void | cd_color_xyz_set ()
void | cd_color_rgb_set ()
void | cd_color_lab_set ()
void | cd_color_yxy_set ()
void | cd_color_uvw_set ()
void | cd_color_swatch_set_name ()
void | cd_color_swatch_set_value ()
void | cd_color_xyz_copy ()
void | cd_color_yxy_copy ()
void | cd_color_uvw_copy ()
void | cd_color_lab_copy ()
gdouble | cd_color_lab_delta_e76 ()
void | cd_color_xyz_clear ()
void | cd_color_rgb_copy ()
void | cd_color_rgb8_to_rgb ()
void | cd_color_rgb_to_rgb8 ()
void | cd_color_yxy_to_xyz ()
void | cd_color_xyz_to_yxy ()
void | cd_color_xyz_to_uvw ()
void | cd_color_yxy_to_uvw ()
void | cd_color_uvw_set_planckian_locus ()
gdouble | cd_color_uvw_get_chroma_difference ()
gboolean | cd_color_get_blackbody_rgb ()
gboolean | cd_color_get_blackbody_rgb_full ()
void | cd_color_rgb_interpolate ()
void | cd_color_rgb_from_wavelength ()
gdouble | cd_color_xyz_to_cct ()
void | cd_color_xyz_normalize ()
GPtrArray * | cd_color_rgb_array_new ()
gboolean | cd_color_rgb_array_is_monotonic ()
GPtrArray * | cd_color_rgb_array_interpolate ()

## Types and Values

| CdColorRGB8
enum | CdColorBlackbodyFlags

## Description

Functions to manipulate color values.

## Functions

### cd_color_swatch_get_name ()

    const gchar *
    cd_color_swatch_get_name (const CdColorSwatch *swatch);

Since: 0.1.32

### cd_color_swatch_get_value ()

    const CdColorLab *
    cd_color_swatch_get_value (const CdColorSwatch *swatch);

Since: 0.1.32

### cd_color_xyz_new ()

    CdColorXYZ *
    cd_color_xyz_new (void);

Allocates a color value.

#### Returns

A newly allocated CdColorXYZ object

Since: 0.1.0

### cd_color_lab_new ()

    CdColorLab *
    cd_color_lab_new (void);

Allocates a color value.

#### Returns

A newly allocated CdColorLab object

Since: 0.1.32

### cd_color_rgb_new ()

    CdColorRGB *
    cd_color_rgb_new (void);

Allocates a color value.

#### Returns

A newly allocated CdColorRGB object

Since: 0.1.0

### cd_color_yxy_new ()

    CdColorYxy *
    cd_color_yxy_new (void);

Allocates a color value.

#### Returns

A newly allocated CdColorYxy object

Since: 0.1.0

### cd_color_uvw_new ()

    CdColorUVW *
    cd_color_uvw_new (void);

Allocates a color value.

#### Returns

A newly allocated CdColorUVW object

Since: 1.1.6

### cd_color_swatch_new ()

    CdColorSwatch *
    cd_color_swatch_new (void);

Allocates a color value.

#### Returns

A newly allocated CdColorSwatch object

Since: 0.1.32

### cd_color_xyz_free ()

    void
    cd_color_xyz_free (CdColorXYZ *src);

Deallocates a color value.

#### Parameters

src | the color object |

Since: 0.1.0

### cd_color_rgb_free ()

    void
    cd_color_rgb_free (CdColorRGB *src);

Deallocates a color value.

#### Parameters

src | the color object |

Since: 0.1.0

### cd_color_lab_free ()

    void
    cd_color_lab_free (CdColorLab *src);

Deallocates a color value.

#### Parameters

src | the color object |

Since: 0.1.32

### cd_color_yxy_free ()

    void
    cd_color_yxy_free (CdColorYxy *src);

Deallocates a color value.

#### Parameters

src | the color object |

Since: 0.1.0

### cd_color_uvw_free ()

    void
    cd_color_uvw_free (CdColorUVW *src);

Deallocates a color value.

#### Parameters

src | the color object |

Since: 1.1.6

### cd_color_swatch_free ()

    void
    cd_color_swatch_free (CdColorSwatch *src);

Deallocates a color swatch.

#### Parameters

src | the color object |

Since: 0.1.32

### cd_color_xyz_dup ()

    CdColorXYZ *
    cd_color_xyz_dup (const CdColorXYZ *src);

Since: 0.1.27

### cd_color_lab_dup ()

    CdColorLab *
    cd_color_lab_dup (const CdColorLab *src);

Since: 0.1.32

### cd_color_rgb_dup ()

    CdColorRGB *
    cd_color_rgb_dup (const CdColorRGB *src);

Since: 0.1.27

### cd_color_yxy_dup ()

    CdColorYxy *
    cd_color_yxy_dup (const CdColorYxy *src);

Since: 0.1.27

### cd_color_uvw_dup ()

    CdColorUVW *
    cd_color_uvw_dup (const CdColorUVW *src);

Since: 1.1.6

### cd_color_swatch_dup ()

    CdColorSwatch *
    cd_color_swatch_dup (const CdColorSwatch *src);

Since: 0.1.32

### cd_color_xyz_set ()

    void
    cd_color_xyz_set (CdColorXYZ *dest,
                      gdouble X,
                      gdouble Y,
                      gdouble Z);

Initialises a color value.

#### Parameters

dest | the destination color |
X | component value |
Y | component value |
Z | component value |

Since: 0.1.27

### cd_color_rgb_set ()

    void
    cd_color_rgb_set (CdColorRGB *dest,
                      gdouble R,
                      gdouble G,
                      gdouble B);

Initialises a color value.

#### Parameters

dest | the destination color |
R | component value |
G | component value |
B | component value |

Since: 0.1.27

### cd_color_lab_set ()

    void
    cd_color_lab_set (CdColorLab *dest,
                      gdouble L,
                      gdouble a,
                      gdouble b);

Initialises a color value.

#### Parameters

dest | the destination color |
L | component value |
a | component value |
b | component value |

Since: 0.1.32

### cd_color_yxy_set ()

    void
    cd_color_yxy_set (CdColorYxy *dest,
                      gdouble Y,
                      gdouble x,
                      gdouble y);

Initialises a color value.

#### Parameters

dest | the destination color |
Y | component value |
x | component value |
y | component value |

Since: 0.1.27

### cd_color_uvw_set ()

    void
    cd_color_uvw_set (CdColorUVW *dest,
                      gdouble U,
                      gdouble V,
                      gdouble W);

Initialises a color value.

#### Parameters

dest | the destination color |
U | component value |
V | component value |
W | component value |

Since: 1.1.6

### cd_color_swatch_set_name ()

    void
    cd_color_swatch_set_name (CdColorSwatch *dest,
                              const gchar *name);

Initialises a swatch name.

#### Parameters

dest | the destination swatch |
name | component name |

Since: 0.1.32

### cd_color_swatch_set_value ()

    void
    cd_color_swatch_set_value (CdColorSwatch *dest,
                               const CdColorLab *value);

Initialises a swatch value.

#### Parameters

dest | the destination swatch |
value | component value |

Since: 0.1.32

### cd_color_xyz_copy ()

    void
    cd_color_xyz_copy (const CdColorXYZ *src,
                       CdColorXYZ *dest);

Deep copies a color value.

#### Parameters

src | the source color |
dest | the destination color |

Since: 0.1.27

### cd_color_yxy_copy ()

    void
    cd_color_yxy_copy (const CdColorYxy *src,
                       CdColorYxy *dest);

Deep copies a color value.

#### Parameters

src | the source color |
dest | the destination color |

Since: 0.1.27

### cd_color_uvw_copy ()

    void
    cd_color_uvw_copy (const CdColorUVW *src,
                       CdColorUVW *dest);

Deep copies a color value.

#### Parameters

src | the source color |
dest | the destination color |

Since: 1.1.6

### cd_color_lab_copy ()

    void
    cd_color_lab_copy (const CdColorLab *src,
                       CdColorLab *dest);

Deep copies a color value.

#### Parameters

src | the source color |
dest | the destination color |

Since: 0.1.32

### cd_color_lab_delta_e76 ()

    gdouble
    cd_color_lab_delta_e76 (const CdColorLab *p1,
                            const CdColorLab *p2);

Calculates the ΔE of two colors using the 1976 formula.

#### Parameters

p1 | Lab value 1 |
p2 | Lab value 2 |

#### Returns

distance metric, where JND ΔE ≈ 2.3

Since: 0.1.32

### cd_color_xyz_clear ()

    void
    cd_color_xyz_clear (CdColorXYZ *dest);

Initialises a color value.

#### Parameters

dest | the destination color |

Since: 0.1.27

### cd_color_rgb_copy ()

    void
    cd_color_rgb_copy (const CdColorRGB *src,
                       CdColorRGB *dest);

Deep copies a color value.

#### Parameters

src | the source color |
dest | the destination color |

Since: 0.1.27

### cd_color_rgb8_to_rgb ()

    void
    cd_color_rgb8_to_rgb (const CdColorRGB8 *src,
                          CdColorRGB *dest);

Convert from one color format to another.

#### Parameters

src | the source color |
dest | the destination color |

Since: 0.1.27

### cd_color_rgb_to_rgb8 ()

    void
    cd_color_rgb_to_rgb8 (const CdColorRGB *src,
                          CdColorRGB8 *dest);

Convert from one color format to another.

#### Parameters

src | the source color |
dest | the destination color |

Since: 0.1.27

### cd_color_yxy_to_xyz ()

    void
    cd_color_yxy_to_xyz (const CdColorYxy *src,
                         CdColorXYZ *dest);

Convert from one color format to another.

#### Parameters

src | the source color |
dest | the destination color |

Since: 0.1.27

### cd_color_xyz_to_yxy ()

    void
    cd_color_xyz_to_yxy (const CdColorXYZ *src,
                         CdColorYxy *dest);

Convert from one color format to another.

#### Parameters

src | the source color |
dest | the destination color |

Since: 0.1.27

### cd_color_xyz_to_uvw ()

    void
    cd_color_xyz_to_uvw (const CdColorXYZ *src,
                         const CdColorXYZ *whitepoint,
                         CdColorUVW *dest);

Convert from one color format to another.

#### Parameters

src | the source color |
whitepoint | the whitepoint |
dest | the destination color |

Since: 1.1.6

### cd_color_yxy_to_uvw ()

    void
    cd_color_yxy_to_uvw (const CdColorYxy *src,
                         CdColorUVW *dest);

Convert from one color format to another.

#### Parameters

src | the source color |
dest | the destination color |

Since: 1.1.6

### cd_color_uvw_set_planckian_locus ()

    void
    cd_color_uvw_set_planckian_locus (CdColorUVW *dest,
                                      gdouble temp);

Sets the CIEUVW color from a Planckian locus of specific temperature.

#### Parameters

dest | destination color |
temp | temperature in Kelvin |

Since: 1.1.6

### cd_color_uvw_get_chroma_difference ()

    gdouble
    cd_color_uvw_get_chroma_difference (const CdColorUVW *p1,
                                        const CdColorUVW *p2);

Gets the chromaticity distance in the CIE 1960 UCS.

#### Parameters

p1 | color |
p2 | color |

#### Returns

The Euclidean distance

Since: 1.1.6

### cd_color_get_blackbody_rgb ()

    gboolean
    cd_color_get_blackbody_rgb (guint temp,
                                CdColorRGB *result);

Get the blackbody color for a specific temperature. If the temperature range is outside 1000K to 10000K then the result is clipped.

#### Parameters

temp | the temperature in Kelvin |
result | the destination color |

#### Returns

TRUE if `temp` was in range and the result accurate

Since: 0.1.26

### cd_color_get_blackbody_rgb_full ()

    gboolean
    cd_color_get_blackbody_rgb_full (gdouble temp,
                                     CdColorRGB *result,
                                     CdColorBlackbodyFlags flags);

Get the blackbody color for a specific temperature. If the temperature range is outside 1000K to 10000K then the result is clipped.

#### Parameters

temp | the temperature in Kelvin |
result | the destination color |
flags | some CdColorBlackbodyFlags, e.g. `CD_COLOR_BLACKBODY_FLAG_USE_PLANCKIAN` |

#### Returns

TRUE if `temp` was in range and the result accurate

Since: 1.3.5

### cd_color_rgb_interpolate ()

    void
    cd_color_rgb_interpolate (const CdColorRGB *p1,
                              const CdColorRGB *p2,
                              gdouble index,
                              CdColorRGB *result);

Since: 0.1.26

### cd_color_rgb_from_wavelength ()

    void
    cd_color_rgb_from_wavelength (CdColorRGB *dest,
                                  gdouble wavelength);

Set an RGB color which is roughly representative to the wavelength.

#### Parameters

dest | a CdColorRGB for the RGB result |
wavelength | the wavelength roughly between 380nm and 780nm |

Since: 1.3.4

### cd_color_xyz_to_cct ()

    gdouble
    cd_color_xyz_to_cct (const CdColorXYZ *src);

Gets the correlated color temperature for the XYZ value.

#### Parameters

src | the source color |

Since: 1.1.6

### cd_color_xyz_normalize ()

    void
    cd_color_xyz_normalize (const CdColorXYZ *src,
                            gdouble max,
                            CdColorXYZ *dest);

Normalizes `src` to y=1.0

#### Parameters

src | the source color |
dest | the destination color |

Since: 1.1.6

### cd_color_rgb_array_new ()

    GPtrArray *
    cd_color_rgb_array_new (void);

Creates a new RGB array.

#### Returns

New array.

[element-type CdColorRGB][transfer full]

Since: 0.1.31

### cd_color_rgb_array_is_monotonic ()

    gboolean
    cd_color_rgb_array_is_monotonic (const GPtrArray *array);

Checks the array for monotonicity.

#### Parameters

array | Input array. | [element-type CdColorRGB]

#### Returns

`TRUE` if the array is monotonic

Since: 0.1.31

### cd_color_rgb_array_interpolate ()

    GPtrArray *
    cd_color_rgb_array_interpolate (const GPtrArray *array,
                                    guint new_length);

Interpolate the RGB array to a different size. This uses the Akima interpolation algorithm unless the array would become non-monotonic, in which case it falls back to linear interpolation.

#### Parameters

array | Input array. | [element-type CdColorRGB]
new_length | the target length of the return array |

#### Returns

An array of size `new_length` or `NULL`.

[element-type CdColorRGB][transfer full]

Since: 0.1.31

## Types and Values

### CdColorRGB8

    typedef struct {
    	guint8	 R;
    	guint8	 G;
    	guint8	 B;
    } CdColorRGB8;

### enum CdColorBlackbodyFlags

Flags used when returning an RGB color from a temperature.

#### Members

CD_COLOR_BLACKBODY_FLAG_NONE | No flags set. |
CD_COLOR_BLACKBODY_FLAG_USE_PLANCKIAN | Use Planckian below 5000K |

Since: 1.3.5