CV2NAT
======

Convert buffer from one GD2 colour mode to another

Specifically: To convert PIC image data of a different mode to the current
display mode.

NB: Not suitable, in this form, for sprite data conversion, as in some
cases padding is involved.


Usage
-----
At present there are four different toolkits in the suit. They all convert
from mode 16, 32, 33, and 64, to all the other native modes:

1. CV216:  To mode 16
2. CV232:  To mode 32
3. CV233:  To mode 33
4. CV2NAT: To any of the above depending on the current display mode.

They all contain the same commands and all use the same parameters:

CV16TONAT, CV32TONAT, CV33TONAT, CV64TONAT

The parameters are:

        CVxxTONAT <from buffer>, <to buffer>, <from data size>

Where <from data size> is the actual source data size in bytes and
<xxxx buffer> -> the graphics data. Ie: Excluding any header! The size and
addresses relate to the graphics data only.

You will know that mode 16 requires one byte per pixel, modes 32 and 33
require two bytes per pixel, and mode 64 requires four bytes per pixel.

In all cases: If the resulting data size will be less than, or equal to,
the original data size, the buffer parameters may point to the same address
(if desired). Thus, if the current display mode is 32 then

        CV33TONAT buffer, buffer, <data size>

and

        CV64TONAT buffer, buffer, <data size>

works fine. The original buffer will be overwritten and the resulting data
will be the same or half the size of the original, respectively. However,

        CV16TONAT <from buffer>, <to buffer>, <from data size>

in the above, [to buffer] must be twice the size of [from buffer], and
thay must be separate areas.

In other words, you can save space and memory fragmentation by judicious
use of buffers, and likewise, you can crash the system and cause a lot of
damage if you get the buffers wrong! The only checks that are performed on
the addesses are: The buffer parameters must be positive and even, and in
cases where the from and to buffers need to be different, an error will be
thrown if they are not.

The reason to choose one toolkit over another is just to save some space
(and a teeny-weeny fraction of speed). In your boot file, or a startup
file for your program, you could have something like:

182 dmode% = DISP_TYPE
184 SELect ON dmode%
186  = 16: LRESPR 'win4_tks_col_CV216_BIN'
188  = 32: LRESPR 'win4_tks_col_CV232_BIN'
190  = 33: LRESPR 'win4_tks_col_CV233_BIN'
192  = REMAINDER : ERT -19
194 END SELect
196 :

Or simply load the CV2NAT_bin file instead.

Note that in each of the three separate toolkits there will be a dud, ie
the command to convert data from the current display mode to the current
display mode. This may need to be tested for and dealt with in SBASIC. It will
only check that the input buffer = output buffer or it will error, and
otherwise do nothing. This is so that the toolkits can operate transparently
for any mode. The error is to remind the programmer that they may be operating
with an empty [to buffer].

Added: CV2ALL. See notes below.


Programming notes
-----------------
If you want to be able to convert to any mode (ie in addition to the current
display mode) you could patch the key files of the first three toolkits (eg
CV16TONAT -> CV16TO33), remove the duds, re-assemble, and load them all.

Update: Oh, what the hell, I just did it! So now we have:

CV16TO32, CV16TO33, CV32TO16, CV32TO33, CV33TO16, CV33TO32, CV64TO16,
CV64TO32, and CV64TO33. Parameters are the same as above. I havent yet
found a need for CVxxTO64, so we'll leave it at that for now..

The link files suffixed with an 'l' use the library files rather than the
source files.


Program status
--------------
Many of the conversion routines and tables were lifted from the current SMSQ/E
sources. They were mainly written by Tony Tebby, Marcel Kilgus or Wolfgang
Lenerz (Apologies if Ive missed anyone! Let me know and I'll fix it!) They
were re-purposed and packaged by me, so any errors will be mine. Further
details may be found in the included source code.

Use and abuse as per the SMSQ/E lisence AND the Knoware.no DISCLAIMER and
distribution conditions.

V0.01, pjw, 2019 Sep 10
V0.02, pjw, 2019 Nov 16