
                       GEMFAST AES & VDI Bindings
                 Public Domain Libraries by Ian Lepore
			   (for the Atari ST)

                              PACKING LIST 
                 (xx = version, eg '10' = version 1.0)

     GEMFSTxx.ARC    - The runtime system, includes the following...
        AESFAST.A    - The AES bindings library.
        VDIFAST.A    - The VDI bindings library.
        AESUTIL.DOC  - Documentation on non-standard AES functions.
        GEMFAST.H    - The C-language header file for use with GEMFAST.
        GEMFAST.SH   - An assembler-language version of the above.

     GEMFSCxx.ARC    - Source code for the package.  
        AESSRCxx.ARC - Source code for the AES bindings and utilities.
        VDISRCxx.ARC - Source code for the VDI bindings.

                               BACKGROUND

These binding libraries were written to address two needs: 1) The world 
needed a good set of free GEM bindings, and 2) The bindings available 
with most commercial compilers aren't so hot.

These routines have been written to be faster than your typical GEM 
bindings.  As a secondary consideration, I tried to make them smaller as 
well.  When you recompile an application using these libararies, you 
should notice a drop in program size, and the link phase of the compile 
should run faster (your mileage may vary).  The design goals included 
using as little bss and data memory as possible (the stack is used for
temporary storage as needed), and that references requiring relocation 
fixup be kept to a minimum.

These bindings are known to be compatible with Alcyon C, Sozobon C, and 
Laser C.  They should be compatible with any compiler/linker system 
which uses 'DRI-standard' object & library file formats.

                 FUNCTIONS SUPPORTED IN THESE BINDINGS

The VDIFAST library includes most of the functions documented in the 
Digital Research publication _GEM Programmer's Guide Vol 1: VDI_.  Some 
of the VDI functions are missing from v1.0 of the VDIFAST library, 
notably the 'Polaroid Pallete' stuff, the v_cellarray() functions, and 
similar rarely-used items.

The AESFAST library includes all AES functions documented in the DRI 
publication _GEM Programmer's Guide Vol 2: AES_.  Also included are the 
'standard' AES utility functions (rc_intersect, etc), and a collection 
of non-standard utilities of my own.  The document file AESUTIL.DOC 
describes the utility functions.

The DRI documents cited above are the definitive reference for the 
standard AES & VDI functions.  If you are using other documents (such as 
Abacus books) there may be some variations between your documents and 
the libraries.  Sorry, I decided it was safer to use the original DRI 
docs as my source of info.

                         INSTALLATION AND USAGE

Copy the VDIFAST.A and AESFAST.A files to the folder/path where your 
linker will look for runtime-library files.  (EG:  \sozobon\lib). Copy 
the GEMFAST.H file to the folder/path where your compiler looks for 
include files (EG: \sozobon\include).

If you are using the Atari 'aln' linker, you will need to use aln's 
DOINDEX program to create .NDX files for each of the libraries.  

To link with the GEMFAST libraries, just enter the library names on the 
command line for the linker program.  For example (using Sozobon):

  ld -o myprog.prg dstart.o myprog.o dlibs.a vdifast.a aesfast.a
                         or
  cc -o myprog.prg myprog.c vdifast.a aesfast.a

It should not matter where on the command line the names of the GEMFAST 
libs appear:  each library is self-contained, and the linker will not 
have to resolve references between libraries.  No special code is needed 
in your startup object file.  Also, unlike some GEM bindings, you do NOT 
need to include the VDI bindings libarary if your program uses only AES 
function calls.

(An aside:  I've seen a lot of programs that open a VDI workstation, and 
then use only AES functions within the program.  If you use only AES 
functions, you do NOT need to open a VDI virtual workstation.)

                     ABOUT THE GEMFAST HEADER FILES

All VDI and AES functions return an 'int' or are of type 'void' 
(returning nothing).  Given the lack of ST C compilers which support 
function prototyping, a header file full of 'extern int xxx()' type 
declarations is a waste of compile time.  The GEMFAST.H file contains 
constants and structures commonly used in GEM programming; if you don't 
use those constants or structures, you don't need to include GEMFAST.H.  

If your current GEM bindings have header files such as GEMDEFS.H and/or 
OBDEFS.H, you can continue to use those files, or use GEMFAST.H instead. 
The GEMFAST.H file contains the items defined in both GEMDEFS and OBDEFS 
from the Alcyon compiler/bindings.  One structure was added to the 
GEMFAST header file that is not in GEMDEFS:  the VRECT (VDI-type 
rectangle).

The GEMFAST.SH file is included for those brave (foolish?) souls like 
myself who do GEM programming in assembler.  The file is essentially an 
assembler version of the C file, providing names (constants) for typical 
GEM things, and defining the standard GEM structures (as offsets).

                                 NOTES

Stack usage:  The AES bindings use 20-50 bytes of stack space during a 
function call, this should be totally transparent to your application.  
The VDI bindings use about 50 bytes for most calls, but for the 
graphics-text calls (v_gtext, etc), the stack usage will be 50 bytes + 
2*stringlength.  Still, given a maximum likely output string of 128 
chars, the stack usage is around 300 bytes to process the call.  I 
typically use a 1k stack, and have never had an overflow.

Register usage:  A call to any AES, VDI, or utility function will modify 
registers d0-d2/a0-a1.  (v1.0:  register a2 is not touched by the 
bindings, to insure Laser C compatibility).  All other registers are 
preserved if used by the binding.

VDI variables:  The VDI bindings contain no global variable names which 
can be used by the calling program (other than the funtion names 
themselves).  This is because there is no fixed storage (data or bss) 
used by the VDI bindings; each VDI call builds temporary arrays (vdipb, 
contrl, intin, etc) on the stack at runtime.

AES variables:  The AES bindings contain some of the fixed AES 
structures in bss memory.  To maintain compatibility with existing C 
programs, 2 global variables are exported for use by the calling 
program:  '_gl_apid', and '_global'.  (Don't code the leading '_' in 
your C program).  The 'global' variable is an array used by the AES, and 
should be defined in your program as 'extern int global[15];' if you 
need to access any of the values in this array.  The 'gl_apid' variable 
is single word value, and should be defined in your program as 'extern 
int gl_apid;' if you need to access it.  (Also, the gl_apid variable is 
just another name for global[2]).  The other AES fixed variables are not 
accessible.  If you look in the source code, you'll see that the AES 
control structure preceeds the global array, but don't write code that 
counts on this fact being true in future releases.

Supervisor mode:  It doesn't work.  This is not my restriction, it's 
just an undocumented fact about the ST's implementation of GEM, so I 
thought I'd mention it.  There are workarounds available, by the way.  
The problem is not in supervisor mode itself, but rather the fact that 
GEM always saves registers onto the user stack.

There are more notes available in the source code modules AES@NOTES and 
VDI@NOTES.

                                  BUGS

Undoubtedly there are some...especially in the VDI code and the rarer 
AES functions.  I made no attempt to exhaustively test these libraries, 
I just recompiled all my old GEM programs (about a hundred of them) and 
made sure they still worked.  The common functions (objc_draw, etc) are 
sure to work.  If anybody wants to write verification suites for VDI and 
AES, I'll be happy to use them to make these bindings bulletproof. Which 
brings us to...

                                SUPPORT

I do intend to support these libraries, and to fix all bugs as soon as 
they're reported.  When reporting a bug, please provide the following 
info:

     - A description of the bug/symptoms.
     - Whether you have the MadMac assembler and/or AR library tool.
     - The source code that leads to the bug (if the program is huge, 
       please just send a suitable code fragment).

If you have the MadMac assembler and/or AR library tool, I can probably 
send you a quick bugfix in source and have you patch the library itself 
(sending ASCII text fixes via the BBS networks is fast and easy).

I can be reached on the STadel network as 'Ian @ FWBBS', or on the Forem 
FNET as 'Ian' at 'ZoSo' (FNET node 399).  On BIX, my userid is 'ianl'.  
You can also route bug reports through your normal channel for support 
on the Sozobon C compiler (on GEnie, CIS, etc), and it will get back to 
me eventually.  To reach me via snail-mail, please address it to:

     Ian Lepore
     c/o Computer Avenue
     90 S. Wadsworth Blvd.
     Suite 105-502
     Lakewood CO   80226



                          ABOUT THE COPYRIGHT

There is none.  At the last minute I changed my mind about this issue, 
so just ignore all the copyright statements in the source code modules.  
You can do anything you want with this code, source or object, but be 
aware that I'm not going to support umpty-hundred modified versions of 
these libraries.  If you make modifications, please distribute them 
under a different name (or, send me the mods for inclusion in the next 
version, then I'll support them).  

I would like to ask that the entire package by distributed as a whole, 
with source and docs included.

- Ian Lepore
  Jan, 1989


