                               Liberty

                          Dokumentation 0.2
                              05.03.1997

                                 von

                           Christian Krger
                           Im Erpelgrund 16
                             13503 Berlin

                  Internet: chrisker@cs.tu-berlin.de



Inhaltsverzeichnis
==================

 1  Rechtliches / Copyright
    1.1  Haftungsausschlu
    1.2  Warenzeichen
    1.3  Spenden

 2  Installation
    2.1  Bootreihenfolge

 3  Was ist Liberty?

 4  Was bietet Liberty?
    4.1  CJar-Erweiterung
    4.2  Soundfunktionen
    4.3  Vektorgrafikfunktionen

 5  An die programmierenden Zunft
    5.1  Allgemeines
         5.1.1  Parameterbergabe
    5.2  Der Liberty-Cookie & XBIOS-Erweiterung
    5.3  ...Schlu fr heute...

 6  Ausblick

 7  Changes

 8  Kontaktadresse



1  Rechtliches / Copyright
**************************

Das Copyright  an Liberty und dieser Dokumentation liegt bei Christian
Krger, Berlin. Die Weitergabe des Programms  ist  Grundstzlich  frei
(Stichwort FREEWARE), dennoch sind folgende Punkte zu beachten:

    Das  Programm  darf  nur  mit  allen  zugehrigen  Dateien und in
     *unvernderter* Form weitergegeben werden.  Entweder  unkomprimiert
     oder als 'Zip'-Archiv. Folgende Dateien mssen folglich im Archiv
     enthalten sein (-> = Ordner):



           LIBERTY -> AUTO        -> LIBERTY.PRG
                      DOKU        -> HTML         -> LIBERTY.HTM
                                                     LIBERTY.GIF
                                                     MYSELF.GIF
                                                     UDO_LF.GIF
                                                     UDO_RG.GIF
                                                     UDO_UP.GIF
                                     LIBERTY.TXT
                                     LIBERTY.H
                                     LIBERTY.HYP
                      MCSNDPAT    -> MACSND.DFY
                                     PATCHY.TTP
                      SIZEJAR.TTP


    Das Programm darf generell nur  kostenlos  weitergegeben  werden.
     Der  Upload  in gebhrenfreie Mailboxen und auf nichtkommerzielle
     FTP-Server ist erlaubt und erwnscht.

    Dem Archiv drfen  keine  weiteren  Dateien  hinzugefgt  werden,
     insbesondere  keine  Mailboxwerbung  und  keine  Werbung  fr PD-
     Serien.  Die  Umbenennung  oder  das  Umpacken  des  Archivs  ist
     unerwnscht.

    Das  Programm darf anderen Programme beigelegt werden - unter der
     Voraussetzung,   da   ich   *vor   der   Verffentlichung* darber
     informiert  werde  und  ein eindeutiger Hinweis auf die Versions-
     nummer   der   beigefgten    Liberty-Version    erfolgt    (z.B.
     hervorgehoben im 'README').
     Auch hier gilt obiges 'Vollstndigkeitsprinzip'!

    Fr  die  Weitergabe auf Disketten im Rahmen einer Public-Domain-
     Serie drfen keine Gebhren verlangt werden, die einen Betrag von
     10 DM (exklusive Versandkosten) berschreiten.

    Die  Weitergabe  via  CD-ROM  darf  nur  dann  ohne  schriftliche
     Genehmigung erfolgen,  wenn  der  Preis  der  CD  pro  bespieltem
     MegaByte 0.1 DM nicht bersteigt!


1.1  Haftungsausschlu
======================

Trotz sorgfltiger  Entwicklung  und  umfangreichen  Tests  kann keine
Gewhrleistung fr die Richtigkeit des  Inhalts  dieser  Dokumentation
und die einwandfreie Funktion von "Liberty" bernommen werden.

Der Autor kann keine Haftung fr irgendwelche direkten oder indirekten
Schden - einschlielich aber nicht  beschrnkt  auf  materielle  oder
finanzielle  -  bernehmen, die durch die Benutzung von "Liberty" oder
dessen Untauglichkeit fr einen bestimmten Zweck entstehen.


1.2  Warenzeichen
=================

Innerhalb dieser Dokumentation wird auf Warenzeichen  Bezug  genommen,
die  nicht  explizit als solche ausgewiesen sind. Aus dem Fehlen einer
Kennzeichnung kann nicht geschlossen werden, da ein Name frei von den
Rechten Dritter ist.


1.3  Spenden
============

Wie schon   erwhnt  ist  Liberty  Freeware.  Ich  habe  aber  selbst-
verstndlich nichts gegen TOS-Programmentwicklungssttzungskufe  ;-).
Wer mit also eine motivationssteigernde Spende zukommen lassen mchte,
kann das ber die Kontaktadresse tun.
Wer keine Lust hat etwas zu  spenden  und  trotzdem  meine  Motivation
steigern  mchte,  der sollte sich 'Freedom2' kaufen. Dann bekommt man
wenigstens etwas fr's Geld ;-) ...



2  Installation
***************

*(Bitte dieses Kapitel komplett _vor_ der Installation durchlesen!)*

Kopieren Sie einfach 'LIBERTY.PRG'  in  den  AUTO-Ordner  ihres  Boot-
Laufwerkes.

Nach dem  Kopieren  von  'LIBERTY.PRG'  und  dem folgenden Systemstart
installiert sich dann die Library automatisch.


2.1  Bootreihenfolge
====================

'LIBERTY.PRG' sollte  physikalisch  mglichst  frh   im   AUTO-Ordner
stehen,  auf  jeden  Fall vor (wenn Sie es denn einsetzen) MiNT! Viele
Bootselektoren   (z.B.   XBOOT)   erlauben   es,    konfortabel    die
Bootreihenfolge  der  AUTO-Ordner  Programme zu verndern. Sollten Sie
nicht in Besitz eines solchen Programms sein hilft folgendes:
Betrachten Sie sich  ihren  AUTO-Ordner  im  Desktop  in  unsortierter
Ausgabeart. Hier sollte 'LIBERTY.PRG' mglichst weit vorne stehen. Ein
ndern  der  Bootreihenfolge  erreichen  Sie  durch  Verschieben   des
kompletten   AUTO-Ordners   in   ein   anderes   Verzeichnis  und  dem
Zurckverschieben   aller   AUTO-Ordner-Programme    in    gewnschter
Reihenfolge  in  den  AUTO-Ordner. (Wer absolut nicht versteht was ich
meine,  kann  mich  unter  spter  genannter  Adresse   kontaktieren.)
MagiCMac  Benutzer  mssen  den Umweg ber Umbenennen der Dateien oder
Bootreihenfolgedatei (wie in der MagiCMac  Dokumentation  beschrieben)
gehen  um  Liberty  mglichst  frh  zu  initalisieren (MiNT wird wohl
keiner auf Macs benutzen ;-) ).



3  Was ist Liberty?
*******************

Liberty ist eine residente Systemerweiterung. Das bedeutet,  da  eine
Vielzahl  von  Funktionen  die  in  Liberty  vorhanden  sind,  anderen
Programmen angeboten  werden.  Das  bloe  Vorhandensein  von  Liberty
ndert  nicht viel an Ihrem System, sondern die Funktionen der Library
(oder auch Systemerweiterung, folgend Lib genannt) mssen von  anderen
Programmen  genutzt  werden.  Freedom2  ist z.B. ein solches Programm.
Freedom2 benutzt viele der Liberty-Funktionen, so da  es  ohne  diese
Lib nicht lauffhig ist.

Nun gibt  es  (oft  zurecht) viele Gegner solcher Systemerweiterungen.
Die Argumente gegen den  Einsatz  einer  residenten  Erweiterung  sind
meistens folgende:

    residente  Systemerweiterungen schlucken permanent Speicher, auch
     wenn sie nicht bentigt werden

    residente Systemerweiterungen  werden  oftmals  nur  von  wenigen
     Programmen  untersttzt  und  viele  Funktionen  der  Erweiterung
     werden nicht bentigt, was dann  ebenfalls  Speicherverschwendung
     bedeutet

    residente  Systemerweiterungen  sind gro, klobig und unflexibel;
     bei  Zugriff  von  mehreren  Programmen  auf  eine  Funktion  der
     Erweiterungen   gibt  es  oft  Probleme  oder  der  Rechner  wird
     'gebremst' (Experten mgen mir verzeihen, da ich hier nicht  von
     Semaphoren spreche :-) )

Die Vorteile solcher Erweiterungen:

    das  'Rad'  mu  nicht  tausendmal neu erfunden werden; Programme
     knnen die angebotenen Funktionen einfach benutzen ohne zu wissen
     was  sie  genau  machen  (daraus  folgt  eine  wesentlich krzere
     Entwicklungszeit und (hoffentlich) mehr Spa am Programmieren, da
     man  sich  auf  die  programmspezifischen  Probleme konzentrieren
     kann)

    benutzen viele Programme  die  Systemerweiterung  gibt  es  einen
     Speicherspareffekt: die von vielen Programmen bentigten Routinen
     der Systemerweiterung sind nur einmal im Speicher  und  nicht  in
     jedem der Programme extra vorhanden.

Liberty hat  natrlich  diese  Vorteile  und entkrftet zustzlich mit
seiner Art des Aufbaus die Nachteile:

    Liberty verbraucht weniger als  25kB  Speicher!  (ist  also  kein
     'grober  Klotz'  wie  andere  Libs  die gleich 300kB oder mehr an
     Speicher verschlingen)

    Liberty konzentriert  sich  auf  die  wesentlichsten  Mankos  des
     Betriebsystems  und  beseitigt  sie;  es ist keine GEM-Interface-
     Library! (wre wohl  auch  sinnlos  zu  versuchen  alle  GEM-Lib-
     Programmier- Sppchen zu einem Standard zu vereinigen ;-) )

    fast  alle  Funktionen  der  Lib werden von Freedom2 benutzt (wer
     kommt schon ohne aus? ;-) ); von Speicherverschwendung  kann  bei
     Einsatz  von  Freedom2 folglich nicht gesprochen werden (bei 25kB
     ist dieses ohnehin schon  ziemlich  unglaubwrdig);  bereits  bei
     Einsatz  eines  zweiten  Programms welches Liberty benutzt, tritt
     der gewnschte Speicherspareffekt ein

    Liberty besteht zu 90%  aus  hochoptimierten  Assembler-Routinen;
     nur  so  konnte  die  Krze  und  Geschwindigkeit der Erweiterung
     erreicht werden

    alle Funktionen von Liberty sind reentrant und 95% der Funktionen
     sind   'Multi-Threading'-fhig  (d.h.  mehrere  Programme  knnen
     gleichzeitig eine Funktion von Liberty benutzen ohne  sich  dabei
     gegenseitig zu stren oder zu blockieren)

berzeugt?



4  Was bietet Liberty?
**********************

Liberty setzt   sich   aus   Funktionen  mit  den  unterschiedlichsten
Aufgabengebieten   zusammen.   Obwohl   daher   das   Funktionsangebot
vielleicht  etwas  zusammengewrfelt  scheint,  ist  dem nicht so. Wie
schon  erwhnt  versucht  Liberty   die   nervensten   Schwchen   des
Betriebsystems    auszugleichen:    Funktionen,   die   immer   wieder
programmiert oder eingebunden werden mssen und  die  viele  Programme
bentigen.  Das diese Schwchen nicht konzentriert an einer Stelle des
Betriebssystems auftreten ist logisch. So besteht die Lib  intern  aus
folgenden Teilen:

     XBIOS-Erweiterung bzw. Nutzung:

         CJar-kompatibele    XBIOS    Erweiterung,    die    auf
          komfortabele Weise das Erzeugen, Abfragen  und  Lschen
          von 'Cookies' ermglicht

         Soundfunktionen    welche    eine    rechnerunabhngige
          Tonausgabe garantieren

     Erweiterungen mit GEMDOS-Charakteristik:

         eine sehr effiziente und  schnelle  Speicherverwaltung,
          die   privaten,  globalen,  normalen  und  alternativen
          Speicher  (wenn  ntig)  unterscheidet   und   kleinere
          Speicherblcke  in  greren  verwaltet  sowie  fr ein
          dauerhaftes, sicheres 'malloc' fr ACCs unter SingleTOS
          sorgt

         eine  Routine  zum  Laden  einer  Datei in einen Puffer
          (sollte die Datei mit ATOMIK 3.5 gepackt sein, so  wird
          diese automatisch ausgepackt!)

     Erweiterungen mit VDI-Charakteristik:

         eine Vielzahl von sehr schnellen Rastergrafikfunktionen
          (Laden von XIMG/GIF, Skalieren etc.)

         Vektorgrafikfunktionen     (Translation,      Rotation,
          Skalierung,  ...) - damit sind endlich auf einfache und
          komfortabele Weise Vektoricons realisierbar

     AES-Untersttzung:

         Funktionen zum einfachen Einhngen  von  Funktionen  in
          einzelne AES- Calls (mit Applikationszustandslisten!)

         LIBERTY  ist  in  der  Lage  (auch  wenn  kein Programm
          Liberty    benutzt)    defekte     AES-Calls     (nicht
          initalisiertes  Global-Field) zu reparieren! Damit wird
          u.a. erreicht, da z.B. der Dateiselektor Freedom  auch
          von ('Schweine'-)Programmen aufgerufen werden kann, bei
          denen  sonst  die  normale  Dateiauswahlbox  erscheinen
          wrde!


4.1  CJar-Erweiterung
=====================

Liberty legt  beim Start im AUTO-Ordner automatisch einen 'Cookie-Jar'
an. Programme die dieses sonst  bernommen  haben  ('CJARxxx.*'  etc.)
sind  damit  berflssig! Ebenfalls, das fr den MiNT Aufsatz 'Geneva'
bentigte 'JARxxx.PRG' ist unntig. In Liberty  sind  die  Fhigkeiten
dieses  Programms  enthalten! (JARxxx wurde getestet, fr gut befunden
und die Funktionalitt (erweitert) aufgenommen.)

Die Gre  des  'Cookie-Jar'  kann  mit   dem   beigefgten   Programm
'SIZEJAR.TTP'  verndert  werden.  In  der  Grundeinstellung wird beim
Start  von  Liberty  fr  32  zustzliche  'Kekse'  (zu  den   aktuell
vorhandenen  Systemcookies)  Platz  geschaffen.  Diesen  Wert kann man
wiefolgt ndern:

  1. Man kopiert 'SIZEJAR.TTP' in das Verzeichnis in dem 'LIBERTY.PRG'
     steht (also normalerweise in den AUTO-Ordner).

  2. Man  startet  das  Programm  durch  Doppelklick und gibt dann die
     gewnschte Anzahl an Keksen als Zahl in den erscheinenden  Dialog
     ein.

  3. Nach  Beendigung  des  Programms mu man 'SIZEJAR.TTP' wieder aus
     dem AUTO-Ordner entfernen.

  4. Beim  Neustart  des  Systems  bercksichtigt  dann  Liberty   die
     angegebene Anzahl. Fertig!

In der  Regel  sollte  dieses  Vorgehen  jedoch  unntig  sein,  da 32
(zustzliche)    Kekse    ausreichen    und    auch    keine     groe
Speicherverschwendung darstellen.


4.2  Soundfunktionen
====================

Liberty bietet  eine  komfortable  und  *einheitliche* Schnittstelle zur
Soundausgabe. Mit Hilfe dieser Erweiterung knnen (bald) alle Benutzer
von  Atarikompatiblen  in  den  Genu  eines  klangvollen  Erlebnisses
kommen. Die Zeiten bei denen Programme die Soundausgabe auf  bestimmte
Systeme   einschrnken,   oder  diese  nur  mit  /kuflichen/ Programmen
garantieren, sollten damit fr immer vorbei sein.

Realisiert wurde die Soundausgabe schon  fr  FalconO3O-Rechner  sowie
fr Apple- Rechner mit 'MacSound'. ST/STE/TT Rechner folgen demnchst.
Bisher  hatte ich noch keinen Kontakt zu Medusen oder dem Hades, halte
hier aber eine Anpassung fr die exisiterende  Soundkarte  ebenso  wie
fr PC's mit XBIOS-Treiber mglich.

Wichtig ist  nur,  da  sich  ein Anwenderprogrammierer keine Gedanken
mehr  um  evt.  Soundfhigkeiten  des   Rechners   machen   mu.   Das
Vorhandensein    von    Liberty    garantiert   ein   Ansprechen   der
Soundfunktionen, auch wenn diese ohne Treiber funktionslos bleiben.

_*Zum Patchprogramm fr MacSound (nur fr Apple-Rechner):*_
MacSound (ein Autoordnerprogramm welches MagiCMac beiliegt und  XBIOS-
Soundfunktionen  zur Verfgung stellt) ist leider nicht so mchtig wie
es anderen Programmen gegenber vorgibt. Um korrektes Funktionieren zu
gewhrleisten, ist es daher ntig MacSound zu patchen. Eine Patchdatei
mit  dem  entsprechenden  Patchprogramm  befindet   sich   im   Ornder
'MCSNDPAT'.

Um MacSound zu patchen, mu man folgendermaen vorgehen:

    Zunchst  'MACSND.PRG'  (mte  im  Auto-Ordner  liegen)  in  das
     'MCSNDPAT'-Verzeichnis verschieben.

    Nun die Datei  'MACSND.DFY'  auf  das  Programm  'PATCHY.TTP'  im
     gleichen Verzeichnis ziehen und fallenlassen (Drag&Drop).

    Anschlieend  das  Programm  'MACSND.PRG'  aus diesem Verzeichnis
     (welches  nun  angepasst   ist)   wieder   in   den   Auto-Ordner
     verfrachten. MagiCMac neustarten, fertig!

Falls irgendwelche  Fehler  auftreten  sollten,  handelt  es sich wohl
nicht um die  Version  1.0  von  MacSound  (nur  diese  kann  gepatcht
werden)!  Sollte  sie  eine ltere Version haben, unbedingt die neuere
besorgen. Ob eine neuere Version als die 1.0 existiert (wenn ja  bitte
melden!),  kann ich nicht sagen, mir ist jedenfalls keine bekannt. Der
Patch setzt die Versionsnummer brigens auf 1.01 herauf!
/Bei Fragen oder Hinweisen zu diesem  Thema  bitte  die  Kontaktadresse
benutzen!/

Nach dem  Patchen  wurde  im  Verzeichnis  'MCSNDPAT'  das Verzeichnis
'PATCHED' angelegt, welches die Ursprungsversion von MacSound enthlt.
Eine Sicherungskopie der Originals wird also automatisch erzeugt.

/An dieser  Stelle  Dank  an  Christian  Wempe  &  Holger Weets fr ihr
Patchprogramm 'DIFFY' bzw. 'PATCHY'. Ich hoffe  es  ist  Ok,  da  ich
'PATCHY'   einfach  so  (einzeln  -  um  Verwirrung  zu  vermeiden...)
beigefgt habe (in eurer Doku steht zu diesem  Thema  leider  nichts),
schlielich  ist  Liberty  ja  auch  Freeware. Das komplette Archiv zu
'Diffy 2' sollte man in jeder guten 'Maus / ftp-site' finden./

Ein kleiner Soundtest der Liberty-Funktionen gefllig?
Den Info-Dialog von Freedom2 aufrufen (Klick mit der rechten Maustaste
auf  das  Freedom2-Logo bei *installiertem* Konfig.CPX) und anschlieend
das groe Freedom2-Logo im Info-Dialog anklicken...
Wenn sie einen FalconO3O haben, oder MagiCMac mit gepatchtem  MacSound
benutzen, dann mten sie was 'Nettes' gehrt haben...


4.3  Vektorgrafikfunktionen
===========================

Vektorzeichenstze und  Bezierkurven  sollten  heutzutage eine Selbst-
verstndlichkeit  sein.  So  werden  diese  Befehle   auch   von   den
Vektorgrafikfunktionen  in  Liberty  ordnungsgem verarbeitet. Leider
ist das Original-VDI (der Betriebssystemteil der fr die  Ausgabe  von
Grafiken  verantwortlich  ist)  nicht  in  der  Lage  diese Befehle zu
verarbeiten und ignoriert sie vllig.
Das bedeutet, da  wenn  ein  Programm  die  Vektorgrafikdarstellungs-
funktionen   von   Liberty   benutzt  und  die  darzustellende  Grafik
Bezierkurven und/oder Vektorzeichenstze enthlt, das Ergebnis auf dem
Bildschirm  nicht  der  Originalgrafik  entspricht. Dieses trifft aber
selbstverstndlich nur fr VDIs zu, die diese Befehle nicht verstehen!
Wie alle Funktionen von Liberty sind auch  die  Vektorgrafikfunktionen
auf  Geschwingidkeit  getrimmt. Bei der Vektorgrafikausgabe wurde z.B.
ein groer Geschwindigkeitsvorteil dadurch erreicht, da  die  Ausgabe
_direkt_ an das VDI geleitet wird und die Befehle nicht erst durch einen
TRAP geschickt werden! Das dabei verwendete Verfahren ist  keinenfalls
'schweinisch' sondern bekannt! (Fr die Experten: Man ld das Register
D0 mit -1 und macht einen TRAP #2 Aufruf. Als Ergebnis erhlt man  die
Einsprungsadresse des VDI-Dispatchers.)
VDI-Erweiterungen,    die    das    VDI    hinsichtlich   z.B.   einer
Bezierkurvenausgabe erweitern, mssen  dieses  Verfahren  untersttzen
(Profibuch, 10. Auflage, Seite 298 unten)!

'NVDI' (da  sauber)  hat  damit  keine  Probleme und in Verbindung mit
diesem VDI klappt die Ausgabe  obiger  Befehle  wunderbar  (auch  wenn
'NVDI'  nur  als  GDOS  eingesetzt  wird)!  Leider  kann  man  das vom
'SpeedoGDOS'  nicht  behaupten.  Diese  VDI-Erweiterung  versumt   es
offensichtlich  obiges  Verfahren zu untersttzen und somit ist dieses
Ausgabesystem   fr   Liberty   praktisch   nicht   vorhanden   (keine
Bezierkurven und keine Vektorzeichenstze!!!).

Ich wei,   da   diese  Tatsache  sicherlich  einige  Leute  ziemlich
verrgert und mchte deshalb hier Forderungen nach 'konformer' Ausgabe
ber den TRAP vorbeugen:

    die  oben beschriebene Vorgehensweise ist konform, da sie bekannt
     ist und es offensichtlich auch  ein  Ausgabesystem  gibt  (NVDI),
     welches   damit   keine   Probleme   hat;  Liberty  ist  folglich
     unschuldig, das Problem liegt beim unvollstndigem  Ausgabesystem
     (SpeedoGDOS)

    ein  Abndern der Liberty-Vektorgrafikausgabe brchte unzumutbare
     Geschwindigkeitseinbuen    fr    Benutzer     mit     konformen
     Ausgabesystemen

    ich   habe   wenig   Lust   die   Fehler   anderer  Programmierer
     auszubgeln...

Meine Empfehlung an SpeedoGDOS-Fanatiker die programmieren knnen:
Programmiert ein Utility welches sich in den TRAP  #2  hngt,  die  -1
abfngt und die Adresse des SpeedoGDOS-Dispatchers zurckliefert. Dann
klappt's auch mit Liberty... ;-)



5  An die programmierenden Zunft
********************************

Sie sind Programmierer, die Featureliste von Liberty  hat  Sie  locker
vom  Hocker  geworfen und Sie sagen sich:"Eine tolle Library, die will
ich auch untersttzen!"

/Kein Problem!/

Einzige Voraussetzung um die Library benutzen zu drfen:  Ich  erhalte
ein  kostenloses  Exemplar  des Programms welches die Library benutzt!
Software die den Status 'Public Domain',  'Freeware'  oder  'Fairware'
hat, ist davon natrlich ausgenommen ;-).

In der  letzten  Doku  zu  Liberty  habe  ich noch von einer seperaten
Dokumentation fr  Programmierer  gesprochen.  Da  die  Resonanz  aber
unerwartet  gro  war  und  ich mir die Arbeit zwei Dokumentationen zu
pflegen ersparen mchte, wird die Beschreibung der  Liberty-Funktionen
*schrittweise* in diese Doku eingeflechtet.

/Was sie folgend als Beschreibung finden ist *keineswegs* vollstndig!!!/

Man kann  aber  schon damit beginnen seine Programme anzupassen, um so
in den Genu der Liberty-Funktionen zu  gelangen.  Alles  was  folgend
dokumentiert  ist,  wird  sich  *nicht* mehr  ndern und kann demzufolge
problemlos verwendet werden.

Lange Rede kurzer Sinn: Here we go... (auch wenn es so gut wie gar nix
ist, ist es immerhin ein Anfang...)


5.1  Allgemeines
================

Ich mchte  an  dieser Stelle nicht alles wiederholen was bereits oben
beschrieben wurde. Daher nur nochmal ein Kurzberblick ber  das,  was
Programmierer wissen mssen:

    Alle Liberty-Funktionen sind reentrant! Man braucht sich folglich
     *keine* Gedanken darber machen, ob eine Funktion schon von anderen
     Programmen/Threads benutzt wird!

    Bevor  man  eine  Liberty-Funktion  aufruft  sollte man lediglich
     sicherstellen, da die Funktion gengend Stack zur Verfgung hat.
     Gengend  heit  dabei *1k*! Mehr ist auf keinen Fall ntig, dieser
     Platz sollte aber bereitgestellt werden.

    Liberty verndert keine Registerwerte in einer Funktion.

    Wenn eine Liberty-Funktion  einen  Rckgabewert  liefert,  sollte
     dieser  auch  geprft  werden,  um  die  korrekte Abarbeitung der
     Funktion festzustellen.

    AUF JEDEN FALL nur  dokumentierte  Funktionen  und  Eigenschaften
     nutzen!

    Jeden Hinweis auf Umgang mit Funktionen *genaustens* beachten.
     Wenn  eine  Variable als 'Read-Only' gekennzeichnet wurde, sollte
     man sie auch nicht berschreiben!


5.1.1  Parameterbergabe
------------------------

Fr die Parameterbergabe gelten die Regeln von Turbo C / Pure C:
_Parameterbergabe Pure C (Auszug aus der Online Hilfe von PureC)_

    Die ersten drei Variablen vom Typ char, int oder long  werden  in
     den Registern D0, D1, D2 bergeben.

    Die ersten zwei Adressparameter (Pointer) werden in den Registern
     A0 und A1 bergeben.

    Weitere Parameter, die keinen Platz mehr in den Registern D0, D1,
     D2, A0 A1 finden werden ber den Stack bergeben.

    Parameter  werden  in  der  Reihenfolge  von  rechts  nach  links
     bergeben.

_Beispiel:_


extern void lbf(int x1, int y1, int x2, int y2, int *l, int *b, int *f);
main()
{
    int x1 = 10, y1 = 10, x2 = 20, y2 = 20, l, b, f;
    lbf(x1, y1, x2, y2, &l, &b, &f);
}

Da mehr Werte-,  als  auch  Adress-Parameter  an  die  Funktion  "lbf"
bergeben  werden,  als  Register  zur Verfgung stehen, bentigen wir
also in jedem Fall den Stack. Der vierte Werte-Parameter mu  auf  dem
Stack  abgelegt  werden.  Ebenso  findet  der  dritte Adress-Parameter
keinen Platz in den Registern,  so  da  auch  dieser  auf  dem  Stack
abgelegt werden mu.

In den Registern befinden sich:

     D0: x1 (Wert von x1)
     D1: y1 (Wert von y1)
     D2: x2 (Wert von x2)
     A0: &l (Adresse der Variablen l)
     A1: &b (Adresse der Variablen b)


Auf dem Stack befinden sich:

     &f (hi) (hchstwertiges Wort im Stack)
     &f (lo)
     y2 (Wert von y2)
     Return- (Rcksprungadresse)
     Adresse (Stackpointer zeigt hierauf)


Der Adress-Parameter  f  wird  nach  der Regel "von-rechts-nach-links"
zuerst auf den Stack gelegt. Danach kommt der  Wert  von  y2  auf  den
Stack.   Bitte   beachten   Sie,   da   die   Rcksprungadresse   des
Unterprogrammes als letzter "Parameter" auf den Stack gelegt wird,  so
da die Parameter im Stack ab dem Offset 4 anfangen. y2 (Offset 4), &f
(Offset 6)!

In C rumt die aufrufende  Funktion  nach  dem  Aufruf  die  Parameter
selbst  vom  Stack (z.B. mit ADDQ.W #8,A7", nach einem Aufruf mit zwei
Adressparametern). Dies erbrigt sich natrlich, wenn  alle  Parameter
in Registern bergeben wurden.


5.2  Der Liberty-Cookie & XBIOS-Erweiterung
===========================================

Liberty legt beim Start im Auto-Ordner einen Cookie-Jar an und erzeugt
einen Keks namens 'Lity' dessen Inhalt auf eine  Struktur  weist,  die
dem beigefgten '.h'-File entnommen werden kann.

Da Liberty   XBIOS-Funktionen   installiert,  die  einen  komfortablen
Zugriff auf den Cookie-Jar ermglichen, kann auf sehr einfache Art und
Weise das Vorhandensein von Liberty festgestellt werden.

Dazu ein Ausschnitt aus dem '.h'-File:


#define CJar_xbios      0x434A            /* "CJ" */
#define CJar_OK         0x6172            /* "ar" */
#define COOKIE_LIBERTY  0x4C697479L       /* "Lity" */
#define CJar( mode, cookie, value )   xbios(CJar_xbios,mode,cookie,value)


Folgendes 'Programm'  prft  somit, ob die Systemerweiterung vorhanden
ist:

Liberty_Cookie *libfuncs;

if (CJar(0, COOKIE_LIBERTY, &libfuncs)==CJar_OK)
{
    printf("LIBERTY vorhanden!!!");
}
else
{
    printf("LIBERTY nicht vorhanden!!!");
}


Bevor ein Programm Liberty benutzt, sollte auf jeden Fall durch obiges
Verfahren  festgestellt werden ob Liberty berhaupt vorhanden ist! Ist
dies nicht der Fall mu das Programm gegebenenfalls terminiert werden.

_Zu den verschiedenen Modi:_ Der erste Parameter der  dem  Makro  'CJar'
bergeben  wird,  bestimmt  den Modus der Cookie-Aufrufs. Im Gegensatz
zum Original 'Cookie Jar Manager' von Dan Wilga (Liberty ist voll  zum
'JARXX' kompatibel, man bentigt es also nicht mehr), existieren sogar
3 Modi zur Keks-Manipulation:

    Modus 0:
     Ermittelt den Wert des Kekses und  legt  in  an  der  angegebenen
     Adresse  ab. bergibt man fr 'value' einen NULL Pointer, so wird
     lediglich die Existenz des Kekses berprft.
     Bei erfolgreicher  Ermittlung  des  Kekses,  liefert  der  Aufruf
     0x6172 (="CJar_OK") zurck sonst einen anderen Wert.


    Modus 1:
     Erzeugt einen neuen Keks (cookie). Value *zeigt* auf einen Wert der
     in den Jar eingetragen  wird.  WICHTIG!  Es  wird  nicht  'value'
     eingetragen  sondern  der  Wert  auf  den  'value'  weist!!!  Bei
     bergabe eines NULL-Pointers wird 0 als Kekswert eingetragen.
     Existiert  der  Keks  bereits,  so   wird   sein   alter   Inhalt
     berschrieben!
     Die  Funktion  liefert "CJar_OK" bei erfolgreicher Eintragung. -1
     wird fr den Fall geliefert, da der Cookie-Jar voll ist!

    Modus 2:
     Entfernt den Keks 'cookie' aus dem Jar. Der Wert von 'value'  ist
     egal.  Liefert bei erfolgreicher Entfernung "CJar_OK" sonst einen
     anderen Wert.


5.3  ...Schlu fr heute...
===========================

...to be continued...



6  Ausblick
***********

Zum Zeitpunkt dieser ersten Verffentlichung von  'Liberty'  sind  die
Rastergrafikfunktionen  leider  alles  andere als komplett. Damit aber
andere schon jetzt zumindest  in  den  Genu  der  restlichen  Liberty
Funktionen  kommen,  habe  ich  mich  dennoch  fr  die Herausgabe der
Library im nicht vollstndigem Zustand entschieden.
Erste Erweiterung wird folglich darin bestehen,  den  Rastergrafikteil
vollstndig  auszubauen.  Aber  auch  im  Vektorgrafikteil fehlen noch
einige wnschenswerte Zusatzfunktionen.

Wie danach  die  Weiterentwicklung  verluft  ist  schwer  zu   sagen.
Hauptschlich  hngt  das  von meinen eigenen Bedrfnissen ab. Selbst-
verstndlich knnen auch Wnsche  anderer  Programmierer  die  Liberty
nutzen (wollen) den Funktionsumfang erweitern. Jedoch werde ich strikt
darauf achten, da Liberty nie mehr  als  50k  Speicher  schluckt  und
nicht zum schon beschriebenen 'Klotz' wird.

Welche Funktionen   Liberty   bietet  kann  dem  'einfachen'  Anwender
eigentlich egal sein. Er  kommt  meist  unbemerkt  in  den  Genu  der
Funktion,  sobald  ein  Programm  sie  benutzt. Das einzige worauf ein
Anwender  achten  sollte  ist,  da  er  mglichst  immer  die  neuste
Liberty-Version  installiert  hat.  Da  Liberty benutzenden Programmen
beigefgt werden darf, drfte diese Forderung leicht zu erfllen sein.



7  Changes
**********

*nderungen Version 1.1*

    Liberty benutzt jetzt ein anderes Verfahren um schweinische  AES-
     Calls  zu  'reparieren'. Damit sollten (hoffentlich) die Probleme
     die im Zusammenhang mit 'Calamus96' auftreten  der  Vergangenheit
     angehren.  Ich mchte ausdrcklich betonen, da die Probleme von
     'Calamus96' ausgehen und Liberty jetzt nur  /noch/ rcksichtsvoller
     mit unsauberen Programmen umgeht.
     Gleiches gilt auch fr 'OverPaint' (getestet mit der Demo-Version
     1.5s).
     Ich weise  in  diesem  Zusammenhang  darauf  hin,  da  das  neue
     Verfahren  mehr  Zeit  bentigt  und  es  dadurch zu (merklichen)
     Performance-Verlusten  bei  unsauberen  Programmen  kommen  kann!
     (...aber  lieber ein langsam ablaufendes Schweineprogramm als ein
     abstrzendes... - oder?)
     Nochmals meine Bitte  an  alle  Programmierer:  Achtet  bei  AES-
     Aufrufen   darauf,  da  ihr  einen  *korrekten/initialiserten* und
     *vollstndigen* AES-Parameterblock verwendet!!!

    Es liegt  ein  Patchfile  fr  MacSnd  dabei.  Das  entsprechende
     Kapitel beachten!

    Die  ersten  Beschreibungen  von Liberty fr Programmierer in die
     Doku integriert.

...to be continued



8  Kontaktadresse
*****************

Falls Sie irgendwelche Fragen, Probleme oder Wnsche bezglich Liberty
haben sollten, knnen Sie mich unter folgender Adresse erreichen:

Christian Krger
Im Erpelgrund 16
13503 Berlin

Internet email: chrisker@cs.tu-berlin.de

*Wichtig:* Wer  Kontakt  via  Sackpost zu mir aufnehmen will, der sollte
(wenn er  eine  Antwort  erwartet)  einen  an  sich  adressierten  und
ausreichend frankierten Rckumschlag beifgen!
Von  privaten  Besuchen  bitte  ich abzusehen, die Erfolgschancen mich
anzutreffen sind ohnehin ziemlich gering.
Auerdem bitte ich alle Anwender der Library nur dann zu  mir  Kontakt
aufzunehmen,  wenn  unlsbare Probleme oder gravierende Mngel bei der
Installation der Library auftreten! (Ich  verstehe  darunter  das  man
sich  mindestens  2x  die  Liberty- Dokumentation durchgelesen hat und
immernoch nicht schlauer ist!!!)
Zeit die ich mit der Beantwortung von Fragen verbringe steht mir nicht
mehr  zum  Programmieren  zur  Verfgung... (Ein gutes und hilfreiches
Forum um solche Fragen evt. zu klren stellt die "Hotline der  Share-/
Freeware",  das  Maus-Netz,  Gruppe 'atari.soft' dar. Wren hier nicht
viele hilfsbereite und kompetente Menschen zugegen, die bei Fragen  zu
Programmen   durch   ihre   Beantwortung   fr   die   Programmautoren
einspringen, wer wei ob Liberty htte jemals entstehen knnen...  Ich
widme  daher  diese  Library  allen  Atari-Enthusiasten im Maus-Netz -
*Danke!* :-) )

/Rchtzszeibunsflr by Zeitmangel./



