                               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
         4.3.1  Der Konvertierer GM2CKVDI

 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
                      DEVELOP     -> IBMR.H
                                     VDICODES.H
                      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
                      GM2CKVDI.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... ;-)


4.3.1  Der Konvertierer GM2CKVDI
--------------------------------

Um GEM-Metafiles  in  das  Liberty-Vektorformat  umzuwandeln  ist  ein
Konvertierer  beigefgt (GM2CKVDI.TTP). Das Liberty-Vektorgrafikformat
kann mehrere einzelne Grafiken enthalten, welche  es  interessant  fr
Vektoricons machen.

Da GEM-Metafiles  oft  sehr  'grozgig' und unprzise erzeugt werden,
ist es nicht ausgeschlossen, da der Konvertierer bei einigen  Dateien
ziemlich komische Ergebnisse erzeugt. Dieses ist abhngig vom Programm
mit dem die Dateien erzeugt wurden. Ausgerichtet ist der  Konvertierer
auf  Dateien  die  mit  'Kandinsky'  kreiert  wurden.  Hiermit  werden
korrekte Ergebnisse erzielt.

_Der Aufruf:_
GM2CKVDI -[cpnswm16h?] metafilename

Die bergebene Datei _mu_ mit  '.GEM'  enden.  Die  Zieldatei  wird  im
Verzeichnis  der  Quelldatei  erzeugt  und  erhlt je nach angegebenem
Zieltyp die Dateiendung '.CVD' oder '.C'.

_Die Optionen:_
Fr den bersetzungsvorgang existieren einige Optionen:

 -h,-help,-?  zeigt eine kurze Hilfe mit Erluterung der Optionen an

 -n           setzt im Header der Zieldatei den Namen der Grafik.
              Dieser  Name  kann  auch  ber  die   Grafik   darselbst
              definiert sein, indem die Grafik mit dem speziellen Text
              '((CN))/NAME/' versehen wird. Dieser Textbefehl wird _nicht_
              bersetzt   und   dient   lediglich   zum   Setzen   des
              Vektorgrafiknamens im Zieldateikopf.

 -s #         setzt  den  Grenmastab.  Dieser  legt  die   maximale
              Ausdehnung  der  zu  erzeugenden  Datei fest. Mit diesem
              Wert  wird  natrlich   auch   die   Quantisierung   der
              Grafikkoordinaten   in   der   Zieldatei  bestimmt.  Der
              Defaultwert ist 255. Der bergebene Wert darf zwischen 1
              und 32000 liegen.

 -c           die  Zieldatei  wird  nicht als Binrfile sondern als C-
              Quellcode abgelegt. Besonders dann praktisch,  wenn  man
              die Vektordaten in ein Programm mit einbinden mchte. Um
              die Vektordaten einbinden zu knnen,  bentigt  man  die
              '.h'-Dateien  im  Ordner  'DEVELOP'. Die Dateiendung der
              Zieldatei ist in diesem Modus '.C'.

 -m           die angegebene Quelldatei enthlt mehrer  Vektorgrafiken
              die     umgewandelt     werden    sollen    (z.B.    bei
              Vektoricondateien).   Der   Konvertierer   erkennt   die
              einzelnen  Vektorgrafiken  in einer solchen Datei daran,
              da die  diversen  Vektorgrafikobjekte  als  'Top-Level-
              'Gruppe  definiert  worden sind (Kandinsky: Gruppieren).
              Als 'Top-Level' bezeichne ich alle Gruppen  die  direkt,
              ohne   weitere   Gruppenauflsung  in  der  Vektorgrafik
              erreichbar  sind.   Diese   'Top-Level-Gruppen'   drfen
              folglich problemlos in ihrer (internen) Struktur weitere
              Objektgruppen enthalten. Top-Level-Gruppen  werden  dann
              jeweils    in    der    Zieldatei    als   eigenstndige
              Vektorgrafiken  verkettet.  Da  es  sinnvoll  ist,   den
              Grafiken  eigene  Namen zu verleihen und ber die Option
              -n nur ein Name gesetzt werden kann, solte man in  jeder
              Gruppe  den  Spezialtext  '((CN))/NAME/'  ablegen  um  die
              einzelne Grafik spter identifizieren zu knnen.
              /Die Vorhergehensweise wird klarer, wenn  man  eine  GEM-
              Meta-Datei   des   Dateiselektors   Freedom2  untersucht
              (liegen   in   der   Freedom2-Distribution   im   Ordner
              'VICON\SRC\')./

 -16          Farbfixierung  nur  mit  den  ersten  16 (Standard-)VDI-
              Farben vornehmen.  Beim  Umwandlungsvorgang  werden  die
              Farben   der  GEM-Metadatei  die  noch  als  Farbanteile
              beschrieben sind in  absolute  VDI-Indizes  umgewandelt.
              Dieses  geschieht  nach dem Verfahren 'Best-Fit' mit der
              aktuellen Farbpalette. Da es  nun  nicht  ausgeschlossen
              ist,  da  die benutzten Farben der GEM-Metadatei leicht
              von  den  16  unteren  Systemfarben  abweichen  und  als
              bestpassenste Farben Farben mit einem Index >16 gefunden
              werden, kann man die Suche auf die ersten 16 Farben  mit
              diesem Schalter beschrnken. Da die ersten 16 Farben von
              DR festgeschrieben sind, kann man so eine 'farbportable'
              CVD-Datei erzeugen.

 -w           Anzeige  des  Konvertierungsvorgangs.  Alle  bersetzten
              VDI-Befehle werden auf dem Bildschirm ausgegeben.

Hauptschtlich ist der Konvertierer (wie man  vielleicht  festgestellt
haben wird) fr ambitionierte Anwender und Programmierer interessant.



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'-Modulen   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!
Man kann mich auch anrufen, aber *_bitte_* nur von Mo-Do in der  Zeit  von
20:30-21:00  Uhr oder 22:00-22:30 Uhr! Wer zu anderen Zeiten die (030)
436 27 85 whlt braucht  sich  nicht  zu  wundern,  wenn  er  entweder
niemanden  erreicht  oder  mich ziemlich sauer oder kurz angebunden an
die Strippe bekommt!
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./



