~ ~ ===================================================================== ~ NOTE ENGINE SONIX for the Apple IIgs ~ ===================================================================== ~ ~ INTRODUCTION ~ ------------ ~ X The Note Engine is a program that plays back song files that have ~ been created by SONIX's Music Editor; it uses Waveform Files for the ~ characteristic instrument or "voice" sounds. The Note Engine can ~ handle 30 separate& simultaneous oscillators over an 8-octave (96- ~ note) range& with 1/64th-note resolution. Music files can be up to ~ 128 measures in length& providing for a gigantic musical score& well ~ in excess of normal requirements. ~ ~ Tempo& Master Volume& and Oscillator Volume can be changed at any ~ point in a music file& plus starting& stopping& or resuming the se- ~ quencing of the music file--from within an Applesoft Basic program. ~ ~ ~ INTERRUPT DRIVEN ~ ---------------- ~ Every sequencer has a "heartbeat"& an evenly-timed& constant& incor- ~ ruptible train of pulses that can be detected by software. Many ~ potential heartbeats are available in the IIgs& but only one of them ~ is fast enough to support the Note Engine's 1/64th-note resolution% ~ interrupts from the video output circuitry in the IIgs. ~ ~ Each horizontal line on the Super Hi-Res screen has a scanline con- ~ trol byte (SCB) associated with it. This byte has several functions& ~ one of which is to provide an interrupt flag that creates an inter- ~ rupt at the rate that the video display is scanned (30 time per sec- ~ X ond). That's more than fast enough for the Note Engine. However& ~ using the SCB interrupts means that the Super Hi-Res screen must be ~ enabled for the Note Engine to operate& and interrupt flags must be ~ set at specific horizontal lines. The Note Engine's CONVERT Call ~ install these flags automatically. (It's described in detail in the ~ section on the CONVERT Call.) ~ ~ ~ INSTALLATION ~ ------------ ~ The Note Engine is installed by BRUN-ing it at startup time. The ~ program needs our LONGLOADER and SONIX.GS binary files already instal- ~ led to handle disk access. Follow this startup sequence% ~ ~ ~ 10 PRINT CHR$(4);"BRUN LONGLOADER" % PRINT CHR$(4);"BRUN SONIX.GS"% ~ PRINT CHR$(4);"BRUN NOTE.ENGINE" ~ ~ Should you wish to use the ICONIX.GS graphics interface file from So ~ What Software's "ICONIX for the Apple IIgs" program along with the ~ full SONIX Basic interface& BRUN the ICONIX.GS file first& then BRUN ~ the SONIX files in the order shown above. We highly recommend that ~ you have all these routines installed at the same time to let your ~ Basic programs both handle Super Hi-Res graphics and give you direct ~ control of the Ensoniq synthesizer chip. ~ ~ X ~ PLEASE NOTE% Memory allocation priorities dictate this sequence; ~ deviations WILL cause a crash! (Try it if you doubt us!) ~ ~ ~ So What Software D-1 1-JUN-88 ~ ~ ~ ~ ===================================================================== ~ NOTE ENGINE SONIX for the Apple IIgs ~ ===================================================================== ~ ~ NOTE ENGINE CALLS ~ ----------------- ~ X There are 6 Call commands that the Note Engine adds to your Basic ~ programming repertoire. 5 of them let you load song files from disk ~ and save them from memory to disk& start and stop a song file in ~ memory& resume a stopped song's play& and "single-step" through a ~ song one 64th note at a time. The last Call modifies your graphic ~ screen files so they and your song programs work together. ~ ~ Let's take a short time out to clarify 2 points. First& when we ~ refer to a "song" file& that doesn't mean strictly that the only ~ thing you're able to make your IIgs sound is music. Actually& liter- ~ ally ANY sound that you can extract or capture via SONIX's Waveform ~ Editor can be used by SONIX's Music Editor to create a sound file ~ that you can execute from a Basic program. So& not only can your ~ programs yield music& they can also yield the spoken word& or dog ~ barks& or thunder& or anything...and any combination! ~ ~ We use the term "song" file because the Music Editor is designed from ~ a musician's point of view--So What Software's staff just happens to ~ comprise engineers who are also musicians. We tend to think of pro- ~ grams that produce sound as music programs& to differentiate them ~ from graphics programs. ~ ~ That brings up the second point. The Calls about to be explained are ~ valid ONLY for programs using song files that were created with ~ SONIX's Music Editor. The Music Editor assembles a lot of data when ~ X you save a song file& and the data are arranged in a particular for- ~ mat so the Note Engine Calls know exactly where to find what they ~ need. OK& let's get into those Calls..... ~ ~ LOAD ~ ---- ~ This Call loads a music file and all the waveform files associated ~ with it. All the digital oscillator control (DOC) parameters and ~ Sound RAM patterns are initialized and put in place& according to the ~ song file data. The "SG$" string descriptor is used to pass the song ~ file pathname to the Note Engine. ~ ~ For example& the following line of code in a Basic program would load ~ a song file called "My.Song.SWF" from a disk named "/WAVE.LIB/" ~ ~ 10 SG$ = "/WAVE.LIB/MY.SONG.SWF&" % CALL 38144 ~ ~ {Note the "trailing comma" after the pathname--it's VERY important!} ~ ~ Experienced programmers save some keystrokes in a program by "declar- ~ ing" a 1- or 2-letter variable to be the same as a numeric address. ~ We do this for Note Engine Calls& setting aside six 2-letter variables ~ for just that purpose. We use "NL" for the LOAD Call. ~ ~ You need to "declare" the variable before you CALL it (of course)& so ~ your code might look like this% ~ X ~ 5 NL = 38144 ~ ~ 10 SG$ = "/WAVE.LIB/MY.SONG.SWF&" % CALL NL ~ ~ So What Software D-2 1-JUN-88 ~ ~ ~ ~ ===================================================================== ~ NOTE ENGINE SONIX for the Apple IIgs ~ ===================================================================== ~ ~ You might find it very convenient to "declare" all 6 of the Note ~ Engine Calls at the beginning of your program& like this% ~ X ~ 10 NL = 38144 % NV = NL + 4 % NS = NC + 8% NP = NS + 4 % ~ NR = NP + 4 % NX = NR + 4 ~ ~ If you do this& be sure that the "declaration" line comes BEFORE the ~ first time you make one of the Note Engine Calls. For the purpose of ~ explaining the next 5 Calls& we're going to presume that the 6 vari- ~ ables have been "declared" in a Basic program. There is a summary of ~ the 6 Calls& their decimal and hexadecimal addresses& and the 2- ~ letter variables we use for them at the end of this section. ~ ~ ~ ~ START ~ ----- ~ This Call begins play of a previously loaded song file from the begin- ~ ning; the song will halt when either a STOP Call is made or the end ~ of the song file is reached. As soon as the Call is made& control of ~ the computer is returned to you so your program can continue while the ~ song file plays. ~ ~ 10 CALL NS ~ ~ ~ STOP ~ X ---- ~ This Call halts the playing of a song file by the Note Engine. ~ ~ 10 CALL NP ~ ~ ~ RESUME ~ ------ ~ This Call continues the playing of a song file from where it was stop- ~ ped (by the STOP Call). ~ ~ 10 CALL NR ~ ~ ~ STEP ~ ---- ~ This Call will "one step" a song file& advancing a 1/64th note dura- ~ tion for each STEP Call that is made. ~ ~ 10 CALL NX ~ ~ ~ CONVERT ~ ------- ~ This Call installs an interrupt pattern for the Note Engine onto a ~ Super Hi-Res screen image. The screen image can be in any memory ~ X bank& but its starting address must be 8192 (hex $2000). This aligns ~ it with the Super Hi-Res screen buffers. ~ ~ ~ So What Software D-3 1-JUN-88 ~ ~ ~ ~ ~ ===================================================================== ~ NOTE ENGINE SONIX for the Apple IIgs ~ ===================================================================== ~ ~ To Convert a screen image& have the image in memory aligned at 8192 ~ ($2000)& POKE its bank number (38989 decimal; $984D hex)& and CALL the ~ X Convert routine. ~ ~ 10 POKE BK& X % CALL NC ~ ~ where X= number of memory bank holding the Super Hi-Res image to ~ be converted. ~ ~ NOTE% All screen images should be Converted AFTER they are loaded in ~ from disk& so that when they are displayed& the interrupt pat- ~ tern for the Note Engine is already present. ~ __________________________________________________ ~ ~ ~ You can use Longloader to get a Super Hi-Res image loaded into memory ~ in the right bank and at the right location& but there's another way% ~ ~ So What Software's ICONIX for the Apple IIgs is our state-of-the-art ~ graphics program that gives you full control of the Super Hi-Res ~ screen from Basic& as well as giving you the ability to add graphics ~ features to your images that NO other software allows. When you use ~ ICONIX's BLoader& images are automatically put into memory at the ~ right location...and that's why we designed SONIX to look for them ~ there. ~ ~ (Skeptical& are you? OK& what OTHER graphics program do you know of ~ X that lets you define and use all 16 colors palettes on the same screen ~ --256 colors at the same time? ICONIX does! What OTHER graphics pro- ~ gram lets you create screens with 320-mode and 640-mode combined? ~ ICONIX does! And what other graphics program lets you create real& ~ full-color animation sequences..not just simple color cycling? ICONIX ~ does! There's much& much more...but you have to see ICONIX to believe ~ it. ICONIX is available at the same place you got SONIX or direct ~ from So What Software.) ~ ~ __________________________________________________ ~ ~ ~ This is a good point to remind you that the superb note resolution ~ and volume/tempo variability the Note Engine gives needs the Super ~ Hi-Res screen to be enabled. What this means is that when you want ~ your Basic program to use the Note Engine to play a song& you can't ~ do it with the screen in either text mode or in Hi-Res graphics mode. ~ Sorry about that& but all software developers have to live within the ~ limits of the hardware...that is& the IIgs. Other IIgs music soft- ~ ware we've seen has only 1/32nd note resolution& or doesn't let you ~ change tempo during a song& or doesn't let you change volume during a ~ song& or....in fact& they have ALL these limitations. And to top it ~ off& NONE of them lets you play songs from your own Basic programs! ~ ~ ~ ~ X ~ ~ ~ ~ So What Software D-4 1-JUN-88 ~ ~ ~ ~ ~ ===================================================================== ~ NOTE ENGINE SONIX for the Apple IIgs ~ ===================================================================== ~ ~ In the Note Engine Programming section& you'll learn about an example ~ program on the SONIX disk that shows you how to enable the Super ~ X Hi-Res screen from your Basic program& and how to do a little bit of ~ Super Hi-Res "graphic-ing" ("graphic-ery"& maybe?). To get COMPLETE ~ control of the Super Hi-Res screen& you'll want to have ICONIX for ~ the Apple IIgs& the graphics program we mentioned just a few para- ~ graphs back. SONIX and ICONIX work perfectly together. ~ ~ ~ ~ NOTE ENGINE CALL SUMMARY ~ ~ CALL FUNCTION VARIABLE DECIMAL ADDRESS HEX ADDRESS ~ -------------------------------------------------------------------- ~ ~ LOAD NL 38144 $9500 ~ CONVERT NC 38152 $9508 ~ START NS 38156 $950C ~ STOP NP 38160 $9510 ~ RESUME NR 38164 $9514 ~ STEP NX 38168 $9518 ~ ~ ~ ~ NOTE ENGINE PROGRAMMING ~ ----------------------- ~ The old adage is that a picture is worth a thousand words& so one ~ X might make the analogy that a Basic program is worth about the same ~ number. There is a program called NOTENGINE.EX on the SONIX system ~ disk& which we invite you to run and examine. You can get it going ~ by clicking the Exit to Basic option on SONIX's Main Menu screen& ~ typing RUN NOTENGINE.EX& and pressing Return. You'll get a text ~ screen asking you for a few choices& then you'll press Return to play ~ a song. ~ ~ NOTENGINE.EX will show what we mean by needing to enable the Super ~ Hi-Res screen& and when the song has finished& you should look at the ~ program's Basic code to see how the Note Engine's many features are ~ used. You can LIST the program by pressing Control and Reset (simul- ~ taneously) and then releasing them& typing LIST& and pressing Return. ~ NOTENGINE.EX might be a good starting point for you in writing your ~ own song-playing Basic programs& but please take care not to erase or ~ overwrite it. ~ ~ => YOU DO HAVE BACKUP COPIES OF BOTH YOUR SONIX DISKS& DON'T YOU? ~ IF NOT& PLEASE MAKE THEM NOW !! ~ ~ ~ NOTE ENGINE PEEKS AND POKES ~ --------------------------- ~ When the Note Engine is in memory and running& there are 2 memory ~ addresses that will contain information you may want to help your ~ Basic program do more things. These data "flag" whether a song is ~ X playing and where in the song the Note Engine is currently playing. ~ Two other addresses let you set tempo and volume "externally". ~ ~ ~ So What Software D-5 1-JUN-88 ~ ~ ~ ~ ~ ===================================================================== ~ NOTE ENGINE SONIX for the Apple IIgs ~ ===================================================================== ~ ~ STATUS PEEK ~ ----------- ~ X The Status address is 38399 ($95FF hex); when it holds a 0& the Note ~ Engine is NOT playing. When you issue the Note Engine's START Call& ~ the song begins playing until either it has finished or you issue the ~ STOP Call. Meanwhile& your program is free to go on to its next line ~ of code. Your program can PEEK the Status address to see if the song ~ is still being played& so that it doesn't execute any program steps ~ you don't want to happen until the song is over. ~ ~ Example% ~ ~ 10 SG$ = "/WAVE/MY.SONG.SWF&" % CALL NL % CALL NS ~ ~ 20 IF PEEK (38399) < > 0 THEN 20 ~ ~ 30 {Another code line to be executed AFTER the song is finished} ~ ~ ~ SONG COUNT PEEK ~ --------------- ~ The 2 bytes of the Song Count address are at 38394 and 38395 ($95FA& ~ $95FB). These 2 bytes tell you how many 64th note "ticks" have occur- ~ red since a song was START-ed. (The way you combine the 2 bytes to ~ yield the decimal number is simple% multiply the value at 38395 by 256 ~ and add it to the value at 38394.) Song Count is very useful for ~ stopping a song exactly at a chosen point& and you can do it by 64th ~ X notes& quarter notes& bars& or almost any way you care to count. ~ ~ The following code would STOP a song at the end of the 15th bar% ~ ~ 10 BAR = (PEEK (38394) + 256 * PEEK (38395)) / 64 {64 notes per bar} ~ ~ 20 IF BAR < 15 THEN 10 ~ ~ 30 CALL NP ~ ~ ~ MASTER VOLUME POKE ~ ------------------ ~ You can change a song's Master Volume at any point while it's play- ~ ing by simply POKE-ing in a value from 0 to 15 (0 is OFF) at Address ~ 38391 ($95F7). When a song is started by the START Call& the Master ~ Volume is set to 8 at this address--and& of course& any Master Volume ~ setting you entered at the beginning of the song immediately POKEs in ~ a different value. ~ ~ Suppose we hadn't set an initial Master Volume setting in a song& but ~ wanted to begin a crescendo at the 16th bar. We can use the measure ~ counting technique as we did in the previous example& but instead of ~ stopping the song at the end of Bar 15& set the Master Volume to 11% ~ ~ X 10 BAR = (PEEK (38394) + 256 * PEEK (38395)) / 64 ~ ~ 20 IF BAR < 15 THEN 10 ~ ~ 30 POKE 38391& 11 ~ ~ So What Software D-6 1-JUN-88 ~ ~ ~ ~ ===================================================================== ~ NOTE ENGINE SONIX for the Apple IIgs ~ ===================================================================== ~ ~ TEMPO INDEX POKE ~ ---------------- ~ X The Note Engine controls tempo in essentially the same way that it ~ does Master Volume& and it uses the very next byte& 38392 ($95F8)& to ~ hold a Tempo Index value. The Note Engine "calculates" the tempo by ~ dividing the value 900 by the Tempo Index& and then setting the tempo ~ "quarter note = " to this value. ~ ~ Here's an example% POKE-ing in a Tempo Index of 6& say& means that ~ the song's tempo will be 900 / 6 = 150 quarter notes per minute. The ~ Note Engine's "default" Tempo Index for a song that is START-ed is 8& ~ so to speed up the song we've been using in our examples at its 15th ~ bar& you could use code like this% ~ ~ 10 BAR = (PEEK (38394) + 256 * PEEK (38395)) / 64 ~ ~ 20 IF BAR < 15 THEN 10 ~ ~ 30 POKE 38392& 6 ~ ~ Notice that the while the Tempo Index can be a number from 1 to 255& ~ since it is divided into another number to "calculate" the tempo& the ~ HIGHER the Tempo Index number& the LOWER the tempo itself. Below is ~ a table of some Tempo Index values and their tempo equivalents. ~ ~ ~ Tempo Index Quarter Notes per Minute ~ X ----------------------------------------- ~ 1 900 ~ 2 450 ~ 3 300 ~ 4 225 ~ 5 180 ~ 6 150 ~ 7 128.6 ~ 8 112.5 ~ 9 100 ~ 10 90 ~ 11 81.8 ~ 12 75 ~ 13 69.2 ~ 14 64.3 ~ 15 60 ~ 16 56.3 ~ 17 52.9 ~ 18 50 ~ 19 47.4 ~ 20 45 ~ 21 42.6 ~ 22 40.1 ~ ~ ~ ~ X ~ ~ ~ ~ So What Software D-7 1-JUN-88 ~ ~ ~ ENDFILE