home *** CD-ROM | disk | FTP | other *** search
/ ST-Computer Leser 2002 January / STC_CD_01_2002.iso / APP / TRAIL_PG / GEMJING / GEMJ136.LZH / Doc / gemjing.txt < prev   
Text File  |  2000-06-01  |  35KB  |  926 lines
  1.                         GEMJing-Dokumentation
  2.  
  3.                                 V.1.36
  4.                               2000-06-01
  5.  
  6.                                  von
  7.  
  8.                              Götz Hoffart
  9.  
  10.  
  11. Inhaltsverzeichnis
  12. ==================
  13.  
  14.  1  Rechtliches
  15.  
  16.  2  Was tut es?
  17.  
  18.  3  Einsatzmöglichkeiten
  19.  
  20.  4  Für Programmierer
  21.     4.1  VA_START-Übergabe
  22.     4.2  Kommandozeilenstart
  23.     4.3  OLGA-Start
  24.          4.3.1  Anpassung der OLGA.INF
  25.     4.4  VA_START-Nachricht
  26.     4.5  GEMJing-Returnmessage
  27.     4.6  WeirdMac
  28.  
  29.  5  Tips & Tricks
  30.  
  31.  6  Dank
  32.  
  33.  7  Historie
  34.  
  35.  
  36.  
  37. 1  Rechtliches
  38. **************
  39.  
  40. GEMJing Public License
  41.  
  42. (c) 2000 by Götz Hoffart.
  43.  
  44. GEMJing untersteht der CAT Public License in der Version 1.0 vom 24.
  45. Oktober 1997 von Dirk Steins, die als CATPL.TXT dem Archiv beiliegt.
  46.  
  47. Ausnahmen betreffen die Beilage zu den Programmen "Texel" von Thomas
  48. Much, "ArtWorx" von Christian Witt, "CAB" von Alexander Clauss,
  49. "Rational Sounds" von Heiko Achilles und Nils Schneider und "Draconis"
  50. von Jens Heitmann.
  51.  
  52. Die Beilage von GEMJing zu den genannten Programmen ist hiermit
  53. ausdrücklich von mir erlaubt. Ein kommerzielles Alleinnutzungsrecht
  54. von GEMJing, auch für die ausgenommenen Programme und Autoren, ergibt
  55. sich damit jedoch nicht, GEMJing hat nur den Status als "schmückendes
  56. Beiwerk". GEMJing darf also in keiner, auch keiner weiterentwickelten
  57. Version, separat verkauft werden.
  58.  
  59. Götz Hoffart, 1. Juni 2000
  60.  
  61.  
  62. E-Mail: Götz Hoffart @ FR (MausNet)
  63. goetz@hoffart.de (Internet)
  64. Web: http://www.hoffart.de/
  65. Adresse: Einsteinstr. 3, 76287 Rheinstetten
  66.  
  67. Von Telefonanrufen bei obiger Adresse bitte ich dringend abzusehen.
  68.  
  69. ----------------------------------------------------------------------
  70.  
  71.                           CAT Public License
  72.  
  73.                     Version 1.0, 24. Oktober 1997
  74.  
  75. Copyright (c) 1997, Dirk Steins (!nl)
  76. Jegliche Veränderung dieser Lizenz ist nicht erlaubt.
  77.  
  78. Dieses Dokument beschreibt die Lizenzvereinbarungen betreffend aller
  79. Programme, die aus dem CAT Projekt entstanden sind oder noch entstehen
  80. werden. Diese Lizenz ist verbindlich für alle Programme und Sourcen,
  81. die aus diesem Projekt heraus entstanden sind und entstehen werden.
  82.  
  83. Das CAT Projekt ist entstanden aus dem MausTausch-Programm CAT für
  84. TOS- kompatible Rechner. Ziel des Projektes ist es, die
  85. Weiterentwicklung von CAT trotz der Aufgabe durch die ursprünglichen
  86. Autoren nicht einschlafen zu lassen, sondern kontinuierlich
  87. weiterzuentwickeln und zu verbessern. Das CAT Projekt umfa₧t die
  88. Programme CAT, CATPUTZ, REPAIR und FRED sowie etwaige
  89. Installationsprogramme und jedes weitere Programm, das unter
  90. Verwendung der Sourcen der obigen Programme entsteht.
  91.  
  92. Diese Lizenz dient dazu, die Weitergabe, das Kopieren und Modifizieren
  93. von Teilen oder des gesamten Projekts zu regeln. Diese Lizenz ähnelt
  94. in einigen Teilen der GNU Public License, ist aber nicht so umfassend
  95. und umfangreich wie diese.
  96.  
  97.   1. Umfang: Das CAT Projekt besteht aus den Programmen CAT, CATPUTZ,
  98.      FRED, REPAIR, INSTALL und allen weiteren Programmen, die im Laufe
  99.      dieses Projektes und unter Verwendung der Sourcen dieses
  100.      Projektes unter dieser Lizenz entwickelt werden. Dazu zählt jedes
  101.      Programm, bei dem der Inhaber des Copyrights erklärt, da₧ es
  102.      unter dieser Lizenz vertrieben wird. Weiterhin gehören dazu die
  103.      Sourcen der Anleitungen zu den verschiedenen Programmen im UDO-
  104.      Format.
  105.  
  106.   2. Teil des CAT Projektes ist die Library MagiC von Peter Hellinger
  107.      in der modifizierten Version 3.3. Diese Library darf in dieser
  108.      mitgelieferten Form nur für Programme innerhalb des CAT Projektes
  109.      benutzt werden. Für alle anderen Programme ist eine Benutzung der
  110.      MagiC-Library in dieser Version nicht gestattet. Es gibt für
  111.      andere Projekte neuere Versionen dieser Library, die unter dem
  112.      Namen TrueMagic erhältlich ist. Diese ist bei Peter Hellinger @ N
  113.      (peter_hellinger@n.maus.de) erhältlich, dort erhält man auch die
  114.      genauen Konditionen für die Benutzung dieser Library.
  115.  
  116.   3. Das CAT Projekt darf mit allen Sourcen auf beliebigen Medien
  117.      kopiert und weitergegeben werden, unter der Voraussetzung, da₧ an
  118.      geeigneter Stelle Hinweise auf das Copyright und die
  119.      Garantiebestimmungen stets mitgeliefert werden. Alle Hinweise auf
  120.      diese Lizenz und auf die Abwesenheit jeglicher Garantie müssen
  121.      beibehalten werden und dürfen nicht verändert werden. Diese
  122.      Lizenz mu₧ bei jedem Teil des Projektes mitgeliefert werden.
  123.  
  124.   4. Alle Teile des CAT Projektes sind Freeware, es ist nicht erlaubt,
  125.      aus Teilen oder dem Gesamten des CAT Projektes kommerzielle
  126.      Software zu entwickeln oder dieses in Teilen oder als Ganzes mit
  127.      Gewinnerzielungsabsichten zu vertreiben. Explizit ausgeschlossen
  128.      von dieser Bestimmung sind Gebühren für die physikalische
  129.      Verteilung jeder Kopie wie zum Beispiel CD-Kosten oder
  130.      Diskettenkosten.
  131.  
  132.   5. Es ist erlaubt, die Programme oder Teile davon zu verändern, also
  133.      ein Werk basierend auf dem Projekt zu erstellen, und diese
  134.      Veränderungen oder dieses Werk unter den Bestimmungen von
  135.      Abschnitt 4 zu vertreiben und zu kopieren, sofern die folgenden
  136.      Bestimmungen eingehalten werden:
  137.  
  138.       (a) Jede Veränderung in den Dateien mu₧ explizit in diesen
  139.           gekennzeichnet werden und das Datum dieser Änderungen mu₧ in
  140.           den Dateien festgehalten werden. Bei Dateien, bei denen
  141.           dieses aus technischen Gründen nicht möglich ist (Resource-
  142.           Dateien oder ähnliches) sind die Veränderungen in einer
  143.           dazugehörenden Textdatei ausführlich zu dokumentieren.
  144.  
  145.       (b) Alle Sourcen zu dem veränderten Programm müssen zur
  146.           Verfügung gestellt werden, auch solche, die auf den Sourcen
  147.           des CAT-Projektes basieren und neu entwickelt wurden.
  148.  
  149.   6. Es ist erlaubt, nur die ausführbaren Programme oder modifizierte
  150.      Versionen davon zu kopieren und zu vertreiben, sofern
  151.      sichergestellt wird, da₧ die Sourcen dieser Programme in
  152.      vollständiger Form zur Verfügung gestellt werden und für jeden
  153.      verfügbar sind. Gegebenenfalls mu₧ sich der Autor der
  154.      Veränderungen bereiterklären, die veränderten Sourcen gegen eine
  155.      Erstattung der Unkosten zu kopieren und zu verteilen. Ausreichend
  156.      für die Erfüllung dieser Bedingung ist es, die vollständigen
  157.      Sourcen in einem öffentlichen Mailboxsystem oder auf ftp-Servern
  158.      zur Verfügung zu stellen.
  159.  
  160.   7. Der Copyright-Inhaber dieser Lizenz darf erweiterte und
  161.      veränderte Versionen dieser Lizenz veröffentlichen. Diese
  162.      veränderten Versionen dieser Lizenz werden dem Sinne dieser
  163.      Lizenz entsprechen, können sich aber in Details unterscheiden, um
  164.      neue Probleme und Bedenken anzusprechen und zu umfassen. Der
  165.      Copyright-Inhaber dieser Lizenz ist dazu berechtigt, diese Lizenz
  166.      an Dritte weiterzugeben, sofern diese im Sinne dieser Lizenz
  167.      weiterarbeiten wollen.
  168.  
  169.      AUSSCHLUSS DER GEWÄHRLEISTUNG
  170.  
  171.   8. Da das gesamte CAT-Projekt frei von Gebühren vertrieben wird,
  172.      gibt es keine Gewährleistung für dieses Projekt und Teile davon,
  173.      soweit dies gesetzlich zulässig ist. Dieses Projekt wird so zur
  174.      Verfügung gestellt, wie es ist, ohne Gewährleistung jedweder Art,
  175.      weder direkte noch indirekte, einschlie₧end, aber nicht
  176.      beschränkt auf, die Funktionsfähigkeit zu irgendeinem Zwecke. Das
  177.      gesamte Risiko für die Benutzung oder Nichtbenutzung der in
  178.      diesem Projekt enthaltenen Informationen und/oder der Programme
  179.      und/oder Teilen davon liegt bei dem Nutzer! Unter keinen
  180.      Umständen wird irgend jemand, egal ob lebeNd, tot oder scheintot
  181.      und/oder irgendeine Gruppe, die der menschlichen Rasse oder sonst
  182.      einer (mehr oder weniger) intelligenten Spezies (einschlie₧lich,
  183.      aber nicht beschränkt auf jenen bisweilen SOL III genannten
  184.      Planeten) entstammt oder vorgibt zu entstammen, und der dieses
  185.      Projekte und/oder Teile davon oder ein anderes, damit in
  186.      Verbindung stehendes Projekt und/oder Programm oder Teile davon
  187.      modifiziert und/oder weiterverbreitet, egal ob legal oder
  188.      illegal, in irgendeiner Art verantwortlich sein für irgendwelche
  189.      Schäden, einschlie₧lich aber nicht beschränkt auf
  190.      entgangener/geschmälerter/verlorerer Profite, Gelder, Geltung,
  191.      Gesundheit, Freunde/Freundinnen etc., die implizit oder explizit
  192.      aus der Verwendung oder Nichtverwendung dieses Projektes und/oder
  193.      Programme und/oder Teilen davon, resultieren.
  194.  
  195. ----------------------------------------------------------------------
  196.  
  197. Copyright (c) by Götz Hoffart. Alle Rechte am Programm und der Doku-
  198. mentation sowie den zugehörigen Dateien vorbehalten.
  199.  
  200. Autor: Götz Hoffart, Rheinstetten.
  201. MausNet: Götz Hoffart @ FR
  202. Internet: goetz@hoffart.de
  203.  
  204. WWW: http://www.hoffart.de/
  205.  
  206.  
  207.  
  208. 2  Was tut es?
  209. **************
  210.  
  211. GEMJing spielt Samples ab, bevorzugt per Fernsteuerung. Wie diese
  212. vorgenommen werden kann, wird im Programmierabschnitt (siehe "Für Pro-
  213. grammierer") erklärt.
  214.  
  215. Akzeptiert werden derzeit WAV-Samples (bekannt aus der Windows-Welt),
  216. HSN-Samples (CrazySounds, Atari), AVR-Samples (Michtron), SMP-Samples
  217. (Galactic Sound- Sampler, Atari) sowie deren Abart "STE-SMP",
  218. ungepackte DVS-Samples (von der Harddisc-Recording-Software "WinRec")
  219. sowie Sun/NeXT-Samples im ".au" bzw. ".snd"-Format (mit einigen
  220. Einschränkungen (siehe "Tips & Tricks")).
  221.  
  222. Die Einsatzmöglichkeiten von GEMJing reichen vom simplen Dateiviewer
  223. bis zum Plug-In.
  224.  
  225. GEMJing läuft mit folgenden Hardwarekonfigurationen:
  226.  
  227.    ∙ ST, MegaST (PSG)
  228.  
  229.    ∙ STE, MegaSTE, TT (DMA)
  230.  
  231.    ∙ Falcon
  232.  
  233.    ∙ MagiCMac (mit WeirdMac oder MSND)
  234.  
  235.    ∙ MagiC-PC 6.0
  236.  
  237.    ∙ Hades040 und Hades060 (PSG)
  238.  
  239.    ∙ Hades mit der Startrack-Soundkarte, mit und ohne Clockmodul
  240.  
  241.    ∙ Milan mit Milanblaster
  242.  
  243. Dabei wird versucht, die jeweils maximale Qualität, die das Sound-
  244. system der Hardware bietet, auszunutzen. Auf ST-kompatiblen Systemen
  245. ist dies der Soundchip (in obiger Auflistung: PSG), STE- kompatible
  246. Systeme werden mittels 8 Bit DMA Sound betrieben (DMA) und auf dem
  247. Falcon wird der 16 Bit XBIOS-Sound verwendet (XBIOS). Bei Apple
  248. Macintosh mit MagiCMac und installiertem MSND oder WeirdMac hängt die
  249. Qualität von der zugrundeliegenden Soundhardware des Macs ab, kleinere
  250. und ältere Macs bieten nur 8 Bit Sound, neuere dagegen 16 Bit (XBIOS).
  251. MagiC-PC 6.0 bietet ebenfalls freie Frequenzwahl an (XBIOS).
  252.  
  253. Das Abspielen kann durch Drücken von Control und Links-Shift un-
  254. terbrochen werden.
  255.  
  256. Fehlermeldungen gibt GEMJing nur aus, wenn der Benutzer den Menüein-
  257. trag gewählt hat, um sich das Sample anzuhören. Bei Aufforderung zur
  258. Wiedergabe per Kommandozeile oder VA_START bleibt GEMJing (für den Be-
  259. nutzer) stumm in Sachen Fehlerrückmeldung.
  260.  
  261.  
  262.  
  263. 3  Einsatzmöglichkeiten
  264. ***********************
  265.  
  266. Man kann GEMJing im Desktop für WAV, AVR, SMP, HSN, DVS, AU und SND-
  267. Dateien anmelden und dann bequem Sample-Dateien doppelklicken, um sie
  268. anzuhören, ohne riesige Programmonster und Super-Viewer nachladen zu
  269. müssen.
  270.  
  271. Bei Verwendung des Desktops Jinnee kann man GEMJing für die
  272. gewünschten Extensionen als Applikation anmelden und in der Einga-
  273. bezeile für die Kommandozeile "-q %$p" eingeben. Das bewirkt, da₧
  274. GEMJing sich nach dem Spielen sofort wieder aus dem Speicher
  275. verabschiedet.
  276.  
  277. Oder man schreibt sich ein Mupfel-Script, das GEMJing beim Booten
  278. startet und ein Sample spielen lä₧t. Einfach mit der Kommandozeile "-q
  279. sample.wav" aufrufen und schon tönt es bei jedem Rechnerstart. Oder
  280. bei jedem Shutdown. Oder zu jeder vollen Stunde ...
  281.  
  282. TOS bietet leider keinerlei Möglichkeiten, Samples über einen Be-
  283. triebssystemaufruf abzuspielen. Daher mu₧ jeder Programmautor, dessen
  284. Programm sich lautstark ausdrücken soll, diese Routinen selbst in sein
  285. Programm integrieren. Mit GEMJing ist das nicht mehr notwendig, es
  286. besitzt mehrere Schnittstellen nach au₧en. Der Abschnitt Für Pro-
  287. grammierer (siehe "Für Programmierer") hilft hier weiter.
  288.  
  289. GEMJing gehört nicht in den AUTO-Ordner.
  290.  
  291. Programme können GEMJing auch über OLGA OLGA (siehe "OLGA-Start")
  292. nachstarten lassen, was sehr bequem ist. Dazu bitte die OLGA.INF
  293. anpassen (siehe "Anpassung der OLGA.INF").
  294.  
  295. Wer will, da₧ andere Programme GEMJing finden, der sollte die Environ-
  296. mentvariable GEMJINGPATH setzen: Machen Sie sich von der Datei
  297. MAGX.INF eine Sicherheitskopie. Öffnen Sie nun Ihre originale MAGX.INF
  298. mit einem Texteditor wie etwa qed, 7Up, Tempus etc. Eine Zeile lautet
  299. "#_ACC C:\" oder ähnlich. Fügen Sie nun danach eine Zeile ein, in die
  300. Sie schreiben:
  301.  
  302. #_ENV GEMJINGPATH=C:\Tools\GEMJing\GEMJing.prg
  303.  
  304. Den Pfad müssen Sie natürlich noch an Ihre Gegenheiten anpassen.
  305. Gemini- Benutzer können die Environmentvariable in der Mupfel-Profile
  306. setzen, N.AES-User in der MINT.CNF. Es ist nicht notwendig, da₧ die
  307. Variable gesetzt wird, aber es spart letztlich Arbeit, da die Program-
  308. me GEMJing von alleine finden.
  309.  
  310.  
  311.  
  312. 4  Für Programmierer
  313. ********************
  314.  
  315. GEMJing ist in erster Linie dazu gedacht, ferngesteuert zu werden. Der
  316. statische RAM Verbrauch beträgt ungefähr 30kB, alles andere wird
  317. dynamisch angefordert.
  318.  
  319. Wer GEMJing von seinem Programm aus aufrufen will, hat drei Möglich-
  320. keiten:
  321.  
  322.    ∙ Start und Übergabe einer VA_START-Nachricht (siehe "VA_START-
  323.      Übergabe")
  324.  
  325.    ∙ Start mit Übergabe einer Kommandozeile (siehe "Kommandozei-
  326.      lenstart")
  327.  
  328.    ∙ Über OLGA (siehe "OLGA-Start")
  329.  
  330.    ∙ Über GEMScript (das OPEN- und QUIT-Kommando wird unterstützt)
  331.  
  332. Beim Start sollte beachtet werden, da₧ die Environmentvariable
  333. GEMJINGPATH anzeigt, wo sich GEMJing befindet. Unter MagiC sähe das in
  334. der MAGX.INF dann etwa so aus:
  335.  
  336. #_ENV GEMJINGPATH=D:\Tools\GEMJing\GEMJing.prg
  337.  
  338. ----------------------------------------------------------------------
  339.  
  340.  
  341. 4.1  VA_START-Übergabe
  342. ======================
  343.  
  344. GEMJing wird normal gestartet. Andere Applikationen können es nun über
  345. die AES ausfindig machen und eine VA_START-Nachricht verschicken. Als
  346. Antwort bekommen sie AV_STARTED und GEMJING_RETURN.
  347.  
  348. Die VA_START-Nachricht ist für GEMJing durch eine Übergabe von Para-
  349. metern erweiterbar. Es wird in msg[3] und msg[4] ein Pointer auf einen
  350. String übergeben, der die Kommandozeile enthält. Dieser String mu₧
  351. global lesbar sein.
  352.  
  353.  -q      Quit. Das Sample wird abgespielt und unmittelbar im Anschlu₧
  354.          an das Ende des Samples beendet sich das Programm selbstän-
  355.          dig.
  356.  
  357.  -rx     Repeat. Das Sample wird x-mal gespielt. "-r1" bedeutet, da₧
  358.          das Sample einmal gespielt wird, "-r0" bedeutet endlose
  359.          Wiederholung. Wird kein "-r"-Parameter übergeben, so ent-
  360.          spricht dies "-r1". Wertebereich für x: [0; 32000]
  361.  
  362.  -dx     Delay. Zwischen den Wiederholungen kann eine Pause von x
  363.          Sekunden liegen, wobei x ganzzahlig und positiv sein mu₧. "-
  364.          d0" bedeutet, da₧ die zwei Wiederholungen direkt aneinander
  365.          folgen (so dicht es GEMJing erlaubt). Wertebereich für x: [0;
  366.          32000]
  367.  
  368.  -mx     Spielen aus dem Speicher (-m für Memory). x steht für einen
  369.          Ausdruck der Form "a,b", wobei "a" die Adresse als Dezimal-
  370.          zahl angibt, ab der das Sample in einem der unterstützten
  371.          Formate komplett liegt. "b" ist die Länge des Samples im
  372.          Speicher, ebenfalls als Dezimalzahl.
  373.          Der Speicher mu₧ natürlich global alloziert sein, d.h.
  374.          Mxalloc(menge, 0 | MGLOBAL), damit GEMJing auch in Systemen
  375.          mit Speicherschutz darauf zugreifen darf.
  376.          Ein korrekter Ausdruck wäre also "-m445340,49768", natürlich
  377.          ohne die ". Das Sample liegt hier ab Adresse 445340 mit einer
  378.          Länge von 49768 Bytes.
  379.  
  380. Mit dem "-m"-Parameter müssen Programme das Sample nicht dauernd von
  381. GEMJing laden lassen, sondern können selbst ein halbes Dutzend Samples
  382. in den Speicher laden, um GEMJing dann nur noch die Adresse
  383. mitzuteilen.
  384.  
  385. Wenn ein Sample plötzlich gestoppt werden mu₧, so ist GEMJing das
  386. MiNT-Signal "SIGUSR1" zu schicken.
  387.  
  388. Nach einem VA_START (siehe "VA_START-Nachricht") bedankt sich GEMJing
  389. mit AV_STARTED und mit der GEMJing-Returnmessage, mittels derer auf
  390. evtl. aufgetretene Fehler reagiert werden kann. GEMJing selbst gibt
  391. keine Fehler aus, wenn das Sample fehlerhaft oder das Soundsystem
  392. gesperrt ist oder ähnliches, damit das bedienende Programm auf jeden
  393. Fall die Kontrolle behält und nicht irgendwo noch Alerts von GEMJing
  394. rumdümpeln. Idealerweise soll der Benutzer GEMJing ja gar nicht
  395. bemerken.
  396.  
  397.  
  398. 4.2  Kommandozeilenstart
  399. ========================
  400.  
  401. Bei Start von GEMJing mit Übergabe einer Kommandozeile wertet GEMJing
  402. die übergebenen Parameter aus und spielt ggf. das Sample. Wird GEMJing
  403. beendet, so wird der Fehlercode zurückgegeben, der beim zuletzt
  404. gespielten Sample auftrat.
  405.  
  406.  -q      Quit. Das Sample wird abgespielt, ohne da₧ eine Menüzeile
  407.          dargestellt wird. Unmittelbar im Anschlu₧ an das Ende des
  408.          Samples beendet sich das Programm selbständig.
  409.  
  410.  -rx     Repeat. Das Sample wird x-mal gespielt. "-r1" bedeutet, da₧
  411.          das Sample einmal gespielt wird, "-r0" bedeutet endlose
  412.          Wiederholung. Wird kein "-r"-Parameter übergeben, so ent-
  413.          spricht dies "-r1". Wertebereich für x: [0; 32000]
  414.  
  415.  -dx     Delay. Zwischen den Wiederholungen kann eine Pause von x
  416.          Sekunden liegen, wobei x ganzzahlig und positiv sein mu₧. "-
  417.          d0" bedeutet, da₧ die zwei Wiederholungen direkt aneinander
  418.          folgen (so dicht es GEMJing erlaubt). Ist kein "-d" ange-
  419.          geben, so wird "-d0" verwendet. Wertebereich für x: [0;
  420.          32000]
  421.  
  422.  -p      Plain. GEMJing startet und bleibt im Speicher, zeigt jedoch
  423.          keine Menüzeile an. Achtung: Nur als Kommandozeilenparameter
  424.          erlaubt!
  425.  
  426.  -mx     Spielen aus dem Speicher (-m für Memory). x steht für einen
  427.          Ausdruck der Form "a,b", wobei "a" die Adresse als Dezimal-
  428.          zahl angibt, ab der das Sample in einem der unterstützten
  429.          Formate komplett liegt. "b" ist die Länge des Samples im
  430.          Speicher, ebenfalls als Dezimalzahl.
  431.          Der Speicher mu₧ natürlich global alloziert sein, d.h.
  432.          Mxalloc(menge, 0 | MGLOBAL), damit GEMJing auch in Systemen
  433.          mit Speicherschutz darauf zugreifen darf.
  434.          Ein korrekter Ausdruck wäre also "-m445340,49768", natürlich
  435.          ohne die ". Das Sample liegt hier ab Adresse 445340 mit einer
  436.          Länge von 49768 Bytes.
  437.  
  438. Mit dem "-m"-Parameter müssen Programme das Sample nicht dauernd von
  439. GEMJing laden lassen, sondern können selbst ein halbes Dutzend Samples
  440. in den Speicher laden, um GEMJing dann nur noch die Adresse
  441. mitzuteilen. Achtung! Der Speicher für das Sample darf erst
  442. freigegeben werden, wenn GEMJing beendet wurde und damit eine Rückmel-
  443. dung vorliegt, da₧ es nicht mehr spielt. AES-Messages kann man als
  444. TOS-Programm ja nicht verschicken.
  445.  
  446. Wenn ein Sample plötzlich gestoppt werden mu₧, so ist GEMJing das
  447. MiNT-Signal "SIGUSR1" zu schicken.
  448.  
  449.  
  450. 4.3  OLGA-Start
  451. ===============
  452.  
  453. GEMJing ist ein OLGA-Server für .WAV, .DVS, .HSN, .AVR, .SMP und .AU
  454. bzw. .SND-Samples. Die Datei OLGA.INF ist also anzupassen (siehe
  455. "Anpassung der OLGA.INF").
  456.  
  457. Danach kann man z.B. in Stella einfach eine WAV-Datei öffnen und
  458. GEMJing wird automatisch über OLGA nachgestartet: man hört das Sample.
  459.  
  460.  
  461. 4.3.1  Anpassung der OLGA.INF
  462. -----------------------------
  463.  
  464. Unter "[Extensions]" sind die folgenden sieben Einträge hinzuzufügen:
  465.  
  466. .WAV=C:\Programme\GEMJing\GEMJing.PRG
  467. .DVS=C:\Programme\GEMJing\GEMJing.PRG
  468. .SMP=C:\Programme\GEMJing\GEMJing.PRG
  469. .AVR=C:\Programme\GEMJing\GEMJing.PRG
  470. .HSN=C:\Programme\GEMJing\GEMJing.PRG
  471. .AU=C:\Programme\GEMJing\GEMJing.PRG
  472. .SND=C:\Programme\GEMJing\GEMJing.PRG
  473.  
  474. Den Abschnitt "[Types]" kann man wie folgt ergänzen:
  475.  
  476. MU=C:\Programme\GEMJing\GEMJing.PRG
  477.  
  478. Man sollte jedoch darauf achten, da₧ keine Einträge doppelt vergeben
  479. werden! Ab OLGA 1.3 liegen dem OLGA-Archiv die OLGA-Tools bei, die
  480. eine bestehende OLGA.INF überprüfen.
  481.  
  482.  
  483. 4.4  VA_START-Nachricht
  484. =======================
  485.  
  486. Hier eine Beispiel-VA_START-Nachricht, wie sie an GEMJing verschickt
  487. werden kann. Daraufhin erhält man AV_STARTED sowie GEMJING_RETURN
  488. (siehe "GEMJing-Returnmessage").
  489.  
  490. ----------------------------------------------------------------------
  491.  
  492. #define MGLOBAL         0x20
  493.  
  494. #define VA_START        0x4711
  495. #define AV_STARTED      0x4738
  496.  
  497. #define GEMJING_RETURN  0x7407
  498.  
  499. #define MagX_COOKIE     0x4D616758L
  500. #define MiNT_COOKIE     0x4D694E54L
  501.  
  502. BYTE *playbuf;
  503. BOOLEAN MagiC, MultiTOS, MiNT;
  504.  
  505. if ((get_cookie(MiNT_COOKIE, &ldum) == TRUE)
  506. {
  507.   MiNT = TRUE;
  508.   if (_GemParBlk.global[1] > 1 || _GemParBlk.global[1] == -1))
  509.     MultiTOS = TRUE;
  510. }
  511. if (get_cookie(MagX_COOKIE, &ldum) == TRUE)
  512.   MagiC = TRUE;
  513.  
  514. [...]
  515.  
  516. /* Globalen Speicher für den String anfordern. Ist weder MiNT noch
  517.  * MagiC aktiv, so werden keine Speicherschutzflags gesetzt (TOS
  518.  * hat damit Probleme).
  519.  */
  520. if (MagiC == TRUE || MiNT == TRUE)
  521.    playbuf = (BYTE *) Mxalloc (150, 0 | MGLOBAL);
  522. else
  523.    playbuf = (BYTE *) Malloc (150);
  524.  
  525. /* Diesen Playbuffer kann man jetzt z.B. mit
  526.  * "-q -r3 E:\Sound\BeBack.wav"
  527.  * belegen - ohne die Anführungszeichen natürlich.
  528.  */
  529.  
  530. /* und jetzt aufrufen */
  531. play_sample (playbuf);
  532.  
  533. [...]
  534.  
  535. Mfree (playbuf);
  536.  
  537. VOID play_sample(CONST BYTE *args)
  538. {
  539.   WORD msg[8], gemjing_id;
  540.   LONG ldum, start;
  541.  
  542.   if (!args) /* ohne Argumente -> fertig */
  543.     return ;
  544.  
  545.   /* AES-ID von GEMJing ermitteln */
  546.   gemjing_id = appl_find("GEMJING ");
  547.  
  548.  
  549.   if (gemjing_id < 0)     /* Läuft GEMJing bereits? */
  550.   {
  551.     /* Environmentvariable "GEMJINGPATH" auslesen */
  552.     PfadvonGEMJing = getenv("GEMJINGPATH");
  553.     if (PfadvonGEMJing && strlen(PfadvonGEMJing) > 0)
  554.     {
  555.       if (MultiTOS == TRUE)
  556.         shel_write(0, 1, 1, PfadvonGEMJing, NULL);
  557.       else if (MagiC == TRUE)
  558.         shel_write(1, 1, 100, PfadvonGEMJing, NULL);
  559.  
  560.       /* Ja, man könnte die Parameterübergabe auch schon beim
  561.          Start per shel_write() erledigen. Dann hat man jedoch
  562.          keine Möglichkeit der Fehlercoderückgabe. */
  563.       }
  564.    }
  565.  
  566.   /* Kurz warten, damit die AES-ID da ist. Nicht optimal gelöst. */
  567.   /* Innerhalb von zwei Sekunden immer mal wieder die AES-ID suchen */
  568.   start = clock();
  569.   while (clock() - start < 2 * CLK_TCK)
  570.     if (appl_find("GEMJING ") >= 0)
  571.       break;
  572.  
  573.    if ((gemjing_id = appl_find("GEMJING ")) >= 0)
  574.    {
  575.      msg[0] = VA_START;
  576.  
  577.      /* die eigene Applikations-ID, die von appl_init()
  578.       * geliefert wird
  579.       */
  580.      msg[1] = app_id;
  581.  
  582.      msg[2] = 0;
  583.  
  584.      /* den Pointer auf zwei Words zerlegen */
  585.      msg[3] = (WORD)(((LONG)args >> 16) & 0x0000ffff);
  586.      msg[4] = (WORD)((LONG)args & 0x0000ffff);
  587.  
  588.      msg[5] = 0;
  589.      msg[6] = 0;
  590.      msg[7] = 0;
  591.  
  592.      /* Die VA_START-Nachricht verschicken */
  593.      appl_write(gemjing_id, 16, msg);
  594.    }
  595.    return ;
  596. }
  597.  
  598. ----------------------------------------------------------------------
  599.  
  600.  
  601. 4.5  GEMJing-Returnmessage
  602. ==========================
  603.  
  604. GEMJing liefert nach einem VA_START die Messages AV_STARTED sowie
  605. GEMJING_RETURN (0x7407). In msg[3] von GEMJING_RETURN erhält man einen
  606. positiven Fehlercode, alle anderen Felder sind 0. Jeder dieser Fehler
  607. führt dazu, da₧ GEMJing das Abspielen nicht beginnt. Je nach auf-
  608. rufender Applikation und Fehlermeldung sollte der Fehler dem Benutzer
  609. mitgeteilt werden.
  610.  
  611. ----------------------------------------------------------------------
  612.  
  613. /* es trat kein Fehler auf, das Sample wurde gespielt           */
  614. #define RT_OKAY                1
  615.  
  616. /* nicht genug Speicher am Stück für den Header oder das Sample */
  617. /* selbst oder für programminterne Zwecke                       */
  618. #define RT_NO_MEM              117
  619.  
  620. /* Datei konnte nicht gefunden werden oder hat die Länge 0 oder */
  621. /* es trat ein Lesefehler auf.                                  */
  622. #define RT_NO_FILE             118
  623.  
  624. /* Das Sample ist gepackt (nur bei DVS-Samples). Gepackte       */
  625. /* Samples werden von GEMJing nicht unterstützt.                */
  626. #define RT_PACKED              119
  627.  
  628. /* Das WAV-Sample enhält keine Sample-Daten                     */
  629. #define RT_WRONG_CHUNK         120
  630.  
  631. /* Die Datei enthält kein bekanntes Sampleformat                */
  632. #define RT_WRONG_FILE          121
  633.  
  634. /* Das Soundsystem ist gesperrt, da ein anderes Programm darauf */
  635. /* zugreift                                                     */
  636. #define RT_LOCKED              122
  637.  
  638. /* Interner Fehler - sollte nie auftreten                       */
  639. #define RT_SND_ERR             123
  640.  
  641. /* Die Hardware wird von GEMJing nicht unterstützt              */
  642. #define RT_WRONG_HARDWARE      124
  643.  
  644. /* Die au/snd-Datei enthält nicht unterstützte Formate          */
  645. #define RT_UNSUPPORTED_AU_SND  125
  646.  
  647. ----------------------------------------------------------------------
  648.  
  649.  
  650. 4.6  WeirdMac
  651. =============
  652.  
  653. WeirdMac von Thorsten Pohlmann <Thorsten_Pohlmann@wi2.maus.de> ist
  654. eine sehr empfehlenswerte Alternative zu MSND, da es wirklich
  655. kompatibel zum Falcon-XBIOS ist und eine freie Frequenzwahl erlaubt.
  656. GEMJing unterstützt es ab WeirdMac Version 0.64.
  657.  
  658. WeirdMac ist Fairware.
  659.  
  660.  
  661.  
  662. 5  Tips & Tricks
  663. ****************
  664.  
  665. Mein GEMJing will nicht spielen, es bleibt einfach stumm!
  666. Das kann viele Gründe haben. Wenn das Sample per Dateiauswahl bestimmt
  667. wurde, so werden Fehlermeldungen per Alert dargestellt, ansonsten
  668. nicht (um die Fernsteuerbarkeit zu gewährleisten).
  669.  
  670.    ∙ Es liegt keine passende Hardware vor, d.h. der Sound-Cookie
  671.      (_SND) zeigt weder eine ST, STE oder Falcon-kompatible Hardware
  672.      an und es ist auch kein MacSound installiert.
  673.  
  674.    ∙ Das Soundsystem ist bereits von einem anderen Programm in Be-
  675.      schlag genommen und daher gesperrt, so z.B. wenn gleichzeitig
  676.      Zeig's mir läuft und dort ein Sample geladen ist.
  677.  
  678.    ∙ Vor GEMJing lief eine veraltete Version von Zeig's mir, die das
  679.      Soundsystem nicht richtig freigab. Ab der Version 0.97 von Zeig's
  680.      mir und den zugehörigen Modulen sollte dieses Problem nicht mehr
  681.      existieren.
  682.  
  683.    ∙ Es ist nicht genug Speicher vorhanden, um das Sample zu laden.
  684.  
  685.    ∙ Das Format des Samples ist unbekannt und wird nicht unterstützt
  686.      (das ist leider relativ oft der Fall, viele Programme schreiben
  687.      sehr seltsame Header).
  688.  
  689. ----------------------------------------------------------------------
  690.  
  691. GEMJing will nicht unter MagiC-PC 1.3 spielen!
  692. Ein Update auf MagiC-PC 6.0 hilft. Ab dieser Version wird die
  693. Soundausgabe via XBIOS unterstützt.
  694.  
  695. ----------------------------------------------------------------------
  696.  
  697. Habe ich Crazy Sounds installiert, so spielt GEMJing nicht.
  698. Crazy Sounds scheint das Soundsystem regelmä₧ig zu initialisieren, so
  699. da₧ GEMJing keine Chance hat. Abhilfe: Rational Sounds von Heiko
  700. Achilles (heiko_achilles@du.maus.de) und Nils Schneider verwenden.
  701.  
  702. ----------------------------------------------------------------------
  703.  
  704. Mein Sample wird zu langsam oder zu schnell gespielt.
  705. Wahrscheinlich ist das Sample mit einer "krummen" Frequenz aufgenommen
  706. worden. Die Abspielhardware des STE und Falcon (MSND für MagiCMac
  707. verhält sich wie ein Falcon) lassen leider keine stufenlose Auswahl
  708. der Frequenz zu. Die recht häufig vorkommenden 22kHz Samples werden
  709. mit 25kHz abgespielt, das hört sich besser an, als 19kHz (Falcon, Mac)
  710. oder gar 12kHz (STE, TT). Abhilfe bei Verwendung von MagiCMac: Be-
  711. nutzen Sie statt MSND besser WeirdMac ab Version 0.64 von Thorsten
  712. Pohlmann, das eine freie Frequenzwahl ermöglicht.
  713.  
  714. ----------------------------------------------------------------------
  715.  
  716. Mein Sun/NeXT-Sample wird nicht abgespielt, obwohl GEMJing das doch
  717. können sollte!
  718. Sun/NeXT-Samples gibt es mit zwei Dutzend Untertypen, von denen
  719. GEMJing derzeit nur einige unterstützt. Es wird daran gearbeitet.
  720.  
  721. ----------------------------------------------------------------------
  722.  
  723. Manche meiner WAV-Samples werden nur verrauscht gespielt, man erkennt
  724. nichts.
  725. Microsoft hat ein WAV-Format definiert, das gepackt vorliegt. GEMJing
  726. kann diese Samples derzeit noch nicht entpacken.
  727.  
  728. ----------------------------------------------------------------------
  729.  
  730. GEMJing will nicht spielen, wenn Freedom 2 (Liberty) installiert ist
  731. An einem Workaround wird gearbeitet. Benutzer von originaler Atari-
  732. Hardware können von mir eine gepatchte Version erhalten, die funktio-
  733. niert. Alle anderen müssen sich noch etwas gedulden.
  734.  
  735.  
  736.  
  737. 6  Dank
  738. *******
  739.  
  740. Ein herzliches Dankeschön haben sich verdient:
  741.  
  742.    ∙ Thomas Much - für geduldiges Betatesten (bei ihm lief's ja immer
  743.      :-) und Vorschläge.
  744.  
  745.    ∙ Dirk Haun - von ihm stammt die verbesserte 16 Bit nach 8 Bit
  746.      Wandlung.
  747.  
  748.    ∙ Alexander Clauss - für Anregungen und den Hinweis auf die SND-
  749.      FAQ.
  750.  
  751.    ∙ Jörg Hahne - er stellte seine Abspielroutinen für den PSG zur
  752.      Verfügung.
  753.  
  754.    ∙ Holger Weets, Thomas Künneth, Gerd Hofmann und Alexander Lorenz
  755.      für das Ertragen von Bombendrohungen und für Betatesting.
  756.  
  757.    ∙ Sven & Wilfried Behne für den verbesserten PureC-Startup-Code.
  758.  
  759.    ∙ Katrin Müller für das Ignorieren des nervtötenden Sample-
  760.      schnipsels ("we don't need no education"), das sie mehrere
  761.      Hundert mal unfreiwillig vorgespielt bekam.
  762.  
  763.    ∙ Uwe Lehmann, Olivier Booklage, Jo Vandeweghe, Marion Messerich,
  764.      Laisani Petersen, Sascha Malatsion, Gideon Jacques, Leona Baba,
  765.      Tiziana Marotta, Christian Marcelo, Atilim und Devrim Erkmen,
  766.      Basar Alabay, Horst Boenisch und Markus Müller für Übersetzungen.
  767.  
  768.    ∙ Das Team von ASH, vor allem Oliver Buchmann und Volker Ritzhaupt,
  769.      für die Unterstützung.
  770.  
  771.    ∙ Ulrich Kaiser für beharrliches Drängen.
  772.  
  773.    ∙ Holger Herzog für den sinnlosen Vorschlag mit der Environ-
  774.      mentvariable, den ich so toll fand :-)
  775.  
  776.    ∙ Dimitri Junker für den neuen Kommandozeilenparser und die Zeit
  777.      für die Tests vor der Source-Veröffentlichung.
  778.  
  779.    ∙ Stephan Wilhelm, der auf dem CETiK '99 viel Geduld bewies, wenn
  780.      ich mal wieder rumwuselte und nachher vor meinem Programmcode
  781.      stand wie der Ochs vor'm Berg :-)
  782.  
  783. GEMJing entstand mit PureC, PureAssembler und Interface auf einem
  784. Apple PowerMacintosh 8600/300, Apple Performa 475, Apple PowerBook
  785. 190cs, Apple Macintosh SE/30 (alle mit MagiCMac) und einem Atari
  786. Falcon (TOS 4.04, N.AES). Für die Dokumentation wurde qed und UDO
  787. verwendet.
  788.  
  789.  
  790.  
  791. 7  Historie
  792. ***********
  793.  
  794. Version 1.36, 01.06.00
  795.  
  796.    ∙ Lizenz von Freeware zur CAT Public License geändert.
  797.  
  798.    ∙ Sourcen veröffentlicht.
  799.  
  800.    ∙ Neuer Kommandozeilenparser mit Workaround für CAB-Quoting.
  801.  
  802. Version 1.35, 07.03.99
  803.  
  804.    ∙ Bei sehr alten SingleTOS-Versionen konnte GEMJing beim Aufruf der
  805.      Dateiauswahl einen Absturz produzieren (ungültiger Pfad). Sollte
  806.      behoben sein.
  807.  
  808.    ∙ GEMJing unterstützt jetzt die StarTrack-Karte mit und ohne
  809.      Clockmodul.
  810.  
  811. Version 1.30, 07.06.98
  812.  
  813.    ∙ Unterstützung von MagiC-PC 6.0 mit beliebigen Frequenzen.
  814.  
  815.    ∙ Böser Bug bei SMP entfernt, Dank an Thorsten Otto.
  816.  
  817.    ∙ Neuer Kommandozeilenparameter "-p" (siehe "Kommandozeilenstart"):
  818.      GEMJing zeigt nach dem Start keine Menüzeile an, bleibt aber als
  819.      AES-Programm im Speicher. Nur für Fernsteuerung sinnvoll.
  820.  
  821.    ∙ Kleinere Bugfixes und Optimierungen, Debug-Code der 1.25-
  822.      Zwischenversion raus.
  823.  
  824.    ∙ Doku etwas überarbeitet.
  825.  
  826.    ∙ Kein AV_SENDKEY bei Gemini als AV-Server wg. eines Bugs in
  827.      Gemini.
  828.  
  829. Version 1.25, 04.04.98
  830.  
  831.    ∙ Messeversion Neuss
  832.  
  833.    ∙ WAV-Einleseroutine fehlertoleranter
  834.  
  835.    ∙ Bugs bei AVR entfernt (Stereo-16-Bit)
  836.  
  837.    ∙ Ferngesteuertes Abspielen geht nun auch aus einem Speicherbereich
  838.      heraus, siehe Programmierdoku (siehe "Für Programmierer").
  839.  
  840.    ∙ GEMJing spielt auch auf dem Hades040, trotz der z.T. grob fehler-
  841.      haften Cookies. Dank an Holger Herzog @ ZW für die
  842.      Testmöglichkeit auf dem CETiK '98.
  843.  
  844. Version 1.06, 15.10.97
  845.  
  846.    ∙ Fremdsprachliche Versionen: Philippinisch von Christian Marcelo,
  847.      italienisch von Tiziana Marotta.
  848.  
  849.    ∙ Kleinere Bugfixes und Korrekturen in der Hinsicht auf alternative
  850.      Systemfonts.
  851.  
  852.    ∙ Bessere Unterbrechbarkeit (CTRL-Shift) auch während eines Delays.
  853.  
  854. Version 1.05, 04.10.97
  855.  
  856.    ∙ Fremdsprachliche Versionen: Englisch von Uwe Lehmann, Französisch
  857.      von Jo Vandeweghe, Latein von Marion Messerich, Bishlamaro von
  858.      Gideon Jacques, Fidschi von Laisani Petersen, Esperanto von
  859.      Sascha Malatsion, Spanisch von Ursula Hoffart, Türkisch von
  860.      Atilim and Devrim Erkmen, Japanisch von Leona Baba.
  861.      Koordination: Markus Müller.
  862.  
  863.    ∙ Fremdsprachliche Dokumentationen: Französisch von Olivier
  864.      Booklage, Englisch von Uwe Lehmann.
  865.  
  866.    ∙ Atari-Messe-Neuss-Edition.
  867.  
  868. Version 1.04, 04.09.97
  869.  
  870.    ∙ Es wird nun nicht nur unter MagiC performanceneutral zwischen den
  871.      Samples gewartet, sondern auch unter N.AES und anderen Betriebs-
  872.      systemen, die Fselect() unterstützen.
  873.  
  874.    ∙ Drei neue Sampleformate: HSN, AVR und SMP. Trotzdem benötigt
  875.      GEMJing mal wieder weniger Platz, das Programm ist jetzt 17 KB
  876.      gro₧. Lange halte ich den Trend aber nicht mehr durch :-)
  877.  
  878.    ∙ WDIALOG wird nicht mehr benötigt. Der fehlende Fensterdialog ist
  879.      hoffentlich zu verschmerzen.
  880.  
  881.    ∙ AV_SENDKEY eingebaut. Tastendrücke, die GEMJing nicht selbst
  882.      auswertet, werden nun an den AV-Server weitergeleitet.
  883.  
  884.    ∙ GEMScript Rel. 0.8 wird unterstützt: OPEN und QUIT.
  885.  
  886.    ∙ Eine französische Version ist verfügbar, Dank an Olivier Booklage
  887.      und Jo Vandeweghe.
  888.  
  889.    ∙ GEMScript-Kommando "QUIT" wird zusätzlich zu "OPEN" unterstützt.
  890.  
  891.    ∙ Bug bei Kommandozeilenübergabe bei SingleTOS raus (Dank an Peter
  892.      Melzer).
  893.  
  894.    ∙ SCCS-Kennung eingebaut
  895.  
  896.    ∙ GS_INFO-Extension korrigiert
  897.  
  898. Version 1.03, 15.07.1997
  899.  
  900.    ∙ Eine englische Version ist verfügbar, Dank an Uwe Lehmann.
  901.  
  902.    ∙ sleep als evnt_timer-Ersatz für TTP-Start: damit funktioniert der
  903.      Parameter "-d" nun auch bei Start als non-GEM-Programm.
  904.  
  905.    ∙ OLGA-Server-Funktionalität eingebaut
  906.  
  907.    ∙ GEMScript implementiert, Kommando "OPEN" wird verstanden
  908.  
  909.    ∙ GS_COMMAND korrigiert, Dank an Alexander Barton
  910.  
  911.    ∙ AP_TERM-Unterstützung wird angemeldet
  912.  
  913.    ∙ böser Bug bei OLGA-Initialisierung raus - Dank an Olivier
  914.      Booklage
  915.  
  916.    ∙ OLE_EXIT wird versandt
  917.  
  918.    ∙ einige Verschlankungen: geringerer Speicherverbrauch
  919.  
  920. Version 1.00, 24.03.1997
  921.  
  922.    ∙ Erste von mir veröffentlichte Version.
  923.  
  924.  
  925.  
  926.