@node Colour Spaces
@chapter Colour Spaces

@menu
* RGB Conversion::                          RGB colour space conversion functions.
@end menu


@command{libclut} has a number of functions for converting
between colour space models. The supported colour space models
are [0, 1] sRGB, [0, 1] linear sRGB, CIE xyY, CIE XYZ, CIE L*a*b*,
CIE 1976 (L*, u*, v*), CIELCh@sub{uv}, YIQ, YD@sub{b}D@sub{r},
YP@sub{b}P@sub{r}, YCgCo, CIE 1960 USC, CIE U*V*W*,

These functions are implemented as macros, but regular functions
are available either by putting the name in the function is
brackets, taking the address of the function, or by undefining
the macro with the name of the function.

@command{libclut} has two functions intended for internal use.
If the macro verions are used, their parameter must not have
any side-effets. Additionally their macro versions require
linking with @option{-lm}.

@table @code
@item double libclut_model_linear_to_standard1(double c)
Convert one component from [0, 1] linear sRGB to [0, 1] sRGB.
@item double libclut_model_standard_to_linear1(double c)
Convert one component from [0, 1] sRGB to [0, 1] linear sRGB.
@end table

@command{libclut} has ten functions that are intended for the
user to use, but some are used internally too. These functions'
parameters may have side-effects. All parameters are of the
type @code{double}, and they do not have a return value.

@table @code
@item libclut_model_linear_to_standard(*r. *g, *b)
Convert [0, 1] linear sRGB to [0, 1] sRGB.

The macro variant requires linking with @option{-lm}, if
the @code{libclut_model_linear_to_standard1} is defined,
otherwise it requires linking with @option{-lclut}.

Parameters:
@table @code
@item r
Pointer to the linear red component, and output parameter
for the red component.
@item g
Pointer to the linear green component, and output parameter
for the green component.
@item b
Pointer to the linear blue component, and output parameter
for the blue component.
@end table


@item libclut_model_standard_to_linear(*r, *g, *b)
Convert [0, 1] sRGB to [0, 1] linear sRGB.

The macro variant requires linking with @option{-lm}, if
the @code{libclut_model_standard_to_linear1} is defined,
otherwise it requires linking with @option{-lclut}.

Parameters:
@table @code
@item r
Pointer to the red component, and output parameter for the
linear red component.
@item g
Pointer to the green component, and output parameter for the
linear green component.
@item b
Pointer to the blue component, and output parameter for the
linear blue component.
@end table


@item libclut_model_ciexyy_to_ciexyz(x, y, Y, *X, *Z)
Convert CIE xyY to CIE XYZ.

Parameters:
@table @code
@item x
The x parameter.
@item y
The y parameter.
@item Y
The Y parameter. This is also the Y (middle) parameter
for the CIE XYZ colour.
@item X
Output parameter for the X parameter.
@item Z
Output parameter for the Z parameter.
@end table


@item libclut_model_ciexyz_to_ciexyy(X, Y, Z, *x, *y)
Convert CIE XYZ to CIE xyY.

Parameters:
@table @code
@item X
The X parameter.
@item Y
The Y parameter. This is also the Y (last) parameter
for the CIE xyY colour.
@item Z
The Z parameter.
@item x
Output parameter for the x parameter.
@item y
Output parameter for the y parameter.
@end table


@item libclut_model_ciexyz_to_linear(X, Y, Z, *r, *g, *b)
Convert CIE XYZ to [0, 1] linear sRGB.

Parameters:
@table @code
@item X
The X parameter.
@item Y
The Y parameter.
@item Z
The Z parameter.
@item r
Output parameter for the red component.
@item g
Output parameter for the green component.
@item b
Output parameter for the blue component.
@end table


@item libclut_model_linear_to_ciexyz(r, g, b, *X, *Y, *Z)
Convert [0, 1] linear sRGB to CIE XYZ.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item X
Output parameter for the X parameter.
@item Y
Output parameter for the Y parameter.
@item Z
Output parameter for the Z parameter.
@end table


@item libclut_model_srgb_to_ciexyy(r, g, b, *x, *y, *Y)
Convert [0, 1] linear sRGB to CIE xyY.

The macro variant requires linking with @option{-lclut}
if any of @code{libclut_model_ciexyz_to_ciexyy},
@code{libclut_model_linear_to_ciexyz}, and
@code{libclut_model_standard_to_linear} are undefined.
The macro variant requires linking with @option{-lm} if
neither @code{libclut_model_standard_to_linear} nor
@code{libclut_model_standard_to_linear1} are undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item x
Output parameter for the x parameter.
@item y
Output parameter for the y parameter.
@item Y
Output parameter for the Y parameter.
@end table


@item libclut_model_ciexyy_to_srgb(x, y, Y, *r, *g, *b)
Convert CIE xyY to [0, 1] sRGB.

The macro variant requires linking with @option{-lclut}
if any of @code{libclut_model_ciexyy_to_ciexyz},
@code{libclut_model_ciexyz_to_linear}, and
@code{libclut_model_linear_to_standard} are undefined.
The macro variant requires linking with @option{-lm} if
neither @code{libclut_model_linear_to_standard} nor
@code{libclut_model_linear_to_standard1} are undefined.

Parameters:
@table @code
@item x
The x parameter.
@item y
The y parameter.
@item Y
The Y parameter.
@item r
Output parameter for the red component.
@item g
Output parameter for the green component.
@item b
Output parameter for the blue component.
@end table


@item libclut_model_ciexyz_to_cielab(X, Y, Z, *L, *a, *b)
Convert from CIE XYZ to CIE L*a*b*.

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item X
The X parameter.
@item Y
The Y parameter.
@item Z
The Z parameter.
@item L
Output parameter for the L* component.
@item a
Output parameter for the a* component.
@item b
Output parameter for the b* component.
@end table


@item libclut_model_cielab_to_ciexyz(L, a, b, *X, *Y, *Z)
Convert from CIE L*a*b* to CIE XYZ.

Parameters:
@table @code
@item L
The L* component.
@item a
The a* component.
@item b
The b* component.
@item X
Output parameter for the X parameter.
@item Y
Output parameter for the Y parameter.
@item Z
Output parameter for the Z parameter.
@end table


@item libclut_model_ciexyz_to_cieluv(X, Y, Z, Xn, Yn, Zn, *L, *u, *v)
Convert from CIE XYZ to CIE 1976 (L*, u*, v*).

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item L
The X component.
@item a
The Y component.
@item b
The Z component.
@item Xn
The X component of the specified white object (white point).
@item Yn
The Y component of the specified white object (white point).
@item Zn
The Z component of the specified white object (white point).
@item X
Output parameter for the L* parameter.
@item Y
Output parameter for the u* parameter.
@item Z
Output parameter for the v* parameter.
@end table


@item libclut_model_cieluv_to_ciexyz(L, u, v, Xn, Yn, Zn, *X, *Y, *Z)
Convert from CIE 1976 (L*, u*, v*) to CIE XYZ.

Parameters:
@table @code
@item L
The L* component.
@item a
The u* component.
@item b
The v* component.
@item Xn
The X component of the specified white object (white point).
@item Yn
The Y component of the specified white object (white point).
@item Zn
The Z component of the specified white object (white point).
@item X
Output parameter for the X parameter.
@item Y
Output parameter for the Y parameter.
@item Z
Output parameter for the Z parameter.
@end table


@item libclut_model_cielch_to_cieluv(C, h, *u, *v)
Convert from CIE LCh@sub{uv} to CIE 1976 (L*, u*, v*).

The L* component remains unchanged.

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item C
The C*@sub{uv} component.
@item h
The h@sub{uv} component.
@item u
Output parameter for the u* parameter.
@item v
Output parameter for the v* parameter.
@end table


@item libclut_model_cieluv_to_cielch(u, v, *C, *h)
Convert from CIE 1976 (L*, u*, v*) to CIE LCh@sub{uv}.

The L* component remains unchanged.

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item a
The u* component.
@item b
The v* component.
@item C
Output parameter for the C*@sub{uv} parameter.
@item h
Output parameter for the h@sub{uv} parameter.
@end table


@item libclut_model_srgb_to_yiq(r, g, b, *Y, *I, *Q)
Convert from [0, 1] sRGB to YIQ.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_standard_to_linear1} has been
undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item Y
Output parameter for the Y parameter.
@item I
Output parameter for the I parameter.
@item Q
Output parameter for the Q parameter.
@end table


@item libclut_model_yiq_to_srgb(Y, I, Q, *r, *g, *b)
Convert from YIQ to [0, 1] sRGB.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_linear_to_standard1} has been
undefined.

Parameters:
@table @code
@item Y
The Y component.
@item I
The I component.
@item Q
The Q component.
@item r
Output parameter for the red parameter.
@item g
Output parameter for the green parameter.
@item b
Output parameter for the blue parameter.
@end table


@item libclut_model_srgb_to_ydbdr(r, g, b, *Y, *Db, *Dr)
Convert from [0, 1] sRGB to YD@sub{b}D@sub{r}.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_standard_to_linear1} has been
undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item Y
Output parameter for the Y parameter.
@item Db
Output parameter for the D@sub{b} parameter.
@item Dr
Output parameter for the D@sub{r} parameter.
@end table


@item libclut_model_ydbdr_to_srgb(Y, Db, Dr, *r, *g, *b)
Convert from YD@sub{b}D@sub{r} to [0, 1] sRGB.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_linear_to_standard1} has been
undefined.

Parameters:
@table @code
@item Y
The Y component.
@item Db
The D@sub{b} component.
@item Dr
The D@sub{r} component.
@item r
Output parameter for the red parameter.
@item g
Output parameter for the green parameter.
@item b
Output parameter for the blue parameter.
@end table


@item libclut_model_yuv_to_ydbdr(U, V, *Db, *Dr)
Convert from YUV to YD@sub{b}D@sub{r}.

The Y component remains unchanged.

Parameters:
@table @code
@item Y
The U component.
@item V
The V component.
@item Db
Output parameter for the D@sub{b} parameter.
@item Dr
Output parameter for the D@sub{r} parameter.
@end table


@item libclut_model_ydbdr_to_yuv(Db, Dr, *U, *V)
Convert from YD@sub{b}D@sub{r} to YUV.

The Y component remains unchanged.

Parameters:
@table @code
@item Db
The D@sub{b} component.
@item Dr
The D@sub{r} component.
@item U
Output parameter for the U parameter.
@item V
Output parameter for the V parameter.
@end table


@item libclut_model_srgb_to_ypbpr(r, g, b, *Y, *Pb, *Pr)
Convert from [0, 1] sRGB to YP@sub{b}P@sub{r}.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_standard_to_linear1} has been
undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item Y
Output parameter for the Y parameter.
@item Pb
Output parameter for the P@sub{b} parameter.
@item Pr
Output parameter for the P@sub{r} parameter.
@end table


@item libclut_model_ypbpr_to_srgb(Y, Pb, Pr, *r, *g, *b)
Convert from YP@sub{b}P@sub{r} to [0, 1] sRGB.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_linear_to_standard1} has been
undefined.

Parameters:
@table @code
@item Y
The Y component.
@item Pb
The P@sub{b} component.
@item Pr
The P@sub{r} component.
@item r
Output parameter for the red parameter.
@item g
Output parameter for the green parameter.
@item b
Output parameter for the blue parameter.
@end table


@item libclut_model_srgb_to_ycgco(r, g, b, *Y, *Cg, *Co)
Convert from [0, 1] sRGB to YCgCo.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_standard_to_linear1} has been
undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item Y
Output parameter for the Y parameter.
@item Cg
Output parameter for the Cg parameter.
@item Co
Output parameter for the Co parameter.
@end table


@item libclut_model_ycgco_to_srgb(Y, Cg, Co, *r, *g, *b)
Convert from YCgCo to [0, 1] sRGB.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_linear_to_standard1} has been
undefined.

Parameters:
@table @code
@item Y
The Y component.
@item Cg
The Cg component.
@item Co
The Co component.
@item r
Output parameter for the red parameter.
@item g
Output parameter for the green parameter.
@item b
Output parameter for the blue parameter.
@end table


@item libclut_model_cie_1960_ucs_to_ciexyz(u, v, Y, *x, *y, *z)
Convert from CIE 1960 UCS to CIE XYZ.

Parameters:
@table @code
@item u
The u component.
@item v
The v component.
@item Y
The Y component.
@item x
Output parameter for the X parameter.
@item y
Output parameter for the Y parameter.
@item z
Output parameter for the Z parameter.
@end table


@item libclut_model_ciexyz_to_cie_1960_ucs(x, y, z, *u, *v, *Y)
Convert from CIE XYZ to CIE 1960 UCS.

Parameters:
@table @code
@item x
The X component.
@item y
The Y component.
@item z
The Z component.
@item u
Output parameter for the u parameter.
@item v
Output parameter for the v parameter.
@item Y
Output parameter for the Y parameter.
@end table


@item libclut_model_cie_1960_ucs_to_cieuvw(U, V, W, u0, v0, *x, *y, *z)
Convert from CIE 1960 UCS to CIE U*V*W*.

Parameters:
@table @code
@item U
The U* component.
@item V
The V* component.
@item W
The W* component.
@item u0
The u parameter for the white point.
@item v0
The v parameter for the white point.
@item x
Output parameter for the X parameter.
@item y
Output parameter for the Y parameter.
@item z
Output parameter for the Z parameter.
@end table


@item libclut_model_cieuvw_to_cie_1960_ucs(x, y, z, u0, v0, *U, *V, *W)
Convert from CIE U*V*W* to CIE 1960 UCS.

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item x
The X component.
@item y
The Y component.
@item z
The Z component.
@item u0
The u parameter for the white point.
@item v0
The v parameter for the white point.
@item U*
Output parameter for the u parameter.
@item V*
Output parameter for the v parameter.
@item W*
Output parameter for the Y parameter.
@end table
@end table


@node RGB Conversion
@section RGB Conversion

@command{libclut} provides a functions for converting
RGB values between RGB colour spaces. An RGB colour space
is described using @code{struct libclut_rgb_colour_space}
(also known as @code{libclut_rgb_colour_space_t}). It
describes the colour of the red, green, and blue,
stimuli as well as the white point, in CIE xyY. It does
however not describe the colour space's gamma function,
because sRGB uses a irregular gamma function, and
ECI@tie{}RGB@tie{}v2 uses L*. The structure contains
the following @code{double}:s:

@table @code
@item red_x
The CIE xyY x-value of the red stimulus.
@item red_y
The CIE xyY y-value of the red stimulus.
@item red_Y
The CIE xyY Y-value of the red stimulus.
@item green_x
The CIE xyY x-value of the green stimulus.
@item green_y
The CIE xyY y-value of the green stimulus.
@item green_Y
The CIE xyY Y-value of the green stimulus.
@item blue_x
The CIE xyY x-value of the blue stimulus.
@item blue_y
The CIE xyY y-value of the blue stimulus.
@item blue_Y
The CIE xyY Y-value of the blue stimulus.
@item white_x
The CIE xyY x-value of the white point.
@item white_y
The CIE xyY y-value of the white point.
@item white_Y
The CIE xyY Y-value of the white point.
@end table

@code{libclut} provides macros used to initialise a
@code{struct libclut_rgb_colour_space} with values
for a number of RGB colour spaces. These are listed
below, along with the gamma each colour space uses.

@multitable {PAL/SECAM RGB} {@b{Gamma}} {@code{LIBCLUT_RGB_COLOUR_SPACE_WIDE_GAMUT_RGB_INITIALISER}}
@item
@b{Model}
@tab
@b{Gamma}
@tab
@b{Initialiser}
@item
sRGB
@tab
sRGB
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_SRGB_INITIALISER}
@item
Adobe RGB (1998)
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ADOBE_RGB_INITIALISER}
@item
Apple RGB
@tab
1.8
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_APPLE_RGB_INITIALISER}
@item
Best RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_BEST_RGB_INITIALISER}
@item
Beta RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_BETA_RGB_INITIALISER}
@item
Bruce RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_BRUCE_RGB_INITIALISER}
@item
CIE RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_CIE_RGB_INITIALISER}
@item
ColorMatch RGB
@tab
1.8
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_COLORMATCH_RGB_INITIALISER}
@item
Don RGB 4
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_DON_RGB_4_INITIALISER}
@item
ECI RGB v2
@tab
L*
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ECI_RGB_V2_INITIALISER}
@item
Ekta Space PS5
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_EKTA_SPACE_PS5_INITIALISER}
@item
ITU-R BT.709@footnote{ITU-R Recommendation BT.709}
@tab
2.4
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ITU_R_BT_709_INITIALISER}
@item
Lightroom RGB
@tab
1.0
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_LIGHTROOM_RGB_INITIALISER}
@item
NTSC RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_NTSC_RGB_INITIALISER}
@item
PAL/SECAM RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_PAL_SECAM_RGB_INITIALISER}
@item
ProPhoto RGB
@tab
1.8
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_PROPHOTO_RGB_INITIALISER}
@item
SMPTE-C RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_SMPTE_C_RGB_INITIALISER}
@item
Wide Gamut RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_WIDE_GAMUT_RGB_INITIALISER}
@end multitable

To create a description for the sRGB colour space write:

@example
struct libclut_rgb_colour_space srgb = \
        LIBCLUT_RGB_COLOUR_SPACE_SRGB_INITIALISER;
@end example

@command{libgamma} and @command{libcoopgamma} can be used
to get the x and y values of the user's monitors' red,
green, and blue stimuli. Otherwise, all values specified
by @code{LIBCLUT_RGB_COLOUR_SPACE_SRGB_INITIALISER} can
be used, and the sRGB gamma function can be used. However,
the Y values of the stimuli may be off, however, this does
not affect conversion.

sRGB uses an irregular gamma function. @command{libclut}
assumes that the colour spaces uses this gamma function
when converting between RGB colour spaces. If you want to
convert from a colour space with another gamma function,
you must first convert the gamma function. This can be
done by linearising the values and then use
@code{libclut_model_linear_to_standard1},
@code{libclut_model_linear_to_standard}, or
@code{libclut_standardise}. If you want to convert to a
colour spce with another gamma function, you must after
the conversion also convert the gamma function. This can
be done by using @code{libclut_model_standard_to_linear1},
@code{libclut_model_standard_to_linear}, or
@code{libclut_linearise}, and then converting from linear
to the proper gamma function. Note that even if you are
converting between two colour spaces with the same gamma
function, gamma function conversion must be done (before
and after) unless they use the sRGB gamma function.

Before RGB colour space conversion can be done, you need
to create a conversion matrix. It has the type

@example
typedef double libclut_colour_space_conversion_matrix_t[3][3];
@end example

@noindent
and can be created with
@table @code
@item int libclut_model_get_rgb_conversion_matrix(*from, *to, M, Minv)
Create a conversion matrix from one RGB colour space to another
RGB colour space, and optionally a matrix for an inverse conversion.

Returns 0 on success, and -1 on error. The only possible error is
@code{EINVAL}, which indicates that there is something wrong with
the colour spaces and a conversion matrix cannot be created.

This function is not available as a macro, thus, linking with
@option{-lclut} is required.

Parameters:
@table @code
@item const libclut_rgb_colour_space_t* from
Description of the input colour space. CIE XYZ is
used use if this parameter is @code{NULL}.
@item const libclut_rgb_colour_space_t* to
Description of the output colour space. CIE XYZ is
used use if this parameter is @code{NULL}.
@item libclut_colour_space_conversion_matrix_t M
Matrix to fill with values so it can be used for
converting from the input colour space to the
output colour space.
@item libclut_colour_space_conversion_matrix_t Minv
Matrix to fill with values so it can be used for
converting from the output colour space to the
input colour space. (That is, inverse conversion.)
This parameter may be @code{NULL}.
@end table
@end table

You can also create the matrix manually. If you for example
have a @code{libclut_colour_space_conversion_matrix_t} named
@code{M}, and want to set the cell at row 1 and column 3, to
0.5, you make the assignment @code{M[0][2] = 0.5}.

Once you have your conversion matrix, @command{libclut} has
three macro functions you can used to convert colours between
RGB colour space. Remember that they require the sRGB gamma
function.

@table @code
@item libclut_model_convert_rgb(r, g, b, M, *out_r, *out_g, *out_b)
Convert a single RGB colour into another RGB colour space.
The colour space must have same gamma functions as sRGB.

This macro is also available a function. If the function is
used, linking with @option{-lclut} is required, otherwise,
linking with @option{-lm} is required, or @option{-lclut} if
@code{libclut_model_standard_to_linear1} or
@code{libclut_model_linear_to_standard1} is undefined.

Parameters:
@table @code
@item double r
The red value of the colour to convert.
@item double g
The green value of the colour to convert.
@item double b
The blue value of the colour to convert.
@item libclut_colour_space_conversion_matrix_t M
The conversion matrix.
@item double* out_r
Output parameter for the red value of the colour after conversion.
@item double* out_g
Output parameter for the green value of the colour after conversion.
@item double* out_b
Output parameter for the blue value of the colour after conversion.
@end table


@item libclut_convert_rgb_inplace(clut, max, type, m, trunc)
Convert the curves between two RGB colour spaces.

The red, green, and blue ramps must be of the same size.

None of the parameter may have side-effects.

Requires linking with @option{-lm}, or @option{-lclut} if
@code{libclut_model_standard_to_linear1},
@code{libclut_model_linear_to_standard1}, or
@code{libclut_model_convert_rgb}  is undefined.

Parameters:
@table @code
@item clut
Pointer to the gamma ramps to convert. This must be a pointer to
an instance of a struct that must at least have the array members
@code{red}, @code{green}, and @code{blue}, whose elements shall be
of the type specified by the parameter @code{type}. The @code{struct}
must also have the scalar members @code{red_size}, @code{green_size},
and @code{blue_size}, and shall be of the type @code{size_t}; they
shall specify the number of stops (elements) in the arrays @code{.red},
@code{.green}, and @code{.blue}, respectively, which shall be the
gamma ramp for the red, green, and blue channels respectively. Its
values will be modified to the new values.
@item max
The maximum value on each stop in the ramps.
@item type
The data type used for each stop in the ramps.
@item libclut_colour_space_conversion_matrix_t m
Conversion matrix.
@item int trunc
If this is a non-zero value, resulting colours that are
out of gamut are truncated. (Not necessarily the best
approximation.)
@end table


@item libclut_convert_rgb(clut, max, type, m, trunc, out)
Convert the curves between two RGB colour spaces.

This is a slower version of @code{libclut_convert_rgb_inplace}
that supports clut:s where the red, green, and blue ramps
are not of the same size.

None of the parameter may have side-effects.

Requires linking with @option{-lm}. If
@code{libclut_model_linear_to_standard1},
@code{libclut_model_standard_to_linear1}, or
@code{libclut_model_convert_rgb} has been undefined,
linking with @option{-lclut} is also required.

Parameters:
@table @code
@item clut
Pointer to the gamma ramps to convert. This must be a pointer to
an instance of a struct that must at least have the array members
@code{red}, @code{green}, and @code{blue}, whose elements shall be
of the type specified by the parameter @code{type}. The @code{struct}
must also have the scalar members @code{red_size}, @code{green_size},
and @code{blue_size}, and shall be of the type @code{size_t}; they
shall specify the number of stops (elements) in the arrays @code{.red},
@code{.green}, and @code{.blue}, respectively, which shall be the
gamma ramp for the red, green, and blue channels respectively. Its
values are not modified.
@item max
The maximum value on each stop in the ramps.
@item type
The data type used for each stop in the ramps.
@item libclut_colour_space_conversion_matrix_t m
Conversion matrix.
@item int trunc
If this is a non-zero value, resulting colours that are
out of gamut are truncated. (Not necessarily the best
approximation.)
@item clut
Pointer to the gamma ramps of the output values. Shall be of
the same data type as @code{clut}. And have the same values on
@code{.red_size}, @code{.green_size}, and @code{.blue_size} as
@code{clut}.
@end table
@end table

There is also two functions for converting between a custom RGB
colour space and CIE XYZ, one function in each direction. Note
that the three functions above do not work if one of the colour
spaces is CIE XYZ.

@table @code
@item libclut_model_rgb_to_ciexyz(r, g, b, M, *X, *Y, *Z)
Convert a single RGB colour if a custom RGB colour space
to CIE XYZ.

The RGB colour space must have the same gamma function as sRGB.

This macro is also available a function. If the function is
used, linking with @option{-lclut} is required, otherwise,
linking with @option{-lm} is required, or @option{-lclut} if
@code{libclut_model_standard_to_linear1} is undefined.

Parameters:
@table @code
@item double r
The red component.
@item double g
The green component.
@item double b
The blue component.
@item libclut_colour_space_conversion_matrix_t M
The conversion matrix.
@item double* X
Output parameter for the X component.
@item double* Y
Output parameter for the Y component.
@item double* Z
Output parameter for the Z component.
@end table


@item libclut_model_rgb_to_ciexyz(X, Y, Z, M, *r, *g, *b)
Convert a single colour from CIE XYZ to a custom RGB colour space.

The RGB colour space must have the same gamma function as sRGB.

This macro is also available a function. If the function is
used, linking with @option{-lclut} is required, otherwise,
linking with @option{-lm} is required, or @option{-lclut} if
@code{libclut_model_linear_to_standard1} is undefined.

Parameters:
@table @code
@item double X
The X component.
@item double Y
The Y component.
@item double Z
The Z component.
@item libclut_colour_space_conversion_matrix_t M
The conversion matrix.
@item double* r
Output parameter for the red component.
@item double* g
Output parameter for the green component.
@item double* b
Output parameter for the blue component.
@end table
@end table