.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)