.TH LIBLSS16_DECODE_TO_COLOUR_INDEX 3 LIBLSS16
.SH NAME
liblss16_decode_to_colour_index \- Decode an LSS16 image file

.SH SYNOPSIS
.nf
#include <liblss16.h>

enum liblss16_decode_state {
	LIBLSS16_DECODE_RUNNING,
	LIBLSS16_DECODE_END_OF_IMAGE,
	LIBLSS16_DECODE_ERROR
};

enum liblss16_decode_error {
	LIBLSS16_DECODE_TRUNCATED_MAGIC,
	LIBLSS16_DECODE_BAD_MAGIC,
	LIBLSS16_DECODE_TRUNCATED_HEADER,
	LIBLSS16_DECODE_BAD_IMAGE_SIZE,
	LIBLSS16_DECODE_BAD_COLOUR,
	LIBLSS16_DECODE_BAD_ROW_PADDING,
	LIBLSS16_DECODE_EXCESSIVE_RUN_LENGTH,
	LIBLSS16_DECODE_TRUNCATED_IMAGE
};

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_decoder {
	struct liblss16_header \fIimage\fP;
	/* internal fields omitted */
};

enum liblss16_decode_state liblss16_decode_to_colour_index(
	struct liblss16_decoder *\fIdecoder\fP,
	const void *\fIdata\fP, size_t \fIlength\fP, size_t *\fIconsumed_out\fP,
	uint8_t *\fIpixels\fP, size_t \fIpixels_size\fP, size_t *\fInpixels_out\fP,
	enum liblss16_decode_error *\fIerror_out\fP);
.fi
.PP
Link with
.IR -llss16 .

.SH DESCRIPTION
The
.BR liblss16_decode_to_colour_index ()
function decodes an image encoded in the LSS16 file format.
Before the decoding of a file is started
.I decoder
must be initialised with the
.BR liblss16_decoder_init (3)
function. The function is then repeatedly while it returns
.IR LIBLSS16_DECODE_RUNNING .
.PP
For each call, currently available file content is input in the
.I data
parameter, and the number of available bytes is input in the
.I length
parameter. After each call, the application shall discard the
.I *consumed_out
first bytes of
.I data
and decrease
.I length
by the same amount, but it may also append newly available
data, and increase
.I length
correspondingly.
.PP
The call shall provide a buffer for at least one pixel in the
.I pixels
parameter, and specify the number of pixels the buffer can
store in the
.I pixels_size
parameter. The function will set
.I *npixels_out
to the number of pixels output to the beginning of
.IR pixels .
Each pixel is encoded with a colour index, which is a non-negative
integer 15 or less. The function will set
.I decoder->image
the first time it sets
.I *npixels_out
to a non-zero value, or earlier. At this time, the width or height
of the image, in number of pixels, can be looked up in
.I decoder->image.width
and
.I decoder->image.height
respectively. Additionally the colour palette is also set, so the
colours of the returned pixels can be looked up. If the value
.I P
is returned for a pixel,
.I decoder->image.colour_map[P]
is a
.B struct liblss16_colour
that describes the pixel's colour;
.I .r
is an unsigned 8-bit integer value for the red component
of the pixel's sRGB colour, likewise
.I .g
is the green value and
.I .b
is the blue value.
.PP
.I decoder
must not be
.IR NULL .
.PP
.I data
may only be
.I NULL
if
.I length
is 0, which is used while still decoding
after then end of the file has been reached.
.PP
.I consumed_out
must not be
.IR NULL .
.PP
.I pixels
must not be null
.IR NULL ,
and
.I pixels_size
must not be 0.
.PP
.I npixels_out
must not be
.IR NULL .
.PP
.I error_out
shall either be
.I NULL
or a pointer to where the error code shall be
stored should the function fail.

.SH RETURN VALUE
The
.BR liblss16_decode_to_colour_index ()
function will returns the following values:
.TP
.B LIBLSS16_DECODE_RUNNING
The end of the image has not yet been reached.
The file if truncated if the end of the file is reached.
.TP
.B LIBLSS16_DECODE_END_OF_IMAGE
The end of the image is reched.
If the end of the file has not yet been reached, it
contains extraneous data.
.TP
.B LIBLSS16_DECODE_ERROR
A decoding error has occured, and processing most be
aborted. This always indicate that the file is corrupted
or not an LSS16 file.
.I *error_out
will be se to indicate the error unless
.I error_out
is
.IR NULL .
.PP
Note that
.I *npixels_out
and
.I *consumed_out
are always set.

.SH ERRORS
The
.BR liblss16_decode_to_colour_index ()
function fails for the following reasons:
.TP
.B LIBLSS16_DECODE_TRUNCATED_MAGIC
The file contains up to the first three bytes of the
LSS16 magic number, but is truncated and does not
contain the fourth byte.
.TP
.B LIBLSS16_DECODE_BAD_MAGIC
The file does not begin with the LSS16 magic number.
.TP
.B LIBLSS16_DECODE_TRUNCATED_HEADER
The file is too short to contain the full header.
.TP
.B LIBLSS16_DECODE_BAD_IMAGE_SIZE
The image width is 0, the image height is 0, or
the image height exceeds 32767.

.I decoder->image.width
and
.I decoder->image.height
will be set so each of the reasons apply can be
determined.
.TP
.B LIBLSS16_DECODE_BAD_COLOUR
The file is corrupt and the colour palette contains
a value greater than 63.
.TP
.B LIBLSS16_DECODE_BAD_ROW_PADDING
The file is corrupt and contains non-zero row padding.
.TP
.B LIBLSS16_DECODE_EXCESSIVE_RUN_LENGTH
The file is corrupt and contains a run length
crossing two or more rows of pixels.
.TP
.B LIBLSS16_DECODE_TRUNCATED_IMAGE
The file contains the full header, but is truncated
and does not contain the full image data.

.SH SEE ALSO
.BR liblss16_decode_strerror (3),
.BR liblss16_encode_from_colour_index (3),
.BR liblss16 (7)