/**
 * RLE related compressions
 *
 * @file	platon/compress/rle.h
 * @author	iMatix SFL project team <sfl@imatix.com>
 * @version	\$Platon: $
 * @date	2004
 *
 * These subroutines are extracted from Standard Function Library (SFL)
 * created by iMatix Corporation.
 */

#ifndef _PLATON_COMPRESS_RLE_H
#define _PLATON_COMPRESS_RLE_H

#ifndef PLATON_FUNC
# define PLATON_FUNC(_name) _name
#endif
#ifndef PLATON_FUNC_STR
# define PLATON_FUNC_STR(_name) #_name
#endif

#ifdef __cplusplus
extern "C" {
#endif

	/**
	 * Compresses a block using RLE algorithm
	 *
	 * @param		src			uncompressed data
	 * @param		dst			compressed data
	 * @param		src_size	size of uncompressed data
	 * @return		size of compressed data
	 *
	 * Takes a block of uncompressed data in src, compresses it using a RLE
	 * algorithm and places the result in dst. To decompress the data, use
	 * the uncompress_rle() function. Returns the size of the compressed data.
	 * The dst buffer should be 10% larger than the src buffer. The src buffer
	 * must be at least src_size + 1 bytes long. It may be modified. The
	 * compressed data contains these strings:
	 *
	 * <PRE>
	 * [01-7F][data...]     String of uncompressed data, 1 to 127 bytes.
	 * [83-FF][byte]        Run of 3 to 127 identical bytes.
	 * [80][len][byte]      Run of 128 to 255 identical bytes.
	 * [81][lo][hi][byte]   Run of 256 to 2^16 identical bytes.
	 * [82][len]            Run of 3 to 255 spaces.
	 * [00][len]            Run of 3 to 255 binary zeroes.
	 * </PRE>
	 */
	int PLATON_FUNC(compress_rle)
		(unsigned char *src, unsigned char *dst, int src_size);

	/**
	 * Expands a block of data previously compressed using
	 * the compress_rle() function
	 *
	 * @param		src			compressed data
	 * @param		dst			uncompressed data
	 * @param		src_size	size of uncompressed data
	 * @return		size of uncompressed data
	 *
	 * The compressed block is passed in src; the expanded result in dst.
	 * Array dst must be large enough to accomodate the largest possible
	 * decompressed block. Returns the size of the expanded data.
	 */
	int PLATON_FUNC(uncompress_rle)
		(const unsigned char *src, unsigned char *dst, int src_size);

	/**
	 * Compresses a block using RLE algorithm optimised towards compression
	 * of binary zeroes
	 *
	 * @param		src			uncompressed data
	 * @param		dst			compressed data
	 * @param		src_size	size of uncompressed data
	 * @return		size of compressed data
	 *
	 * Use this when you are certain that the sparse areas are set to binary
	 * zeroes. You must use uncompress_nulls() to decompress a block compressed
	 * with this function. Returns the size of the compressed data. The dst
	 * buffer should be 10% larger than the src buffer. The src buffer must be
	 * at least src_size + 1 bytes long. It may be modified. The compressed
	 * data contains these strings:
	 *
	 * <PRE>
	 * [01-7F][data...]        String of uncompressed data, 1 to 127 bytes.
	 * [82-FF]                 Run of 2 to 127 binary zeroes.
	 * [81][80-FF]             Run of 128 to 255 binary zeroes.
	 * [80][lo][hi]            Run of 256 to 2^16 binary zeroes.
	 * [00][len][byte]         Run of 4 to 255 identical bytes.
	 * [00][00][lo][hi][byte]  Run of 256 to 2^16 identical bytes.
	 * </PRE>
	 */
	int PLATON_FUNC(compress_nulls)
		(unsigned char *src, unsigned char *dst, int src_size);

	/**
	 * Expands a block of data previously compressed using
	 * the compress_nulls() function
	 *
	 * @param		src			compressed data
	 * @param		dst			uncompressed data
	 * @param		src_size	size of uncompressed data
	 * @return		size of uncompressed data
	 *
	 * The compressed block is passed in src; the expanded result in dst.
	 * Array dst must be large enough to accomodate the largest possible
	 * decompressed block. Returns the size of the expanded data.
	 */
	int PLATON_FUNC(uncompress_nulls)
		(const unsigned char *src, unsigned char *dst, int src_size);

	/**
	 * Compresses a block using RLE algorithm optimised towards compression
	 * of sparse bitmaps
	 *
	 * @param		src			uncompressed data
	 * @param		dst			compressed data
	 * @param		src_size	size of uncompressed data
	 * @return		size of compressed data
	 *
	 * Use this when you are playing with large, sparse bitmaps. You must use
	 * uncompress_bits() to decompress a block compressed with this function.
	 * Returns the size of the compressed data. The dst buffer should be 10%
	 * larger than the src buffer for worst cases. The src buffer must be at
	 * least src_size + 1 bytes long. It may be modified. The compressed data
	 * contains these strings:
	 *
	 * <PRE>
	 * [00-07]                 Single byte containing a bit in position 0 to 7.
	 * [08-7F][data...]        String of uncompressed data, 1 to 120 bytes.
	 * [82-FF]                 Run of 1 to 126 binary zeroes.
	 * [81][00-FD]             Run of 127 to 380 binary zeroes.
	 * [81][FE][len][byte]     Run of 4 to 255 identical bytes.
	 * [81][FF][lo][hi][byte]  Run of 256 to 2^16 identical bytes.
	 * [80][lo][hi]            Run of 381 to 2^16 binary zeroes.
	 * </PRE>
	 */
	int PLATON_FUNC(compress_bits)
		(unsigned char *src, unsigned char *dst, int src_size);

	/**
	 * Expands a block of data previously compressed using
	 * the compress_bits() function
	 *
	 * @param		src			compressed data
	 * @param		dst			uncompressed data
	 * @param		src_size	size of uncompressed data
	 * @return		size of uncompressed data
	 *
	 * The compressed block is passed in src; the expanded result in dst.
	 * Array dst must be large enough to accomodate the largest possible
	 * decompressed block. Returns the size of the expanded data.
	 */
	int PLATON_FUNC(uncompress_bits)
		(const unsigned char *src, unsigned char *dst, int src_size);

#ifdef __cplusplus
}
#endif

#endif /* #ifndef _PLATON_COMPRESS_RLE_H */