info: functions

Signed-off-by: Mattias Andrée <maandree@kth.se>

2 files changed, 78 insertions, 0 deletions

diff --git a/doc/info/chap/functions.texinfo b/doc/info/chap/functions.texinfo
new file mode 100644
index 0000000..9f98353
--- /dev/null
+++ b/doc/info/chap/functions.texinfo
@@ -0,0 +1,75 @@
+@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.
+
+@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
+
diff --git a/doc/info/content.texinfo b/doc/info/content.texinfo
index eee47a3..4ad71d5 100644
--- a/doc/info/content.texinfo
+++ b/doc/info/content.texinfo
@@ -11,6 +11,7 @@
 * Overview::                                Brief overview of @command{libcolour}.
 * Colour Spaces::                           Colour-space conversion.
 * Illuminants::                             Illuminant initialisers.
+* Functions::                               Functions available in @command{libcolour}.
 
 * Free Software Needs Free Documentation::  Why free documentation is important.
 * GNU General Public License::              Copying and sharing @command{libcolour}.
@@ -39,6 +40,7 @@ Colour Spaces
 
 Illuminants
 
+Functions
 
 Free Software Needs Free Documentation
 
@@ -53,6 +55,7 @@ GNU Free Documentation License
 @include chap/overview.texinfo
 @include chap/colour-spaces.texinfo
 @include chap/illuminants.texinfo
+@include chap/functions.texinfo
 
 @include appx/free-software-needs-free-documentation.texinfo