1 files changed, 125 insertions, 0 deletions
diff --git a/liblss16_encoder_init.3 b/liblss16_encoder_init.3
new file mode 100644
index 0000000..b5f37f9
--- /dev/null
+++ b/liblss16_encoder_init.3
@@ -0,0 +1,125 @@
+.TH LIBLSS16_ENCODER_INIT 3 LIBLSS16
+.SH NAME
+liblss16_encoder_init \- Prepare state for encoding LSS16 image file
+
+.SH SYNOPSIS
+.nf
+#include <liblss16.h>
+
+enum liblss16_encode_error {
+	LIBLSS16_ENCODE_BAD_IMAGE_SIZE,
+	LIBLSS16_ENCODE_BAD_COLOUR
+};
+
+struct liblss16_colour {
+	uint8_t \fIr\fP;
+	uint8_t \fIg\fP;
+	uint8_t \fIb\fP;
+};
+
+struct liblss16_header {
+	uint16_t \fIwidth\fP;
+	uint16_t \fIheight\fP;
+	struct liblss16_colour \fIcolour_map\fP[16];
+};
+
+struct liblss16_encoder { /* fields omitted */ };
+
+int liblss16_encoder_init(struct liblss16_encoder *\fIencoder\fP,
+                          const struct liblss16_header *\fIheader\fP, int \fIrgb6\fP,
+                          enum liblss16_encode_error *\fIerror_out\fP);
+.fi
+.PP
+Link with
+.IR -llss16 .
+
+.SH DESCRIPTION
+The
+.BR liblss16_encoder_init ()
+function initialises
+.I *encoder
+for the first call to the
+.BR liblss16_encode_from_colour_index (3)
+function.
+.PP
+.I header->width
+shall be the width, in pixels, of the image.
+.PP
+.I header->height
+shall be the height, in pixels, of the image.
+.PP
+.I header->colour_map
+shall be the image's colour palette. Each
+.B struct liblss16_colour
+is encoded in sRGB with either 6 bits per channel
+or 8 bits per channel
+.RI ( .r
+for the red channel,
+.I .g
+for the green channel, and
+.I .b
+for the blue channel).
+.PP
+If
+.I rgb6
+is zero, each
+.B struct liblss16_colour is encoded with 8 bits
+per channel, and scaled down to 6 bits by the
+function (the scaled down value will be stored in
+.I *header
+and output when ending the file).
+.PP
+If
+.I rgb6
+is non-zero, each
+.B struct liblss16_colour is encoded with 6 bits
+per channel, and the function will validate that
+the 2 highest bits in each value is cleared.
+.PP
+.I error_out
+shall either be
+.I NULL
+or a pointer to where the error code shall be
+stored should the function fail.
+.PP
+Before calling the
+.BR liblss16_encoder_init ()
+function, the application may choose to call the
+.BR liblss16_optimise (3)
+function.
+
+.SH RETURN VALUE
+The
+.BR liblss16_encoder_init ()
+function returns 0 upon successful
+completion. On failure, returns -1
+and sets
+.I *error_out
+(unless
+.I error_out
+is
+.IR NULL )
+to indicate the error.
+
+.SH ERRORS
+The
+.BR liblss16_encoder_init ()
+function will fail for the following reasons:
+.TP
+.B LIBLSS16_ENCODE_BAD_IMAGE_SIZE
+The image width was 0.
+.TP
+.B LIBLSS16_ENCODE_BAD_IMAGE_SIZE
+The image height was 0.
+.TP
+.B LIBLSS16_ENCODE_BAD_IMAGE_SIZE
+The image height was greater than 32767.
+.TP
+.B LIBLSS16_ENCODE_BAD_COLOUR
+.I rgb6
+was non-zero, and one of the colour values
+was create than 63.
+
+.SH SEE ALSO
+.BR liblss16_encode_strerror (3),
+.BR liblss16 (7)