@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 RGB, CIE xyY, CIE XYZ, and CIE Lab.
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 RGB to [0, 1] sRGB.
@item double libclut_model_standard_to_linear1(double c)
Convert one component from [0, 1] sRGB to [0, 1] linear RGB.
@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 RGB 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 RGB.

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

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 RGB 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 RGB 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 @code{-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
@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
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
@code{-lclut} is required.

Parameters:
@table @code
@item const libclut_rgb_colour_space_t* from
Description of the input colour space.
@item const libclut_rgb_colour_space_t* to
Description of the output colour space.
@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 RGB.

This macro is also available a function. If the function is
used, linking with @code{-lclut} is required, otherwise,
linking with @code{-lm} is required, or @code{-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 @code{-lm}, or @code{-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 @code{-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 @code{-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