                                Dokumentation zu
                                JML-Snapshot 3.10

Inhalt

  1.      Einleitung

     1.1. Features

     1.2. Rechtliches

  2.      Installation

  3.      Bedienung

  4.      Falls es nicht geht...  

  5.      Was noch zu sagen wre...

  6.      Bekannte Fehler

  7.      History

  8.      Aussichten

  9.      Updates/Upgrades
  
 10 .      Dank an...

 11.      Meine Anschrift


1. Einleitung

Es war ein Tag nach der ATARI-Messe 1992. Die frisch erstandene Grafikkarte im 
ST eingebaut. Da sa ich nun, und brauchte eine Hardcopy des Bildschirms.

"Kein Problem, mein Diskettenlager ist doch voll von sowas!" dachte ich. Weit 
gefehlt. Die wenigsten davon waren Auflsungsunabhngig, und nur Eines konnte 
Farbe. Das aber nur im DEGAS-Format bei 4 oder 16 Farben.

Also kam ich auf die Idee, sowas selbst zu programmieren.

So in der Art drften wohl die meisten Sharewareprogramme entstanden sein, so 
auch dieses Snapshot Utility.

Ich gehe davon aus, da der/die Leser(in) dieser Zeilen das Programm rechtmig, 
also direkt von mir, erworben, und somit die Sharewaregebhr von DM 20,- bezahlt 
hat. Ich mchte mich daher an dieser Stelle dafr bedanken, da die Arbeit an 
JML-Snapshot mittlerweile ettliche Stunden verbraucht hat, und auch noch ver-
brauchen wird.


1.1 Features

Prinzipiell stellt JML-Snapshot ein Programm dar, da beliebige Bildschirm-
ausschnitte auf einem Massenspeicher ablegt. Dabei kann man zwischen folgenden 
Optionen whlen:

- Freie Wahl des Ausschnitts ber ein "Gummiband" oder direktes Ausschneiden 
  eines Fensterinhaltes bzw. des kompletten Bildschirms

- Ausgabeformate IFF, (X)IMG oder TIFF

- Freie Wahl des Speicherpfades und Dateinamens oder Benutzung eines 
  voreingestellten Standardpfades.

Dabei ist die Gre des Bildausschnittes beliebig, nur bei freier Namenswahl mu 
gengend Hauptspeicher zur Verfgung stehen! Die Anzahl der Farben kann zwischen 
2 und 256 liegen. Mehr Farben (32768, 65536, 16777216) werden leider zur Zeit 
noch nicht untersttzt. Das kann (und wird) sich aber durchaus noch ndern.


1.2. Rechtliches

Registrierte Benutzer(innen) drfen das Programm uneingeschrnkt verwenden, 
jedoch nicht weitergeben. 

Die Weitergabe von JML-Snapshot 3.x an Dritte wird hiermit ausdrcklich unter-
sagt. Dazu gibt es die Demo Version, die zum Testen freigegeben wurden. Nach 
einer angemessenen Zeit ist der Benutzer dann aufgefordert, die fllige Gebhr 
an mich zu zahlen. 

Das Copyright von JML-Snapshot liegt komplett bei mir! Das Programm ist frei von 
Rechten Dritter.

Mit Ausnahme von drei kleinen Assemblerroutinen wurde das Programm vollstndig 
mit einer Turbo-C Demoversion erstellt, obwohl sie mehr Einschrnkungen als 
Funktionen hat... (und es geht doch!)

Ich hafte in keiner Weise fr irgendwelche Schden, die mittelbar oder 
unmittelbar durch JML-Snapshot entstehen knnten. Es liegt allerdings auerhalb 
meiner Vorstellungskraft, was das fr Schden sein sollten. 


2.      Installation

Ganz simpel! Entweder, man benutzt JML-Snapshot als Programm (PRG, APP), dann 
kopiert man es dorthin, wo man es haben mchte. Sollte es als Accessory (ACC) 
verwendet werden, so gehrt JML_SNAP.ACC natrlich auf die Bootpartition bzw. 
Bootdiskette.

Der Programmname sollte jedoch immer  JML_SNAP  lauten. Als Extender werden 
programmig ACC, ACX, APP und PRG untersttzt. Wer auf Komfort beim Abspeichern 
der Optionen verzichtet, kann dem Programm auch jeden anderen Namen geben, warum 
auch immer...


3.      Bedienung

JML-Snapshot besteht aus zwei Teilen. Der eigentlichen Snapshotroutine und einem 
Dialog zum Konfigurieren.

Startet man JML_SNAP als Programm unter Standard-TOS (ohne Multitaking), ist nur 
der Dialog erreichbar. Wird das Programm unter Multitaking gestartet, passiert 
zunchst nichts. Man kann wie gewohnt mit anderen Applikationen arbeiten.

JML-Snapshot wird als Programm unter Multitasking oder als Accessory erst 
aktiviert, wenn man den Eintrag in der Menleiste anwhlt. Alternativ dazu 
versteht JML_SNAP die VA-START Mitteilung von GEMINI (siehe GEMINI Dokumenta-
tion).

Wird beim Aufruf von JML-Snapshot die rechte Shifttaste und/oder die rechte 
Maustaste niedergedrckt, wird der Dialog aufgerufen. Dies sollte beim ersten 
Start von JML_SNAP auf jeden Fall getan werden, um das Programm auf die 
persnlichen Bedrfnisse einzustellen.


Der Dialog:

- Die Checkboxen

     Gummiband:
          
          Ist Gummiband angekreuzt, kann der Snapshot mit einem "Gummiband" frei 
          gewhlt werden. Anderenfalls ist die WINDOW-Snap Funktion aktiv. Dazu 
          spter mehr.

     Breite anpassen:

          Diese Funktion ist nur fr IFF Bilder gltig. Es gibt leider 
          Programme, die IFF Files erwarten, deren Breite durch 16 teilbar ist. 
          Deshalb kann man mit "Breite anpassen" den Snapshot auf eine 
          entsprechende Gre bringen.

     Fileselector aufrufen:

          Ist diese Option aktiv, und das System hat gengend Speicher frei, 
          knnen Pfad und Name des Snapshots ber eine Fileselectbox gewhlt 
          werden. Anderenfalls werden Standard- Pfad und Name verwendet.

     alte Files berschreiben:

          Hiermit kann man bestimmen, ob JML-Snapshots bestehende, 
          gleichnamige Files berschreibt, oder nicht. Diese Funktion gilt nur, 
          wenn keine Fileselectbox aufgerufen wurde.

- Die Radiobuttons
     Hier wird das Ausgabeformat des Snapshots ausgewhlt. Es stehen IFF, (X)IMG 
     und TIFF (nach TIFF 5.0) zur Verfgung.

- Der Standardpfad

     Wird ein Snapshot ohne Fileselector durchgefhrt, legt JML_SNAP das File im 
     Standardpfad ab, der hier bestimmt wird. Durch Anklicken des Feldes mit dem 
     Pfadnamen ruft man eine Fileselectbox auf. Nun kann man den neuen Pfad 
     einstellen.

     Die Pfeilfelder links und rechts des Pfadnamens dienen zum Durchscrollen 
     des Namens, falls dieser zu lang ist, um in die Box zu passen.

     Wurde kein Pfad ausgewhlt, steht hier das Rootdirectory des Laufwerks, von 
     dem JML_SNAP gestartet wurde.

- Die Buttons

     Info:

          Es erscheint die bliche Infobox, mit mehr oder weniger wichtigen 
          Informationen

     Save:

          Die eingestellten Optionen werden in JML_SNAP gespeichert. Sollte das 
          Programm sich selbst nicht finden, kann man es mittels Fileselector 
          auswhlen. Die momentanen Optionen werden gltig!

     Abbruch:

          Die Vernerungen, die man seit Aufruf des Dialogs vorgenommen hat, 
          werden ungltig, und der Dialog wird verlassen. 

     OK:
          
          Auch "OK" fhrt zum verlassen des Dialogs. Gleichzeitig werden die 
          momentanen Einstellungen bis zur nchsten nderung gltig.

     Programmende:

          Der Dialog wird verlassen, das Programm beendet. Natrlich nur, wenn 
          JML-Snapshot nicht als Accessory gestartet wurde, da man Accessories 
          normalerweise nicht beenden darf. Eine Ausnahme bildet MultiTOS, aber 
          dafr stellt es eine eigene Funktion zum Beenden von ACCs zur 
          Verfgung.

Wurde JML_SNAP als PRG/APP unter Singletasking TOS gestartet, fhren "Abbruch" 
und "OK" zum Beenden des Programms.


Die Snapshotroutine:

Die eigentliche Funktion von JML-Snapshot. Es werden alle Optionen 
bercksichtigt, die zuvor im Dialog eingestellt wurden.

Der Vorgang hngt stark von der Option "Gummiband" ab. 

Startet man den Snapshot mit Gummiband-Option, wird der Mauspfeil zum Faden-
kreuz. Drckt man jetzt die rechte Maustaste, bricht man den Snapshot ab. 
Bettigt man dagegen die linke Maustaste, wird die erste Ecke des Ausscnitts 
festgelegt. Der Mauszeiger wird zur zeigenden Hand. Bei gedrckter linker 
Maustaste lsst sich nun ein Gummiband aufziehen, das den Ausschnitt festlegt. 
Lsst man nun die Taste los, wird der Snapshot durchgefhrt.

Ist "Gummiband" ausgeschaltet, erscheint gleich die zeigende Hand. Auch hier 
bricht die rechte Maustaste den Snapshot ab. Die linke Maustaste fhrt den 
WINDOW-SNAP durch. Diese, von UNIX-Systemen abgeschaute, Funktion speichert den 
Inhalt des Fensters unter dem Mauszeiger als Bild ab. Befindet sich kein Fenster 
unter dem Mauszeiger, wird der komplette Bildschirm "gesnappt".

Zu beachten ist, da nur der sichtbare Bereich eines Fensters gesnappt wird, 
auf den die Hand zeigt. berlappende Fensterbereiche werden somit nicht mitge-
speichert.

Gespeichert wird das Bild als "SNAP_xx.ext". "xx" steht fr die Nummer des 
Snapshots, und wird nach jedem Bild hochgezhlt. "ext" ist der Extender des 
Bildes, also "IFF", "IMG" oder "TIF", abhngig welcher Bildtyp gewhlt wurde.

Hat man "Fileselector aufrufen" eingestellt, wird das Bild natrlich unter dem 
selbst gewhlten Namen geschrieben. Die Extension wird automatisch richtig 
gesetzt.

Aufgrund TOS-spezifischen Eigenheiten, mu gengend Speicher frei sein, um den 
Namen des Snapshots frei zu whlen. Sollte das nicht der Fall sein, speichert 
JML_SNAP das Bild im Standardpfad. Eine ALARM-Box informiert dann ber den Pfad 
und den Namen, unter dem der Snapshot gespeichert wurde.


4.      Falls irgendwas nicht geht...  

Tja, trotz intensiver Tests, kann immer noch ein Fehler durchrutschen. 
Irgendjemand findet immer etwas. In diesem Fall, mchte sich der/die 
Benutzer(in) an mich wenden. 

Um den Fehler zu finden, bentige ich allerdings eine mglichst genaue 
Beschreibung. Dazu gehrt:

- Rechnertyp (ST, STE, TT, Falcon, etc.)
- Hauptspeicher
- TOS Version
- Multitasking (MTOS, MagX!, MultiGem)
- geladen Accessories
- Programme im AUTO-Ordner
- Verfahrensweise, die zu dem Fehler gefhrt hat

Es empfiehlt sich, immer eine Disk und das Rckporto der Fehlerbeschreibung 
beizulegen. Eventuell ist das Problem schon behoben und dann kann die neue 
Version sofort mit der Post abgehen.


5.      Was noch zu sagen wre...

Gerade bei 256 Farben kann ein Snapshot etwas lnger dauern! Das VDI mu den 
Ausschnitt in das Standard-Format umrechnen, und das dauert. Bei TIFF-Files mu 
JML-Snapshot zustzlich noch umrechnen. Die Assembler-Routinen sind aber recht 
schnell. 

Also nicht verzweifeln, falls es mal etwas lnger dauert. Es sind nur ein paar 
Sekunden (die halt lang werden knnen, wenn man auf etwas wartet...).

Aus diesem Grund wollte ich mir die Zeit zum komprimieren sparen. Ein Snapshot 
wird aber meistens weiterverarbeitet, dann ist das auch nicht so schlimm...

JML_SNAP speichert die Optionen in sich selbst. Deshalb darf es nicht gepackt 
verwendet werden!

6.      Bekannte Fehler

Fr Benutzer von TOS 1.04 und einem Grobildschirm stellen sich Probleme. Die 
vr_trnsform - Routine des TOS arbeitet fehlerhaft. In diesem Fall mu NVDI (ab 
2.0) oder ein Patch frs TOS installiert sein!

Auch kann es (bei Grafikkarten) zu leichten Fehlern in den Farben kommen. Das 
resultiert aus der Tatsache, da die Farbwerte mehrfach umgerechnet werden 
(mssen). Die Fehler sind aber nur theoretisch (zumindest mit meiner Grafik-
karte)!

Andere Fehler sind mir z.Z. nicht bekannt. Getestet wurde JML-Snapshot unter 
folgenden Bedingungen:

- 1040 STF Bj. 1987, 3MB und 1040 STF Bj. 1988 4MB, FALCON 030, TT 030

- TOS 1.04, 2.06, 3.06 und 4.01

- MultiTOS 1.01

- 68000-8, 68010-8 68000-16, 68020-16, 68030-16 und 68030-32

- NVDI 2.01

- Mit und ohne GDOS (NVDI, ATARI-GDOS, AMC-GDOS, FontGDOS)

- in ATARI ST Hi, ST Mid, ST Lo, TT Mid, TT Lo und diversen FALCON Modi

- mit NOVA Grafikkarte in verschiedenen Auflsungen mit 2, 16 und 256 
  Farben

- mit NOVA Grafikkarte und ResSwitch


7.      History

v <1.0 Interne Versionen, viele Fehler.

v1.0 Die erste verffentlichte Version!

v1.1 Hat man den Snapshot mit der rechten Maustaste abgebrochen, wurde der      
     Mauszeiger nicht restauriert!

v1.2 JML Snapshot ist nun nach der Installation vom freien Hauptspeicher      
     unabhngig!
     Es gibt keine Fileselectbox mehr.
     Der Pfad fr den Snapshot kann in einer Datei "JML_SNAP.INF" voreinge-
     stellt werden.
     Die Installation erfolgt, auf Wunsch, durch ein Installations-Programm.

v1.3 Der Speicherpfad kann nun auch von JML-Snapshot aus gendert und auf 
     Wunsch gespeichert werden.

v1.4 Die JML_SNAP.INF-Datei ist weggefallen, der Standardpfad wird direkt im 
     Accessory gespeichert. Dies war notwendig, da GEM >3.0 (TOS 2.xx, TOS 
     3.xx) Accessories anders installiert, und das Laden der INF-Datei "zu 
     lange" dauert. Es kommt dann zu blen Effekten (meist in Form von drei 
     Bomben).

v1.5 vq_color liefert jetzt den gesetzten, nicht den eingestellten VDI Wert 

v1.6 Sehr dummer Fehler in Zusammenhang mit Multitasking behoben;
     Letzte PD-Version

v2.0 Shareware-Status eingefhrt. JML-Snapshot untersttzt nun auch 
     Multitasking. Kein Installationsprogramm mehr.

v3.00 Interne Version der 3er Serie. Viele Fehler, ettliche Fehlversuche. Immer 
      neue nderungen am Dialog. Komplette berarbeitung des Programms. Neu 
      sind smtliche Auswahlmglichkeiten, sowie die Speicherformate (X)IMG und 
      TIFF. IFF-Files werden jetzt als IFF, statt als LBM gesichert. WINDOW-SNAP
      eingefhrt.

v3.01 Erste Version fr registrierte, zahlende Benutzer.

v3.02 Abfrage der rechten Maustaste verbessert, LINE-A Aufrufe aus dem Compilat 
      weitgehend entfernt

v3.10 Erste C-Version. Das Programm wurde komplett in C neugeschrieben.


8.      Aussichten

Von meiner Seite aus ist noch eine Auslsung des Snaps mit ALT-HELP geplant, ist 
aber noch mit ein paar Schwierigkeiten verbunden.

Vorstellbar wre noch Kompression der Files, sowie direkte Untersttzung des 
Clipboards. Da aber gerade die Kompression auf Kosten der Geschwindigkeit geht, 
werde ich das wohl nur auf Wunsch einfgen.

Auf jeden Fall werden Hi- und True- Color Auflsung Untersttzung finden. 
Die Grafikkarte ist schon bestellt.

Fr andere Vorschlge bin ich zugnglich. Was sinnvoll und durchfhrbar ist, 
werde ich implementieren. Man sollte dabei aber immer im Auge haben, da JML-
Snapshot keine eierlegende Wollmilchsau ist und auch nicht werden soll.


9. Updates/Upgrades

Zuerst eine Begriffsdefinition (so wie ich es verstehe, und fr JML-Snapshot 
gilt)

Ein Update ist eine Programmversion, in der Fehler bereinigt wurden

Ein Upgrade ist eine Programmversion, die neue Funktionen enthlt

Updates sind kostenlos, Upgrades werde ich mir jedoch bezahlen lassen. Ich 
denke, das ist fair so. 

Ich mchte natrlich Niemanden zwingen, ein Upgrade zu bezahlen, obwohl er/sie 
'nur' eine fehlerfreie Version haben mchte und auf die neuen Features 
verzichten kann. In dem Fall geht das zu Lasten von mir, und ich werde ein 
Upgrade umsonst rausrcken.

Wie kommt man nun zum Update/Upgrade? Ersteres ist leicht. Wer keinen Fehler 
findet, braucht kein Update. Wer einen findet, meldet ihn bei mir und erhlt, so 
schnell wie mglich, die neue Version.

Bei Upgrades ist es schwieriger. Abhngig von der Anzahl der Benutzer wird sich 
eine Lsung finden, jede(n) User(in) zu benachrichtigen. Ansonsten hilft nur 
nachfragen. Auch hier gilt: Wer keine Funktion vermisst, braucht auch kein 
Upgrade (logisch, oder?).

Und wie das Ganze? Auch einfach. Da ich bei einer Sharewaregebhr von DM 20,- 
keine Kosten haben mchte, erwarte ich immer eine Diskette und das Rckporto. 
Ein Rckumschlag ist nicht ntig, aber vorteilhaft. Bei Upgrades mu natrlich 
auch die Upgradegebhr dabei sein.

Eine Alternative bietet DF. Eingetragenen Benutzer(innen) der MAUS WI2 oder 
MAUS MTK kann ich die neue Version auch in den  persnlichen Programmteil legen.
Das ist unter Umstnden billiger. Mir verursacht es keine Kosten und nur 
minimalen Aufwand.


10.      Dank an...

- alle Betatester (man mge mir verzeihen, da ich nicht alle einzeln Aufzhle)

- die Autoren des `Profibuches'

- Laurenz Prssner, fr Anregungen durch Artikel im ST-Magazin

- Joachim Loder fr's Betatesten und Ertragen meiner Launen

- Reinhard Weger, der mich a) als erster angeschrieben und b) auf einen bsen 
  Fehler aufmerksam gemacht hat.

- Mike Steffl frs Betatesten, MEMOHELP und ner Menge PMs

- Michael Ruge fr den Test am FALCON, obwohl seine Platte zerschossen wurde

- Reiner Rosin fr nen guten Assembler-Tip

- *MHG* von Computer Insel fr einen tollen Support, obwohl ich wie immer 
  nerve! (Danke)

- Dieter Fiebelkorn fr GemView und so...

- Theo fr's BANG 2082

- Pink Floyd fr `The Dark Side Of The Moon'

- last, but not least, meiner Verlobten fr ihr Verstndnis, wenn ich mal wieder 
  zu lange am Rechner hnge! (Und fr vieles Andere...)


11.      Meine Anschrift 

per Post:

John McLoud
Mozartstrae 1a

W-6093 Flrsheim am Main 

Ab (voraussichtlich) 1.7.93 lautet die Postleitzahl 65439!!!


per E-Mail im Mausnetz:

    John McLoud @ WI2


Bankverbindung:

Taunussparkasse  BLZ 512 500 00
                 Kto. Nr.: 9 45 02 97


