erkyrath.infocom-zcode-terps/st

					About GIA.TOS and pump_sound()
					------------------------------

	This file describes the various files on this disc, what they are,
and how to use them.  If you need more information, please contact

Alex Leavens
Activision, Inc
2350 Bayshore Pkwy
Mountain View, CA  94043
(415)-960-0518, ex. 5324

What's on this disc
-------------------
	The following files should be on this disc:

		GIA.C		(a short C sample driver for the sound play routine)
					(compiles under Mark Williams C, ver. 2.1.7)
		GIA.O		(object file for GIA.C)
		GIA.TOS		(executable version of GIA.C)
		PUMPSND.S	(68K source code to the sound driver routine, in
					 MADMAC (Atari ST assembler) format)
		PUMPSND.O	(object file for PUMPSND.S)
		MAKEFILE.GIA	(The makefile for GIA and PUMPSND)
		BADVIO.SND	(Demo sound file)
		SPLASH.SND	(Demo sound file)
		README.DOC	(This file)


Using pump_sound()
------------------
	pump_sound() is an assembly language subroutine that is internally
self-contained.  It need only be passed a single parameter, which is the
address of the sound sample that is to be played.  This sample is assumed
to be in the format created and generated by Russ Leiblich, to wit:

	* Sound data is signed 8 bit data (-128 to 127)
	* Data file header looks like:

	Byte(s)		What
	------------------------------------------------
	0-1			Length of the rest of the sound sample, including header
	2			Repeat count (# of times to play this sample--0 originally
				meant 'play forever', however in our routine, we change 
				this to 'play once', thus a repeat count of 0 is functionally
				equivalent to a repeat count of 1).
	3			Unused in this application
	4-5			Sample Frequency
	6-7			Unused in this application
	8-9			Length of the data to be played back
	10-nnnn		Sound data, in byte format

Several things should be noted:
	* pump_sound() takes COMPLETE CONTROL of the machine.  Interrupts are
disabled, the system clock will lose time during playback, etc.  (This is
also why we don't use the 'repeat forever' value in the repeat count, since
to do so would send the system away forever, and never come back).
	* pump_sound() disables keyclicks and any other sounds that are happening
through the three sound registers, and takes complete control of them.
	* pump_sound() assumes a specific set of hardware locations for the
sound chip.  As of this writing, all Atari ST's conform to this location,
but it _could change in the future_.

Given all the above, it's actually trivially easy to use pump_sound-->all
you do is load in the appropriate sound file, and then pass the address
of the start of that file to pump_sound.  The routine takes care of the
rest.  For an example of how to use pump_sound, see GIA.C, which is, itself,
a pretty simple program.