@node Functions
@chapter Functions

The following functions are available in @command{libcolour}:

@table @code
@item int libcolour_convert(const libcolour_colour_t* restrict, libcolour_colour_t* restrict)
Colour space and colour model conversion.
Described in @ref{Colour Spaces}.

@item double libcolour_srgb_encode(double)
Apply the sRGB transfer function.
Described in @ref{sRGB}.

@item double libcolour_srgb_decode(double)
Unapply the sRGB transfer function.
Described in @ref{sRGB}.

@item int libcolour_delta_e(const libcolour_colour_t*, const libcolour_colour_t*, double*)
Calculates the @math{\Delta E^*_{ab}} distance
(the distance in CIE L*a*b*) of two colours,
and outputs it to the last parameter.
Returns 0 on success and @math{-1} one error.
This function fails if and only if
@code{libcolour_convert} fails.

@item int libcolour_proper(libcolour_colour_t*)
Sets any member or submember that may be
incorrectly set. Returns 0 on success, and
@math{-1} on error. On error @code{errno}
set appropriately. Error is only possible
is there is something wrong with the described
colour space that cannot be fixed.

@item int libcolour_get_rgb_colour_space(libcolour_rgb_t*, libcolour_rgb_colour_space_t)
Selects RGB colour space.
Described in @ref{RGB}.

@item size_t libcolour_marshal(const libcolour_colour_t*, void*)
Store a colour into a buffer, and returns the number
of bytes written. If @code{NULL} is given instead of
a buffer, the number of bytes that would have been
written is returned.

This function will always write an @code{int} that
is used to identify the version of @command{libcolour}
so it can be decoded by future versions.

In addition to this @code{int}, all the content of
the structure is copied, so uninitialised values
can be copied. However, it will never copy more than
the size of the structure used to represent colours
with used colour model. For example, is the @code{.model}
member if the colour is set to @code{LIBCOLOUR_SRGB},
no more than @code{sizeof(libcolour_srgb_t)} is written
in addition to the initial @code{int}. If the value
of @code{.model} is invalid, 0 is returned and
@code{errno} is set to @code{EINVAL}.

The written data is machine architecture specific.

@item size_t libcolour_unmarshal(libcolour_colour_t*, const void*)
Restores a colour from a buffer, and returns the number
of bytes read. If @code{NULL} is given instead of
an output pointer for the colour, the number of bytes
that would have been read is returned.

If the stored @code{int} at the beginning does
not match a recognised version of @command{libcolour},
0 is returned and errno is set to @code{EINVAL}, this
also happens if the stored colour does not used
a recognised colour model.

If the stored colour uses a custom (not pre-defined)
RGB colour space with custom a transfer function, the
user must set them after calling @code{libcolour_unmarshal}.

@end table