Dokumentation 0.2
05.03.1997
von
Christian Krüger
Im Erpelgrund 16
13503 Berlin
Internet: chrisker@cs.tu-berlin.de
Das Copyright an Liberty und dieser Dokumentation liegt bei Christian Krüger, Berlin. Die Weitergabe des Programms ist Grundsätzlich frei (Stichwort FREEWARE), dennoch sind folgende Punkte zu beachten:
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
Trotz sorgfältiger Entwicklung und umfangreichen Tests kann keine Gewährleistung für die Richtigkeit des Inhalts dieser Dokumentation und die einwandfreie Funktion von "Liberty" übernommen werden.
Der Autor kann keine Haftung für irgendwelche direkten oder indirekten Schäden - einschließlich aber nicht beschränkt auf materielle oder finanzielle - übernehmen, die durch die Benutzung von "Liberty" oder dessen Untauglichkeit für einen bestimmten Zweck entstehen.
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.
Wie schon erwähnt ist Liberty Freeware. Ich habe aber
selbstverständlich nichts gegen
TOS-Programmentwicklungsstützungskäufe ;-). Wer mit
also eine motivationssteigernde Spende zukommen lassen möchte,
kann das über die Kontaktadresse tun.
Wer keine Lust hat etwas zu spenden und trotzdem meine Motivation
steigern möchte, der sollte sich 'Freedom2' kaufen. Dann bekommt
man wenigstens etwas für's Geld ;-) ...
(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.
'LIBERTY.PRG' sollte physikalisch möglichst früh 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 verändern. 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' möglichst weit vorne
stehen. Ein Ändern der Bootreihenfolge erreichen Sie durch
Verschieben des kompletten AUTO-Ordners in ein anderes Verzeichnis und
dem Zurückverschieben aller AUTO-Ordner-Programme in
gewünschter Reihenfolge in den AUTO-Ordner. (Wer absolut nicht
versteht was ich meine, kann mich unter später genannter Adresse
kontaktieren.) MagiCMac Benutzer müssen den Umweg über
Umbenennen der Dateien oder Bootreihenfolgedatei (wie in der MagiCMac
Dokumentation beschrieben) gehen um Liberty möglichst früh
zu initalisieren (MiNT wird wohl keiner auf Macs benutzen ;-)
).
Liberty ist eine residente Systemerweiterung. Das bedeutet, daß eine Vielzahl von Funktionen die in Liberty vorhanden sind, anderen Programmen angeboten werden. Das bloße Vorhandensein von Liberty ändert nicht viel an Ihrem System, sondern die Funktionen der Library (oder auch Systemerweiterung, folgend Lib genannt) müssen 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 lauffähig ist.
Nun gibt es (oft zurecht) viele Gegner solcher Systemerweiterungen. Die Argumente gegen den Einsatz einer residenten Erweiterung sind meistens folgende:
Die Vorteile solcher Erweiterungen:
Liberty hat natürlich diese Vorteile und entkräftet zusätzlich mit seiner Art des Aufbaus die Nachteile:
Überzeugt?
Liberty setzt sich aus Funktionen mit den unterschiedlichsten Aufgabengebieten zusammen. Obwohl daher das Funktionsangebot vielleicht etwas zusammengewürfelt scheint, ist dem nicht so. Wie schon erwähnt versucht Liberty die nervensten Schwächen des Betriebsystems auszugleichen: Funktionen, die immer wieder programmiert oder eingebunden werden müssen und die viele Programme benötigen. Das diese Schwächen 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 Löschen von 'Cookies' ermöglicht
- Soundfunktionen welche eine rechnerunabhängige Tonausgabe garantieren
Erweiterungen mit GEMDOS-Charakteristik:
- eine sehr effiziente und schnelle Speicherverwaltung, die privaten, globalen, normalen und alternativen Speicher (wenn nötig) unterscheidet und kleinere Speicherblöcke in größeren verwaltet sowie für ein dauerhaftes, sicheres 'malloc' für 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-Unterstützung:
- Funktionen zum einfachen Einhängen 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 würde!
Liberty legt beim Start im AUTO-Ordner automatisch einen 'Cookie-Jar' an. Programme die dieses sonst übernommen haben ('CJARxxx.*' etc.) sind damit überflüssig! Ebenfalls, das für den MiNT Aufsatz 'Geneva' benötigte 'JARxxx.PRG' ist unnötig. In Liberty sind die Fähigkeiten dieses Programms enthalten! (JARxxx wurde getestet, für gut befunden und die Funktionalität (erweitert) aufgenommen.)
Die Größe des 'Cookie-Jar' kann mit dem
beigefügten Programm 'SIZEJAR.TTP' verändert werden. In der
Grundeinstellung wird beim Start von Liberty für 32
zusätzliche 'Kekse' (zu den aktuell vorhandenen Systemcookies)
Platz geschaffen. Diesen Wert kann man wiefolgt ändern:
In der Regel sollte dieses Vorgehen jedoch unnötig sein, da 32 (zusätzliche) Kekse ausreichen und auch keine große Speicherverschwendung darstellen.
Liberty bietet eine komfortable und einheitliche Schnittstelle zur Soundausgabe. Mit Hilfe dieser Erweiterung können (bald) alle Benutzer von Atarikompatiblen in den Genuß eines klangvollen Erlebnisses kommen. Die Zeiten bei denen Programme die Soundausgabe auf bestimmte Systeme einschränken, oder diese nur mit käuflichen Programmen garantieren, sollten damit für immer vorbei sein.
Realisiert wurde die Soundausgabe schon für FalconO3O-Rechner
sowie für Apple- Rechner mit 'MacSound'. ST/STE/TT Rechner folgen
demnächst.
Bisher hatte ich noch keinen Kontakt zu Medusen oder dem Hades,
halte hier aber eine Anpassung für die exisiterende Soundkarte
ebenso wie für PC's mit XBIOS-Treiber möglich.
Wichtig ist nur, daß sich ein Anwenderprogrammierer keine
Gedanken mehr um evt. Soundfähigkeiten des Rechners machen
muß. Das Vorhandensein von Liberty garantiert ein Ansprechen der
Soundfunktionen, auch wenn diese ohne Treiber funktionslos bleiben.
Zum Patchprogramm für MacSound (nur für
Apple-Rechner):
MacSound (ein Autoordnerprogramm welches MagiCMac beiliegt und
XBIOS-Soundfunktionen zur Verfügung stellt) ist leider nicht so
mächtig wie es anderen Programmen gegenüber vorgibt. Um
korrektes Funktionieren zu gewährleisten, ist es daher nötig
MacSound zu patchen. Eine Patchdatei mit dem entsprechenden
Patchprogramm befindet sich im Ornder 'MCSNDPAT'.
Um MacSound zu patchen, muß man folgendermaßen vorgehen:
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 enthält. Eine Sicherungskopie der Originals wird also automatisch erzeugt.
An dieser Stelle Dank an Christian Wempe & Holger Weets für ihr Patchprogramm 'DIFFY' bzw. 'PATCHY'. Ich hoffe es ist Ok, daß ich 'PATCHY' einfach so (einzeln - um Verwirrung zu vermeiden...) beigefügt habe (in eurer Doku steht zu diesem Thema leider nichts), schließlich 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 gefällig?
Den Info-Dialog von Freedom2 aufrufen (Klick mit der rechten
Maustaste auf das Freedom2-Logo bei installiertem Konfig.CPX)
und anschließend das große Freedom2-Logo im Info-Dialog
anklicken...
Wenn sie einen FalconO3O haben, oder MagiCMac mit gepatchtem
MacSound benutzen, dann müßten sie was 'Nettes' gehört
haben...
Vektorzeichensätze und Bezierkurven sollten heutzutage eine
Selbstverständlichkeit sein. So werden diese Befehle auch von den
Vektorgrafikfunktionen in Liberty ordnungsgemäß
verarbeitet. Leider ist das Original-VDI (der Betriebssystemteil der
für die Ausgabe von Grafiken verantwortlich ist) nicht in der
Lage diese Befehle zu verarbeiten und ignoriert sie völlig.
Das bedeutet, daß wenn ein Programm die
Vektorgrafikdarstellungsfunktionen von Liberty benutzt und die
darzustellende Grafik Bezierkurven und/oder Vektorzeichensätze
enthält, das Ergebnis auf dem Bildschirm nicht der Originalgrafik
entspricht. Dieses trifft aber selbstverständlich nur für
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 großer
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! (Für die Experten: Man
läd das Register D0 mit -1 und macht einen TRAP #2 Aufruf. Als
Ergebnis erhält man die Einsprungsadresse des VDI-Dispatchers.)
VDI-Erweiterungen, die das VDI hinsichtlich z.B. einer
Bezierkurvenausgabe erweitern, müssen dieses Verfahren
unterstützen (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 versäumt es offensichtlich obiges Verfahren zu unterstützen und somit ist dieses Ausgabesystem für Liberty praktisch nicht vorhanden (keine Bezierkurven und keine Vektorzeichensätze!!!).
Ich weiß, daß diese Tatsache sicherlich einige Leute ziemlich verärgert und möchte deshalb hier Forderungen nach 'konformer' Ausgabe über den TRAP vorbeugen:
Meine Empfehlung an SpeedoGDOS-Fanatiker die programmieren
können:
Programmiert ein Utility welches sich in den TRAP #2 hängt,
die -1 abfängt und die Adresse des SpeedoGDOS-Dispatchers
zurückliefert. Dann klappt's auch mit Liberty... ;-)
Sie sind Programmierer, die Featureliste von Liberty hat Sie
locker vom Hocker geworfen und Sie sagen sich:"Eine tolle
Library, die will ich auch unterstützen!"
Kein Problem!
Einzige Voraussetzung um die Library benutzen zu dürfen: Ich erhalte ein kostenloses Exemplar des Programms welches die Library benutzt! Software die den Status 'Public Domain', 'Freeware' oder 'Fairware' hat, ist davon natürlich ausgenommen ;-).
In der letzten Doku zu Liberty habe ich noch von einer seperaten Dokumentation für Programmierer gesprochen. Da die Resonanz aber unerwartet groß war und ich mir die Arbeit zwei Dokumentationen zu pflegen ersparen möchte, wird die Beschreibung der Liberty-Funktionen schrittweise in diese Doku eingeflechtet.
Was sie folgend als Beschreibung finden ist keineswegs vollständig!!!
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...)
Ich möchte an dieser Stelle nicht alles wiederholen was bereits oben beschrieben wurde. Daher nur nochmal ein Kurzüberblick über das, was Programmierer wissen müssen:
Für die Parameterübergabe gelten die Regeln von Turbo C
/ Pure C:
Parameterübergabe Pure C (Auszug aus der Online Hilfe von
PureC)
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 Verfügung stehen, benötigen 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) (höchstwertiges Wort im Stack)
&f (lo)
y2 (Wert von y2)
Return- (Rücksprungadresse)
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 Rücksprungadresse 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 räumt 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 erübrigt sich natürlich, wenn alle Parameter in Registern übergeben wurden.
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 beigefügten '.h'-File entnommen werden kann.
Da Liberty XBIOS-Funktionen installiert, die einen komfortablen Zugriff auf den Cookie-Jar ermöglichen, 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' prüft 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 benötigt es also nicht mehr), existieren sogar 3 Modi zur Keks-Manipulation:
...to be continued...
Zum Zeitpunkt dieser ersten Veröffentlichung 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 für
die Herausgabe der Library im nicht vollständigem Zustand
entschieden.
Erste Erweiterung wird folglich darin bestehen, den
Rastergrafikteil vollständig auszubauen. Aber auch im
Vektorgrafikteil fehlen noch einige wünschenswerte
Zusatzfunktionen.
Wie danach die Weiterentwicklung verläuft ist schwer zu sagen. Hauptsächlich hängt das von meinen eigenen Bedürfnissen ab. Selbstverständlich können auch Wünsche 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 möglichst immer die neuste Liberty-Version installiert hat. Da Liberty benutzenden Programmen beigefügt werden darf, dürfte diese Forderung leicht zu erfüllen sein.
Änderungen Version 1.1
...to be continued
Falls Sie irgendwelche Fragen, Probleme oder Wünsche bezüglich Liberty haben sollten, können Sie mich unter folgender Adresse erreichen:
Christian Krüger
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 Rückumschlag beifügen!
Von privaten Besuchen bitte ich abzusehen, die Erfolgschancen mich
anzutreffen sind ohnehin ziemlich gering.
Außerdem bitte ich alle Anwender der Library nur dann zu mir
Kontakt aufzunehmen, wenn unlösbare Probleme oder gravierende
Mängel 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 Verfügung... (Ein gutes und
hilfreiches Forum um solche Fragen evt. zu klären stellt die
"Hotline der Share-/Freeware", das Maus-Netz, Gruppe 'atari.soft' dar.
Wären hier nicht viele hilfsbereite und kompetente Menschen
zugegen, die bei Fragen zu Programmen durch ihre Beantwortung für
die Programmautoren einspringen, wer weiß ob Liberty hätte
jemals entstehen können... Ich widme daher diese Library allen
Atari-Enthusiasten im Maus-Netz - Danke! :-) )
Rächtzszeibunsfälör by Zeitmangel.