~ ~ ====================================================================== ~ BASIC INTERFACE SONIX for the Apple IIgs ~ ====================================================================== ~ ~ INTRODUCTION ~ ------------ ~ The Basic Interface part of SONIX gives you complete control of what ~ X sounds your IIgs' Ensoniq synthesizer chip makes--and why. There are ~ 5 Call commands that you use in your Basic programs to load waveform ~ files (thus selecting the "voices" your program can use)& select ~ which of the IIgs' 30 oscillators is to sound& select pitch and vol- ~ ume of sounds& and so on. To use the Call commands& you POKE values ~ into specific memory addresses and then issue a CALL command in your ~ program--SONIX takes care of all the details. ~ ~ We've designed SONIX's Basic Interface with 2 frames of reference. ~ On one hand& there are simple programming techniques that you can use ~ to keep your code short and uncomplicated. Of course& the price to ~ be paid for keeping your code simple is that you have to give up a ~ little of the control you have over some of the real nuances of pro- ~ ducing sound from a IIgs. In almost every case& though& the only real ~ difference would be noted in a VERY complex Basic program...one that ~ would probably be tackled by a quite experienced code writer. On the ~ other hand& for those who want to be able to control virtually every ~ bit and byte in their machines& SONIX's Basic Interface can give as ~ much flexibility for locating files and data in memory as is needed ~ for absolute control. ~ ~ ~ BASIC INTERFACE CALLS ~ --------------------- ~ X The easiest way to explain how to use the Basic Interface in your ~ programs is to describe the 5 Calls& which fall into 2 categories% ~ (1) how you get waveform file data into the IIgs' Sound RAM (the ~ special 64K memory bank that Apple designed to handle waveforms)& and ~ (2) how you control the sounds the waveforms make. Let's go over the ~ "loading waveforms into the Sound RAM" part first. ~ ~ ~ LOADING FROM DISK [ CALL DI Hex = $960C Decimal = 38412 ] ~ --------------------------------------------------------------- ~ A waveform file resides primarily on disk; SONIX's Waveform Editor ~ saves waveform files to disk with the suffix ".SWF"& for instance. ~ To get the waveform file from disk into the Sound RAM& you define ~ some pieces of information in a single "string descriptor" and CALL ~ the loading routine. ~ ~ The "string descriptor" specifies 6 things% ~ ~ * That something is to be loaded... ~ ~ * What the waveform file's pathname (on disk) is... ~ ~ * Where in the Sound Buffer it's to be loaded... ~ ~ * Where the waveform's semitone table is to be located... ~ ~ X * Where in the Sound RAM the waveform is to be located...and... ~ ~ * Which oscillator is to use the waveform. ~ ~ ~ So What Software E-1 1-JUN-88 ~ ~ ~ ~ ====================================================================== ~ BASIC INTERFACE SONIX for the Apple IIgs ~ ====================================================================== ~ ~ Sound complicated? It really isn't. Remember& the IIgs' Sound RAM ~ memory is only 64K bytes in size. Now& that memory only has to hold ~ X the waveform data (so the oscillators can use it to produce sound)... ~ and the Sound RAM has to be loaded carefully& because it's got to ~ hold ALL the waveform data you want to use while a program is run- ~ ning. BUT...there's a complication% the Sound RAM isn't accessible ~ in the same way that "regular" RAM (that is& one of the 64K byte ~ banks of memory on your IIgs' memory card) is& so you can't just load ~ a waveform file from disk directly into the Sound RAM. ~ ~ The way we've set SONIX up to work is to let you select a bank of ~ "regular" RAM as a "holding area"--that is& a Sound Buffer--for get- ~ ting waveform data organized. (We usually use Bank 4.) Then& when ~ your program makes the DISK Call& the waveform data are moved quickly ~ into the Sound RAM. ~ ___________________________________________________ ~ ~ By the way....We use 2-letter variables for SONIX Calls; "DI" is ~ typical. If you need a refresher on how and when you "declare" varia- ~ bles this way& please refer to p. D-2 of the Note Engine instruc- ~ tions. The true hex and decimal addresses for each of the Calls are ~ shown in square brackets at the beginning of each Call's description. ~ __________________________________________________ ~ ~ This example of code would load a waveform named VOICE& in a subdirec- ~ tory called SOUNDS on a disk named /WAVES/& into the Sound RAM and ~ ready Oscillator 2% ~ X ~ 10 SG$ = "LS&/WAVES/SOUNDS/VOICE&A$042000&S$042000&R$0000&O$02&" ~ ~ 20 CALL DI ~ ~ What this code does is to identify the waveform's on-disk location by ~ specifying its COMPLETE pathname& load the waveform into Bank 4 at ~ address $2000& then identify the waveform's semitone table as being ~ at the same address (that'll be explained in a moment). The address ~ in the Sound RAM to put the waveform file is specified as the begin- ~ ning of the Sound RAM's 64K space& and the parameters for using Oscil- ~ lator 2 are identified (these are explained in an upcoming section). ~ The CALL DI command makes it happen. ~ ~ Semitone tables are short& since they only have to specify informa- ~ tion about 96 notes& and they are ALWAYS at the beginning of a com- ~ plete waveform file. The waveform data are much more extensive& ~ often 32K bytes long. The DISK Call takes care of copying the wave- ~ form into the Sound RAM& and it leaves the ENTIRE waveform file where ~ it was loaded into the Sound Buffer. So& the semitone table for the ~ waveform just moved into the Sound RAM is still at the "regular" ~ memory address where the waveform file was loaded. This is important ~ information needed by the Calls that control oscillator parameters. ~ ~ If you plan to load several different waveforms from disk& you need ~ to be careful that loading a second one doesn't overwrite the begin- ~ X ning of the previous one in the Sound Buffer. You can avoid THAT ~ problem by defining a new Sound Buffer as a place in memory that's far ~ enough away from the previous Sound Buffer to keep the semitone ~ tables from being interfered with. ~ ~ So What Software E-2 1-JUN-88 ~ ~ ~ ~ ====================================================================== ~ BASIC INTERFACE SONIX for the Apple IIgs ~ ====================================================================== ~ ~ Now& if you do load another waveform& the other thing you've got to ~ watch for is the length of the waveform(s) you've already loaded into ~ X the Sound RAM& so that you don't load one over another that's already ~ in place. In the example above& we used the very beginning of the ~ Sound RAM (address $0000) because this was the first waveform to be ~ loaded. If the VOICE waveform were& say& 2048 bytes long& then the ~ next waveform to be loaded would need to have a Sound RAM address ~ specified at least as high as $0800. (Because VOICES took up the ~ first 2048 bytes of Sound RAM space& from $0000 to $07FF.) ~ ~ Here's a formal layout of the string descriptor for the DISK Call% ~ ~ +--- Load sound command ~ | +-- ProDOS pathname ~ | | +---- Load addr. ~ | | | +-- Semitone table addr. ~ | | | | +--- Sound RAM addr. ~ | | | | | +-- Oscillator ~ | | | | | | number ~ ~ SG$ = "LS&/FULL/PATHNAME&A$012345&S$6789AB&R$CDEF&O$00&" ~ ~ ~ ~ LOADING FROM MEMORY [ CALL RA Hex = $9600 Decimal = 38400 ] ~ ----------------------------------------------------------------- ~ Once a waveform file with its semitone table is in "regular" memory ~ X somewhere& you can use the Basic Interface's other Sound RAM-loading ~ Call to copy the waveform into the Sound RAM. As you've gathered ~ from the discussion of the DISK Call& there are some pieces of data ~ that will need to be specified before a waveform goes into the Sound ~ RAM% the Sound RAM address& the memory addresses of the waveform and ~ its semitone table& and the oscillator number. That's done by POKE- ~ ing values into certain memory locations& which the Basic Interface ~ identifies as these 4 variables% ~ ~ SR $961E 38430 Sound RAM address (low& high) ~ ~ WF $9620 38432 SONIX waveform file address (low& high& bank) ~ ~ SM $9623 38435 Semitone table address (low& high& bank) ~ ~ OS $962D 38445 Oscillator number (0 to 29) ~ ~ Here's an example% ~ ~ 10 POKE SR&0 % POKE SR+1&96 % POKE WF&0 % POKE WF+1&32 % POKE ~ WF+2&4 % POKE SM&0 % POKE SM+1&32 % POKE SM+2&4 % POKE OS&0 ~ ~ 20 CALL RA ~ ~ ~ Notice that 3 of the 4 variables call for multiple POKEs. POKE-ing a ~ X bank number for an oscillator is no big deal; just use the decimal ~ value. ~ ~ ~ So What Software E-3 1-JUN-88 ~ ~ ~ ~ ~ ====================================================================== ~ BASIC INTERFACE SONIX for the Apple IIgs ~ ====================================================================== ~ ~ The "low / high" terminology& though& refers to fact that POKE values ~ in Applesoft Basic can't be any bigger that 255 (decimal). BUT...in ~ this Call (and several others in the Basic Interface)& you need to be ~ X able to POKE a value as high as 65535& since that's the upper limit ~ of a memory bank's address space. So& the SONIX Basic Interface POKEs ~ that are for BIG numbers are done in 2 pieces. ~ ~ The second piece& the high byte& is the number of WHOLE multiples of ~ 256 the desired POKE value has...and the first piece& the low byte& ~ is simply the remainder. ~ ~ Example% To POKE in a value of 25000 for a waveform file address& ~ divide 25000 by 256 (97.6) and round it down to the number of WHOLE ~ multiples of 256 in 25000& 97. Now& convert those 97 multiples of 256 ~ to a real decimal number (97 x 256 = 24832) and subtract that value ~ from 25000 (25000 - 24832 = 168); 168 is the low byte. The POKEs them ~ selves are& then % POKE WF&168% POKE WF+1&97 ~ ~ NOTE% For some rather detailed reasons that needn't be discussed now& ~ the LOW byte of a Sound RAM address POKE is always 0. ~ ~ ~ Here's an example of code that takes waveform file data from memory ~ address 8192 in Bank 4 and puts it into the Sound RAM at address ~ 24576 for Oscillator 7 to use% ~ ~ 10 POKE SR&0 % POKE SR+1&96 {Pokes the value 0 + 96 x 256 = 24576} ~ X ~ 20 POKE WF&0 % POKE WF+1&32 % POKE WF+2&4 {Pokes 32 x 256 = 8192} ~ ~ 30 POKE SM&0 % POKE SM+1&32 % POKE SM+2&4 {Pokes 8192} ~ ~ 40 POKE OS&7 % CALL RA ~ ~ ~ CONTROLLING OSCILLATOR PARAMETERS ~ --------------------------------- ~ There are 7 parameters that specify and control the performance of ~ the IIgs' 30 oscillators% oscillator number& pitch& volume& resolu- ~ tion& mode& waveform length& and Sound RAM address. SONIX's Basic ~ Interface gives you 3 different Calls for setting oscillator parame- ~ ters& with increasing levels of detail. The easiest to use is the ~ AUTO Call& then the SEMI Call& and the ROOT Call gives most control. ~ ~ AUTO CALL [ CALL AO Hex = $9609 Decimal = 38409 ] ~ ------------------------------------------------------ ~ This routine controls the parameters for a specified oscillator. The ~ only data needed are the oscillator number and pitch. The AUTO Call ~ retrieves all parameter and semitone information automatically from ~ the locations that were identified by either the DISK Call or the RAM ~ Call when the waveform data were copied into the Sound RAM. ~ ~ PT $9632 38444 Pitch (0 to 95) ~ X ~ OS $9633 38445 Oscillator number (0 to 29) ~ ~ ~ So What Software E-4 1-JUN-88 ~ ~ ~ ~ ~ ====================================================================== ~ BASIC INTERFACE SONIX for the Apple IIgs ~ ====================================================================== ~ ~ Example% ~ 10 POKE PT&36 % POKE OS&1A % CALL AO ~ X ~ This causes Oscillator 10 to sound the 4th octave's C-natural in the ~ waveform previously set for it (if the waveform was tuned accurately ~ ...see Section B for a discussion of this). ~ ~ ~ SEMI CALL [ CALL SE Hex = $9603 Decimal = 38403 ] ~ --------------------------------------------------------- ~ This routine controls the parameters for a specified oscillator and ~ lets you specify volume& pitch& resolution& and mode. The Sound RAM ~ address and semitone table address must be the same as set by a prev- ~ ious RAM or DISK Call. ~ ~ VO $9629 38441 Volume (0 to 255) ~ ~ PT $962C 38444 Pitch (0 to 95) ~ ~ RE $962B 38443 Resolution (0 to 7) ~ ~ MO $962A 38442 Mode (Free Run% 0&1 ; One Shot% 2&3) ~ ~ ~ Example% ~ ~ 10 POKE VO&40 % POKE PT&24 % POKE RE&7 % POKE MO&2 % CALL SE ~ X ~ ~ ROOT CALL [ CALL RO Hex = $9606 Decimal = 38406 ] ~ --------------------------------------------------------- ~ This routine controls the parameters for a specified oscillator& ~ letting you specify all of the parameters for each Call. The pitch ~ becomes a two byte number (0 to 65535). A ROOT Call uses its own ~ buffer for data values& not the buffer used by the SEMI and AUTO ~ Calls. ~ ~ S0 $9772 38770 Pitch (low byte) ~ S1 $9779 38777 Pitch (high byte) ~ S2 $9780 38784 Volume (0 to 255) ~ S3 $9787 38791 Sound RAM address (high byte only) ~ S4 $97BC 38844 Waveform length (coded number; see note) ~ S5 $978E 38798 Resolution (0 to 7) ~ S6 $9798 38808 Mode (Free Run% 0&1 ; One Shot% 2&3) ~ S7 $979A 38810 Oscillator number (0 to 29) ~ ~ NOTE% Waveform length is handled in a "lookup table" format; ~ details are in the Waveform Length Address section. ~ ~ Example% ~ ~ 10 POKE S0&0 % POKE S1&30 % POKE S2&128 % POKE S3&0 % POKE S4&7% ~ POKE S5&7 % POKE S6&2 % POKE S7&0 % CALL RO ~ X ~ ~ ~ ~ So What Software E-5 1-JUN-88 ~ ~ ~ ~ ~ ====================================================================== ~ BASIC INTERFACE SONIX for the Apple IIgs ~ ====================================================================== ~ ~ ADDRESS NOMENCLATURE ~ -------------------- ~ X There are 10 memory addresses that are important to effective use of ~ the SONIX Basic Interface's Calls. Some have been described in some ~ detail in the foregoing Call explanations& while others have only ~ been mentioned briefly. A more complete description of each follows. ~ ~ ~ SOUND RAM ADDRESS [ Hex Address = $961E Decimal Address = 38430 ] ~ -------------------------------------------------------------------- ~ This data location is the starting address in the special Sound RAM ~ where your waveform pattern exists. The address must be page aligned ~ (that is& the low order byte must always be zero). This address is ~ automatically inserted when an AUTO Call is made& but it must be sup- ~ plied by the user for SEMI and RAM Calls. The DISK Call creates this ~ address with the string descriptor segment "S$XXXX". ~ ~ ~ SOURCE ADDRESS [ Hex Address = $9620 Decimal Address = 38432 ] ~ ----------------------------------------------------------------- ~ This data location is the loading address for a SONIX waveform file. ~ This is a 3-byte address in this form% BANK& HIGH BYTE& LOW BYTE. ~ The DISK and RAM Calls need this information as part of the data ~ necessary to set up the DOC and Sound RAM. The RAM Call will need ~ the bytes POKE-ed in separately& while the DISK Call gets the address ~ from the string descriptor segment "A$XXXXXX". ~ ~ X ~ SEMITONE TABLE ADDRESS [Hex Address = $9623 Decimal Address = 38435 ] ~ ---------------------------------------------------------------------- ~ This data location is the address where the semitone table and oscil- ~ lator parameters for a specific waveform exist. This address is in ~ 3-byte format (BANK& HIGH BYTE& LOW BYTE)& and it is usually the same ~ as the Source Address. The Semitone Table Address needs to be sup- ~ plied to a RAM Call by the user& while a DISK Call gets the informa- ~ tion from the string descriptor segment "S$XXXXXX". ~ ~ ~ WAVEFORM LENGTH [ Hex Address = $9626 Decimal Address = 38438 ] ~ --------------------------------------------------------------------- ~ This data location holds the length of the waveform last installed. ~ The value is returned from RAM and DISK Calls and is intended for ~ user reference only. This address is in 2-byte format% LOW BYTE& ~ HIGH BYTE. ~ ~ ~ LENGTH NUMBER [ Hex Address = $9629 Decimal Address = 38440 ] ~ ------------------------------------------------------------------ ~ This data location holds the coded length of the waveform last instal- ~ led. The value must be supplied for SEMI Calls. The value is record- ~ ed in the waveform file and written to this location from any RAM& ~ DISK& or AUTO Call. ~ ~ X {Table follows& next page.} ~ ~ ~ ~ So What Software E-6 1-JUN-88 ~ ~ ~ ~ ====================================================================== ~ BASIC INTERFACE SONIX for the Apple IIgs ~ ====================================================================== ~ ~ Actual Waveform Length Coded Length Number ~ -------------------------------------------------- ~ X 256 0 ~ 512 8 ~ 1024 16 ~ 2048 24 ~ 4096 32 ~ 8192 40 ~ 16384 48 ~ 32768 56 ~ ~ ~ VOLUME [ Hex Address = $9629 Decimal Address = 38441 ] ~ ----------------------------------------------------------------- ~ This data byte is the volume for the oscillator currently being used. ~ The value is added to the Master System Volume byte at $E1/00CA (the ~ same byte set by the Volume function in the Control Panel) to create ~ the actual volume for that oscillator. The volume byte can be any ~ value between 0 and 255 (where 255 is the highest volume value). This ~ value is installed as the Control Panel volume setting at default by ~ AUTO& RAM& and DISK Calls. ~ ~ ~ OSCILLATOR MODE [ Hex Address = $9630 Decimal Address = 38442 ] ~ ------------------------------------------------------------------- ~ This data byte describes the operating mode for the oscillator cur- ~ rently being used. There are 4 modes of operation% One Shot& Free ~ X Run& Sync& and Swap. ~ ~ One Shot% Plays the waveform from the beginning to the end and the ~ shutoff. ~ ~ Free Run% Plays the waveform over and over until you shut it off. ~ ~ Sync% Playing an even-numbered oscillator will start up its odd ~ pair oscillator and play simultaneously. ~ ~ Swap% Playing an even-numbered oscillator will start up its odd ~ pair oscillator after the even-numbered one reaches the end ~ of its waveform. ~ ~ Free Run ON % 0 One Shot ON% 2 Sync ON % 4 Swap ON % 6 ~ Free Run OFF% 1 One Shot OFF% 3 Sync OFF% 5 Swap OFF% 7 ~ ~ ~ RESOLUTION [ Hex address = $9631 Decimal address = 38443 ] ~ ----------------------------------------------------------------- ~ This data byte sets the resolution at which the waveform is played ~ back from memory. A resolution of 7 will play back every byte in the ~ waveform& 6 will play back every other one& 5 plays back every 4th ~ one & and so on. The value is supplied by SEMI and AUTO Calls& but ~ can only be altered through the ROOT Call. ~ ~ X 0 = Every 128th byte 4 = Every 8th byte ~ 1 = Every 64th byte 5 = Every 4th byte ~ 2 = Every 32nd byte 6 = Every 2nd byte ~ 3 = Every 16th byte 7 = Every byte ~ ~ So What Software E-7 1-JUN-88 ~ ~ ~ ~ ===================================================================== ~ BASIC INTERFACE SONIX for the Apple IIgs ~ ====================================================================== ~ ~ PITCH NUMBER [ Hex Address = $9632 Decimal Address = 38444 ] ~ ------------------------------------------------------------------- ~ X This data byte sets the pitch at which the waveform is played. The ~ pitch is a value from 0 to 95& corresponding to the notes of an 8- ~ octave chromatic scale from C0 to B7. ~ ~ This value is supplied by SEMI and AUTO calls and is derived from ~ a semitone table associated with the selected waveform. ~ ~ ~ OSCILLATOR NUMBER [ Hex Address = $9633 Decimal Address = 38445 ] ~ --------------------------------------------------------------------- ~ This data byte selects the oscillator to be supported by the current ~ data bytes. The value must be supplied for both AUTO and SEMI calls. ~ ~ To point your data at Oscillator "n"& set this byte to "n". 30 oscil- ~ lators (numbers 0 through 29) are available for your use at any time. ~ ~ ~ PROGRAMMING ~ ----------- ~ These preceding discussions may leave you feeling as though you've ~ taken a drink from a fire hose. To help you bring everything into ~ focus& we'll now give a quick word summary of the basic (no pun inten- ~ ded) points of using SONIX's Basic Interface& and then invite you to ~ run and examine a sample program. ~ ~ X The Apple IIgs' sound section has 30 separate digital oscillators ~ that can produce music or other sounds when given certain data and ~ commands. The sound section uses a special 64K-byte memory bank& ~ the Sound RAM& to hold waveform data& while other important data must ~ be put into the "regular" IIgs memory. SONIX's Basic Interface tools ~ let you load the Sound RAM with waveform data& place all the other ~ important data where you want it in "regular" memory& and then issue ~ all the appropriate commands to cause oscillators to sound when and ~ how you wish them to. ~ ~ You've already gotten a taste of the way a simple Basic program can ~ exercise the IIgs's sound talents...when you booted up the SONIX sys- ~ tem disk. There is a special example program on that same disk& ~ which we've written to illustrate the use of the Basic Interface. To ~ run it& get into Basic by clicking the Exit to Basic entry on SONIX's ~ Main Menu screen& type in RUN BASIC.EX& and press Return. What the ~ BASIC.EX program will do is show how a Basic program can load differ- ~ ent waveforms and cause them to sound at different pitches and vol- ~ umes& as a function of what keys you press. After you've played ~ around with the program& press Control and Reset (simultaneously) and ~ release them& then type LIST and press Return to see the actual Basic ~ program itself. You're welcome to use BASIC.EX as a starting point ~ for your own programs.....but take care not to erase or overwrite ~ your only copy of BASIC.EX ! ~ ~ ====> IF YOU HAVEN'T MADE BACKUP COPIES OF BOTH YOUR SONIX DISKS YET& ~ X PLEASE DO IT NOW !!! ~ ~ ~ ~ So What Software E-8 1-JUN-88 ~ ~ ~ENDFILE