diff options
| -rw-r--r-- | libcolour_marshal.3 | 86 | ||||
| -rw-r--r-- | libcolour_unmarshal.3 | 62 |
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 > |