PE_MBLK
                                =======

                  Move a block of graphics memory


Moves a block of graphics data of the current screen mode (see DISP_TYPE)
from a block with one geometry to a buffer with a different geometry.


Usage:
------

PE_MBLK xsize%, ysize%, sox%, soy%, dox%, doy%, sinc, dinc, sbase, dbase

where   x/ysize is size of block                        (pixels)
        sox%, soy% is origen in source area             (pixels)
        dox%, doy% is origen in destination area        (pixels)
        sinc and dinc are respective line increments    (bytes)
        sbase and dbase are respective bases            (addresses)

Errors: None except SBASIC Bad Parameter errors

Note: Only the most basic error checking is done on the parameters, eg
buffer addresses even and none-zero. So if you get anything wrong you are
likely to crash!

Note: do not (mis)use this vector to move general memory about. The size of
the memory actually moved depends on the screen driver that is being used.
Thus, if you move a block of 10x20 pixels (x|y size), in modes 16 and 31,
then 200 bytes will be moved (1 pixel = 1 byte). In modes 32 and 33, 400 bytes
will be moved (1 pixel = 2 bytes) and in the QL modes, less bytes will be moved.


Example:
--------

The size of the destination buffer must be calculated based on the number
of pixels to move and the current screen mode. Typical uses are for
copying screen data to a buffer for use as a PIC or as a SPR.

PIC data must be padded to an even length in all modes, while SPR data
must be padded to a multiple of 4 bytes.

In this example an area of screen is copied to a buffer to create a PIC of that area:

10 Scr2Pic#1; 200, 100, (SCR_XLIM(#1)-200)/2, (SCR_YLIM(#1)-100)/2, 'ram1_test_pic'
11 :
100 DEFine PROCedure Scr2Pic(ch, xs%, ys%, xo%, yo%, fnm$)
110 LOCal sx%, ox%, md%, ll%, buf, pic
120 md% = DISP_TYPE: sx% = xs%: ox% = xo%:       REMark So as not to alter parameters..
130 SELect ON md%
140  = 0:      ll% = ((xs% + 7) DIV 8) * 2
150  = 8:      ll% = ((xs% + 7) DIV 8) * 2
160            ox% = xo% && -2:                  REMark Mode 8 doesnt do odd pixels
170            sx% = xs% && -2
180  = 16:     ll% = (xs% + 1) && -2:            REMark Round up to word
190  = 32, 33: ll% = xs% * 2
200  = REMAINDER : ERT -19:                      REMark Mode 2 should be possible..
210 END SELect
220 :
230 buf = 10 + ys% * ll%
240 pic = ALCHP(buf)
250 PE_MBLK sx%, ys%, ox%, yo%, 0, 0, SCR_LLEN(#ch), ll%, SCR_BASE(#ch), pic + 10
260 :
270 POKE_W pic, 19196, sx%, ys%, ll%, md% * 256: REMark Set PIC header
280 SBYTES fnm$, pic, buf
290 RECHP pic
300 END DEFine Scr2Pic
310 :
320 :

The routine should work in any current screen mode (including mode 2, Atari
mono, but I cant test this so it is not included. Feel free to feedback any
certain information!)


Software status:
----------------

The PE_MBLK command makes use of the "new" pv_mblk vector, which is only
available in SMSQ/E V3.00+ (but by now perhaps also in PTR_GEN/WMAN V2+?)
The underlying routine was written by others (eg Tony Tebby, Jonathan Oakley,
Wolfgang Lenerz and Marcel Kilgus). The wrapping is my own work.

For DISCLAIMER and conditions of use, see Knoware.no

V0.01, pjw, 2020 Nov 28