Add libcolour_marshal.3 and libcolour_unmarshal.3

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

2 files changed, 148 insertions, 0 deletions

diff --git a/libcolour_marshal.3 b/libcolour_marshal.3
new file mode 100644
index 0000000..9cbb0da
--- /dev/null
+++ b/libcolour_marshal.3
@@ -0,0 +1,86 @@
+.TH LIBCOLOUR_MARSHAL 3 libcolour
+.SH NAME
+libcolour_marshal - Marshal a colour record
+.SH SYNOPSIS
+.nf
+#include <libcolour.h>
+
+size_t \fBlibcolour_marshal_f\fP(const libcolour_colour_f_t *\fIcolour\fP, void *\fIbuffer\fP);
+size_t \fBlibcolour_marshal_lf\fP(const libcolour_colour_lf_t *\fIcolour\fP, void *\fIbuffer\fP);
+size_t \fBlibcolour_marshal_llf\fP(const libcolour_colour_ll_ft *\fIcolour\fP, void *\fIbuffer\fP);
+
+#define \fBlibcolour_marshal\fP(\fIcolour\fP, \fIbuffer\fP)\\
+	(_Generic((\fIvalue\fP),\\
+	          const libcolour_colour_f_t *:   \fBlibcolour_marshal_f\fP(\fIcolour\fP, \fIbuffer\fP),\\
+	          const libcolour_colour_lf_t *:  \fBlibcolour_marshal_lf\fP(\fIcolour\fP, \fIbuffer\fP),\\
+	          const libcolour_colour_llf_t *: \fBlibcolour_marshal_llf\fP(\fIcolour\fP, \fIbuffer\fP)))
+	          /* list is incomplete */
+.fi
+.SH DESCRIPTION
+.B libcolour_marshal
+and its non-generic functions stores a
+.I colour
+into a
+.IR buffer ,
+and returns the number of bytes written. If
+.B NULL
+is given instead of a
+.IR buffer ,
+the number of bytes that would have been written
+is returned.
+.P
+These function will always write an
+.B int
+that is used to identify the version of libcolour
+so it can be decoded by future versions.
+.P
+In addition to this
+.IR 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
+.I .model
+member if the colour is set to
+.BR LIBCOLOUR_SRGB ,
+no more than
+.BR sizeof(libcolour_srgb_f_t) ,
+.BR sizeof(libcolour_srgb_lf_t) ,
+or
+.BR sizeof(libcolour_srgb_llf_t) ,
+depending on which function is called,
+is written in addition to the initial
+.IR int .
+If the value of
+.I .model
+is invalid, 0 is returned and
+.I errno
+is set to
+.IR EINVAL .
+.P
+The written data is machine dependant.
+.SH RETURN VALUES
+Upon successful completion, the number of bytes
+written to
+.I buffer
+is returned, or if
+.I buffer
+is
+.BR NULL ,
+the number of bytes needed to to store the
+.IR colour .
+On error, 0 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I .model
+is invalid.
+.SH SEE ALSO
+.BR libcolour (7),
+.BR libcolour_unmarshal (3)
+.SH AUTHORS
+Mattias Andrée
+.RI < maandree@kth.se >
diff --git a/libcolour_unmarshal.3 b/libcolour_unmarshal.3
new file mode 100644
index 0000000..4a859d1
--- /dev/null
+++ b/libcolour_unmarshal.3
@@ -0,0 +1,62 @@
+.TH LIBCOLOUR_UNMARSHAL 3 libcolour
+.SH NAME
+libcolour_unmarshal - Unmarshal a colour record
+.SH SYNOPSIS
+.nf
+#include <libcolour.h>
+
+size_t \fBlibcolour_unmarshal_f\fP(libcolour_colour_f_t *\fIcolour\fP, const void *\fIbuffer\fP);
+size_t \fBlibcolour_unmarshal_lf\fP(libcolour_colour_lf_t *\fIcolour\fP, const void *\fIbuffer\fP);
+size_t \fBlibcolour_unmarshal_llf\fP(libcolour_colour_ll_ft *\fIcolour\fP, const void *\fIbuffer\fP);
+
+#define \fBlibcolour_unmarshal\fP(\fIcolour\fP, \fIbuffer\fP)\\
+	(_Generic((\fIvalue\fP),\\
+	          libcolour_colour_f_t *:   \fBlibcolour_unmarshal_f\fP(\fIcolour\fP, \fIbuffer\fP),\\
+	          libcolour_colour_lf_t *:  \fBlibcolour_unmarshal_lf\fP(\fIcolour\fP, \fIbuffer\fP),\\
+	          libcolour_colour_llf_t *: \fBlibcolour_unmarshal_llf\fP(\fIcolour\fP, \fIbuffer\fP)))
+	          /* list is incomplete */
+.fi
+.SH DESCRIPTION
+.B libcolour_unmarshal
+and its non-generic functions restores a
+.I colour
+from a
+.IR buffer
+and returns the number of bytes read.
+If
+.I colour
+is
+.BR NULL ,
+no
+.I colour
+is restored, the same value is returned.
+.P
+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 any of
+these functions.
+.SH RETURN VALUES
+Upon successful completion, the number of bytes
+read from
+.I buffer
+is returned.
+On error, 0 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+The stored
+.I .model
+is not recognised.
+.TP
+.B EINVAL
+The libcolour version, indicated by the first bytes in
+.BR buffer ,
+is not recognised.
+.SH SEE ALSO
+.BR libcolour (7),
+.BR libcolour_unmarshal (3)
+.SH AUTHORS
+Mattias Andrée
+.RI < maandree@kth.se >