So What Techncial Notes
#10
Call Box
Using Sound in your BASIC Applications
Written by: William Stephens - February 24,1990
This technical note describes how to add Sound Manager and ACE (Audio Compression and Expansion) tool calls to your Call Box BASIC Applications.
Care and feeding
Edit the CB.TOOL.LIST
(see tech note #1) file in the SYSTEM/TOOLS subdirectory of your boot volume.
Load or
(import) the file into your word processor or text edit software and copy the lines for Sound Manager and ACE and insert them just below the Dialog Manager in the tool list ... save the CB.TOOL.LIST file back to the subdirectory.
(make sure it's still has filetype TXT)
If you are running Call Box BASIC on disk then the file SYSTEM/START will install the ACE tools, if your on a hard drive and are not using HyperLaunch V3.0.2 as the launching program then you will have to launch the file CB.PreLaunch prior to launching into Call Box BASIC
(usually once ACE gets put in it stays in) ... however, this is not guaranteed, when the system reverts to GS/OS again this tool is marked as purge able and a subsequent applications memory allocation process may wipe the tools code out!
Going back to Call Box BASIC and using ACE again will probably do something screwy ... or destructive!!!be careful, if your not sure launch the file CB.PreLaunch again.
This is not a concern on a bootable 3.5 inch disk but you must copy the tool TOOL.029 to your disks SYSTEM/TOOLS subdirectory, it is not put in by the default initialization.
You can also alter your disk initialization installer script to include this tool as well.
Programming with sound
The sound calls are very simple, but the 2.0 version of SoDOS is limited to 256 block files.
(No trees as of yet)
This is where ACE comes in handy as well as saving disk space for those of you who do not have the benefit of a hard drive.
Both Sound Manager and ACE require a direct page,
(that's 2 pages) and waveforms should never be loaded in bank zero for obvious space reasons so you will need GSOS calls to load in your waveforms
(use tech note #6).
When your program does its environment initialization you should do 2 "Allocate and Clear a Direct Page" gosub's to get these pages, save the returned variable Dl as SO for the first page and AC for the second. Next you should GOSUB 56000 in the GS/OS code to setup the GS/OS call block.
Now it's time to start these guys up:
CALL LC,SO\$0208\: REM SoundStartup
CALL LC,AC\$0210\: REM Startup ACE
The next thing you need to do is allocate a block of memory for your sound parameter block ... for this explanation we will use only 1. Each parameter block is 18 bytes long, to allocate a memory block for it go sub "Allocate a block of memory" and zero it out:
L = 18 : GOSUB 45000 : H1 = H: P1 = P :
FOR A = 0 TO 17 : CALL PO,1,0 + A + P1,0 : NEXT
Now you need to load in your sound file. Put the files pathname in the variable A$ then GOSUB "Load a file into memory GS/OS Class 1" .
A$ = "{sound file pathname}" : GOSUB 50000 : H2 = H : P2 = P : L2 = L
Even with the file closed you still have the open file infonnation in the as/os caller block, so check the Aux type for the freqOffset.
This is not a recommended practice by Apple Computer Inc. but is the way many waveforms are annotated.
The shareware program ACERS by Joe Jaworski uses this type of annotation.
CALL PE,2,16 + D2,PB : IF PB > 32767 THEN PB = PB - 32768
You can now check the filetype and see if it's an ACEd file or not: (filetype $CD = ACEd sound file ).
CALL PE,2,14 + D2,A : IF A = 205 THEN (goto ACE routine)
The last piece of overhead you must take care of before playing your sound is the setting up the sound parameter block. The toolbox reference specifies this parameter block as follows:
-----------------------
+0 | | Starting address of wave
|-- waveStart --|
| |
-----------------------
+4 | waveSize | Waveform size in pages
-----------------------
+6 | freqOffset | Output sample rate
-----------------------
+8 | DOCBuffer | DOC buffer start address
-----------------------
+10 | BufferSize | DOC buffer size
-----------------------
+12 | | Start of next wave parameter block
|-- nextWavePtr --|
| |
-----------------------
+16 | volSetting | DOC volume setting
-----------------------
You need only supply the waveStart (P), the wavesize, the freqOffset (PS), and the volSetting (0 - 255).
All other parameters should be zero.
CALL PO,4,P2,P : CALL PO,2,4 + P1,0 + L2/256 : CALL PO,2,6 + P1,PS :
CALL PO,2,16 + P1,255
Any time after this you can play your sound by issuing the following line:
CALL LC,$0401,_P1\$OE08\: REM FFStartSound
Refer to the Apple IIgs Tool Box reference manual for the flags and other subtle nuances of the Sound Manager routines. Your sound file will play while your Applesoft program continue to execute. If you want program execution to stop while the sound is playing add the following lines after the FFStartSound line:
CALL LC,0,4\$1408\F: REM FFSoundDoneStatus
IF F = 0 THEN {GOTO the FFSoundDoneStatus line}
CALL LC,16\$OF08\: REM FFStopSound
The ACE Routine
ACE has 2 compression styles expressed as ratios ... 8:4 or 8:3. 8:4 means that the compressed waveform stored as a file is 1/2 the size of the same waveform uncompressed, and the 8:3 means that the stored file is 3/8 the size of its uncompressed size.
When you load in a compressed sound file you need to get its size and allocate another block either 2 (the reciprocal of.5 or 1/2) times the size of the compressed file for 8:4 or 2.6667 (the reciprocal of .375 or 3/8) times the compressed size for 8:3.
You can usually tell if a file is in 8:4 or 8:3 style by checking the files AuxType and see if it's greater than 32767, If it is then the file is usually compressed in 8:3 style, if it's not then it's 8:4.
Allocate the expanded sound file memory block as follows:
L = 2 * L : F = 1 : CALL PE,2,16 + D2,A : IF A > 32767 THEN L = (L / 2) *
2.6667 : F = 2
GOSUB 45000 : H3 = H : P3 = P : L3 = L : L = L3 / 512
It's now time to expand the sound file in the first memory block to the new memory block
(this can take a while depending on the size of the original sound file):
CALL LC,_H2,_0,_H3,_0,L,F\$0A1D\ " REM ACEExpand
Now dispose of the first memory block:
CALL LC,_H2\$1002\ : REM DisposeHandle
And setup the sound parameter block:
CALL PO,4,P1,P3 : CALL PO,2,4 + P1,0 + L3/256 : CALL PO,2,6 + P1,A CALLPO,2,16 + P1,255
Finally goto the FFStartSound line to play the sound file.
Remember your Memory ...
YOU MUST BE VIGILANT! When you use these procedures you must dispose of the H2 or H3 blocks accordingly before you reuse these routines from within the same application.
Failure to do this will cause the IIgs to accumulate uncompressed sound files in memory which takes up "Lots'" of room!!!
Sometimes this is exactly what you want to do.
Remember to keep a record of all the allocated blocks handles and pointers for disposal or access later on because H2 and H3 are overwritten each time a sound file is loaded.
Example Code:
This page presents actual Applesoft program lines which you can copy into your programs. There are 3 Sound Manager and ACE routines, The load sound routine needs the GS/OS code presented in tech note #6. The variables ID,Dl,D2,DT,SO,AC,A,PB,F,H,Hl,H2,H2,P,Pl,P2,P3,L,Ll,L2 and L3 are used by these routines.
H-H3 = Memory block handle L-L3 = Block size P-P3 = Memory block address ill = special user LD. number Dl = Direct page address.
Load/Uncompress sound file: (in = A$, out = H,H2,H3,P,P2,P3,L,L2,L3,ID)
Play Sound: (in = , out = )
Play Sound exclusive: (in = , out = )
39999 REM
Load/uncompress sound file
40000 GOSUB 50000 : H2 = H : P2 = P : L2 = L
40010 CALL PE,2,16 + 02,PB : IF PB > 32767 THEN PB = PB - 32768
40020 CALL PE,2,14 + 02,A : IF A = 205 THEN 40040
40030 CALL P0,4,P1,P : CALL PO,2,4 + P1,O + L2 / 256 : CALL PO,2,6 + P1,PB CALL PO,2,16 + P1 ,255: RETURN
40040 L = 2 * L : F = 1 : CALL PE,2,16 + 02,PB : IF PB > 32767 THEN L = (L / 2) *
2.6667 : F = 2 : PB = PB - 32768
40050 GOSUB 45000 : H3 = H : P3 = P : L3 = L : L = L3 / 512
40060 CALL LC,_H2,_0,_H3,_0,L,F\$0A1D\ : CALL LC,_H2\$1002\ : CALL PO,4,P1,P3 :
CALL PO,2,4 + P1,0 + L3 / 256 : CALL PO,2,6 + P1,PB : CALL PO,2,16 + P1,255
: RETURN
40099 REM
Play sound
40100 CALL LC,0,4\$1408\F : IF F = 0 THEN 40100
40110 CALL LC,16\$0F08\ : CALL LC,$0401,_P1\$0E08\ : RETURN
40199 REM
Play sound (exclusive)
40200 CALL LC,$0401,_P1\$0E08\
40210 CALL LC,0,4\$1408\F: IF F = 0 THEN 40210
40220 CALL LC,16\$0F08\: RETURN
56099 REM
Sound / ACE setup
56100 DT = D1 : GOSUB 45030 : SO = D1 : GOSUB 45030 : AC = D1 : D1 = DT : CALL LC,SO\
$0208\ : CALL LC,AC\$021D\
56110 L = 18 : GOSUB 45000 : H1 = H : P1 = P : FOR A = 0 TO 17 : CALL PO,1,0 + A + P1, 0 : NEXT: RETURN
Further Reference
Apple IIgs Toolbox Reference: Volume(s) 1,2 and 3 Call Box BASIC Manual V2.0
Tech Notes 2, 4 and 6
Call Box - So What Software 10221 Slater Ave. Suite 103 Fountain Valley, CA. 92708