Multimedia Classic

home *** CD-ROM | disk | FTP | other *** search

/ Multimedia Classic / MultimediaClassic.mdf / app_midi / drum / mididrum.asc < prev next >

Wrap

Text File | 1993-01-19 | 54.4 KB | 1,073 lines

***** Computer Select, October 1992 : Doc #24357 ***** Journal: PC Magazine May 12 1992 v11 n9 p394(3) * Full Text COPYRIGHT Ziff-Davis Publishing Co. 1992. ----------------------------------------------------------------------------- Title: Creating a computer drum machine, part 1. (Environments)(column) (Tutorial) Author: Petzold, Charles. AttFile: Program: DRUM1.EXE Self extracting archive. Table: L09ENT1.WKS Drum's source files. Abstract: A guide to creating a Musical Instrument Digital Interface (MIDI)-based drum machine is presented. Drum machines are a special type of sequencer that is somewhat simpler than a complete musical sequencer because it replicates percussion and does not need to define musical pitch. The two parameters of a drum machine are percussion instrument and time. Microsoft's Multimedia Windows supports several MIDI channels, one of which is usually reserved as a non-melodic drum channel. The programmer should send a percussion channel the Program Change message for instrument voice 0; there are 47 different percussion sounds available as defined by the MIDI Manufacturers Association. A sample program is discussed. ----------------------------------------------------------------------------- Descriptors.. Topic: MIDI Tutorial Musical Instruments Programming Instruction. Feature: illustration table. Record#: 12 162 077. ----------------------------------------------------------------------------- Full Text: by Charles Petzold A strong, regular drumbeat is the crucial rhythmic foundation of much of American popular music. Under the influence of African-American culture, jazz, rhythm and blues, and rock 'n' roll have all been built around the driving pulse of percussion. Drummers are often highly regarded for their rhythmic accuracy and precision, and it is not uncomplimentary to say that a drummer "plays like a machine." Although electronic drum machines can't capture the improvised variations that make good drumming so enjoyable, a drum machine can still be a reasonable compromise. Standalone electronic drum machines have been around for years, and now even inexpensive small synthesizers often include several built-in percussion patterns, letting you switch from tango to rock to bossa nova riffs with the push of a button. While you may associate these incessant, repetitive rhythms with tacky lounge singers or the worst of house music, real drum machines can be much more versatile. They let you customize your rhythms with a variety of percussion instruments, and can be very useful for experimentation when composing or arranging music, even if you switch to real drummers for performances or recording sessions. As an accompaniment to a solo guitar, piano, saxophone, or whatever, drum machines can be a lot of fun. DRUM MACHINES AND SEQUENCING A drum machine is a sequencer, but a special case. Back in the old days (two decades ago), sequencers were stand- alone devices that could store a sequence of musical notes and play them back, very often repeated in a cyclic pattern. Several forward-looking rock bands used sequencers during that period, including Pink Floyd, The Who, and Tangerine Dream. During the mid and late 1970s, sequencers became quite common in disco and some varieties of New Wave rock. Standalone sequencers are still used in performance settings, although for studio or home recording they've largely been replaced with computers. Because of the increased storage capacity of a computer, sequencing software can handle entire multi-instrument compositions rather than just basic repeated patterns of notes. Drum machines are somewhat simpler than full-fledged sequencers, though. Compositions played by sequencing software involve (at the very least) three parameters: pitch, time, and the instrument voice. Because each of the various percussion instruments played by drum machines has a single pitch (or no definable musical pitch at all), drum machines can be limited to two parameters: the percussion instrument and time. In this column and the next two, I'll describe a computer drum machine program called DRUM that I wrote for Windows with Multimedia Extensions. This program lets you construct a sequence of up to 32 notes using 47 different percussion sounds. The program plays the sequence repetitively at a selectable tempo and volume. For accurate timing, DRUM requires a dynamic link library called DRUMDLL, which I'll describe in the next column. The final column will discuss a second module used in the program that has code to store percussion patterns on-disk. THE MIDI CHANNELS As I've discussed in previous columns, a multimedia PC requires an internal synthesizer based on the industry-standard Musical Instrument Digital Interface (MIDI). A multimedia PC also has at least one MIDI Out port for connecting an external MIDI synthesizer, and a MIDI In port for connecting an external MIDI controller (such as a keyboard). Multimedia Windows includes support for MIDI through function calls beginning with the prefixes midiOut and midiIn, and through the Media Control Interface (MCI). As we've seen, the primary purpose of the midiOut functions is to send 2-, 3-, and 4-byte MIDI messages to a synthesizer to play musical notes. Most MIDI messages include a 4-bit code that identifies a MIDI channel. Generally, a Program Change message is sent to a synthesizer to select an instrument voice for a particular channel. Then, Note On and Note Off messages for that channel play particular pitches using that instrument voice. These messages include key numbers to identify the note, where key number 60 is middle C. The use of 16 channels allows (in theory) 16 different instrument sounds to play simultaneously. One channel, however, is usually reserved as a nonmelodic percussion channel. In this case, Note On messages do not trigger different pitches for a particular instrument voice, but instead trigger different percussion sounds based on the key numbers. GENERAL MIDI MODE The MIDI Manufacturers Association has recently defined a standard for synthesizers to facilitate the interchange of computer-based MIDI sequences. This standard is called General MIDI Mode. In particular, General MIDI Mode defines a collection of 128 instrument voices selectable with Program Change messages. It also assigns channels 0 through 8 and 10 through 15 as the melodic channels for which these instrument voices may be chosen. (The term melodic implies that different key numbers play different pitches.) Channel 9 is the percussion channel, for which 47 different percussion sounds are defined. When using the percussion channel, you should send it a Program Change message for instrument voice 0. You can then play the 47 different percussion sounds by sending Note On and Note Off messages using key numbers ranging from 35 (an acoustic bass drum) through 81 (a triangle). Multimedia Windows generally adheres to the General MIDI Mode specification, with one significant departure: Because many inexpensive MIDI synthesizers cannot match the level of polyphony (the number of simultaneous sounds) implied by General MIDI Mode, Multimedia Windows classifies synthesizers as either base-level or extended. An extended synthesizer (capable of playing nine melodic instruments with 16-note polyphony and percussion with 16-note polyphony) uses channels 0 through 8 for the melodic voices and channel 9 for percussion. This is the same as General MIDI Mode, but without the top six channels. A base-level synthesizer (capable of playing three melodic instruments with 6-note polyphony and percussion with 3-note polyphony) uses channels 12 through 14 for the melodic voices and channel 15 for percussion. If you have a synthesizer that uses a different channel for percussion, or if it has a percussion channel in which the key numbers trigger percussion sounds other than the ones defined by Multimedia Windows, that's a job for the MIDI Mapper. This MIDI output device uses mapping tables (which can be created in the MIDI Mapper utility invoked from the Control Panel) to alter MIDI messages on their way to a synthesizer. USING THE DRUM PROGRAM We are now ready to start up the program. When you first run DRUM, it looks like Figure 1. The 47 different percussion instruments are listed by name in two columns on the left half of the window. (Figuring out how to fit these names on the screen was one of the hardest jobs in designing this program!) The grid on the right is a two-dimensional array of percussion sound versus time. Each instrument is associated with a row in the grid. The 32 columns are 32 beats. If you think of these 32 beats as occurring within a measure of 4/4 time (four quarter notes per measure), then each beat corresponds to a 32nd note. When you select Running from the Sequence menu, the program will attempt to open the MIDI Mapper device. If it's unsuccessful, you'll get a message box. Otherwise, you'll see a little "bouncing ball" skip across the bottom of the grid as each beat is played. You can click with the mouse anywhere within the grid to play a percussion sound during that beat. Use the left mouse button for a base-level synthesizer; the square will turn light gray. Use the right mouse button for an extended synthesizer; the square will turn dark gray. If you click with both mouse buttons (either together or independently), the square will turn black and the percussion sound will be heard on both a base-level and an extended synthesizer. Clicking again with either or both buttons will turn off the sound for that beat. Across the top of the grid is a dot every four beats. Those dots simply make it easier to pinpoint your button clicks without too much counting. At the upper-right-hand corner of the grid is a colon and bar (:|) that resembles a repeat sign used in traditional music notation and indicates the length of the sequence. You can click with the mouse anywhere above the grid to put the repeat sign someplace else. The sequence plays up to but not including the beat beneath the repeat sign. If you want to create a waltz rhythm, for example, you should set the repeat mark for some multiple of three beats. The horizontal scroll bar controls the velocity byte in the MIDI Note On messages. This generally affects the volume of the sounds, although it may also affect timbre in some synthesizers. The program initially sets the velocity scroll bar thumb in the center position. The vertical scroll bar controls the tempo. This is a logarithmic scale ranging from 1 second per beat when the thumb is at the bottom to 10 milliseconds per beat at the top. The program initially sets the tempo at 100 milliseconds (one-tenth of a second) per beat, with the scroll bar thumb in the center. The File menu allows you to save and retrieve files with the extension .DRM, a format I invented. These files are fairly small (512 bytes) and use the RIFF file format, which is recommended for all new Multimedia Windows data files. The .DRM files include the data for both base-level and extended synthesizers, the number of beats for the sequence, the velocity, and the tempo. The About option from the Help menu displays a dialog box that contains a very brief summary of the use of the mouse on the two scroll bars and their functions. Finally, the Stopped option from the Sequence menu stops the music and closes the MIDI Mapper device after finishing the sequence being executed. DEVICE-INDEPENDENT .DRM FILES Let's say you and some of your friends all have my DRUM program and use it to create new and fascinating percussion sequences, which you pass around to each other in .DRM files. Or perhaps you're interested in creating a collection of .DRM files yourself and uploading them to PC MagNet. If you do, each .DRM file should include sequences for both base-level and extended synthesizers. Otherwise, some people who try to play the file won't hear anything! The sequence for base-level synthesizers should have 3 or fewer percussion sounds per beat; those for extended synthesizers can include up to 16 percussion sounds per beat. The result will look something like the DRUM screen display shown in Figure 2. Though it's not readily discernible in the screenshot, some of the grid squares are black (meaning that the percussion sound is played on both base-level and extended synthesizers), and others are dark gray (meaning that the percussion sound is played only on extended synthesizers). At no time are more than three percussion sounds played on the base-level synthesizer. There's nothing wrong with trying to play more than three simultaneous percussion sounds on a base-level synthesizer, of course, but there's no guarantee that you'll hear them all. Some synthesizers will give highest priority to the notes that come first and discard the rest when the limit has been reached, while others give highest priority to notes that come later and turn off the earlier notes. It's probably easiest to make the sequence for a base-level synthesizer a subset of the extended-synthesizer sequence. But there are alternatives. You may discover a more satisfactory solution in completely rethinking an arrangement for a base-level synthesizer. The preparation of MIDI sequences for both base-level and extended syn-thesizers is very important in creating device-independent MIDI data for Multimedia Windows. And keep in mind that you have the freedom to make the base-level sequence much different from the extended-synthesizer sequence to account for the lower number of simultaneous voices. It is for such flexibility that the designers of Multimedia Windows made the base-level synthesizer channels separate from and not a subset of the extended-synthesizer channels. THE DRUM SOURCE CODE You can download all source code for DRUM, including the DRUM.EXE executable and two dynamic link libraries from PC MagNet. Figure 3 lists all the files involved, with brief descriptions. In the next column, I'll show code for the DRUMDLL dynamic link library. This DLL performs all the midiOut function calls. To achieve the precision required of a program such as this (which can play sequences as quickly as 10 ms. per beat), DRUMDLL makes use of the Multimedia Windows high-resolution timer, using functions beginning with the prefix time. Without these functions, DRUM would not be able to play faster than 55 ms. per beat, and would be dependent on the mushy, imprecise nature of the normal Windows timer. Meanwhile, have fun with the program. Class resumes in two weeks. ***** Computer Select, October 1992 : Doc #22006 ***** Journal: PC Magazine May 26 1992 v11 n10 p367(5) * Full Text COPYRIGHT Ziff-Davis Publishing Co. 1992. ----------------------------------------------------------------------------- Title: Creating a computer drum machine, part 2. (DRUM utility software) (Tutorial) Author: Petzold, Charles. AttFile: Program: DRUMDLL.BCP Make file for Borland C++ 3.0. Program: DRUMDLL.C C source code. Program: DRUMDLL.DEF Definition file. Program: DRUMDLL.H Header file. Program: DRUMDLL.MSC Make file for Microsoft C 7.0. Abstract: The timer provided in Microsoft Corp's Windows graphical user interface (GUI) called SetTimer is easy to use and suffices for clock programs and simple animation, but it is a faulty tool when implemented for time-critical applications. It is based on the microcomputer's system clock and can only display elapsed time in multiples of 55m seconds. Music applications are typical cases that require a better clock than the time provided by Windows. A utility called DRUM is a drum machine program for the Windows environment written with Multimedia Extensions. It utilizes the percussion channel on Musical Instrument Digital Interface (MIDI)-compliant musical instruments. ----------------------------------------------------------------------------- Descriptors.. Topic: Clocks Tutorial Shareware Programming Music Software Packages. Feature: illustration program. Record#: 12 220 583. ----------------------------------------------------------------------------- Full Text: The standard Windows timer is certainly easy to use. Just call SetTimer, specifying an elapsed time in milliseconds, and you'll receive WM_TIMER messages periodically. It's a fine facility for clock programs and even for simple animation. For time-critical applications, though, the Windows timer is a disaster. In the first place, the timer is based on the PC system clock, which means that you can't receive WM_TIMER messages more frequently than every 55 milliseconds or with an elapsed time that is not a multiple of 55 milliseconds. Second, the timer messages are not asynchronous. They come through the program's message queue, and processing may be delayed if another program is at work. Third, because a message queue can hold only one WM_TIMER message at any time, you're not even guaranteed that you'll get all the timer messages you expect. Playing music is one such time-critical application for which the Windows timer is simply inadequate. I tried to get away with it in the BACHTOCC program discussed in the April 14, 1992, column, but it was obvious that using the Windows timer was not a good solution, and I admitted that at the time. Now it's time to do the job right. In the previous issue I began discussing a drum machine program written for Microsoft Windows with Multimedia Extensions. DRUM uses the percussion channel on an electronic music synthesizer conforming to the Musical Instrument Digital Interface (MIDI) specification. The program will also run under Windows 3.1 (which includes Multimedia Extensions) if you have a MIDI board and a driver for it. As shown in Figure 1, DRUM lets you interactively create a percussion pattern by clicking on a grid that represents 47 percussion sounds and 32 beats. You can also adjust the velocity (which generally corresponds to the volume), the tempo (as fast as 10 milliseconds per beat), and the number of beats in the sequence. In this column I'll discuss a dynamic link library called DRUMDLL that DRUM uses to play the MIDI sequence. THE MULTIMEDIA TIME FUNCTIONS To provide the accuracy we need to play MIDI sequences on the PC, Multimedia Windows includes a high-resolution timer that is implemented using seven functions beginning with the prefix time. One of these functions is superfluous; DRUMDLL demonstrates the use of the other six. The timer functions work with a callback function located in your code, specifically in a dynamic link library that your program uses. This callback function is called by the timer device driver according to a timer delay value specified by the program. When dealing with the multimedia timer, you specify two different times, both in milliseconds. The first is the delay time, and the second is called the resolution. You can think of the resolution as a tolerable error. If you specify a delay of 100 milliseconds with a resolution of 10 milliseconds, the actual timer delay may range anywhere from 90 to 110 milliseconds. There is sometimes a terminology problem when talking about resolution. The higher the resolution, the lower the time value. For example, a 5-millisecond resolution is higher than a 10-ms. resolution. To avoid this problem, I'll use the words higher and lower in conjuction with the term resolution value to indicate a numerical relationship. For example, a 5-ms. resolution value is lower than a 10-ms. resolution value. Before you use the timer, you should obtain the timer device capabilities: timeGetDevCaps (&timecaps, wSize) ; The first parameter is a pointer to a structure of type TIMECAPS, and the second parameter is the size of this structure. The TIMECAPS structure has only two fields, wPeriodMin and wPeriodMax. These are the minimum and maximum resolution values supported by the timer device driv-er. If you look at these values after calling timeGetDevCaps, you'll find that wPeriodMin is 1 and wPeriodMax is 65535, so this function may not seem crucial. It's a good idea, however, to get these resolution values anyway and use them in the other timer function calls. The next step is to call timeBeginPeriod (wResolution) ; to indicate the lowest timer resolution value that your program requires, within the range given in the TIMECAPS structure. This call lets the timer device driver best provide for multiple programs that may be using the timer. Every call to timeBeginPeriod must be paired with a later call to timeEndPeriod (which we'll get to shortly). Now you're ready to set a timer event: wTimerID = timeSetEvent (wDelay, wResolution, CallBackFunc, dwData, wFlag) ; The wTimerID return from the call will be 0 if an error occurs. Following this call, the function CallBackFunc will be called from Windows in wDelay milliseconds with an allowable error specified by wResolution. The wResolution value must be greater than or equal to the resolution value passed to timeBeginPeriod. The dwData parameter is program- defined data, which is later passed to CallBackFunc. The last parameter can be either TIME_ONESHOT, to get a single call to CallBackFunc in wDelay milliseconds, or TIME_PERIODIC, to get calls to CallBackFunc every wDelay milliseconds. I'll discuss CallBackFunc shortly. To stop a one-shot timer event before CallBackFunc is called, or to halt periodic timer events, call timeKillEvent (wTimerID) ; You don't need to kill a one-shot timer event after CallBackFunc is called. When you're finished using the timer in your program, call timeEndPeriod (wResolution) ; with the same param-eter passed to time-BeginPeriod. Try not to be greedy when specifying resolution values in these timer function calls. Selecting a 1-ms. resolution requires that the timer device driver process timer hardware interrupts every millisecond. This can cause a serious drain on the rest of the system. Two other functions begin with the prefix time. The function dwSysTime = timeGetTime () ; returns the system time in milliseconds since Windows first started up. The function timeGetSystemTime (&mmtime, wSize); requires a pointer to an MMTIME structure as the first parameter and the size of this structure as the second. Although MMTIME can be used in other circumstances to get the system time in formats other than milliseconds, in this case it always returns the time in milliseconds. So timeGetSystemTime is superfluous. THE TIMER CALLBACK FUNCTION As I mentioned, the multimedia timer works by calling a callback function located in a dynamic link library that your program uses. The address of the callback function is passed as a parameter to time-SetEvent. The timer device driver calls the callback function during hardware timer interrupts. This has several important implications: nThe callback function must be located in a dynamic link library, and it must be exported. (The easiest way to export the callback function is to use the _export keyword when defining the function.) Un-like the case with other callback functions used in Windows, you don't need to call MakeProcInstance for the callback. nAs stated in the documentation, the code segment in which the callback function resides must be fixed in memory, and any data that it uses must be in a fixed data segment. Segments are flagged as fixed or movable in the dynamic link library's module definition file. The seg-ments must be defined as fixed so they are not swapped out to disk and require reloading during the interrupt. nThe callback function is limited in the Windows function calls it can make. The callback function can only call Post- Message, four timer functions (timeSet-Event, timeKillEvent, timeGetTime, and the superfluous timeGetSystemTime), two MIDI output functions (midiOutShort-Msg and midiOutLongMsg), and the debugging function OutputDebugStr. nAnd remember, don't even think about making any DOS function calls from the callback function. As you can see, the multimedia timer is designed specifically for playing MIDI sequences and is limited in its usefulness beyond that. You can use PostMessage for informing a window procedure of timer events, and the window procedure can do whatever it likes with the information, but it won't be responding with the accuracy of the timer callback itself. The callback function has five param-eters, but only two of them are used: the timer ID number returned from time-SetEvent and the dwData value origi- nally passed as a parameter to time-SetEvent. THE DRUMDLL SOURCE CODE The source code for the DRUMDLL dynamic link library is shown in Figures 2 through 6. All source code for DRUM and the DRUMDLL dynamic link library can be downloaded from PC MagNet. If you want to recreate DRUMDLL.DLL using the Microsoft C 7.0 compiler, run NMAKE DRUMDLL.MSC With the Borland C++ 3.0 compiler, use MAKE -f DRUMDLL.BCP If you're familiar with the compiler flags for these two products, you'll notice that DRUMDLL.C is compiled for C++ mode. Although I'm not using any C++- specific code in DRUMDLL.C, adding such code is easier if you don't have to make further changes to account for the better type checking in C++. Currently, it appears as if the retail version of Microsoft C 7.0 will include much of what is now included in the Windows 3.0 Software Development Kit (SDK), but beta versions have not included the multimedia MMSYSTEM.H header file or MMSYSTEM.LIB import libraries. These files, however, are being included in the beta version of the Windows 3.1 SDK, indicating that the separate Multimedia Development Kit (MDK) is being phased out. It's not clear now how all this will shake out; at any rate, an upgrade to Borland C++ 3.0 is expected to account for the enhancements to Windows 3.1, including multimedia. DRUMDLL.C contains four exported functions. Three of them--DrumSet- Params, DrumBeginSequence, and Drum-EndSequence--are defined in DRUM-DLL.H and are called from the DRUM program. The other is the timer callback function, DrumTimerFunc. The three functions called from the DRUM program are defined in DRUMDLL.H within a construction that looks like this: extern "C" { .... } This is to prevent C++ from "name-mangling" these functions. C++ usually alters function names to include codes that indicate the parameter data types and return value, allowing for C++ function overloading and intermodule type checking during linking. Because different compilers perform name mangling in different ways, you'll probably want to avoid it for functions exported from dyna-mic link libraries for use by Windows programs. Otherwise you won't be able to use a dynamic link library from a program compiled with a compiler different from that used for the DLL. In DRUM-DLL.C, I've also used the extern "C" statement for the MMSYSTEM.H header file, because the version I have is not C++-ready. DRUMDLL also has a LibMain function. Such a function usually unlocks the DLL's data segment, but here it needn't do anything because the data segment is fixed. The only other function is MidiOutMessage, which simplifies the construction of MIDI messages in preparation for calling the Multimedia Windows function midiOutShortMsg. I usually don't like to use global variables very much, but this DLL is made much simpler with them. Global variables in a DLL are shared among all pro-grams that use the DLL, so only one program (or one instance of a program) can use DRUMDLL at any time. The DRUM program does not allow running a second instance, and I've used the -p flag when running the resource compiler in the DRUMDLL Make files so that other programs can't use DRUMDLL while DRUM is running. THE WORKINGS OF DRUMDLL The DRUM program calls the DrumSet-Params function in DRUMDLL at various times: when DRUM's window is cre-ated, when the user clicks on the grid or manipulates the scroll bars, when the pro-gram loads a .DRM file from disk, or when the grid is cleared. The single parameter to DrumSetParams is a pointer to a structure of type DRUM, defined in DRUMDLL.H. This structure stores the beat time in milliseconds, the velocity, the number of beats in the sequence, and two sets of 32-bit integers (47 integers per set) for storing the grid settings for the base-level and extended synthesizers. Each bit in these 32-bit integers corresponds to a beat of the sequence. The DRUM program maintains a structure of type DRUM in static memory and passes a pointer to it when calling DrumSetParams. DrumSetParams simply copies the contents of the structure to static memory in the DLL. You might think that it would only be necessary for DRUMDLL to save a pointer to the DRUM structure located in DRUM, but this would violate one of the rules for using a timer callback function: Any data the timer callback function accesses must be in a fixed data segment. To start the sequence, DRUM calls the DrumBeginSequence function in DRUMDLL. The only parameter is a window handle. This is used for notification. DrumBeginSequence opens the MIDI Mapper output device and, if successful, sends Program Change messages to select instrument voice 0 for MIDI channels 9 and 15. As you may recall from the last issue, channel 9 is the percussion channel for extended synthesizers, and channel 15 is the percussion channel for base-level synthesizers. To use the percussion channel, you select voice 0. Different key numbers in the Note On messages then select different percussion sounds. DrumBeginSequence continues by calling timeGetDevCaps and then time-BeginPeriod. The desired timer resolution defined in the TIMER_RES constant is 5 ms., but I've defined a macro called minmax to calculate a resolution within the limits returned from timeGetDevCaps. The next call is timeSetEvent, which specifies the beat time, the calculated resolution, the callback function Drum-TimerFunc, and the constant TIME_ONE-SHOT. DRUMDLL uses a one-shot timer rather than a periodic timer so that the tempo can be dynamically changed while a sequence is running. After the timeSet-Event call, the timer device driver will call DrumTimerFunc when the delay time has elapsed. PLAYING THE SEQUENCE The DrumTimerFunc callback is the func-tion where most of the heavy action takes place. The variable iIndex stores the cur-rent beat in the sequence. The callback begins by sending MIDI Note Off messages for the drum sounds currently playing. (iIndex has an initial value of -1 to prevent this when the sequence first be-gins.) Note Off messages are sent to chan-nel 9 for extended synthesizers and channel 15 for base-level synthesizers. Next, iIndex is incremented, and its value is delivered to the window procedure in DRUM with a user-defined message called WM_USER_NOTIFY. The wParam message parameter is set to iIndex so that WndProc in DRUM.C can move the "bouncing ball" at the bottom of the grid. The lParam parameter is set to the current system time obtained from time-GetTime. WndProc doesn't do anything with the system time, but I used it for debugging purposes and left it in so I could claim that DRUMDLL illustrates all six essential multimedia timer functions! DrumTimerFunc finishes by sending Note On messages to the synthesizer for channels 9 and 15, saving the grid values so the sounds can be turned off the next time through, and then setting a new one-shot timer event by calling timeSetEvent. To stop the sequence, DRUM calls DrumEndSequence with a single parameter that can be set to either TRUE or FALSE. If it is TRUE, then DrumEnd-Sequence ends the sequence right away by killing any pending timer event, calling timeEndPeriod, sending "all notes off" messages to the two MIDI channels, and closing the MIDI output port. DRUM calls DrumEndSequence with a TRUE parameter when the user decides to terminate the program. If the user selects Stop from the Sequence menu in DRUM, however, the program instead calls Drum-EndSequence with a FALSE parameter. This allows the sequence to complete the current cycle before ending. DrumEndSequence responds to this call by setting the bEndSequence global variable to NULL. If bEndSequence is TRUE and the beat index has been set to 0, DrumTimerFunc posts a user-defined message called WM_USER_FINISHED to WndProc. WndProc must respond to this message by calling DrumEndSequence with a TRUE parameter to terminate the use of the timer and the MIDI port properly. In an earlier version of the program, DrumTimerFunc itself called DrumEndSequence with a TRUE parameter to shut down. It seemed to work fine, but I realized that DrumEndSequence was calling functions not listed as those allowed within timer callbacks. The lesson: Be careful when writing a timer callback function. Because you're coding in C, it's easy to forget that you're writing code that has to be executed during a hardware timer interrupt. Keep the list of allowable functions close at hand. It could well be that other functions can safely be called from a timer callback, but do you really want to take a chance that the next version of Windows will still work that way? Most C runtime functions should be okay, but don't try any file I/O during the timer callback. If you need to perform a task based on the multimedia timer that you can't do without calling some other Windows function, use PostMessage to inform a window procedure of the timer event and let the window procedure do it. PostMessage is fine because all it does is place a message in a message queue. The window procedure retrieves the message later--not during the timer interrupt. Keep in mind also that the hardware timer could interrupt code in your program or other code in the DLL. This might be a problem if you're altering data that the callback function accesses. I decided this would not be a problem in DRUMDLL, but if you have critical sections of your code that should not be interrupted by a timer interrupt, surround the code with calls to the _disable and _enable functions provided in both the Microsoft C and Borland C++ runtime libraries. FINISHING UP We're not finished with DRUM just yet. The DRUM program can also save and retrieve files containing the information stored in the DRUM structure. These files are in the Resource Interchange File Format (RIFF) recommended for multimedia file types. You can read and write RIFF files using standard file I/O functions, of course, but an easier approach is provided by functions beginning with the prefix mmio (multimedia input/output). In the next issue, I'll discuss these functions and the new "common dialog box" library included in Windows 3.1. ***** Computer Select, October 1992 : Doc #14307 ***** Journal: PC Magazine June 30 1992 v11 n12 p367(6) * Full Text COPYRIGHT Ziff-Davis Publishing Co. 1992. ----------------------------------------------------------------------------- Title: Creating a computer drum machine, part 3. (Environment)(column) (Tutorial) Author: Petzold, Charles. AttFile: Program: DRUMFILE.C File I/O Routines for DRUM. Abstract: A guide to programming Microsoft Windows to create electronic 'drums' in multimedia applications is presented. The multimedia I/O functions provided with Microsoft's Windows Multimedia Extensions are specifically tailored for reading and writing the RIFF file format. A RIFF file includes nested chunks of information, each of which has a type, size and data. Basic techniques for using 'mmio' functions are discussed. The mmioOpen function returns a handle to a file and can include parameters for data structures. It works with the mmioCreateChunk function to write information to a RIFF file. Reading RIFF files involves the mmioRead and mmioDescend functions. ----------------------------------------------------------------------------- Descriptors.. Product: Microsoft Windows (Graphical user interface) (Programming). Topic: Music Multimedia technology Tutorial Programming Instruction Graphical user interface. Feature: illustration program. Record#: 12 216 586. ----------------------------------------------------------------------------- Full Text: File I/O under Windows has always been a little peculiar. Until Windows 3.0, the only documented file I/O function in Windows was OpenFile, which returned a DOS file handle. This function had the advantage of being able to create a fully qualified path and filename based on the current directory, but it was often clumsy to use. Some programmers used the DOS file handle obtained from OpenFile with the low-level C file I/O functions (read, write, close, and so forth). I took this approach in one of the programs in my book Programming Windows (Microsoft Press, 1990). The program worked fine with Microsoft C 6.0, but it had problems when compiled under Borland C++ 2.0. Under Borland's compiler, file handles associated with the low-level C file I/O functions were not the same as the DOS file handles. Windows programmers often need to use global memory blocks with files. The easiest way to do this is to pass far pointers to file I/O functions. But when you write small- or medium-model programs (which is highly recommended for Windows programming), all the standard C runtime functions accept near pointers. Windows 3.0 finally documented some file I/O functions ( _lcreate, _lopen, _lwrite, _lread, _llseek, and _lclose) that had actu-ally been part of Windows since Version 1.0. These functions accept far pointers and hook almost directly into the equivalent DOS file I/O function calls. They probably have come to be the most commonly used file I/O functions in Windows application programs. It does seem strange, though, to be making raw DOS function calls in the middle of a sophisticated graphical Windows program. PROBLEMS AND SOLUTIONS Beyond the actual mechanics of file I/O, Windows posed another problem for programmers who wanted to add file support to their applications. Windows programs should display a File Open dialog box for the user to select a file, but such dialog boxes proved rather complex to write. Many programmers wished for a standard File Open dialog box to be built into Windows itself. With Windows 3.1, this finally happened. This version includes a common-dialog-box library that contains dialog-box templates and procedures for opening files, saving files, printing, search-and-replace operations, choosing colors, and choosing fonts. In most cases, all you have to do is set up a structure's fields, pass the structure to a function, and get back your results when the user closes the dialog box. These dialog boxes are implemented in a dynamic link library called COM- MDLG.DLL. COMMDLG.H is the header file defining the functions and structures, and COMMDLG.LIB is the import library for linking the program to use the DLL. Microsoft allows COMMDLG.DLL to be shipped with applications that use the common-dialog-box library but continue to run under Windows 3.0. (For more information on the Windows common-dialog library, see the May 26, 1992, Power Programming column.) Moreover, because Windows 3.1 includes Multimedia Extensions, it makes available 16 functions, beginning with the prefix mmio (multimedia input/output), that are specifically designed for working with RIFF (Resource Interchange File Format) files. As I discussed in the previous column, RIFF files are used to store multimedia data. FINISHING UP DRUM With the common-dialog-box library and the mmio functions, adding file I/O to DRUM requires little more than the DRUMFILE.C module shown in Figure 1. DRUM maintains two filenames: The szTitleName variable stores the filename and extension only. This is used for displaying the filename in the title bar of the program's window and in message boxes. The szFileName variable stores the fully qualified path and filename and is used for reading from and writing to the file. GetOpenFileName and GetSaveFileName are the two functions in the common-dialog-box library that display the dialog boxes. Both of these functions ac-cept structures of type OPENFILENAME. Although the structure is large, for typical use most of its fields can be set to 0. Basically, as shown in the functions Drum-FileOpenDlg and DrumFileSaveDlg in DRUMFILE.C, you need pointers to buffers to receive the fully qualified filename, the title name, and the size of these buffers, as well as a filter string containing the file types for the dialog. MMIO BASICS In comparison with other sets of file I/O functions, the mmio functions are very versatile. If you like, you can use the mmioOpen, mmioRead, mmioWrite, mmioSeek, and mmioClose functions for general-purpose file I/O. One advantage of mmio over both Windows and C file I/O is that the mmioRead and mmioWrite functions accept huge pointers. You can read or write a global memory block greater than 64K in one function call. The mmio functions also let you directly manipulate the file I/O buffer, supply your own I/O procedures, and create memory files. Here I'll restrict use of the mmio func-tions to those few required for writing and reading RIFF files. As I described last time, RIFF files are composed of nested chunks of information, each of which has a chunk type (a four-character name), a chunk size (32 bits long), and chunk data. I also presented the RDUMP program, which displays the layout of a RIFF file. Figure 2 shows RDUMP output for one of DRUM's data files. The DRUM data file uses a form type of DRUM. As recommended in the Microsoft Windows Multimedia Programmer's Reference, I registered this form type with the Product Marketing area of the Multimedia Systems Group at Microsoft. Although you can create RIFF files using normal file I/O functions, calculating and storing the chunk sizes can be a nuisance. That's one of the things the mmio functions handle very well. When reading a RIFF file, the mmio functions also hide the process of skipping over unnecessary chunks. When you open a file using the mmio functions, you get a file handle of type HMMIO. Don't attempt to use this handle with DOS file I/O function calls or C file functions. The four-character chunk names, form types, and list types are treated as 32-bit integers in the mmio functions. These have a data type of FOURCC, which stands for four-character code. Two methods are provided for obtaining a 32-bit integer from characters or strings. One approach is to use the following macro: fcc = mmioFOURCC (ch1, ch2, ch3, ch4) ; The four parameters are the four characters individually; for example: fcc = mmioFOURCC ('W','A','V', 'E') ; You can also use a function that accepts an entire string: fcc = mmioStringToFOURCC (szFCC, wFlag) ; In this case: fcc = mmioStringToFOURCC ("WAVE", 0) ; The wFlag parameter can be MMIO_TOUPPER to make the characters of the string uppercase before conversion. Some of the mmio functions require a pointer to a structure of type MMCKINFO (multimedia chunk information). This structure is shown in Figure 3. In the examples below, I'll use the variable name mmckinfo as a structure of type MMCKINFO. CREATING A RIFF FILE To open a file using the mmio functions, the first step is to call hmmio = mmioOpen (szFilename, &mmioinfo, dwFlags) ; The function returns a handle to the file. The second parameter can be a pointer to an MMIOINFO structure (not the MMCKINFO structure discussed above), but in many cases you can set that parameter to NULL. The dwFlags parameter specifies whether you want to create the file or open the file for reading or writing; it also lets you indicate sharing modes and other information. The following function creates a chunk in the file: wError = mmioCreateChunk (hmmio, &mmckinfo, wFlags) ; There are two ways to use this function: If you are creating a chunk that is not a RIFF chunk or a LIST chunk, prepare for the call by doing the following: * Set the ckid field of the MMCKINFO structure to the four-character code of the chunk type. * Optionally set the cksize field to the chunk size of the data in the chunk. * Set the wFlags parameter of mmio-CreateChunk to 0. In this case, mmioCreateChunk writes 8 bytes to the file--the chunk type (from the ckid field) and the chunk size (from the cksize field). The file pointer is left positioned at the end of the chunk size. If you are creating a RIFF or a LIST chunk, then prepare as follows: * Set the fccType field of the MMCKINFO structure to the four-character code of the form type (for a RIFF chunk) or the list type (for a LIST chunk). * Optionally set the cksize field to the chunk size of the data in the chunk. * Set the wFlags parameter of the function to MMIO_CREATERIFF or MMIO_CREATELIST to create a RIFF chunk or a LIST chunk. In this case, mmioCreateChunk writes 12 bytes to the file--the chunk-type ("RIFF" or "LIST"), chunk size (from the cksize field), and form type (from the fccType field). The file pointer is left positioned at the end of the form type. In either case, you don't have to set the cksize field of the structure. The file's chunk-size field can be filled in at a later time by calling mmioAscend (as we'll see). On return from the mmioCreate-Chunk function, the file pointer and the dwDataOffset field of the structure will be set to the beginning of the chunk-data area relative to the beginning of the file. Next write the chunk data using lWritten = mmioWrite (hmmio, pData, lSize) ; The pointer can be to a memory block greater than 64K. The size of the data is given in the last parameter, and the function returns the number of bytes written. This may be less than the number of bytes requested if you run out of disk space. After writing the chunk data, you call wError = mmioAscend (hmmio, &mmckinfo, 0) ; The mmioAscend function has two distinct purposes, one when reading a RIFF file and another when writing to one. When use in conjunction with mmioCreateChunk and mmioWrite while writing to a file, mmioAscend fills in the chunk size for the chunk originally created by mmio-CreateChunk. The MMCKINFO structure passed to mmioAscend must be the same MMCKINFO structure passed earlier to mmioCreateChunk to create the chunk. The mmioAscend function works by subtracting the dwDataOffset field of the structure from the current file pointer (which will now be at the end of the chunk data) and storing that value before the data. The mmioAscend function also takes care of data padding if the chunk data is not a multiple of 2 bytes in length. RIFF files are composed of nested levels of chunks. For mmioAscend to work correctly, you must maintain multiple MMCKINFO structures, each of which is associated with a level in the file. The DRUM data files have three levels. Hence, in the DrumFileWrite function in DRUMFILE.C, I've defined an array of three MMCKINFO structures, which can be referenced as mmckinfo[0], mmckinfo[1], and mmckinfo[2]. Mmckinfo[0] is used in the first mmio-CreateChunk call to create a RIFF chunk type with a DRUM form type. This is followed by a second mmioCreateChunk call using mmckinfo[1] to create a LIST chunk type with an INFO list type. A third mmioCreateChunk call using mmckinfo[2] creates a chunk type of ISFT, identifying the software that created the data file. Following the mmioWrite call to write the string szSoftware, a call to mmioAscent using mmckinfo[2] fills in the chunk size field for this chunk. This is the first completed chunk. The next chunk is also within the LIST chunk. The program proceeds with another mmioCreateChunk call to create an ISCD (creation data) chunk, using mmckinfo[2]. After the mmioWrite call to write the chunk data, a call to mmioAscend using mmckinfo[2] fills in the chunk size. That's the end of this chunk, and it is also the end of the LIST chunk. To fill in the chunk-size field of the LIST chunk, mmioAscend is called again, this time using mmckinfo[1], which was originally used to create the LIST chunk. To create the "fmt " and "data" chunks, mmioCreateChunk uses mmckinfo[1]; the mmioWrite calls are followed by mmioAscend, also using mmckinfo[1]. Now all the chunk sizes have been filled in except for the RIFF chunk itself. That requires one more call to mmioAscend using mmckinfo[0]. There's only one call left, and that's to mmioClose. It probably seems as if an mmioAscend call changes the current file pointer, and it certainly may in order to fill in the chunk size, but by the time the function returns, the file pointer is restored to its position at the end of the chunk data (or perhaps incremented by 1 byte for data padding). All writing to the file is sequential from beginning to end. After a successful mmioOpen call, nothing can really go wrong except running out of disk space. I use the variable wError to accumulate error codes from the mmioCreateChunk, mmioWrite, mmioAscend, and mmioClose call, each of which could fail if insufficient disk space is available. If that happens, the file is deleted using mmioOpen with the MMIO_DELETE constant, and an error message is returned to the caller. READING A RIFF FILE Reading a RIFF file is similar to creating one, except that mmioRead is called instead of mmioWrite, and mmioDescend is called rather than mmioCreateChunk. To descend into a chunk means to locate a chunk and put the file pointer after the chunk size (or after the form type or list type for a RIFF or LIST chunk type). To ascend from a chunk means to move the file pointer to the end of the chunk data. Neither the mmioDescend nor mmioAscend functions move the file pointer to an earlier position in the file. The documentation for mmioDescend is confusing. Let's use a cookbook approach to examine the function: You want a separate MMCKINFO structure for each level in the file. I'll refer to these structures as mmckinfo[0], mmckinfo[1], and mmckinfo[2]. The first thing to do after opening a file is to verify that it is in the RIFF format and, optionally, that the form type is the one you want. If you're only interested in a specific form type, set the fccType field of the MMCKINFO structure to that form type and call wError = mmioDescend (hmmio, &mmckinfo[0], NULL, MMIO_FINDRIFF) ; Watch out: The documentation indicates that the ckid field should be set to the form type. But the mmioDescend function called with the MMIO_FINDRIFF parameter does not even check that field. If the fccType field is not set to a form type, mmioDescend will return successfully for a RIFF file with any form type. Then you will have to check the fccType field explicitly. After this function call, the ckid field will contain "RIFF", the cksize field will have the chunk size, the fccType will be the form type you specified (or the form type of the file), and dwDataOffset will indicate the position in the file just after the form type (that is, 12 bytes). Now you're ready to search for chunk types within the RIFF chunk. If the chunk types that interest you occur in a fixed order (as in a waveform audio file or a DRUM file, where the "fmt " chunk must precede the "data" chunk), set the ckid field of the mmckinfo[1] structure to the first chunk type you need (for example, the four-character code for "fmt") and call wError = mmioDescend (hmmio, &mmckinfo[1], &mmckinfo[0], MMIO_FINDCHUNK) ; The third parameter indicates a "parent" chunk as defined by the MMCKINFO structure. Notice that the last parameter is MMIO_FINDCHUNK. After this function call, the fields of the mmckinfo[1] structure are set as follows: ckid is the chunk type you specified, cksize is the size of the chunk, fccType is set to 0, and dwOffset indicates the offset from the beginning of the file to the beginning of the chunk data. Now you can read the chunk using mmioRead: lRead = mmioRead (hmmio, pData, lSize) ; After reading the chunk data, call mmioAscend (hmmio, mmckinfo[1], 0); This moves the file pointer to the end of the chunk data, accounting for possible padding. You can now search for the next chunk you need using mmioDescend, read it with mmioRead, and move to the end of the chunk data with mmioAscend. If the ordering of the chunk types is not defined, set the ckid field of the mmckinfo[1] structure to 0 before calling the mmioDescend function with the MMIO_FINDCHUNK parameter. The function will find the next subchunk, and you can then check the ckid field of the structure to determine the chunk type. If you're not interested in the chunk, call mmioAscend and mmioDescend again. MmioDescend will return an error code if no more subchunks are present. If the chunk type is "LIST", mmio- Descend will correctly increment the file pointer to follow the form type. You can check the fccType field of the mmckinfo[1] structure for the list type. If you're interested in this list type, you can descend into the subchunks by calling the mmioDescend function with mmckinfo[3]. (The chunks probably won't be in a specific order, so you will set the ckid field to 0L.) Otherwise, just call mmioAscend with mmckinfo[2] to skip the LIST chunk. You can also search for a specific LIST type by calling mmioDescend with the MMIO_FINDLIST parameter. If you are interested in a particular list type, set the fccType field of the MMCKINFO structure to that list type. DRUM is interested only in the "fmt data" chunks of the RIFF file it uses for storing data. The code in DRUMFILE.C follows the cookbook approach, and most of the work involves verifying that the file follows the correct format. COMING UP: MIDI Input If you attach a MIDI keyboard (or other MIDI controller) to the MIDI In port of a MIDI board, you can also use Multimedia Windows to read MIDI messages. In the next column, we'll begin an exploration of MIDI input.