MIDI data streams through your application, passing from one BMidi-derived object to another. Each object does whatever it's designed to do: Sends the data to a MIDI port, writes it to a file, modifies it and passes it on, and so on.

You form a tree of BMidi objects through BMidi's Connect() function, which takes a single BMidi argument. By calling Connect(), you connect the output of the calling object to the input of the argument object. (i.e. the caller is the source; the argument is the destination.)

Let's say you want to connect a MIDI keyboard to your computer, play it, and have the performance recorded in a file. You connect a BMidiPort object, which reads data from the MIDI port, to a BMidiStore object, which stores the data that's sent to it and can write it to a file:

/* Connect the output of a BMidiPort to the input of a BMidiStore. */
BMidiPort m_port;
BMidiStore m_store;

m_port.Connect(&m_store);

You also have to tell the BMidiPort to start listening to the MIDI port, by calling its Start() function. This is explained in a later section.

Once you've made the recording, you can play it back by re-connecting the objects in the opposite direction:

/* We'll disconnect first, although this isn't strictly necessary. */
m_port.Disconnect(&m_store);
m_store.Connect(&m_port);

In this configuration, a Start() call to m_store would cause its MIDI data to flow into the BMidiPort (and thence to a synthesizer, for example, for realization).

a_midi.Connect(&b_object);
a_midi.Connect(&c_object);
a_midi.Connect(&d_object);

b_midi.Connect(&e_object);
c_midi.Connect(&e_object);
d_midi.Connect(&e_object);

If your class wants to generate new MIDI data (as opposed to filtering or realizing the data it receives), it must implement the Run() function. An implementation of Run() should include a while() loop that broadcasts one or more MIDI message on each pass (typically it broadcasts only one), by invoking a spray function. To predicate the loop you must test the value of the KeepRunning() boolean function.

The outline of a Run() implementation looks like this:

void MyMidi::Run()
{
   while (KeepRunning()) {
      /* Generate a message and spray it. For example... */
      SprayNoteOn(...);
   }
   /* You MUST exit when KeepRunning() returns false. */
}

Warning

The Run() function must exit when KeepRunning() returns false. If it doesn't, you'll leak threads.

To tell an object to perform its Run() function, you call the object's Start() function—you never call Run() directly. Start() causes the object to spawn a thread (its "run" thread) and execute Run() within it. When you're tired of the object's performance, you call its Stop() function.

Keep in mind that the Run() function is only needed in classes that introduce new MIDI data into a performance. As examples, BMidiStore's Run() sprays messages that correspond to the MIDI data that it stores, and BMidiPort reads data from the MIDI port and sprays messages accordingly.

Another point to keep in mind is that the Run() function can run ahead of real time. It doesn't have to generate and spray data precisely at the moment that the data needs to be realized. This is further explained in the section "Time".

Note

The BMidiSynthFile class differs from the other classes in the way that it implements and uses its Run() function; in particular, it doesn't spawn a run thread. See the BMidiSynthFile class for more information.

The spray functions send data to the BMidi objects that are connected to the running object's output. There's a separate spray function for each of the MIDI message types: SprayNoteOn(), SprayNoteOff(), SprayPitchBend(), and so on. Spray functions are always found within a BMidi's Run() loop, but they can be found in other places as well. For example, if you're creating a MIDI filter, you would use spray functions in the implementations of the object's MIDI hook functions (as explained next).

The MIDI hook functions are hooks that are invoked upon an object's connections when the object sprays MIDI data. The functions take the names of the MIDI messages to which they respond: NoteOn() responds to a Note On message, NoteOff() responds to a Note Off, and so on. For example, this…

a_midi.Connect(&b_midi);
a_midi.SprayNoteOn(...);

…causes b_midi's NoteOn() function to be invoked. The arguments that are passed to NoteOn() are taken directly from the SprayNoteOn() call.

BMidi doesn't provide default implementations for any of the MIDI hooks; it's up to each BMidi-derived class to decide how to respond to MIDI messages.

Every BMidi object automatically spawns an "inflow" thread when it's constructed. It's in this thread that the spray-invoked MIDI hooks are executed. The inflow thread is always running—the Start() and Stop() functions don't affect it. As soon as you construct an object, it's ready to receive data.

BMidiSynth midiSynth;

/* Initialize the BMidiSynth as described in that class. */
...
/* Play a note. */
midiSynth.NoteOn(...);

void Transposer::NoteOn(uchar channel, uchar keyNumber,
                  uchar velocity, uint32 time)
{
   uchar new_key = max(keyNumber + 1, 127);
   SprayNoteOn(channel, new_key, velocity, time);
}

Every spray and MIDI hook function takes a final time argument. This argument declares when the message that the function represents should be performed. The argument is given in ticks (milliseconds). Tick 0 occurs when you boot your computer; the tick counter automatically starts running at that point. To get the current tick measurement, you call the global, Kernel Kit-defined system_time() function and divide by 1000 (system_time() returns microseconds).

By convention, time arguments are applied at an object's input. In other words, a MIDI hook should look at the time argument, wait until the designated time, and then do whatever it does that it does do. However, this only applies to BMidi-derived classes that are designed to perform MIDI data. Objects that simply filter data shouldn't apply the time argument.

To apply the time argument, you call the SnoozeUntil() function, passing the value of time. For example, a "performance" NoteOn() function would look like this:

void MyPerformer::NoteOn(uchar channel, uchar keyNumber,
                  uchar velocity, uint32 time)
{
   SnoozeUntil(time);
   /* Perform the data here. */
}

If time designates a tick that has already tocked, SnoozeUntil() returns immediately; otherwise it tells the inflow thread to snooze until the designated tick is at hand.

If you're implementing the Run() function, then you have to generate a time value yourself which you pass as the final argument to each spray function that you call. The value you generate depends on whether your class runs in real time, or ahead of time.

void MyTicker::Run()
{
   uint32 when = B_NOW;
   uchar key_num;

   while (KeepRunning()) {

      /* Make a new note. */
      SprayNoteOn(1, 60, 64, when);

      /* Turn the note off 99 ticks later. */
      when += 99;
      SprayNoteOff(1, 60, 0, when);

      /* Bump the when variable so the next Note On
      * will be 100 ticks after this one.
      */
      when += 1;
   }
}