Topic       : The GFA-Basic Compendium
Author      : GFA Systemtechnik GmbH
Version     : GFABasic.HYP v2.98 (12/31/2023)
Subject     : Documentation/Programming
Nodes       : 899
Index Size  : 28056
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Document not found
@help       : Help
@options    : +g -i -s +z
@width      : 75
@hostname   : STRNGSRV
@hostname   : CAB     
@hostname   : HIGHWIRE
@hostname   : THING   
View Ref-FileBITBLT s_mfdb%(),d_mfdb%(),par%()

s_mfdb%(), d_mfdb%(), par%(): integer-array

The command BITBLT allows the copying of rectangular screen sections. It is
similar to the commands GET and PUT but it is quicker and more flexible.
However, it is also more complicated to use.

The parameters of the command are stored in three arrays. The first one,
s_mfdb%(), contains the structure of the source screen - the one to be copied.
In the same way, d_mfdb%() contains the structure of the destination, i.e. the
place where the picture is to be copied to. The third array contains the
coordinates of the source and target areas and also the copy mode.

This command has a VDI routine as its basis. During BITBLT adr% and BITBLT x%()
a Line-A routine is called (see the section on Line-A calls).

The structure of the source (s_mfdb%) is same as that of the destination screen
(d_mfdb%). The abbreviations mean:

    s_mfdb%() Source Memory Form Description Block
    d_mfdb%() Destination Memory Form Description Block

The Array Elements are: (OPTION BASE 0 is assumed)

x_mfdb%(0)  Contains the source/destination address. This address must be an
            even number. Usually either s_mfdb%(0) or d_mfdb%(0) equals the
            screen address (XBIOS(2)).
x_mfdb%(1)  Width of the screen in pixels. This value must be divisible by 16.
x_mfdb%(2)  Height of the screen in pixels.
x_mfdb%(3)  Screen width in words (equals pixel count/16).
x_mfdb%(4)  Format type.
            0 = Device specific (normally this is used)
            1 = VDI format
x_mfdb%(5)  Number of bit planes:
             1 = 2 colors (mono)
             2 = 4 colors
             4 = 16 colors
             8 = 256 colors
            16 = 32768/65536 high color
            24 = True color
            32 = True color (extra alpha byte)
x_mfdb%(6)  Reserved field. (should be set to 0)
x_mfdb%(7)  Reserved field.
x_mfdb%(8)  Reserved field.

If x_mfdb%(0)=0, the VDI will fill in the rest of the x_mfdb() parameters by
itself, pointing to the current screen.

The array par%() has the following structure:

    par%(0)  Left x-coordinate of the source block
    par%(1)  Upper y-coordinate of the source block
    par%(2)  Right x-coordinate of the source block
    par%(3)  Lower y-coordinate of the source block
    par%(4)  Left x-coordinate of the destination block
    par%(5)  Upper y-coordinate of the destination block
    par%(6)  Right x-coordinate of the destination block
    par%(7)  Lower y-coordinate of the destination block
    par%(8)  Copy mode

The values for 'copy mode' correspond to those with GET/PUT. The important ones
are:

     3 = Replace             -> GRAPHMODE 1
     6 = XOR                 -> GRAPHMODE 2
     7 = Transparent         -> GRAPHMODE 3
    13 = Inverse transparent -> GRAPHMODE 4

Example:

    DIM smfdb%(8),dmfdb%(8),p%(8)
    '
    FOR i%=0 TO 639 STEP 8
      LINE i%,0,639,399
    NEXT i%
    '
    GET 0,0,639,399,a$
    mirrorput(0,0,a$)
    '
    PROCEDURE mirrorput(x%,y%,VAR x$)
      IF LEN(x$)>6 !Only if something there
        a%=V:x$
        b%=INT{a%}
        h%=INT{a%+2}
        '
        smfdb%(0)=a%+6
        smfdb%(1)=(b%+16) AND &HFFF0
        smfdb%(2)=h%+1
        smfdb%(3)=smfdb%(1)/16
        smfdb%(5)=DPEEK(a%+4)
        '
        dmfdb%(0)=XBIOS(3)
        dmfdb%(1)=640
        dmfdb%(2)=400
        dmfdb%(3)=40
        dmfdb%(5)=1
        '
        p%(1)=0
        p%(3)=h%
        p%(4)=x%+b%
        p%(5)=y%
        p%(6)=x%+b%
        p%(7)=y%+h%
        p%(8)=3
        FOR i%=0 TO b%
          p%(0)=i%
          p%(2)=i%
          BITBLT smfdb%(),dmfdb%(),p%()
          DEC p%(4)
          DEC p%(6)
        NEXT i%
        '
      ENDIF
    RETURN

--> Draws a set of lines, forming a triangle. The entire screen is read into a
    string and then each pixel-wide column is placed back on the screen on the
    other side. This has the effect of reflecting the screen in an axis down
    the center of the screen (see BITBLT in the section on Line-A calls).

Memo: This is the only variation of BITBLT that is based on a VDI call.
      The other variants are Line-A calls and should be avoided.
      This call does not fill in the reserved fields even if you pass them.

      If you pass 0 for the source or destination address the VDI will assume
      the screen and fill in the MFDB itself.

vro_cpyfm()+