** 1 page feature SAM/SACK / 974 words **
** On Reader Disk logo here **

Play it again SAM... again!

Xav takes a closer look at SAM and SACK...

** SAM13.GIF here **

In case you missed the "Stop Press" last issue Kosmik Phish Productions (KPP) has been given permission by Atari to distribute a patched version of their System Audio Manager (SAM) to accompany KP SACK, an acronym for, "SAA Construction Kit". KP SACK is a nifty utility which makes it easy for programmers to incorporate sounds samples into projects for use by SAM.

There are a couple of files you should read before using SAM. README.1ST contains a copy of the email we received from Atari along with the contact details for KPP. The second, MANUAL.DOC, is the manual supplied with SAM v1.1 but, although out of date, is still worth reading because the changes between that version and the patched release are minimal and there isn't space here to detail all of SAM's functions.

To install SAM you require at least TOS 2.05 or a replacement, such as MultiTOS or other AES replacements (N.AES, MagiC), although not all the system events trigger sounds correctly under every OS. SAM consists of an Auto folder program, an accessory, and a CPX. The CPX ensures SAM still works even if the accessory isn't loaded but you'll need one or the other to get any output. The accessory is required to configure SAM but if you're short of memory it makes sense to leave it disabled until needed and rely on the CPX.

Do remember all assigned samples are buffered in memory, so unless you have lots of free memory forget that three minute comedy sketch in favour of a five second outburst. Memory use can also be minimised by assigning the same sample to multiple events because each sample is only loaded into the buffer once. On the other hand if you're trying to justify a memory upgrade SAM is as good an excuse as any!

A sackful of samples

KP SACK is an application written primarily for programmers who wish to use SAM. The documentation is in ST-Guide format, so you'll need a working set-up (ST-Guide v1.4 was on the AC2 reader disk). The hypertext serves as a simple user guide and programmer's guide, providing all the information needed to call SAM from your own code.

Using SACK, it's possible to create SAA (SAM Aware Application) files, which enables programs to inform SAM of specific events. These events take two forms: globals and macros. Globals are events such as "Cut" or "Quit" and so on, which are common to a large number of programs. By activating these within SACK, then loading the resulting SAA into SAM, the user can assign samples to these events. Officially every program that uses globals should be supplied with an SAA file - even if it doesn't use any macros. This, however, is unnecessary so long as the user has at least one SAA with them all turned on. For this reason we recommend you distribute the global.saa file with your programs because this has all the globals activated.

Macros are similar to globals, except they're application specific. Typically they're used when you want to give the user the chance to assign a sample to a specific event in your program - maybe a particular sound when the program starts, or the "About" dialog is called. To use macros, you have to choose a four character cookie. Be careful to choose something unique or you could end up calling another program's sounds (so don't use "PROG"!)

With the cookie name, it's possible to call samples from other application's SAA files. Generally this isn't recommended, in case they get updated and changed, but this trick has enabled us to create the global.saa file, which includes a number of "globals" as macros, to address the areas we felt were lacking in the original set of globals. All these are detailed in the on-line help, but include events such as "Iconisation" and "Select All".

Of course SAM won't become widespread unless it's easy for programmers to use. For this reason you'll find a few header files (*.H) cluttering up the place. The WAVEPLAY.H file includes all the data necessary to call SAM's routines from Lattice C. Currently there are no ports to other compilers, but if you modify this file to suit your compiler, please, please do send us a copy so we can distribute it for the benefit of other users. The GLOBAL.H header simply contains standard names for the 'new' globals of the GLOBAL.SAA file.

There's one other header file you'll come across. AP_MACRO.H is created whenever you save an SAA, and is designed to make your life easier by #defining your macro and cookie names. Provided you keep each project in a different folder, this should be fine, but be aware if you save an SAA in a directory in which there is already an AP_MACRO.H file, the old one will be overwritten. This is probably only an issue if your program requires more than one SAA file - in which case keep them in separate folders during development.

Finally, if you do write or modify your programs to use SAM, send us a copy to review or include on the Reader disk.

** boxout 1 **
Where to get them
Apart from the Reader disk, SAM and SACK are both available from:
** bc font on **
http://www.compsoc.man.ac.uk/~xav/
http://www.cs.man.ac.uk/~jacquesa/
** bc font off **
And most PD/Shareware libraries.
** end boxout **

** Product boxout **
Software
KP SACK v1.0 and SAM v1.3
Category
Utility
Status
Freeware
System
STe/TT/Falcon and TOS 2.05 or later for SAM
** end boxout **

** Captions **
** SAM13.GIF **
Old dog, new tricks!
** macros.gif **
Just type your macro names into SACK...
** headers.gif **
...and it creates labels for them - which can be overridden if necessary
** globals.gif **
Application globals are as simple as selecting some buttons
** end captions **