Related Info: Sound Manager Device Manager

Sounding Off with MS QuickBasic

By Ron Butcher, Libertyville, IL

Playing Digitized Sounds with MS QuickBasic

[Ron Butcher bought his first computer in November of 1984; luckily, it was a Macintosh. He first learned BASIC on a DEC minicomputer at DeSoto, Inc., where he works as an Industrial Chemist. He discovered programming on the Mac with MS Basic 1.0 in December of 1984.]

There have been many occasions when I wished I could use digitized sounds instead of Basic’s SOUND statements for enhancing programs I was writing. Judging from questions seen in magazines and on BBS’s from other Basic programmers, I guess I wasn’t alone. As I have a game written in Basic that could benefit greatly from sound effects, I decided to look into this further. This lead me to some heavy reading in Inside Macintosh.

Well yes, you can play digitized sounds from Basic, using the free form synthesizer in the Mac, and very handy Library routines implemented in QuickBasic. These routines allows you to implement Operating System ROM traps which return information in a Parameter Block. Many of these functions are used by the File Manager and Device Manager, such as _Open, _Close, _Read, _Write, etc. I suggest you beg or borrow (don’t steal) a copy of Inside Mac so you can follow some of this background information.

Sound Background

To play digitized sounds, we need to utilize the Free-Form Synthesizer. Inside Mac’s Pascal structure looks like this:

            
Type FFSynthRec = RECORD
 mode:   INTEGER; {always ffMode}
 count:  Fixed;{“sizing” factor}
 waveBytes:   FreeWave{waveform description}
 END;

 FFSynthPtr = ^FFSynthRec;

 FreeWave= PACKED ARRAY OF Byte;

Let’s translate this for our use with QuickBasic. We need to allocate a block of memory for the size of the sound involved, and save the first 6 bytes of this block for the mode (integer ffmode, which is always 0 for the free form synthesizer), and count (fixed point, which is how we tell the sound driver at what “speed” to play the sound). Inside Mac also tells us that we can play a free-form sound by making a Device Manager Write call with the following parameters: ioRefNum must be -4 (the Sound Driver), ioBuffer must point to the synthesizer buffer, and ioReqCount must contain the length of the synthesizer buffer. The sound data needs to be read into the buffer, the mode and count entered as the first six bytes, and that buffer (FFsynthRec) is then written to the Sound Driver.

The count constants, being fixed point, threw me a curve. When count is equal to 1, the “sizing factor” is 1, and sounds are played at the 22KHz sampling rate. But how to get .5 (11Khz), .33 (7.4Khz), and .25 (5.5Khz) presented a minor challenge. Fixed point numbers on the Mac are 32 bits long. The high word is the integer, and the low word the fractional part. The bit representation is shown in Fig. 1. For example, 1.0 would be represented as: 0000000100000000. 1.5 would be represented as: 0000000110000000. From this we get the count& hex values of &H10000 for 1.0, &H8000& for .5, &H5555& for .33, and &H4000 for .25. The actual sample rate is taken from this equation:

frequency (Hz) = 1000000 / (44.93 *  (wavelength / count) )

This is derived from the fact that the sound is created by starting play at the first byte, and skipping ahead count bytes every 44.93 microseconds; so with the smallest wavelength (1 byte) and a count value of 1, the frequency works out to 22,256.8 Hz, which is the highest quality sampling rate of most sound digitizing software.

Figure 1. Fixed Point Number Representation

The ToolBox MBLC

The following illustrates the formats for the Operating System (OS) calls needed to be made to implement the SoundPlayer program. The calls we are going to make are register based calls. As a general rule, OS calls are register based, and ToolBox calls are stack based, but there are exceptions on both sides (here I mean Mac ToolBox, not QuickBasic ToolBox calls). You can tell one Trap from another by checking bit 11 of the Trap word. If it is set (1), then it is a Toolbox Trap word; if bit 11 is not set (0), then the call is an OS Trap word. For example, traps starting with A0 are OS traps, and traps starting with A9 are ToolBox traps.

The generic register based QuickBasic call is:

 ToolBox”R”,Trap%,ReturnArray&(0),(a0&),(a1&),(d0&),(d1&),(d2&)

For our calls having values passed to and from a Parameter Block, the call in our program will look like this:

Param&=VARPTR(ParamBlock%(0))
ToolBox “R”,Trap%,Reg&(0),(Param&)

Per Inside Macintosh, after we pass the appropriate values to the Parameter Block, we can make the call with a0 pointing to the address of the Block (Param&). Values are first passed to the appropriate registers (a0&.. etc) and ReturnArray Reg&() will contain the values passed to them after the call is made. Any errors will be returned in d0 (Reg&(2)).To get a pointer to our sound record, I’ve used NewPointer to allocate the blocksize:

NewPtr%=&HA01E
ToolBox “R”,NewPtr%,Reg&(0),,,(Siz&)

The size of the soundrecord is contained in Siz&, and the pointer to the record will be return in a0 (Reg&(0)). To manipulate the sound resources (snd ), I’ve used a slightly different technique. I first use the QuickBasic ToolBox call GetHandleSize to obtain the size of the snd resource. NewPointer is then used to allocate the appropriate soundrecord. To coerce the snd resource Handle to a Pointer, I used BlockMove to transfer the sound information referenced by Handle h& to the block of memory pointed to by NewPointer. I could then release the memory used by the resource and the Handle using ReleaseRes. Note that in actuality, the header bytes of an snd resource contain resource info, including the length of the sound data (this length varies depending on the snd format; format 1 was developed for the Sound Manager, and format 2 is for HyperCard). I’ve ignored these bytes for simplicity’s sake, but you can use them to your advantage in your own program. The program is set up to only open resource files of type SFIL and STAK, but you can expand on this to include other types. The same goes for the sound data files, which I have limited to type FSSD for this program example.

The File and Device Manager Routines

The following formats are for using File Manager _Open, _Close, and GetEOF calls. The --> indicates values to be passed to a routine, the <-- indicates values returned by the routine, and <-> indicates values passed to and from the routine. The Parameter block size required is different for different calls, but the 80 byte array size used in the program is large enough for the calls we’ll be implementing. The parameter block will be stored as an integer array.

   
FUNCTION PBOpen, PBClose, PBGetEOF (paramBlock: ParmBlkPtr; async: BOOLEAN) 
: OSErr;

Trap macro_Open, _Close, _GetEOF
(_Close only uses ioCompletion,ioResult, and ioRefNum)
(_GetEOF additionally uses ioMisc, which returns the logical
 end of file, or filelength) 
Parameter block
 -->  12ioCompletion pointer
 <--  16ioResult word
 -->  18ioNamePtrword
 -->  22ioVRefNumpointer
 -->  24ioRefNum long word
 <--  26ioVersNum  long word
 -->  27ioPermssnword
 <->  28ioMisc   long word

To open a sound data file, we need only to pass the address of the Pascal string of the file pathname (from FILES$ and SADD function) to ioNamePtr, and call the _Open Trap. ioRefNum will be returned at byte 24 of the array. _GetEOF, which requires ioRefNum, can then be called to get the length of the file. You can also set byte 27 to 1 to make the Open call read only, just to be on the safe side. I used the QuickBasic B2PStr call to coerce the Pascal string from the Basic string. You could also use the Pstr$=LEN(Bstr$)+Bstr$ method.

Here’s the format for a File Manager _Read call and Device (or File) Manager _Write call:

FUNCTION PBWrite, PBRead (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;

Trap macro_Write, _Read
 
Parameter block
 -->  12ioCompletion pointer
 <--  16ioResult word
 -->  24ioRefNum word
 -->  32ioBuffer pointer
 -->  36ioReqCount long word
 <--  40ioActCount long word
 -->  44ioPosModeword
 <->  46ioPosOffsetlong word

To read in all the sound file data into the buffer, we now need to give the Parameter block the address of the soundbuffer in ioBuffer, and how many bytes we want read in ioReqCount. Since all reads will be from the beginning of the file, ioPosMode and ioPosOffset are zero. ioRefnum is still the file reference number. When the Write call to the Sound Driver is made, ioRefNum is the Driver’s reference number, -4 (&HFFFC). As we’re set up here, the Write call is synchronous, that is, the program will not continue until the write call is finished. You can make an asynchronous call which allows your program to continue while the sound is being played by polling ioResult. This word returns a positive value while the sound is being played. This way you can limit certain operations of your program through a WHILE-WEND or IF-THEN operation. To make an asynchronous call, set bit 10 of the trap word; this would make the _Write trap &HA403, for example. I’ve found the asynchronous calls to be fairly touchy when being implemented from Basic. You can use _KillIO to stop any current sound being played and cancel every pending asynchronous call.

Bells and Whistles

The subroutine “Drawgraph” allows you to graphically illustrate the sound wave that has been opened for play. As byte values go, &H80 (128 decimal) represents 0 amplitude, while &HFF (255 decimal) represents 100% positive amplitude, and 0 represents 100% negative amplitude (See fig. 2). The routine takes a y axis sample every ScreenWidth\filelength bytes in order to have an even sampling over the width of the screen. Since the y values will be drawn down with respect to the screen coordinates, I implemented a simple inversion routine so the plot could be viewed right side up with respect to the actual wave. Although compressed, the graph that is drawn gives a decent visual representation of the sounds actual waveform, such as that which might be seen on an oscilloscope in real time.

Figure 2.

Thanks for the Memory

The main problem I ran into when setting up this program was finding an efficient way of allocating memory for the sound record, FFSynthRec. For a sound call, the memory block should ideally be locked until the sound call is finished, and then disposed of to free up the memory in the heap. I used one of QuickBasic’s new features, the ToolBox calls, to use the NewPointer function to grab a non-relocatable block of memory to hold the sound record. In my initial version of the program, I used an array to hold the sound record. This works, but really slows things down a lot. The most efficient use of the array would be to dimension a dynamic array only to the size needed as dictated by size of the sound file and erase it after use. It is best to have a static array for the sound record, because some pretty weird things happen if that array shifts around in memory while being written to the Sound Driver. Ah, there’s the rub.... you can’t use static arrays in the interpreter, and if you use them in the compiler, you can’t erase and resize them.

I’ve left a few items off of the program that may be implemented later, such as sound file decompression, and the ability to save sound resources as data, and visa-versa. Compressed sound data files have the header “HCOM”, and I’ve flagged this condition with a BEEP sound, as I haven’t figured out the decompression algorithm yet. Error handling is also at a minimum. For the ToolBox calls, Reg&(2) returns the error code, which is 0 for no error. The OS errors returned can be many and varied, so you may want to show the error number in an Alert and stop the program. When compiling the program, check the “Make all arrays Static” and “Process Runtime Events” box. You can uncheck the boxes for “Use Default Menu” and “Use Default Window”.

Being able to use the File Manager calls has other advantages which enable you to manipulate files in ways you can’t do with normal BASIC commands such as INPUT, OUTPUT, WRITE, etc. Using the ToolBox calls, I’ve been able implement MacBinary in a telecom program, and write a disk cataloging utility, for example. Hopefully this program will shed some light on using the sound driver from BASIC, and give you some ideas on how to use digitized sound in some of your own applications.

‘ SoundPlayer
‘ Plays digitized sounds from snd resources
‘ and sound data files using
‘ MicroSoft QuickBasic 1.0
‘ 2/26/1989

CLEAR, 100000&
DIM Paramblock%(39),scr%(3),bar%(3),pt%(2),r%(3)
DIM PHS$(200),id%(200)
DIM a&(5)
‘ Trap calls
RITE%=&HA003:Ohpen%=&HA000
Dread%=&HA002:Klose%=&HA001:GetEOF%=&HA011
NewPtr%=&HA01E : DisposePtr%=&HA01F
‘Initialize variables and constants
FFsynthPtr&=0:Param&=0:Siz&=0:h&=0:S&=0:ResH&=0
oldbut%=0:butnum%=0:Tag&=0:state%=0
x0%=0:y0%=0:y%=0:x%=0
true%=-1:false%=0:GotPointer%=false%:er%=0:
MenuItem%=0:MenuChoice%=0
ForkOpen%=false%:gotresource%=false%
num%=2:num1%=0:ref%=0:id%=0:action%=0
type$=”snd “:nam$=””:F$=””:G$=””:pic$=””
lfd&=0:I=0:count&=0:resid%=0
TwentyTwoK&=&H10000& ‘ count values
ElevenK&=&H8000&
SevenK&=&H5555&
FiveK&=&H4000&
ToolBox “i”
WINDOW CLOSE 1
MENU 1,0,1,”File”
MENU 1,1,1,”Open Sound Data”
MENU 1,2,1,”Open Sound Resource”
MENU 1,3,0,”Draw Sound Graph”
MENU 1,4,1,”Quit”
CmdKey 1,1,”D”
CmdKey 1,2,”R”
CmdKey 1,3,”G”
CmdKey 1,4,”Q”
Sheight=SYSTEM(6)
Swidth=SYSTEM(5)
WINDOW 2,””,(50,100)-(Swidth-32,Sheight-77),3
BUTTON 1,1,”22 KHz”,(25,25)-(100,40),3
BUTTON 2,2,”11 KHz”,(25,60)-(100,75),3
BUTTON 3,1,”7.4 KHz”,(25,95)-(100,110),3
BUTTON 4,1,”5.5 KHz”,(25,130)-(100,145),3
BUTTON 5,0,”Play”,(130,75)-(190,100)
SetRect scr%(0),200,6,400,158
SetRect bar%(0),399,6,415,158
r%(0)=75
r%(1)=130
r%(2)=100
r%(3)=190
inSetRect r%(0),-4,-4
oldbut%=2:count&=ElevenK&
linenum%=0:top%=0:S&=0:in%=0
NewScroll S&,bar%(0),1,1,1,1
InactiveScroll S&
PICTURE ON
PENSIZE 3,3
FRAMEROUNDRECT VARPTR(r%(0)),16,16
PENNORMAL
ERASERECT VARPTR(scr%(0))
FRAMERECT VARPTR(scr%(0))
PICTURE OFF
pic$=PICTURE$
PICTURE ON : PICTURE OFF
refresh

ON MENU GOSUB MenSelect : MENU ON
ON DIALOG GOSUB ChoiceWait : DIALOG ON

UserWait:
WHILE true%
 hittest
 ScrollText S&,scr%(0),PHS$(1),top%,num1%,linenum%,3
WEND

ChoiceWait:
MENU STOP : MOUSE STOP
action%=DIALOG(0)
IF action%=5 THEN CALL refresh
IF action%<>1 THEN
  MENU ON : MOUSE ON
  RETURN
END IF
ON action% GOSUB HandleButton
MENU ON : MOUSE ON
RETURN

HandleButton:
butnum%=DIALOG(1)
IF butnum%=oldbut% THEN RETURN
IF butnum% <> 5 THEN
  BUTTON butnum%,2
  BUTTON oldbut%,1
  oldbut%=butnum%
END IF
SELECT CASE butnum%
  CASE 1
    count&=TwentyTwoK&
  CASE 2
    count&=ElevenK&
  CASE 3
    count&=SevenK&
  CASE 4
    count&=FiveK&
  CASE 5
    GOSUB writefork
END SELECT
RETURN

openDataFile:
F$=FILES$(1,”FSSD”):IF F$=”” THEN RETURN
BUTTON 5,0
gotresource% = false%
IF ForkOpen% THEN
    GOSUB CleanItUp
    ForkOpen%=false%
END IF
PtrTest
GOSUB ReadFork
Tag&=PEEKL(FFsynthPtr&+6) ‘“HCOM”
IF Tag&=1212370765& THEN BEEP:RETURN ‘compressed
BUTTON 5,1
RETURN

openResFile:
F$=FILES$(1,”SFILSTAK”):IF F$=”” THEN RETURN
BUTTON 5,0
PtrTest
in%=0:top%=0:linenum%=0:resid%=0
GOSUB CountResources
GOSUB ClearBuffer
RETURN

Quit:
IF ForkOpen% THEN GOSUB CleanItUp
PtrTest
DisposeScroll S&
WINDOW CLOSE 2
END

MenSelect:
MenuItem%=MENU(0)
IF MenuItem% <>1 THEN RETURN
MenuChoice%=MENU(1)
MENU
ON MenuChoice% GOSUB openDataFile,openResFile,Drawgraph,Quit
RETURN

writefork:
IF gotresource% THEN GOSUB LoadResource
POKEW FFsynthPtr&,0 ‘0 for ffmode
POKEL FFsynthPtr&+2,count& ‘sizing value
Param&=VARPTR(Paramblock%(0))
POKE Param&+27,0       ‘reset permission
POKEW Param&+24,&HFFFC ‘Sound Driver refnum
POKEL Param&+36,lfd&   ‘length to write
POKEW Param&+44,0      ‘ioPosMode
POKEL Param&+46,0      ‘ioPosOffSet
POKEL Param&+32,FFsynthPtr& ‘address of synthrec
ToolBox “R”,RITE%,Reg&(0),(Param&) ‘ call _Write
RETURN

ReadFork:
GOSUB ClearBuffer
B2PStr F$,G$
Param&=VARPTR(Paramblock%(0))
POKEL Param&+18,SADD(G$) ‘address of filename
POKE Param&+27,1         ‘read only
ToolBox “R”,Ohpen%,Reg&(0),(Param&)  ‘call _Open
ToolBox “R”,GetEOF%,Reg&(0),(Param&) ‘call _GetEOF
Param&=VARPTR(Paramblock%(0))
lfd&=PEEKL(Param&+28) ‘file length
IF lfd& =0 THEN       ‘No data
  ToolBox “R”,Klose%,Reg&(0),(Param&)
  BEEP : RETURN
END IF
Siz&=lfd&+6              ‘6 bytes for mode and count
GOSUB GetPointer
Param&=VARPTR(Paramblock%(0))
POKEL Param&+36,lfd&        ‘number of bytes to read
POKEL Param&+32,FFsynthPtr&+6 ‘block address
POKEW Param&+44,1 ‘ioPosMode read from start of file 
ToolBox “R”,Dread%,Reg&(0),(Param&) ‘call _Read
ToolBox “R”,Klose%,Reg&(0),(Param&) ‘call _Close
RETURN

GetPointer:
‘Get block of Siz& bytes and
‘return address in FFsynthPtr&
ToolBox “R”,NewPtr%,Reg&(0),,,(Siz&) ‘call _NewPointer
GotPointer%=true%
FFsynthPtr&=Reg&(0)
RETURN

LoadResource:
IF resid%=id%(linenum%) THEN RETURN
PtrTest
‘Get the resource
GetRes ref%,type$,id%(linenum%),h&
resid%=id%(linenum%)
HLock h&
GetHandleSize h&,lfd&
Siz&=lfd&
GOSUB GetPointer
‘coerce pointer
ResH&=PEEKL(h&)
BlockMove ResH&,FFsynthPtr&,Siz&
Hunlock h&
ReleaseRes h&
RETURN

CountResources:
IF ForkOpen% THEN GOSUB CleanItUp:ForkOpen%=false%
PtrTest
CountRes type$,num%        ‘number in System
ToolBox “WQ”,&H997,F$,ref% ‘openresfile
ForkOpen%=true%
updateresfile ref%
CountRes type$,num1%
num1%=num1%-num%           ‘number of type snd     
GOSUB GetResources
RETURN

GetResources:
‘set ResLoad to false
POKEW &HA5E,0 ‘comment out for interpreter
FOR ind%=1 TO num1%
  GetIndRes type$,ind%,h&
  GetResInfo h&,id%(ind%),type$,nam$
  ReleaseRes h&
  PHS$(ind%)=nam$+” - “+STR$(id%(ind%))
  NEXT ind%
‘set ResLoad to true
POKEW &HA5E,-1 ‘comment out for interpreter
gotresource%=true%
ActiveScroll S&
RETURN

ClearBuffer:
Param&=VARPTR(Paramblock%(0))
FOR I=0 TO 79: POKE Param&+I,0: NEXT I
RETURN

CleanItUp:
CloseResfile ref%
InactiveScroll S&
in%=0:top%=0:linenum%=0:resid%=0:num1%=0
RETURN

Drawgraph:
DIALOG STOP :MENU OFF
WINDOW 3,””,(0,20)-(Swidth,Sheight),3
MOVETO 0,0
inc=lfd&\Swidth
x0%=0:y0%=0:y%=0:x%=0
FOR I=1 TO lfd& STEP inc
  LINETO x0%,y%
  y%=PEEK(FFsynthPtr&+(I))
  y%=(128-y%)+128 ‘Invert it
  PSET (x%,y%)
  x0%=x%
  x%=x%+1
NEXT I
TEXTFONT 0
MOVETO 180,300
DrawText “Click Mouse to Continue”
TEXTFONT 1
WHILE MOUSE(0)=0:WEND
WINDOW CLOSE 3
WINDOW 2
DIALOG ON:MENU ON
RETURN

SUB hittest STATIC
SHARED scr%(),pt%(),num1%,linenum%,gotresource%
in%=0
IF NOT gotresource% THEN EXIT SUB
IF MOUSE(0)=1 THEN
  GetMouse pt%(1)
  PtInRect pt%(1),scr%(0),in%
    IF in% THEN
      found
    END IF
    IF linenum%<>0 AND linenum%<=num1% THEN
      state%=1 
    ELSE
      state%=0
    END IF
  BUTTON 5,state%
  refresh
END IF
END SUB

SUB found STATIC
SHARED linenum%,num1%,top%,pt%(),scr%()
 linenum%=top%+(pt%(1)-scr%(0))\20
END SUB

SUB refresh STATIC
SHARED scr%(),PHS$(),S&,num1%,linenum%,pic$
PICTURE,pic$
top%=0
ScrollText S&,scr%(0),PHS$(1),top%,num1%,linenum%,3
END SUB

SUB PtrTest STATIC
SHARED GotPointer%,a&(),FFsynthPtr&
DisposePtr%=&HA01F
IF GotPointer% THEN  ‘call _DisposePointer
  CALL ToolBox(“R”,DisposePtr%,Reg&(0),(FFsynthPtr&))
  GotPointer%=0
END IF
END SUB

My thanks to Jim Reekes, whose Sound Manager document cleared up a lot of muddy mental audio, and to Michelle and all the helpful MicroSoft folks on the GEnie MicroSoft Roundtable, who steered me in the right direction with some of the ToolBox syntax.