DxMidi Tutorial - MidiModule project - chapter 1 |
To follow this tutorial you need :
RealBasic 2 |
Considerations We implicitely introduce DxMidi functions directly, considering that you know well the Midi specifications (or quite well), and the Midi implementation and interface connections between the Macintosh and instruments. DxMidi was created with the idea that a program, that would be as simple to write as possible, could posess in it the standard Midi functions and all the power of other standard Music commercial program. Realbasic is really efficient to this purpose and the deal between Basic and Midi seems to be very near the Realbasic philosophy. First, we will introduce you to the DxMidi "client" interface, and the methods that you must use in every program to connect your program to Midi. The examples are choosed for more clarity but a commercial product will be a little more complex to prevent any case (Mac compatibility, Interface missing, etc.).
Midi manager - OMS : the choice ? To connect Midi to a Mac, maybe you are using serial driver. It is cool to develop a Midi interface with the serial driver and RealBasic, but you will lose long long hours to program functions, debug, and... crash ! There is now a best method : use a driver. The reason ? ok !... now, the music world evoluates on the Macintosh and the Midi devices are not only present on the serial port, but also on PCI cards, ! For those reasons, and because you will use more than one Midi application on a Mac, Opcode created OMS, a driver leader on the Mac music market to implement Midi applications and you studio. Yesterday, Apple was on the road with its Apple Midi Manager, that is a big driver, always active and compatible, but limited to serial driver. because market evolution and law problems (with the Beatles and Apple records), Apple renounced to the driver, but currently let you the opportunity to download it on its server. OMS it the new way to make Midi music on the mac, with the complementarity of Audio power (PCI cards with softwares). OMS is not as easy to use as Midi manager but you really can do the same things, without any difference (moreover, OMS keep into his code the Midi Manager compatibility). There is other drivers for the Macintosh, FreeMidi, Midishare, etc. but it seems that it's a hard way (for us) to be compatible with all of them. Do you need to choice between OMS and Midi Manager ? Maybe yes, maybe not. For a simple and easy to implement application, use the Midi Manager. To write big and compatible application, use OMS. If you want the most of compatiblity, test OMS and Midi manager. If OMS is not present, test Midi Manager presence, and sign with one of them. (If OMS and Midi Manager are active, select OMS, and don't sign with the other).
Project 1 First, we consider a Midi Manager application with a simple connection (IN and OUT). It is very simple to do it and will surprise you by this easyness. Open the midi. folder, and open the midi01.rbp project. It is the Midi Manager connection program. The simplest as we could write with DxMidi. - Verify that Midi Manager is active (report to the Midi Manager installation guide included in this manual), Project window Open the project and examine the items : Menu item : App : Application : Midi : Application Midi client scope Because most of Midi applications needs to sign to Midi at start, and sign out at end, we need to do the same with an "Application" module wich is specific to RealBasic system. it permits to open the program without opening first a window. There will be times when you want just to start application without opening a window ! Make like this to maintain good client relation with the Midi driver, and force application to sign out at the end.
Application : "Open" event This procedure executes two methods : Connect_midi is a custom method to connect DxMidi to the driver When close is executed, at the end of the program, disconnect_midi, examines Midi connection and sign out to the driver if the connection was active. By this, you are shure that the client has sign out at the end, without any other code elsewhere. Midi module This module maintains ours connect_midi and disconnect_midi methods. Open the module (double-click on it). And see the code. This is the connection code. Just to connect to Midi manager as a "client". You can see also the global variables (properties of the "Midi" module). Midi connection Desciption of the code : mm_connected = false This setting implicite that the connection is off, at start. avail = DxMidiMMAvail() DxMidiMMAvail is a DxMidi method. It allow you to know if the driver is active in the system. If not, you must not call any other DxMidi function, or you could get an error (or fatal error). The local Boolean variable avail is the result of this method and gives you "TRUE" if the driver is active. if avail = true then This is necessary code to prevent any other problem is the driver is not active. result = DxMMConnect("dfmm","miditest") This is the connection code itself. At this point, you send a command to DxMidi to ask the driver to sign IN into it. The OSTYPE is the same "Type" as your application type when you define the bundle for a commercial program. It is a 4 byte code (it draws a 32 bit unique value). If the signature is successful, result contains "0", which is the 'noErr' code for DxMidi implementation (and many other Macintosh managers). If the signature failed, the value could be any other value (see the implementation manual). if result = 0 then Now, you are sure that the connection is active, and you can set the global property "mm_connected" to TRUE to let the program runs with other Midi commands. - to test mm_connected each time you want to place a DxMidi command to play music. In our example, we just test for mm_connected into the program when we want to send a DxMidi command. NOTE : an DxMidi internal system prevents calls to functions that could crash the driver communication, but it is not a reason to don't assume your program protection !
Midi disconnection This time, we just have to close the connection if it is active. Just test this value and close the client session is it is TRUE. if mm_connected = true then You don't have to set anymore mm_connected after DxMMdisconnect() but just do it for clearity of the program. Next step : test the program, with Apple Midi Manager Patchbay help See the connection To see the action made, open the patchbay accessory (in the apple menu), and observe the window : Only the Apple Midi Driver is here (it represents the Midi connection with physical output, and all the serial Driver facilities). Then, return in Realbasic, and test your app : run the project. Return in the Patchbay : Ok !... there is now a new icon... DxMidi !... and two connections, In and OUT. Then, click on the new icon... Surprise ! ... The prompt title is "miditest", like the text in the DxMidiConnect() command.
Now, return to Realbasic, and close application. If you return to patchbay, you will see that the icon diseappeared again. The connection is closed !
In the next chapter, we will see how to send notes from this project.
1.3 Play one note automatically and for each bank number from 1 to 16.
|
|