                               Liberty

                    Dokumentation zur Version 1.30
                              22.02.1998

                                 von

                           Christian Krger
                           Im Erpelgrund 16
                             13503 Berlin

                       Internet: chris@pace.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  Die Liberty-Struktur
    5.4  Die Utility-Funktionen
         5.4.1  Init_Liberty();
         5.4.2  lock_Sema();
         5.4.3  release_Sema();
         5.4.4  memcpy();
         5.4.5  memset();
    5.5  Die 'GEMDOS-Erweiterungen'
         5.5.1  CK_init_meminfo()
         5.5.2  CK_malloc()
         5.5.3  CK_realloc()
         5.5.4  CK_free()
         5.5.5  CK_load_buffer()
    5.6  Die 'VDI-Erweiterungen'
    5.7  Die 'AES-Untersttzung'
    5.8  Die Sound-Funktionen
    5.9  Programmbeispiel

 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  (die  Funktionen  ;-))  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  30kB  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 30kB
     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 90% 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  Atari-Kompatiblen  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  Rechner  mit  DMA-Sound
((Mega)STE/TT),  FalconO3O  sowie  fr  Apple-Rechner  mit 'MacSound'.
Rechner mit PSG-(Emulation) 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 (...legt  STARTRACK  ein  McSn-Keks
an?  -  Dann  funktioniert  auch  mit  dieser  Karte  schon die Sound-
Ausgabe...).

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 man 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  (Mega)STE/TT/FalconO3O  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 (2.01)' 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.


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!

    Um  Doppeldeutungen  zu  vermeiden:  Ein Programm welches Liberty
     benutzt wird folgend  immer  als  'Applikation'  bezeichnet.  Das
     sollte man im Hinterkopf behalten...


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  und  dem  entsprechendem   Kapitel   (Die
Liberty-Struktur) 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  Die Liberty-Struktur
=========================

Der Inhalt des Liberty-Cookies weist auf folgende Struktur:

typedef struct
{
        WORD            version;        /* Hexadezimale Version. (0x0100 = 1.0)  */
        WORD            gdriver;        /* Untersttzes Grafiksystem (READ_ONLY!):
                                                 * 0 = keins -> Standardformat (SLOW!!!)
                                                 * 1 = ATARI Grafiksystem (IBPs)
                                                 * 2 = NOVA Grafikkarten (Intel-Zahlenformat)
                                                 * 3 = andere Grafikkarten/Mac? (Motorola)
                                                     * Wert ist bist zur Version 1.5 ungltig!!! */                                              */
        Lity_Utils  *misc_funcs;/* Zeiger auf diverse Routinen */
        Lity_GDExt      *gd_funcs;      /* Zeiger auf die 'GEMDOS'-Erweiterungen */
        Lity_VDIExt     *vdi_funcs; /* Zeiger auf die 'VDI'-Erweiterungen    */
        Lity_AESExt *aes_funcs; /* Zeiger auf die 'AES'-Erweiterungen    */
        Lity_SNDExt *snd_funcs; /* Zeiger auf Sound-Funktionen */

} Liberty_Cookie;

Neben der  Versionsnummer  und   dem   Code   fr   das   untersttzte
Grafiksystem  findet  man  hier fnf weitere Zeiger auf Strukturen die
folgend erlutert werden.


5.4  Die Utility-Funktionen
===========================

Die Funktionen  die  man  hier  vorfindet  lassen  sich  nicht   einer
bestimmten  Kategorie  unterordnen.  Die  Struktur  enthlt  mehr oder
weniger 'zusammengewrfelte' Funktionszeiger:

typedef struct
{
        LONG     (*Init_Liberty)(WORD g_handle);
        void     (*lock_Sema)(BYTE *semaphore);
        void     (*release_Sema)(BYTE *semaphore);
        void     (*memcpy)(void *dest, void *src, ULONG len);
        void     (*memset)(void *dest, int val, ULONG len);
} Lity_Utils;


5.4.1  Init_Liberty();
----------------------

bekommt als  Eingabeparameter  das  Handle  der  physikalischen   VDI-
Workstation, in der Form wie es vom AES-Call 'graf_handle()' geliefert
wird. Der Rckgabewert ist reserviert.
*Diese Funktion ist vor  allen  anderen  Liberty-Funktionen  aufzurufen
(abgesehen von der XBIOS-CJar-Erweiterung)!*
Da  der  Aufruf  von graf_handle() unbedingt _nach_ einem appl_init() zu
erfolgen hat (Stichwort: korrekte Applikationsprogrammierung), mu der
appl_init()-Aufruf logischerweise vor dem graf_handle()-Aufruf erfolgt
sein.  Die  Reihenfolge  der  Initalisierung   kann   man   auch   dem
Programmbeispiel entnehmen.


5.4.2  lock_Sema();
-------------------

Setzt (z.B.  fr  Prozesskommunikation) eine Semaphore, dessen Adresse
bergeben wird. Wer mit dem Begriff 'Semaphore' nichts anfangen  kann,
wird diese Funktion wahrscheinlich auch nicht bentigen.


5.4.3  release_Sema();
----------------------

Gibt eine 'gelockte'-Semaphore wieder frei.


5.4.4  memcpy();
----------------

Bei dieser  Funktion handelt es sich um das altbekannte 'memcpy' jeder
'string.h'-C-Biblothek,  welches  einen  Speicherbereich  vorgegebener
Lnge kopiert.
Warum dieser Funktion in Liberty aufgenommen wurde?
Weil  viele  Programme (inkl. Liberty selbst) diese Funktion bentigen
und das Benutzen der Funktion  via  Liberty  ein  wenig  Speicher  bei
Applikation  einspart.  (Vorausgesetzt  man verwendet wirklich *nur* das
Liberty 'memcpy()'!)


5.4.5  memset();
----------------

Fr 'memset()' (ebenfalls eine  Standard-C  Funktionalitt)  gilt  das
gleiche  wie  schon bei 'memcpy()' beschrieben. Nur das diese Funktion
zum Setzen eines Speicherbereiches auf einen bestimmten Wert verwendet
wird.


5.5  Die 'GEMDOS-Erweiterungen'
===============================

Die Struktur  'Lity_GDExt'  enhlt  fnf Funktionen die alle 'GEMDOS'-
charakteristisch  sind.  Hauptschlich  dienen  die   Funktionen   der
Kontrolle ber die Liberty Speicherverwaltung:

typedef struct
{
        Meminfo *       (*CK_init_meminfo)(Meminfo *info, BOOLEAN app);
        void *          (*CK_malloc)(Meminfo *info, const long size, const WORD type);
        void *          (*CK_realloc)(Meminfo *info, const void *block, const LONG newsize);
        void            (*CK_free)(const Meminfo *info, const void *ptr);
        void            *reserved;
        void *          (*CK_load_buffer)(char *filename, Meminfo *info, WORD type, LONG addmem, LONG *buflen);

} Lity_GDExt;

/Die Form  der  'Meminfo'-Struktur  entnimmt  man der beigefgten '.h'-
Datei./


5.5.1  CK_init_meminfo()
------------------------

Eine Applikation die die Liberty-Speicherverwaltung nutzen will,  muss
bevor sie Speicher via Liberty anfordern kann drei Dinge tun:

  1. Eine globale Variable des Typs 'Meminfo' bereitstellen...

  2. Eine  globale  Variable  der  Typs  'Meminfo*'  (Zeiger  auf eine
     'Meminfo'-Struktur' anlegen

  3. und  diese  durch  Zuweisung  des  Rckgabewertes  der   Funktion
     'CK_init_meminfo()' initalisieren.

Als ersten  Parameter muss man dabei die Adresse der globalen Meminfo-
Variablen bergeben (siehem auch Programmbeispiel).

/Was ist der Sinn dieser Aktion?/
Liberty untersucht je nach Betriebssystem und Startmodus (ACC/APP)  ob
es die Meminfoblcke verschiedener Liberty-Applikationen zusammenlegen
kann, um eine effizientere Speicherverwaltung zu ermglichen.
Folglich muss  der  Zeiger  den  man  als  Rckgabewert  erhlt  nicht
identisch  mit  der  Adresse des eigenen 'Meminfo'-Blocks sein. *Dieser
Zeiger  (Rckgabewert)  ist  aber   der   einzige,   der   bei   allen
nachfolgenden  Liberty-Funktionsaufrufen die nach einem entsprechenden
Typ verlangen bergeben werden darf.*

_Auerdem:_
Jeglicher Inhalt  der  'Meminfo'  (Struktur-)Variablen  darf  von  der
Applikation   *nicht* angetastet   werden!   Liberty  obligt  die  volle
Kontrolle dieser Struktur! Ein Verndern der  'Meminfo'-Inhalte  fhrt
unweigerlich   zur   totalen  Verwirrung  der  Speicherverwaltung  und
Systeminstabilitt ist die Folge!

Der zweite Parameter des 'CK_init_meminfo()'-Calls  (app)  besagt,  ob
die  Applikation  als eine solche (1) oder als Accessory (0) gestartet
wurde. Zur Ermittlung dieses  Wertes  verwendet  man  das  landlufige
Verfahren  welches  im  Profibuch  (10. Auflage) Seite 541 beschrieben
ist.

/Im Falle der Verwendung von PureC kann man auch  gleich  die  Variable
des    PureC-Startup-Codes    '_app'    benutzen    (wie    auch    im
Programmbeispiel), oder man setzt den Parameter, fr den Fall da  die
Applikation  nur  als  eine  solche  und nicht als Accessory gestarted
werden darf, gleich statisch auf 'TRUE'./

Noch etwas:
Natrlich sollte man in seiner Applikation nur /eine/ Speicherverwaltung
nutzen.  Die Vermischung von Speicheranforderungen via z.B. GEMDOS, C-
Library und Liberty fhren zwar  nicht  zur  Applikationsinstabilitt,
aber   sind   alles   andere  als  guter  Programmierstil,  da  schwer
kontrollierbar (welchen Block mu ich wie freigeben) und ineffizient.
Die Verwendung  der  Liberty-Speicherverwaltung  sollte  ohnehin  alle
Speicheranforderungsbedrfnisse des Programmierers befriedigen und ein
Mischen von Aufrufen unntig machen.


5.5.2  CK_malloc()
------------------

Diese Funktion fordert Speicher vom System an. Im Gegensatz zum GEMDOS
werden  aber  kleinere Speicherblcke automatisch in grsseren Blcken
gehalten  um  evt.  Betriebssystembeschrnkungen   zu   umgehen.   Die
Verwaltung  der  Blcke  ist uerst effizient, schnell und sollte auf
jedem Fall andern Speicheranforderungsmechanismen  vorgezogen  werden,
da  auch  noch  andere  Argumente  fr  die  Verwendung  der  Liberty-
Speicherverwaltung sprechen:

    Liberty sorgt auch bei  Accessories  unter  Single  TOS  fr  ein
     'festes'  Malloc. Normalerweise gehrt Speicher, der nachtrglich
     von Accessories unter Single TOS angefordert wird  der  aktuellen
     Hauptapplikation  und /nicht/ dem Accessory. Das fhrt beim Beenden
     der Hauptapplikation zu ungewolltem Speicherverlust  seitens  des
     Accs und ist eine hufige Fehlerquelle.
     Dieses    Problem   existiert   bei   Verwendung   der   Liberty-
     Speicherverwaltung nicht mehr!

    Liberty ermglicht eine optimale  Verwaltung  von  Speicher  auch
     unter Systemen mit Speicherschutz ('Memory-Protection').
     Bei  der  Anforderung  von  Speicher  via  'CK_malloc()' kann die
     gewnschte Speicherart bergeben werden (Parameter 'type'):

      MM_STGLOBAL   bei bergabe dieses Speichertyps  fordert  Liberty
                    globales   (ungeschtztes)  ST-RAM  an  (z.B.  fr
                    'Message-Puffer')

      MM_STPRIVATE  Liberty fordert privates (geschtztes) ST-RAM an

      MM_TTGLOBAL   hier   fordert    Liberty    *vorzugsweise* globales
                    (ungeschtztes)  TT-RAM  an.  Steht nicht gengend
                    TT-RAM (wird auch als 'Fast-RAM'  bezeichnet)  zur
                    Verfgung,   wird  automatisch  (globales)  ST-RAM
                    angefordert.

      MM_TTPRIVATE  Liberty versucht privates (geschtztes) TT-RAM  zu
                    reservieren.   Steht  nicht  gengend  TT-RAM  zur
                    Verfgung,  wird  automatisch  (privates)   ST-RAM
                    angefordert.  Dieses  ist  wohl  der am hufigsten
                    verwendete Typ der Speicheranforderung ('schnell &
                    sicher').

     Das Besondere  der  Speicheranforderungen seitens Liberty besteht
     nun  darin,  dass  die   Speicherblcke   je   nach   tatschlich
     vorhandener  Speicherart  optimiert  gehalten werden. Mit anderen
     Worten:  Exisitiert  nur  globaler  Speicher   (weil   z.B.   die
     Applikation  unter  einem  Betriebssystem gestartet wurde welches
     nur  'nicht   privaten   Speicher'   untersttzt)   werden   alle
     Anforderungen von privatem Speicher in Anforderungen von globalem
     Speicher umgesetzt. Dieses Verfahren spart dadurch sogar z.T. das
     Anfordern von neuen GEMDOS-Systemblcken und damit Speicherplatz.

    Die  Speicherverwaltung von Liberty prft einige Kriterien ob der
     von ihr verwaltete Speicher durch  eine  Applikation  korrumpiert
     wurde.  In  diesem  Fall erhlt man entsprechende Fehlermeldungen
     auf dem Bildschirm. So wird man auf  Applikationsfehler  bei  der
     Verendung  von  Speicher hingewiesen, was bei der Entwicklung von
     Programmen kein unwesentlicher Punkt ist.

Doch zurck zum 'CK_malloc()':
Neben der bergabe des  zuvor  beschriebenen  'Meminfo'-Pointers  wird
noch  die  anzuforderne  Blockgrsse  in  Byte  sowie  der  oben schon
beschriebene Speichertyp  mit  bergeben.  Der  Rckgabewert  ist  ein
Zeiger  auf  den  Block oder 'NULL' falls entsprechener Speicher nicht
angefordert werden konnte (Speicherknappheit).


5.5.3  CK_realloc()
-------------------

Diese Liberty-Routine  arbeitet  analog  zum  C-'realloc()'  und   dem
Liberty-'CK_malloc()'.
/ Eine Speichertypnderung ist *nicht* mglich!/


5.5.4  CK_free()
----------------

ist die Implementierung des C-'free()' der Liberty-Speicherverwaltung.


5.5.5  CK_load_buffer()
-----------------------

Wie oft  kommt es vor das ein Programmierer eine Datei in einen Puffer
laden mu und  jedesmal  die  gleiche  Sequenz  von  Funktionsaufrufen
gettigt wird...

Damit sollte  nun Schluss sein. Die Parameter der Liberty-Buffer-Lade-
Funktion sollten eigentlich selbsterklrend sein, hier  aber  trotzdem
die bersicht:

 filename  Dateiname der zu ladenen Datei

 info      der schon bekannte Meminfo-Pointer

 type      anzuforderne Speicherart

 addmem    Anzahl  der  Bytes  die  zustzlich anzufordern sind. Diese
           sind nach dem Laden der  Datei  am  Ende  des  Buffers  und
           unbelegt.

Die Funktion  liefert einen Zeiger auf den angeforderten und geladenen
Buffer oder 'NULL' falls ein  Fehler  aufgetreten  ist  (Datei  konnte
nicht geladen werden, zu wenig Speicher vorhanden etc.).

Jetzt kommt's:  Als  besonderes Schmankerl kann die Buffer-Laderoutine
aber noch mehr: Dateien die mit  dem  'ATOMIK'-Packer  gepackt  wurden
(ein  uerst  effzienter  Packer  dessen Dateien zustzlich auch noch
flink zu dekodieren sind) werden automatisch ausgepackt!

Das Packen ist z.B. sinnvoll bei MOD-Files, bestimmten Grafikformaten,
archivierten  Texten  oder  sonstigen  einteiligen, groen Dateien die
nicht oder sehr selten angetastet werden.


5.6  Die 'VDI-Erweiterungen'
============================

Hier kommt noch etwas hin...


5.7  Die 'AES-Untersttzung'
============================

Hier kommt noch etwas hin...


5.8  Die Sound-Funktionen
=========================

Hier kommt noch etwas hin...


5.9  Programmbeispiel
=====================

Das Programmbeispiel geht davon aus, da die '.h'-Dateien  'LIBERTY.H'
und  'IBMR.H'  in Standard-Include-Verzeichnis des C-Compilers liegen.
Das hier gezeigte Beispiel demonstriert die Initalisierung der Library
und Speicherverwaltung unter PureC:

#include <liberty.h>
#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <aes.h>
#include <vdi.h>
#include <tos.h>

Meminfo         minfo, *mi;                     /* Applikations Meminfo-Block und Zeiger */

void main(void)                 /* Dieses Programm macht nix... */
{
        Liberty_Cookie  *libstruct;
        Lity_GDExt              *gdfuncs;
        int                     d1, d2, d3, d4, grhandle;

        appl_init();                            /* ...obwohl es einige Programmierer noch
                                                                   nicht begriffen haben: DAS GEHRT SICH SO! */

        if (CJar(0,COOKIE_LIBERTY,&libstruct) != CJar_OK)
        {
                form_alert(1,"[3][This Application needs LIBERTY to run...][Exit!]");
                appl_exit();
                return;
        }

        vh = graf_handle(&d1, &d2, &d3, &d4);

        libstruct->misc_funcs->Init_Liberty(grhandle);  /* Liberty initalisieren */

        gdfuncs = libstruct->gd_funcs;                                  /* ...trgt nur zur
                                                                                                           Lesbarkeit bei... */

        mi = gdfuncs->CK_init_meminfo(&minfo,_app);     /* Speicherverwaltungsinit */

/* HIER STEHT DAS EIGENTLICHE PROGRAMM ! */
/* ...fr Meminfos wird jetzt immer 'mi' bergeben !!! */

        if (_app)                                       /* Applikation ? */
                appl_exit();                                /* raus... (MT-OS Behandlung
                                                                                                           der Einfachheit wegen
                                                                                                           weggelassen) */
        else
                for (;;)                                    /* Beim Acc sporadisch */
                        evnt_timer(0,32000);                                    /* beenden             */
}



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

Zum Zeitpunkt  dieser  Verffentlichung von 'Liberty' sind die Raster-
grafikfunktionen 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.30*

    Ich  kann's  nicht  fassen.  Unsaubere  Applikation  bringen mich
     irgendwann einmal noch um den Verstand. In  dieser  Version  habe
     ich       DEFINITIV       die       letzte       nderung      am
     Schweineprogrammbehandlungsteil         vorgenommen.         Eine
     Sonderbehandlung  fr  MTOS/NAES  und  MagiC  soll  nun  maximale
     Kompatibilitt  auch  bei  unsauberen  Programmen  bringen.  U.a.
     profitieren dadurch auch ltere Versionen von MGCOPY,MGVIEW etc.,
     die, was die Sauberkeit der Systemanbindung anging, noch nicht so
     prall  waren.  Die jetzige Schweineprogrammbehandlungsroutine ist
     *definitiv* der Weisheit letzter Schluss!
     Da  OAESis  nicht  ein  vernnftiges  appl_find(NULL)   anbietet,
     sondern ziemlich Bldsinn macht, kann ich OAESis *nicht* empfehlen.
     Liberty    es    ist    praktisch    unmglich   Liberty&Freedom2
     unproblematisch unter OAESis zum Laufen zu bringen. Aussagen ber
     GENEVA und XAES kann ich nicht treffen.
     _WICHTIG:_ Damit  Liberty  ordnungsgem  unter MagiC arbeitet, ist
     eine MagiC-Version >= 3.x unabdingbar!!!

    Besitzer von Rechnern mit DMA-Sound ((Mega)STE,  TT)  kommen  nun
     endlich auch in den Genu der Liberty-Soundfunktionen. Neben Macs
     mit 'MACSOUND' und Falcons kommt bei  diesen  Rechnern  nun  also
     auch  Freude  auf, wenn man im Freedom2 Info-Dialog auf das groe
     'Freedom-Logo' klickt... (wenn die Software  der  Startrack-Karte
     fr  den  HADES auch einen 'McSn'-Cookie anlegt (tut sie das? wer
     sagt's mir?), bekommen die HADES-User auch was zu hren...)

    Weitere Beschreibungen von Liberty fr Programmierer in die  Doku
     integriert.

    ...und immer noch viel zu tun...

*nderungen Version 1.20*

    Endlich  arbeitet  Liberty mit NAES korrekt zusammen. Was war die
     Ursache? Na ? - Die Schweineprogrammbehandlung.
     Ohne einen Anruf von Rainer Mannigel (NAES-Entwickler)  wre  das
     wohl  nie  etwas  geworden.  Durch  ihn  habe  ich von einer NAES
     internen Sache erfahren und das ermglichte  mir  Liberty  darauf
     abzustimmen.
     Ich  hoffe  den  Schweineprogrammbehandlungsteil  nun  nicht mehr
     anfassen zu mssen... ;-)

*nderungen Version 1.15*

    Liberty  ist   jetzt   /noch/ rcksichtsvoller   Schweineprogrammen
     gegenber  und  billigt  ihnen  mehr  SV-Stack zu. (Das kostet 5k
     mehr... :-()
     Dadurch luft jetzt Liberty mit dem VT52 Emulator in der  Version
     1.3 zusammen was einem Benutzer ;-) besonders wichtig war...

    Das  'free' der Speicherverwaltung von Liberty erlaubte nicht das
     Freigeben eines NULL-Pointers, was  aber  offiziell  dokumentiert
     ist.

*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: chris@pace.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 und Portfolio-Tastatur!/



