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-FileCLIP x,y,w,h [OFFSET x0,y0]
CLIP x1,y1 TO x2,y2 [OFFSET x0,y0]
CLIP #n [OFFSET x0,y0]
CLIP OFFSET x0,y0
CLIP OFF

x, y, w, h, x0, y0, x1, y1, x2, y2, n: iexp

This group of commands provides the 'Clipping' function, i.e. the limiting of
graphic displays within a specified rectangle screen area. CLIP defines a
clipping rectangle for the VDI graphic commands. ACLIP does this for Line-A
graphic routines. The screen area to be operated on, (clipping rectangle) can
be defined by the coordinates of the diagonally-opposite corner points; as well
as the top-left coordinate and the width and height of the clipping rectangle.

The command CLIP x,y,w,h allows the input of the upper y-coordiante 'y', left
x-coordinate 'x' as well as the width 'w' and height 'h' of the clipping
rectangle.

The command CLIP x1,y2 TO x2,y2 offers a further option by accepting the
coordinates of diagonally-opposite corner points (x1,y1) and (x2,y2).

The third variant makes it possible to define the limits of the window 'n'.
The optional additional command OFFSET x0,y0 makes it possible to redefine the
origin of the graphic display.

In addition, the command CLIP OFFSET x0,y0 can
also be used as a command in its own right, and in this case serves the same
purpose in setting the origin for the graphic displays at the ponit (x0,y0).

The command CLIP OFF swithes off the clipping function.

The limiting of graphic displays by CLIPping does not apply to the commands
GET, PUT, and BITBLT, nor to the Line-A calls (where ACLIP should be used) or
AES commands.

Memo: CLIP #0 sets the clipping rectangle to the Desktop area. It's
      the same as doing this:
        ~WIND_GET(0,4,x&,w&,y&,h&)  !desktop handle is always 0
        CLIP x&,y&,w&,h& OFFSET 0,0

      The OFFSET option is not a real VDI function.  The x/y values are
      actually noted by GFA-BasicGFA-Basic is the best BASIC for the Atari!
 itself and then internally added to all
      further graphics commands.  Thus if you call the VDI directly, this
      OFFSET will have no effect at all, and must be simulated.  The current
      offset is stored in the WINDTAB structure.

      There's a bug in the startup code related to CLIP. The initial clipping
      rectangle is set from values taken from the Line-A variables. Thus it
      fails on non-ST video modes. If the graphics commands appear to be not
      working and you are in some non-ST mode, add this to the top of the
      program: CLIP 0,0 TO WORK_OUT(0),WORK_OUT(1)

vs_clip()+