Dokumentation zur Version 1.35
06.09.2000
von
Christian Krüger
Sophienstr. 10a
12203 Berlin
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
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
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 Atari-Kompatiblen 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 Rechner mit
DMA-Sound ((Mega)STE/TT), FalconO3O sowie für Apple-Rechner mit
'MacSound'. Rechner mit PSG-(Emulation) 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 (...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. 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 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 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 (Mega)STE/TT/FalconO3O 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... ;-)
Um GEM-Metafiles in das Liberty-Vektorformat umzuwandeln ist ein Konvertierer beigefügt (GM2CKVDI.TTP). Das Liberty-Vektorgrafikformat kann mehrere einzelne Grafiken enthalten, welche es interessant für Vektoricons machen.
Da GEM-Metafiles oft sehr 'großzügig' und unpräzise erzeugt werden, ist es nicht ausgeschlossen, daß der Konvertierer bei einigen Dateien ziemlich komische Ergebnisse erzeugt. Dieses ist abhängig 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 erhält je nach angegebenem Zieltyp die Dateiendung '.CVD' oder '.C'.
Die Optionen:
Für den Übersetzungsvorgang existieren einige Optionen:
| -h,-help,-? | zeigt eine kurze Hilfe mit Erläuterung 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 Größenmaßstab. Dieser legt die
maximale Ausdehnung der zu erzeugenden Datei fest. Mit diesem Wert
wird natürlich 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 Binärfile sondern als
C-Quellcode abgelegt. Besonders dann praktisch, wenn man die
Vektordaten in ein Programm mit einbinden möchte. Um die
Vektordaten einbinden zu können, benötigt man die
'.h'-Dateien im Ordner 'DEVELOP'. Die Dateiendung der Zieldatei ist in
diesem Modus '.C'.
|
| -m | die angegebene Quelldatei enthält 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
Gruppenauflösung in der Vektorgrafik erreichbar sind. Diese
'Top-Level-Gruppen' dürfen folglich problemlos in ihrer
(internen) Struktur weitere Objektgruppen enthalten. Top-Level-Gruppen
werden dann jeweils in der Zieldatei als eigenständige
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 später
identifizieren zu können.
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 beschränken. 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.
|
Hauptsächtlich ist der Konvertierer (wie man vielleicht festgestellt haben wird) für ambitionierte Anwender und Programmierer interessant.
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.
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 und dem entsprechendem Kapitel (Die Liberty-Struktur) 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:
Der Inhalt des Liberty-Cookies weist auf folgende Struktur:
typedef struct
{
WORD version; /* Hexadezimale Version. (0x0100 = 1.0) */
WORD gdriver; /* Unterstützes Grafiksystem (READ_ONLY!):
* 0 = keins -> Standardformat (SLOW!!!)
* 1 = ATARI Grafiksystem (IBPs)
* 2 = NOVA Grafikkarten (Intel-Zahlenformat)
* 3 = andere Grafikkarten/Mac? (Motorola)
* Wert ist bis zur Version 1.5 ungültig!!! */ */
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 für das unterstützte Grafiksystem findet man hier fünf weitere Zeiger auf Strukturen die folgend erläutert werden.
Die Funktionen die man hier vorfindet lassen sich nicht einer bestimmten Kategorie unterordnen. Die Struktur enthält mehr oder weniger 'zusammengewürfelte' 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;
bekommt als Eingabeparameter das Handle der physikalischen
VDI-Workstation, in der Form wie es vom AES-Call 'graf_handle()'
geliefert wird. Der Rückgabewert 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.
Setzt (z.B. für Prozesskommunikation) eine Semaphore, dessen Adresse übergeben wird. Wer mit dem Begriff 'Semaphore' nichts anfangen kann, wird diese Funktion wahrscheinlich auch nicht benötigen.
Gibt eine 'gelockte'-Semaphore wieder frei.
Bei dieser Funktion handelt es sich um das altbekannte 'memcpy'
jeder 'string.h'-C-Biblothek, welches einen Speicherbereich
vorgegebener Länge kopiert.
Warum dieser Funktion in Liberty aufgenommen wurde?
Weil viele Programme (inkl. Liberty selbst) diese Funktion
benötigen und das Benutzen der Funktion via Liberty ein wenig
Speicher bei Applikation einspart. (Vorausgesetzt man verwendet
wirklich nur das Liberty 'memcpy()'!)
Für 'memset()' (ebenfalls eine Standard-C Funktionalität) gilt das gleiche wie schon bei 'memcpy()' beschrieben. Nur das diese Funktion zum Setzen eines Speicherbereiches auf einen bestimmten Wert verwendet wird.
Die Struktur 'Lity_GDExt' enhält fünf Funktionen die alle 'GEMDOS'-charakteristisch sind. Hauptsächlich 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 beigefügten '.h'-Datei.
Eine Applikation die die Liberty-Speicherverwaltung nutzen will, muss bevor sie Speicher via Liberty anfordern kann drei Dinge tun:
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 Meminfoblöcke verschiedener Liberty-Applikationen
zusammenlegen kann, um eine effizientere Speicherverwaltung zu
ermöglichen.
Folglich muss der Zeiger den man als Rückgabewert erhält
nicht identisch mit der Adresse des eigenen 'Meminfo'-Blocks sein.
Dieser Zeiger (Rückgabewert) ist aber der einzige, der bei
allen nachfolgenden Liberty-Funktionsaufrufen die nach einem
entsprechenden Typ verlangen übergeben werden darf.
Außerdem:
Jeglicher Inhalt der 'Meminfo' (Struktur-)Variablen darf von der
Applikation nicht angetastet werden! Liberty obligt die volle
Kontrolle dieser Struktur! Ein Verändern der 'Meminfo'-Inhalte
führt unweigerlich zur totalen Verwirrung der Speicherverwaltung
und Systeminstabilität 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 landläufige 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, für den Fall daß die Applikation nur als eine solche und nicht als Accessory gestarted werden darf, gleich statisch auf 'TRUE'.
Noch etwas:
Natürlich sollte man in seiner Applikation nur eine
Speicherverwaltung nutzen. Die Vermischung von Speicheranforderungen
via z.B. GEMDOS, C-Library und Liberty führen zwar nicht zur
Applikationsinstabilität, 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
Speicheranforderungsbedürfnisse des Programmierers befriedigen
und ein Mischen von Aufrufen unnötig machen.
Diese Funktion fordert Speicher vom System an. Im Gegensatz zum GEMDOS werden aber kleinere Speicherblöcke automatisch in grösseren Blöcken gehalten um evt. Betriebssystembeschränkungen zu umgehen. Die Verwaltung der Blöcke ist äußerst effizient, schnell und sollte auf jedem Fall andern Speicheranforderungsmechanismen vorgezogen werden, da auch noch andere Argumente für die Verwendung der Liberty-Speicherverwaltung sprechen:
| MM_STGLOBAL | bei Übergabe dieses Speichertyps fordert Liberty globales
(ungeschütztes) ST-RAM an (z.B. für 'Message-Puffer')
|
| MM_STPRIVATE | Liberty fordert privates (geschütztes) ST-RAM an
|
| MM_TTGLOBAL | hier fordert Liberty vorzugsweise globales
(ungeschütztes) TT-RAM an. Steht nicht genügend TT-RAM (wird
auch als 'Fast-RAM' bezeichnet) zur Verfügung, wird automatisch
(globales) ST-RAM angefordert.
|
| MM_TTPRIVATE | Liberty versucht privates (geschütztes) TT-RAM zu
reservieren. Steht nicht genügend TT-RAM zur Verfügung, wird
automatisch (privates) ST-RAM angefordert. Dieses ist wohl der am
häufigsten verwendete Typ der Speicheranforderung ('schnell &
sicher').
|
Doch zurück zum 'CK_malloc()':
Neben der Übergabe des zuvor beschriebenen 'Meminfo'-Pointers
wird noch die anzuforderne Blockgrösse in Byte sowie der oben
schon beschriebene Speichertyp mit übergeben. Der
Rückgabewert ist ein Zeiger auf den Block oder 'NULL' falls
entsprechener Speicher nicht angefordert werden konnte
(Speicherknappheit).
Diese Liberty-Routine arbeitet analog zum C-'realloc()' und dem
Liberty-'CK_malloc()'.
Eine Speichertypänderung ist nicht
möglich!
ist die Implementierung des C-'free()' der Liberty-Speicherverwaltung.
Wie oft kommt es vor das ein Programmierer eine Datei in einen Puffer laden muß und jedesmal die gleiche Sequenz von Funktionsaufrufen getätigt wird...
Damit sollte nun Schluss sein. Die Parameter der Liberty-Buffer-Lade-Funktion sollten eigentlich selbsterklärend 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 zusätzlich 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 äußerst effzienter Packer dessen Dateien zusätzlich 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, großen Dateien die nicht oder sehr selten angetastet werden.
Hier kommt noch etwas hin...
Hier kommt noch etwas hin...
Hier kommt noch etwas hin...
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 GEHÖRT 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; /* ...trägt nur zur
Lesbarkeit bei... */
mi = gdfuncs->CK_init_meminfo(&minfo,_app); /* Speicherverwaltungsinit */
/* HIER STEHT DAS EIGENTLICHE PROGRAMM ! */
/* ...für 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 */
}
Zum Zeitpunkt dieser 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.35
Änderungen Version 1.31
Änderungen Version 1.30
Änderungen Version 1.20
Änderungen Version 1.15
Ä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
Sophienstr. 10a
12203 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 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 und Portfolio-Tastatur!
