docs/user/midi2/MidiConsumer.dox

   1 /*!
   2         \file MidiConsumer.h
   3         \ingroup midi2
   4         \brief Defines consumer classes for the MIDI Kit.
   5 */
   6
   7
   8 /*!
   9         \class BMidiConsumer MidiConsumer.h
  10         \ingroup midi2
  11         \brief Receives MIDI events from a producer
  12
  13         A consumer is an object that knows how to deal with incoming MIDI events. A
  14         consumer can be connected to multiple producers at the same time. There is no
  15         way to find out which producers are connected to this consumer just by looking
  16         at the BMidiConsumer object; you will have to consult BMidiRoster for that.
  17
  18         A BMidiConsumer either represents a local consumer, i.e. a class extending from
  19         BMidiLocalConsumer, or is a proxy for a remote object published by another app.
  20 */
  21
  22
  23 /*!
  24         \fn bigtime_t BMidiConsumer::Latency() const
  25         \brief Returns the latency of this consumer
  26
  27         The latency is measured in microseconds. Producers should attempt to get MIDI
  28         events to this consumer by <I>(when - latency)</I>. You do this by subtracting
  29         the latency from the performance time when you spray the events (provided that
  30         you spray these events ahead of time, of course).
  31
  32         You cannot <I>set</I> the latency on a BMidiConsumer, only on a
  33         BMidiLocalConsumer.
  34
  35         The latency issue gets slightly more complicated when multiple endpoints are
  36         chained together, as in the following picture:
  37
  38 \verbatim
  39 +-------+     +-------------+     +-------+
  40 |       |     |             |     |       |
  41 | prodA |---->| consB prodB |---->| consC |
  42 |       |     |             |     |       |
  43 +-------+     +-------------+     +-------+
  44   appA          appB (filter)       appC
  45 \endverbatim
  46
  47         Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply
  48         reports 100ms, then prodA will schedule its events for (t - 100), which is
  49         really 200ms too late. (Of course, producers send out their events as soon as
  50         possible, so depending on the load of the system, everything may work out just
  51         fine.)
  52
  53         ConsB should report the latency of the consumer that is hooked up to its
  54         output, consC, in addition to its own latency. In other words, the full
  55         downstream latency. So, the reported latency in this case would be 300ms. This
  56         also means that appB should change the latency of consB when prodB makes or
  57         breaks a connection, and when consC reports a latency change. (If multiple
  58         consumers are connected to prodB, you should take the slowest one.)
  59         Unfortunately, the Midi Kit provides no easy mechanism for doing any of this,
  60         so you are on your own here.
  61 */
  62
  63 /*!
  64         \class BMidiLocalConsumer MidiConsumer.h
  65         \ingroup midi2
  66         \brief A consumer endpoint that is created by your own application.
  67
  68         If you want to create a consumer that reacts to MIDI events, you should
  69         subclass BMidiLocalConsumer.
  70
  71         Each local consumer has its own thread that receives and dispatches the MIDI
  72         events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to
  73         a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so
  74         on. Calls to these hook functions are serialized -- they will never have to be
  75         re-entrant. They also should not be called from outside the thread that is
  76         invoking them.
  77
  78         Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer
  79         doesn't provide default implementations for them, so you don't have to call a
  80         hook's default implementation if you override it. For complete control, you can
  81         also override Data().
  82
  83         Most hook functions take a channel argument. Even though MIDI channels are
  84         really numbered 1 through 16, the hook functions work with channels 0 through
  85         15. The performance time for the event is specified in microseconds relative to
  86         the system time base. A performance time that is 0 (or really any time in the
  87         past) means "play as soon as possible". See the \ref midi2time "introduction"
  88         for more information about timing and consumers.
  89
  90         The thread driving the consumer's events is a very high priority real time
  91         thread. Events should be handled as quickly as possible (not counting
  92         snoozing). If non-time-critical computation is needed it may be wise to queue
  93         events up for a lower priority thread to handle them external to the main event
  94         thread.
  95 */
  96
  97
  98 /*!
  99         \fn BMidiLocalConsumer::BMidiLocalConsumer(const char *name = NULL)
 100         \brief Creates a new local consumer endpoint
 101
 102         The new endpoint is not visible to other applications until you Register() it.
 103
 104         You can tell the constructor what the name of the new consumer will be. If you
 105         pass NULL (or use the default argument), then the consumer's name will be an
 106         empty string. It won't be NULL, since endpoint names cannot be NULL.
 107
 108         There is no guarantee that the endpoint will be successfully created. For
 109         example, the Midi Server may not be running. Therefore, you should always call
 110         IsValid() after creating a new endpoint to make sure that everything went okay.
 111         If not, Release() the object to reclaim memory and abort gracefully.
 112
 113 \code
 114 MyConsumer* cons = new MyConsumer(...);
 115 if (!cons->IsValid())
 116 {
 117     cons->Release();
 118     ...exit gracefully...
 119 }
 120 \endcode
 121
 122 */
 123
 124
 125 /*!
 126         \fn void BMidiLocalConsumer::SetLatency(bigtime_t latency)
 127         \brief Changes the published latency of the consumer.
 128
 129         \sa Latency()
 130 */
 131
 132
 133 /*!
 134         \fn int32 BMidiLocalConsumer::GetProducerID()
 135         \brief Returns the ID of the producer that most recently sent a MIDI event to
 136                    this consumer.
 137
 138         You can call this from one of the hooks to determine which producer the event
 139         came from.
 140 */
 141
 142
 143 /*!
 144         \fn void BMidiLocalConsumer::SetTimeout(bigtime_t when, void* data)
 145         \brief Requests that the Timeout() hook will be called at some point.
 146
 147         This method asks the consumer thread to call the Timeout() hook as soon as
 148         possible after the timeout expires. For every call to SetTimeout(), the
 149         Timeout() hook is only called once. Note: the term "timeout" may be a little
 150         misleading; the hook will <I>always</I> be called, even if events are received
 151         in the mean time. Apparently, this facility is handy for dealing with early
 152         events.
 153
 154         Note that the event thread blocks on the consumer's port as long as no events
 155         arrive. By default no timeout is set, and as a result the thread blocks
 156         forever. Your call to SetTimeout() doesn't change this. The new timeout value
 157         will go into effect the next time the thread tries to read from the port, i.e.
 158         after the first event has been received. If no event ever comes in, the
 159         Timeout() hook will never be called. This also means that you cannot cancel a
 160         timeout once you have set it. To repeat, calling SetTimeout() only takes effect
 161         after at least one new event has been received.
 162
 163         \param when An absolute time that's measured against the system clock.
 164
 165         \param data A pointer to a "cookie" that you can pass along to Timeout(). The
 166         data is not copied, so you must ensure that the pointer remains valid until
 167         Timeout() is called. You typically delete the data inside Timeout().
 168 */
 169
 170
 171 /*!
 172         \fn void BMidiLocalConsumer::Timeout(void* data)
 173         \brief Hook function that is called per your own request.
 174
 175         \sa SetTimeout()
 176 */
 177
 178 /*!
 179         \fn void BMidiLocalConsumer::Data(uchar* data, size_t length, bool atomic,
 180                 bigtime_t time)
 181         \brief Invoked when raw MIDI is received.
 182
 183         What the default implementation of Data() does depends on the value of atomic.
 184         If atomic is true, the data received comprises a single MIDI event; i.e. one
 185         status byte followed by the appropriate number of data bytes and nothing else.
 186         In this case, Data() calls the event-specific hook function that corresponds to
 187         that status byte. This optimization is used by the Midi Kit to allow faster
 188         dispatch of events generated by the specific Spray functions from
 189         BMidiLocalProducer.
 190
 191         If atomic is false, Data() ignores the MIDI event. If you want a consumer to
 192         handle non-atomic events, you have to override Data() and program this
 193         yourself. In that case, you probably also want to call the default
 194         implementation to handle the "normal" MIDI events.
 195
 196         Data() is rarely overridden, but you can override it if you want to. If you do,
 197         remember that the data buffer is owned by the Midi Kit. Do not attempt to
 198         modify or free it, lest you wish to be laughed at by other developers.
 199
 200         \param data the MIDI event data
 201         \param length byte size of the data buffer
 202         \param atomic whether the data buffer contains a single complete MIDI event
 203         \param time the requested performance time of the event
 204
 205         \sa BMidiLocalProducer::SprayData()
 206 */
 207
 208
 209 /*!
 210         \fn void BMidiLocalConsumer::NoteOff(uchar channel, uchar note,
 211                 uchar velocity, bigtime_t time)
 212         \brief Invoked when a Note Off event is received.
 213
 214         \sa BMidiLocalProducer::SprayNoteOff()
 215 */
 216
 217
 218 /*!
 219         \fn void BMidiLocalConsumer::NoteOn(uchar channel, uchar note,
 220                 uchar velocity, bigtime_t time)
 221         \brief Invoked when a Note On event is received.
 222
 223         \sa BMidiLocalProducer::SprayNoteOn()
 224 */
 225
 226
 227 /*!
 228         \fn void BMidiLocalConsumer::KeyPressure(uchar channel, uchar note,
 229                 uchar pressure, bigtime_t time)
 230         \brief Invoked when a Polyphonic Pressure (Aftertouch) event is received.
 231
 232         \sa BMidiLocalProducer::SprayKeyPressure()
 233 */
 234
 235
 236 /*!
 237         \fn void BMidiLocalConsumer::ControlChange(uchar channel,
 238                 uchar controlNumber, uchar controlValue, bigtime_t time)
 239         \brief Invoked when a Controller Change event is received.
 240
 241         \sa BMidiLocalProducer::SprayControlChange()
 242 */
 243
 244
 245 /*!
 246         \fn void BMidiLocalConsumer::ProgramChange(uchar channel,
 247                 uchar programNumber, bigtime_t time)
 248         \brief Invoked when a Program Change event is received.
 249
 250         \sa BMidiLocalProducer::SprayProgramChange()
 251 */
 252
 253
 254 /*!
 255         \fn void BMidiLocalConsumer::ChannelPressure(uchar channel,
 256                 uchar pressure, bigtime_t time)
 257         \brief Invoked when a Channel Pressure event is received.
 258
 259         \sa BMidiLocalProducer::SprayChannelPressure()
 260 */
 261
 262
 263 /*!
 264         \fn void BMidiLocalConsumer::PitchBend(uchar channel, uchar lsb,
 265                 uchar msb, bigtime_t time)
 266         \brief Invoked when a Pitch Bend event is received.
 267
 268         \sa BMidiLocalProducer::SprayPitchBend()
 269 */
 270
 271
 272 /*!
 273         \fn void BMidiLocalConsumer::SystemExclusive(void* data, size_t length,
 274                 bigtime_t time)
 275         \brief Invoked when a System Exclusive event is received.
 276
 277         The data does not include the sysex start and end control bytes
 278         (0xF0 and 0xF7), only the payload of the sysex message.
 279
 280         The data belongs to the Midi Kit and is only valid for the duration of
 281         this event. You may not modify or free it.
 282
 283         \sa BMidiLocalProducer::SpraySystemExclusive()
 284 */
 285
 286
 287 /*!
 288         \fn void BMidiLocalConsumer::SystemCommon(uchar status, uchar data1,
 289                 uchar data2, bigtime_t time)
 290         \brief Invoked when a System Common event is received.
 291
 292         Not all data bytes are used for all common events. Unused bytes are
 293         set to 0.
 294
 295         \sa BMidiLocalProducer::SpraySystemCommon()
 296 */
 297
 298
 299 /*!
 300         \fn void BMidiLocalConsumer::SystemRealTime(uchar status, bigtime_t time)
 301         \brief Invoked when a Real Time event is received.
 302
 303         \sa BMidiLocalProducer::SpraySystemRealTime()
 304 */
 305
 306
 307 /*!
 308         \fn void BMidiLocalConsumer::TempoChange(int32 beatsPerMinute, bigtime_t time)
 309
 310         \brief Invoked when a Tempo Change event is received
 311         \sa BMidiLocalProducer::SprayTempoChange()
 312 */
 313
 314
 315 /*!
 316         \fn void BMidiLocalConsumer::AllNotesOff(bool justChannel, bigtime_t time)
 317         \brief Not used.
 318 */