Introduction
MIDI Player for SansGUI is a utility program that plays MIDI files and displays their channel data in the SansGUI Modeling and Simulation Environment. In addition to having some fun, we wrote this program to demonstrate simultaneous execution of both external and in-process simulators in SansGUI so that they can work in coordination. After the following Quick Start and Operation Details sections, we will explain some of the Program Elements from the user's point of view.
If you have not installed SansGUI and MIDI Player for SansGUI software from the distribution, please follow the instructions in the Welcome section. Here, we assume that you have SansGUI version 1.1 or later and the MIDI Player utility program installed and ready to go. Follow the steps below to get a quick start:
Run SansGUI.
Select File>Open and load Piano.sgp Project Model file from the samples\MIDIplay subdirectory of your SansGUI installation directory.
Click on the Run External button on the Run toolbar. The toolbar may be located at the right side of your SansGUI window. As depicted below, the Run External button is the up-pointing green triangle, which is similar to the eject button on your VCR or CD/DVD player. If you have installed the software properly, a command window will appear and the external process program of the MIDI Player program will start to play Scott Joplin's The Entertainer.
While the music is playing, click on the Run In-Process button on the Run toolbar. It is the right pointing green triagle, similar to the play button on your VCR or CD/DVD player.
When you see the in-process program running with messages scrolling in the bottom pane, click on the Plot Results button on the Run toolbar. The button has a X-Y Plot icon located in the last position of the Run toolbar.
You should see the pitch information of the MIDI data being plotted in strip charts. The screen should look like the title image in the Welcome section. When the music ends, both programs will stop. If you would like to play the music again, you can start it by running the external program. If you want to stop the music while it is being played, simply click on the command window that has the external MIDI Player running and type in Ctrl-C. The in-process program will detect the interruption and will stop automatically.
It does not really matter when you click on the Plot Results button on the Run toolbar. SansGUI activates the Plot Results function button whenever there are attributes logged and selected for plotting. You can click on it to display the Plot Results Dialog before playing the MIDI music, before starting the in-process program to fetch the MIDI data, or while the music is playing and the data in the Result View is scrolling.
The input parameters of the Piano.sgp Project Model are stored in a myMIDI reference object derived from the Collection.MIDI class. Every MIDI Player Project Model file should have a unique reference object derived from such class that all the channel components (parts) can refer to it.
You can locate it by clicking on the Object tab (the first tab) in the Left Pane and scroll down to the bottom to reveal the object from the Tree View. If the branches are collapsed, click on the small plus icon to expand them.
When you see the myMIDI object, double click on the name or its icon to obtain an Object Properties dialog, as shown below.
The MIDI file for playing is specified in the MIDI File Name field. If you would like to play other MIDI file that you have created or downloaded, right click on the Value cell, select Input Assistant from the context menu, click on the <File / Dir>... button to obtain a File dialog, and use it to locate the MIDI file. The file name is enclosed by a pair of angle brackets < >. If there is no directory path in the file name, the file is located in the same directory as the Project Model file; otherwise, absolute or relative file path information may be included. The file name is displayed in green, meaning that it is a hyperlink to the file. If you have the .mid extension registered in the Windows registry for a certain MIDI file player (such as Windows Media Player), you can invoke that program to play the file by right clicking on the Value cell and select Open from the context menu.
The Unique Name for Shared Memory can be any string that identifies the communication channel between the external process and the in-process MIDI player program.
The Sampling Interval is set to 50 milliseconds initially. It is the time delay for the in-process program to sample the MIDI data in the shared memory from the previous sampling cycle. You can set it to 0 so that the in-process program will work as fast as it can, or increase the value to "slow down" the data charting. Please note that this is a simple implementation without taking true real-time system requirements into account.
You don't need to modify the Current Sampling Time field. It will be reset to 0 each time the in-process program is run.
By default, the Piano.sgp Project Model looks up MIDI data from channel 0 and channel 1. You can create more parts to look up data from more MIDI channels. Each channel part contains an input attribute, Channel Number, being used to fetch its channel data from the MIDI events. The Ch16.sgp Project Model has been created to show how to access channel 0 through 15.
The reason for creating S-1 through S-4 subclasses is that MIDI Player allows data to be plotted to up to four strip charts. If you would like to plot multiple data curves into the same strip, simply create the parts from the same S-n subclass. Again, please load Ch16.sgp to see more details.
When you create a new part for a MIDI channel, you need to enter the Channel Number to match one of those in the particular MIDI file.
The MIDI Message Object is an object reference field, meaning that it has to contain the name of a reference object derived from the Collection.MIDI class. This is the object we use to enter paramters for the MIDI Player, as described previously.
This MIDI Player utility program consists of two executable elements:
Invoked from the Run External button: a console-based program (.EXE) that is executed in an external process outside SansGUI. It reads the MIDI file, sends the MIDI stream to the Windows multimedia facility, and passes the MIDI channel numbers and data to the in-process program (.DLL).
Invoked from the Run In-Process button: an in-process program (.DLL) that fetches the channel numbers and data from the external process program and interacts with SansGUI to plot the data in each channel.
When you run the external program in SansGUI, it writes out a textual model file that contains all the necessary information, including the values of the attributes in the myMIDI object described previously, for the MIDI player to read. The in-process program is tightly coupled with SansGUI for data access and display.
Please see the Developer's Corner section for implementation details of this program.
|
Icon |
Class |
Description |
|
|
Class containing common parameters shared by the external process and in-process programs for playing MIDI files. | |
|
|
Abstract class to implement common behavior for the S-1 to S-4 subclasses below. | |
|
|
Component class for creating MIDI channels to receive data from the external process program. | |
|
|
MIDI player control for the in-process program. | |
|
|
MIDI player control for the external process program. |
 |
 |
MIDI Player for SansGUI Version 1.0
Copyright © 2002-2003 ProtoDesign, Inc. All rights reserved.
