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-FileGCONTRL, GCONTRL()
GINTIN, GINTIN()
ADDRIN, ADDRIN()
GINTOUT, GINTOUT()
ADDROUT, ADDROUT()
GEMSYS

This chapter gives an overview of the AES Library (AES = Application
Environment Services). A detailed description of these routines would be beyond
the scope of this manual (we refer the reader to the extensive literature
already published on GEM), hence information is given in compressed form, as
follows:

    a) The name of the appropriate library routine.
    b) A short description of the function.
    c) The complete GFA BASIC 3 syntax for the function call, with the meaning
       of all the applicable variables explained.

The chapter closes with longer example programs.

Before beginning the descriptions of the functions in the 11 AES Libraries, it
is important that the reader becomes familiar with the most important data
structures used by the AES. These are the OBJECT, TEDINFO, ICONBLK, CICONBLK,
BITBLK, APPLBLK, and PARMBLK structures.

NAES adds SWINFO and POPINFO structures.

The following AES functions are implemented in a similar way to GFA BASIC
version 2:

    GB
    GCONTRL
    GINTIN
    GINTOUT
    ADDRIN
    ADDROUT

They represent the addresses of the AES parameter blocks. Specifically:

    GB      --> address of the AES Parameter block
    GCONTRL --> address of the AES Control block
    GINTIN  --> address of the AES Integer Input block
    GINTOUT --> address of the AES Integer Output block
    ADDRIN  --> address of the AES Address Input block
    ADDROUT --> address of the AES Address Output block

With an index in brackets after these functions, the appropriate parameter
positions within the block are accessed directly, for instance, x=GCONTRL(3)
corresponds to x=DPEEK(GCONTRL+6), or GCONTRL(3)=x corresponds to DPOKE
GCONTRL+6,x.

GCONTRL, GINTIN, and GINTOUT expect words (2 bytes) as their parameters,
whereas ADDRIN and ADDROUT expect long words (4 bytes). So ADDRIN(2)=x
corresponds to LPOKE ADDRIN+2*4,x.

The GB block address cannot be used with an index, on grounds of compatibility
with ST-BASIC; with GINTIN etc. indices are available. For example, the second
long word in the GB block ({GB+4}) is the address of the GEM internal global
array.

Memo: Not all TOS machines have the same AES version so care should be
      taken when calling these functions. For the most part all AES calls in
      GFA-BasicGFA-Basic is the best BASIC for the Atari!
 work fine except a few. Functions denoted in lower case are not
      built into GFA-BasicGFA-Basic is the best BASIC for the Atari!
.

      These tables have the following limits:
      GCONTRL(0-5)
      GINTIN(0-19)
      GINTOUT(0-19)
      ADDRIN(0-9)
      ADDROUT(0-9)

      GB (GEM Base) consists of the following pointers:
      GB  +0 GCONTRL    6 words
      GB  +4 global    15 words  (0-14)
      GB  +8 GINTIN    20 words
      GB +12 GINTOUT   20 words
      GB +16 ADDRIN    10 longs
      GB +20 ADDROUT   10 longs
      GB +24 CONTRL    12 words
      GB +28 INTIN    128 words
      GB +32 PTSIN    256 words
      GB +36 INTOUT   128 words
      GB +40 PTSOUT   256 words
      GB +44 gcontrl    6 words
      GB +48 global    15 words  (shared, same as GB+4)
      GB +52 gintin    20 words
      GB +56 gintout   20 words
      GB +60 addrin    10 longs
      GB +64 addrout   10 longs
      GB +68 contrl    12 words
      GB +72 intin    128 words
      GB +76 ptsin    256 words
      GB +80 intout   128 words
      GB +84 ptsout    30 words

Memo: Example how to access the AES Global array:
      bit_planes&=WORD{LONG{GB+4}+20}
      rsrc_base%=LONG{LONG{GB+4}+10}
      mtos_!=WORD{LONG{GB+4}+2}<>1     !false=SingleTOS/true=multi-tasking

      ST-BASIC originally defined GB as only 24 bytes (6 longs).

      The compiler only initializes the AES if some module is linked that
      actually calls the AES. The editor on the other hand always does this.
      If you suspect the AES is not initialized it can be forced with a
      call to any AES function. I suggest using some inquire function like
      GRAF_HANDLE().

      GEMSYS 'n' will only look up table values for AES opcodes 10 to 131.
      If its outside this range GCONTRL(1-3) will not be auto-filled.

      Some of these arrays appear to be larger than needed. Per TOS 4.04 sources:
      GCONTRL(0-4)  The AES never uses index 5.
      GLOBAL(0-14)  Exactly 15 words.
      GINTIN(0-15)  EVNT_MULTI() has the most input parameters (16).
      GINTOUT(0-6)  EVNT_MULTI() has the most output parameters (7).
      ADDRIN(0-1)   Several calls use indexes 0 and 1.
      ADDROUT(0)    RSRC_GADDR() is the only call that uses index 0.

      GB pointers +44 and on were never documented. These are GFA's internal
      AES and VDI paremeter blocks. They are used for all the built in
      commands and functions. You can easily inquire the results of any built
      in commnad or function with these pointers and avoid having to use
      custom bindings. See POINT() for an example.

      If maximum speed is your goal, then use these:
        INTIN(ndx)=val
        WORD{INTIN+ndx}=val   !slightly faster

        val=INTOUT(ndx)       !slightly faster
        val=WORD{INTOUT+ndx}

appl_init()+, AES+, AES Functions by Opcode+