Computer Club Elmshorn Atari PD

home *** CD-ROM | disk | FTP | other *** search

/ Computer Club Elmshorn Atari PD / CCE_PD.iso / mac / 0700 / CCE_0705.ZIP / CCE_0705.PD / GBELL10C / GBELL.MAN < prev next >

Wrap

Text File | 1994-01-24 | 24KB | 482 lines

GBELL(1) GEM action audio effect device GBELL(1) NAME GBell v1.0c - GemBell v1.0c IMPORTANT Read the segments titled MAILWARE, DISCLAIMER and HARDWARE REQUIREMENTS before using/copying this excellent piece of software for your Atari STe/TT/Falcon. If you're head of a company, please read the NOTICE TO SOFTWARE/HARDWARE COMPANIES. INDEX OF THIS FILE Name, Important, Index of this file, Description, Background, Value, Hardware requirements, Disclaimer, Installation, System vectors, Cookie jar, Recurtion lock, Configuration, Aes functions, Future plans, Up the sleeve, Bugs, Mailware, Notice to software/hardware companies, Norwegian symbols, Files, Versions, Author, See also, Scriba is available from, Thanks to. DESCRIPTION GBell is a small and effective program which hooks up to the GEM trap vector and looks for identifiable system calls, like window_open, window_close, drag_bar and so on. When a system call has been identified, an appropriate sample is selected, loaded (if not already present in memory) and replayed by the soundchip. Which system call gives which sample is user defined in the GBELL.INF file as explained below. BACKGROUND We are moving into an age where audio is just as important as video. The McIntosh has had the ability to play off different samples at different events for ages, and not too long ago, MS Windows achieved the same thing. Why shouldn't this be possible on the ST? Why should we have to look another way when a McIntosh owner shows off his computer as he opens the trash can and the trash can goes "Bring out your dead!" (Monty Python quote). It is close to assume that the best reason that such a program hasn't been made is the fact the original ST didn't have a soundchip advanced enough to do this, and so, no standard for sound handling really showed up in the ST operating system. Most audio programs go directly on the hardware and therefore, it is easy to crash with the other programs. Another interesting thing is how the system would slow down. That is, unless you actually use the DMA for replay. And that is exactly what has been done in GBell. GBell checks if the soundchip is busy. If it is, the it drops the whole sound, thereby saving us for both time and unwanted interruptions in the soundtrack you were replaying. If the soundchip is free, then load sample if necessary and simply set the chip to replay that sound from a buffer which cannot be overwritten by other programs. And where does the name GBell come from? Well, it started with myself downloading NewBell from atari.archive, and I soon came to realize that changing _only_ the bell was far too little. Especially when the program didn't make use of the DMA, thus halting the system every time there was a bell. Thereby the name 'bell'. I must admit that the original 'G' has something to do with my name, but it fits good as "Gem" as well, and that is exactly what this program listens for; GEM functions! VALUE What's the real purpose of this program, I hear you ask? Well, to the average user, it's just pure vanity and has no real value other than that it _feels_ nicer. You dare to turn on the stereo while you're using your computer, and no Mac or Amiga owner will need to ask you why they never hear any sounds from your computer? This is the same reason why you love the 3d-look AES, too. For the GEM programmer, however, this can become a handy tool, too. Hooking different samples on different functions can make debugging easier. You can actually _hear_ if an invisible function is called or not. Very handy indeed, if you're programming something multitasking, like an accessory or MiNT application that communicates with other accessories or applications. HARDWARE REQUIREMENTS GBell will only work with Atari computers that run a TOS compatible operating system and has DMA sound available. As of this date, this indicates a STe, TT or Falcon. GBell is preferred run from harddisk, but nobody said you couldn't use it with floppies... DISCLAIMER Even though I can't seem to find any bugs that will affect the reliability of your system, usage of this software package is totally your own responsibility. Thereof, risks of damage or loss of data are completely your own, and can not be blamed on the programmer. But it helps to have the newest update... 8*) INSTALLATION Put GBell in auto folder, as early as possible. Preferably before MiNT, which should be the second program in the auto folder. Create a folder on you harddisk for samples. Move all samples into this folder. The create GBELL.INF as instructed later in this file. GBELL.INF should be put in the root directory of the boot device. SYSTEM VECTORS GBell bends two vectors. One is the BIOS, trap #13, to catch the ROM when it installs GEM, so that GBell's other vector bending, trap #2, doesn't disappear after boot. It is preferred to put GBell as early as possible in the auto folder, so that it is the last program to install itself on the GEM trap, thus becoming the first to receive the GEM function call from the program. This will allow GBell to catch virtually any function, despite of the presence of function library replacements, like file selectors, let'em fly and MiNT. The trap #2 bending is the most interesting one. This is the part that catches the function call, compares it to the function/sample table given in the GBELL.INF file, and replays a sample if a match has been found. Notice, however, that the entire test will be skipped if the soundchip is busy doing something else. The vector bending follows the XBRA standard, with the XBRA ID "GBel". COOKIE JAR As any other resident application which alters the achievements of your STe/TT/Falcon, GBell has its own cookie. The Cookie ID is the same as the XBRA ID, "GBel". The Cookie data is a pointer to a GBell variable table, which is the same kind of variable library used in Scriba Communis Responsi for communication between the program and the menu data. In practice, it is very much like a cookie jar in every way, except that the NULL cookie does not tell you how many cookies there are room for. The point of this is that if the variable system is expanded or altered, it shouldn't cause any application that reads these variables to crash. Variables for GBell v1.1 are: VARIABLE VALUE !"MAGI" 24892 (Magic number to make sure it's GBell) !"_VER" version number "BUFF" *sample buffer (see info on GBELL.INF) !"SIZE" sample buffer size "TABL" *action table (what to do when) !"TSIZ" Size of allocates action table block including sample names. !"PATH" *path name where samples are located "LOCK" Recurtion lock. Set while GBell is loading a sample, thus preventing recursive self- activition. Only the first word is altered by Gbell itself, but the entire longword is tested, so setting the least significant word to non-zero will let you "turn off" GBell. "FALC" Falcon detection. ASCII "TRUE" when a Falcon has been detected, and certain soundchip init routines need to be executed. Otherwise zero. "STAK" Amount of data pushed on stack when executing a trap. 6 for a 68000 and 8 for a 68030. !"LAST" *Full path and name of last loaded sample. !"PROG" *Actual program block. !"PSIZ" Size of resident program block. 0 (end of table) Variables marked with a '*' are pointers. Variables marked with a '!' are informative variables that will not change the program's performance if changed. Strings that are pointed at, however, will alter program performance if tempered with. Some of these, however, are due to change to actual real pointers in a future version, so you shouldn't touch these unless you have a good reason to do so. The longword before the table, the cookie/XBRA ID is present to identify the correctness that this _is_ the GBell variable area. During installation, if there is not enough cookie slots left, GBell will allocate a cookie jar which is twice as big and move all cookies to the new space. RECURTION LOCK Since GBell needs to load the samples from disk whenever they are not in the buffer, this does in itself cause a minimum of three GEMDOS calls. In future versions, these can be caught by GBell, resulting a dead loop, eventually corrupting all memory from the supervisor stack and down. There is a chance for this to happen even on this version, if an error occures during loading, causing a GEM alert error message, which _can_ be caught in this version of GBell. For this reason, as soon as GBell has found a match and starts loading a sample, this flag is set, causing GBell to ignore all new matches for as long as it already is busy loading another sample. After loading, the sample being played will in itself cause GBell to ignore function calls, and so the flag is dropped immediately after the replay has started. CONFIGURATION Everything that can be configured is configured in the GBELL.INF file. Keep in mind that the GBELL.INF file will only be backward compatible, not forward. I.e., an unknown command will cause the parsing to break, and the entire installation will be skipped, rather than just the line (this is true for version 1.1. It might be altered in later versions.) The GBELL.INF file should be located in the root directory of the boot device. The GBELL.INF file contains ASCII commands to easily make your own setup of sounds and functions. The file is loaded at boot time, so altering it will not change the current settings before next reboot. All lines have in common the following synopsis: <command> <parameters> The last parameter is always followed immediately by a new line. Spaces behind the last parameter will cause a parsing error. (v1.1) Parameter descriptions are as follows: <string> - a text string as in BASIC. Must be contained in quotation marks due to possible spaces in quote. To quote a quotation mark, use double quotation marks. <integr> - a 16 bit unsigned integer. <byte> - an 8 bit unsigned integer. <spec> - a filename or path, not contained in quotation marks, since spaces don't give any nice filenames. <sample> - <byte> <byte> <spec>, where the first byte is replay speed, which is one of the following: 0 = 6.26 kHz (Falcon=off) 1 = 12.52 kHz 2 = 25.04 kHz 3 = 50.07 kHz The second byte is sample type, which can be one of the following supported: 0 = signed 8-bit mono sample 1 = unsigned 8-bit mono sample The filespec is the filename of the sample to replay, relative to the path name given. So far, the following commands are supported: PATH <spec> Sets path to find samples. BUFFER <long int> Sets size of sample buffer. The samples will be loaded into this buffer and then replayed. The same sample will not load twice in a row, as GBell keeps track of which sample is already in the buffer, and which is not. At the time being, the buffer will only contain one sample at a time, meaning that the buffer size should be the same as the largest sample to load. Defaults to 70000 if command not included in script. AES <integr> <sample> Activates sample when AES function <integr> is called. See section AES TABLE for a list of AES functions. ALERT <string> <sample> Activates sample when form_alert is called with a string whose beginning is alike the given string. ALERTEXT <string> <sample> Same as ALERT, but string compare begins at the actual text, thereby skipping the symbol used in the box. WINAME <string> <sample> Activates sample when a window's name is set. Usually, this happens before the window is opened, so this sample should normally supress your open window sample. Check out how nice it is to go through directories with MiNT, when you put different samples on different directory names... The tests will be performed in the same order as the commands appear in the GBELL.INF file, and as soon as a match has been found, the rest is skipped. Thus, the exceptions should be entered before the rules. AES FUNCTIONS (just a few of them) Application initiation/termination 10 appl_init 19 appl_exit Event requests 20 evnt_keybd 24 evnt_timer 21 evnt_button 25 evnt_multi 22 evnt_mouse 27 evnt_dclick 23 evnt_mesag Menu fixes/events 30 menu_bar 33 menu_tnormal 31 menu_icheck 34 menu_text 32 menu_ienable 35 menu_register Object functions and events 42 objc_draw 53 form_error 50 form_do 55 form_keybd 51 form_dial 56 form_button 52 form_alert (see commands ALERT and ALERTEXT) Graphical effects and events 70 graf_rubberbox 74 graf_shrinkbox 71 graf_dragbox 75 graf_watchbox 72 graf_movebox 76 graf_slidebox 73 graf_growbox 78 graf_mouse Fileselector 90 fsel_input 91 fsel_exinput Window events 100 wind_create 102 wind_close 101 wind_open 103 wind_delete FUTURE PLANS (FOR THIS PIECE OF SOFTWARE) Future versions of this program will probably contain one or more of the following items that are on my todo-list: o OBJECT-command - recognizes when you draw an object which contains a string given as a parameter. o Static buffer - if internal buffer is too small for sample, allocate memory for whole sample if possible and get rid of it afterwards. o Multi-buffer - if there's room, keep more than one sample in the buffer at a time, reducing load-time. o GEMDOS-command - recognizes GEMDOS function calls. o EXEC/LAUNCH - recognizes the launch of a specific program. o FOPEN - recognizes file handling to a specific file or file pattern (like yelling for help when you write to a .PRG file as indication of a possible link-virus?) o XBIOS - recognizes XBIOS function calls. o Static table - possibility to change recognition table without resetting. o ASCII 7 (bell) interception. o DATE/TIME commands, allowing you to have the computer automatically play "Happy Birthday to you" on your birthday! *grin* Thanks to Kai for the idea! ;-) o Sample editor to alter samples to fit replay speeds. UP THE SLEEVE (coming soon) Flexible use of the buffer, meaning more than one sample in the buffer at a time will be the next addition for version 1.1. The reason this will be added first is a problem about loading stuff when calling the BIOS (don't ask me why) at times, causing the computer to crash totally. And since one of the most important bell-checks is in the BIOS trap, it would probably be 'ok' to have the bell-replacement sample ready in the buffer at any time. This would give you a 'free' buffer of 'buffer length - bell sample'. More about this in the 1.1 release MAN file. After this, the BELL and GEMDOS commands should be just around the corner, together with object recognition. BUGS No known bugs (I hope). MAILWARE This program is mailware. This means that it can be copied freely all over the world, as long as all files, including this one, are all intact and follow the package, and nothing is charged for the copy other than the expenses of actually copying it, shipping it and whatever you had to pay for the disk you copied it onto. But this is not all. Because if you enjoy this program just as much as I do, then some kind of communication is in order. Preferably snailmail. Preferably with a photo of yourself, your sister, girl friend, mother or any other female. Alternatively, you could sample her whisper something to me. Or you could just send her over (if she's not too old or too young, of course). Money donations, postcards, valentines cards, flowers, air tickets, free holidays, holiday invitations, pen pals, free disks, free TV sets, free computer upgrades, free software, interviews, fame and fortune are all, of course, also appreciated. The programmer's address is, and will remain so until June 1995, as follows: Gard Eggesb\oe Abrahamsen, PO Box 5061, Larsg\aarden, 6021 \Aalesund, Norway After that, mail can be redirected through this address: Gard Eggesb\oe Abrahamsen, PO Box 71, 6092 Eggesb\oenes, Norway Electronic mail is valid as long as the \Aalesund address: Gard.Abrahamsen@mrih.no Telephonically, these numbers are currently valid: 7015 5497 (if you're in Norway) Usually after 21:20 +47 7015 5497 (overseas) as I'm logged in as long as possible. 7008 8812 (if you're in Norway) During the odd weekend +47 7008 8812 or holiday, when I decide to go home. NOTICE TO SOFTWARE/HARDWARE COMPANIES If you think the programmer is doing a great job, and wishes to put him on your staff, don't hesitate to get in touch. The programmer is just a poor student who is sleeping through classes to get papers telling him that he can do the things he can. Right now, this is just above half way through the bachelor degree of computer science/engineering (some crazy mix of the two - ask for details). The programmer has 10 years of programming experience, ranging from Sinclair BASIC, Z80a assembler to C-programming on the PC, GEM programming on the ST as well as a _lot_ of MC680x0 programming. If you want to pay my education, which so far has put me in a NOK 100'000 (GBP 10'000) debt, please feel free to do so. *grin* If you wish to take me up for an interview, don't hesitate getting in touch. See my addresses/phone numbers above. Internet users: finger ga@samson.mrih.no or mail me for my .plan file. NORWEGIAN SYMBOLS , The \oe is written as an 'o' with a slash across it: (/) ' . The \aa is written as an 'a' with a circle above it: A FILES GBELL.PRG - The actual program GBELL.INF - The GBell sample info script GBELL.MAN - This file The following samples are to "get you started" HALELUJA - "Halleluja" DOING - A "doing" sound. CHORDS - Frequently heard Mac sampling. VERSIONS (Official release dates) 1.21.1994 : Version 1.0beta Supported GBELL.INF file, PATH, BUFFER, AES, ALERT, ALERTEXT, cookie jar. 1.24.1994 : Version 1.0c Added WINAME. Recurtion lock. Fixed bug for Falcon, where I forgot to save registers before using the XBIOS to init chip, resulting in some rather ugly noise when I wrote the registers - now with false values - to the soundchip. More variables exposed through cookie. Expanded MAN file. AUTHOR Gard Eggesb\oe Abrahamsen, (MAILWARE) January 1994 SEE ALSO (Softography) Scriba Communis Responsi diskmagazine Reverse - the better reversi? (definitely not, but the user interface is nice...) Memorized - Classic concentration type game. Catchup - short, quick, effective nntp reader (HPUX/Bash). PinuP - Pinup Is Not Unlike Pine, email-file reader for ST. SCRIBA IS AVAILABLE FROM atari.archive.umich.edu ~atari/Magazines/Diskmags/Scriba src.doc.ic.ac.uk computing/systems/atari/umich/Magazines/Diskmags/Scriba ftp.uni-kl.de pub/atari/diskmagazines THANKS TO Kai Trygve Holst, co-editor of Scriba Communis Responsi and programmer of AntiDote - probably the best virus killer on the ST/STe/TT/Falcon, for testing this software on the Falcon and coming up with ideas of things that could be done better as well as good support during development of this software.