diff options
Diffstat (limited to 'liblss16_decode_to_colour_index.3')
| -rw-r--r-- | liblss16_decode_to_colour_index.3 | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/liblss16_decode_to_colour_index.3 b/liblss16_decode_to_colour_index.3 new file mode 100644 index 0000000..797c4f5 --- /dev/null +++ b/liblss16_decode_to_colour_index.3 @@ -0,0 +1,221 @@ +.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) |