RLE
                                   ===

Run Length Encoding - de/compression routines for (graphics) data.

These two routines will RLE compress and RLE decompress data in a buffer
to a second buffer. The routines are mainly designed for "QL" graphics
data, mainly sprites and PIC files. The routines are agnostic as to which
graphics format it is to be used for. It is intended that the
format-specific partion of the conversion will be done in BASIC.

For examples of how this might be done, see the Pic2Spr, Pic2Pac, and
Pac2Pic routines in the GO SUB section.


Features and Limitations
------------------------

ENRLE and DERLE can be used on any data that lends itself to RLE
compression. The code is not optimised for more advanced MC68 CPUs - it
could be, but it would then not be universal.

Only byte, word and long word element sizes are catered for, as these are
the most common GD2 element sizes for graphics data. Ie, these routines
will mainly be useful for high-colour graphics data on SMSQ/E-capable
platforms - modes 16, 32, 33, and 64, although there appears to be support
for sprite compression for QL mode (0/4, & 8) sprites under Wman2. (RLE
compression with a word size of 2 seems to work adequately for QL mode
graphics in most cases.)

WARNING! If the programmer makes mistakes with buffer addresses or sizes
the machine is likely to crash - spectaculary if you are lucky; silently
if you are not!


Usage
-----

        compsz = ENRLE(from_buffer, to_buffer, data_size, element_size)

Where:  from_buffer  = buffer containing data
        to_buffer    = buffer for compressed data
        data_size    = size of data to compress - ie can be less than
                       actual buffer size. to_buffer must be at least as
                       large as data_size too.
        element_size = type of RLE compression 1, 2, 4 for byte, word, long

Obviously, neither from_buffer or to_buffer need point to the actual start
of the buffers containing the data, only to the data itself.

Return: compsz       = size of comressed data or error

Errors: BF - the data is not compressable, ie the compressed data would be
             bigger than the source data. The contents of the to_buffer
             are in that case rubbish.

   NI & BP - These are "hard" errors as they programmer-avoidable

NB!     Only basic checking is performed on validity or sizes of buffers!
        It is the programmer's responsibility to get them right!


        DERLE from_buffer, to_buffer, uncompsz, element_size

Where:  from_buffer  = buffer containing compressed data
        to_buffer    = buffer for uncompressed data
        uncompsz     = size of uncompressed data. The to_buffer must be at
                       least this size
        element_size = type of RLE compression 1, 2, 4 for byte, word, long

Obviously, neither from_buffer or to_buffer need point to the actual start
of the buffers containing the data, only to the data itself.

No return value.

Errors: BP - a "hard" error as it is programmer-avoidable

On error contents of to_buffer are invalid.

NB!     Only basic checking is performed on validity or sizes of buffers!
        It is the programmer's responsibility to get them right!


Software status
---------------

The DERLE code was lifted straight out of the SMSQ/E sources. It was
written by Marcel Kilgus and modified for non-MC68020+ CPUs by Wolfgang
Lenerz. The wrapping and packaging was done by me.

ENRLE was written by me. Both should be compatible with all current CPUs in
use on QL systems.

For DISCLAIMER and conditions of use, see Knoware.no

V0.01, pjw, 2018 Feb 21
V0.02, pjw, 2020 May 28, re-write
V0.03, pjw, 2020 Dec 09, debugged