*** Reader Disk 5 (SAM & SACK) ***
*** Xav (Mark Crutch) *** *** Utilities *** *** STe/TT/Falcon ( >= TOS 
2.05 for SAM) ***


*** Heading & Standfirst ***
Play it again... again!

To accompany the reader disk, Xav takes a closer look at SAM and SACK

*** Main Text ***
In case anyone missed the "Stop Press" in last issue's PD section, KPP has 
been given permission by Atari to distribute a patched version of SAM. 
What better way, we thought, than on the AC reader disk - and we've bunged 
on a copy of KP SACK as well.

There are a couple of files that you are advised to read when using SAM. 
The readme.1st contains a copy of the email we received from Atari, as 
well as our contact details. The second, manual.doc, is the manual that 
was supplied with version 1.1 of SAM. Although out of date, the changes 
between this version and the latest are minimal. As there isn't space in 
this article to detail all of SAM's functions, it's well worth having a 
read through.

Installing SAM is quite straightforward, though you should note that it 
requires at least TOS 2.05 (or a replacement, such as MultiTOS). It also 
works with other AES replacements (N.AES, MagiC) although not all the 
system events trigger sounds correctly under every OS. It consists of an 
auto folder program, an accessory, and a CPX. The latter ensures that SAM 
still works even if the accessory isn't loaded, so 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 you can leave it disabled normally, provided you 
have Xcontrol and the CPX installed.

Bear in mind that all the samples you assign are buffered in memory, so if 
space is a little tight you might want to forego that three minute comedy 
sketch in favour of a five second outburst. One point worth noting though, 
is that assigning the same sample to multiple events only loads it into 
the buffer once, so think carefully about whether you really need 
different sounds for each type of alert box, as doubling up can greatly 
reduce your memory needs. Alternatively you could just use SAM as an 
excuse to justify that upgrade you've been promising yourself.

*** Subtitle ***
A sackful of samples

KP SACK is an application which was written primarily for programmers, to 
accompany SAM. The documentation is in ST-Guide format, so you'll need a 
working set-up (version 1.4 was on the issue 2 reader disk). As well as a 
simple user guide, the hypertext also includes all the programming 
information you should need for calling SAM from within your own code.

Using SACK, it's possible to create SAA (SAM Aware Application) files, 
which allow a program to inform SAM of specific events. These events take 
two forms: globals and macros. Globals are events such as "Cut" or "Quit" 
which are common to a large number of programs. By activating these within 
SACK, then loading the resulting SAA into SAM, the user will be able to 
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 if the user has at least one SAA with them 
all turned on. For this reason we recommend that you distribute the 
global.saa file with your programs, as this has all the globals activated.

Macros themselves are actually quite similar to globals, except that they 
are application specific. Typically they are used when you want to give 
the user the chance to assign a sample to a specific event in your program 
- such as a particular sound when the program starts, or the "About" 
dialogue is called. In order to use macros, you have to choose a four 
character cookie, but 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 online help, but include events such as 
"Iconisation" and "Select All".

Of course SAM isn't going to find widespread use 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 aren't 
any ports to other compilers, but if you modify this file to suit your 
own, please let us know so that we can distribute the new file to 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 that you will come across. ap_macro.h is 
created whenever you save an SAA, and is purely there 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 note that if you 
save an SAA in a directory in which there is already an ap_macro.h file, 
the old one will be overwritten. Therefore, if your program is large 
enough to require more than one SAA file, it's best to keep them in 
separate folders whilst the program is being developed.

*** Subtitle ***
And Finally...

Well that's about it. For those of you who don't get the reader disk, SAM 
and SACK are both available from (www.compsoc.man.ac.uk/~xav) or from 
(www.cs.man.ac.uk/~jacquesa/). It's worth reading the manuals for both 
programs in order to get the best from them, and if you write or modify a 
program to use SAM, why not send us a copy - it might even make it onto 
the reader disk.


*** Screenshots	***

*** macros.gif ***
Just type your macro names into SACK...

*** headers.gif ***
...and it creates labels for them which you can override if necessary

*** globals.gif ***
Application globals are as simple as selecting some buttons


*** End of article ***