Some more work on the Doxygen version of the haiku_book.
I will keep working on the Docbook version, but as I'm still not completely comfortable with that as final choice, I'm playing around with this as well. The String.cpp file contained doxygen documentation for almost all methods, I copied those to a new file (string.dox) and grouped them accordingly. (Done because Axel is absolutely against in-header or in-source docs) Integrated the BMidiConsumer and BMidiLocalConsumer class into the same file (like I did now to the producers), since I think it's better to keep a 1:1 relation with the headers. Removed the mididefs.dox file and replaced it with the midi2/Midi2Defs.dox file which actually documents the Midi2Defs.h file, rather than contain a custom page that was somewhat hard to find. Please see http://www.myhouserules.nl/haiku_book/index.html for a generated book from the current source. I actually quite like the output so far, though I'm aware of the fact that I needed to perform some tricks to let Doxygen get to this point. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@19651 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
@@ -0,0 +1,279 @@
|
||||
/*!
|
||||
\file Midi2Defs.h
|
||||
\ingroup midi2
|
||||
*/
|
||||
|
||||
/*!
|
||||
\name Channel Message Masks
|
||||
\brief Some definitions to define the raw MIDI events.
|
||||
|
||||
The default implementation of BMidiLocalConsumer::Data() uses these constants
|
||||
to determine which event has been passed on. If you override that method, you
|
||||
may use the constants yourself.
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\var B_NOTE_OFF
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_NOTE_ON
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_KEY_PRESSURE
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_CONTROL_CHANGE
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_PROGRAM_CHANGE
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_CHANNEL_PRESSURE
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_PITCH_BEND
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name System Messages
|
||||
\brief Some definitions to define the raw MIDI system messages.
|
||||
|
||||
The default implementation of BMidiLocalConsumer::Data() uses these constants
|
||||
to determine which event system message has been passed on. See
|
||||
BMidiLocalProducer::SpraySystemCommon() and BMidiLocalProducer::SpraySystemRealTime()
|
||||
for more details on how and when to use these messages.
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\var B_SYS_EX_START
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_MIDI_TIME_CODE
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_SONG_POSITION
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_SONG_SELECT
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_CABLE_MESSAGE
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_TUNE_REQUEST
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_SYS_EX_END
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_TIMING_CLOCK
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_START
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_CONTINUE
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_STOP
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_ACTIVE_SENSING
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_SYSTEM_RESET
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Controller Numbers
|
||||
\brief Constants that represent specific controller messages.
|
||||
|
||||
These constants can be used in BMidiLocalProducer::SprayControlChange()
|
||||
and BMidiLocalConsumer::ControlChange(). These constants represent the
|
||||
MIDI specification.
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_MODULATION
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_BREATH_CONTROLLER
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_FOOT_CONTROLLER
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_PORTAMENTO_TIME
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_DATA_ENTRY
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_MAIN_VOLUME
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_MIDI_BALANCE
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_PAN
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_EXPRESSION_CTRL
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_GENERAL_CTRL_1
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_GENERAL_CTRL_2
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_GENERAL_CTRL_3
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_GENERAL_CTRL_4
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_SUSTAIN_PEDAL
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_PORTAMENTO
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_SOSTENUTO
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_SOFT_PEDAL
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_HOLD_2
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_GENERAL_CTRL_5
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_GENERAL_CTRL_6
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_TEMPO_CHANGE
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_GENERAL_CTRL_7
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_GENERAL_CTRL_8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_EFFECTS_DEPTH
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_TREMOLO_DEPTH
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_CHORUS_DEPTH
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_CELESTE_DEPTH
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_PHASER_DEPTH
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_DATA_INCREMENT
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_DATA_DECREMENT
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_RESET_ALL_CONTROLLERS
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_LOCAL_CONTROL
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_ALL_NOTES_OFF
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_OMNI_MODE_OFF
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_OMNI_MODE_ON
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_MONO_MODE_ON
|
||||
*/
|
||||
|
||||
/*!
|
||||
\var B_POLY_MODE_ON
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
@@ -288,7 +288,7 @@ as the BeOS R5 kits, although there are a few small differences in the API
|
||||
|
||||
More about the Midi Kit:
|
||||
|
||||
- \subpage midi2defs
|
||||
- \ref Midi2Defs.h
|
||||
- Be Newsletter Volume 3, Issue 47 - Motor Mix sample code
|
||||
- Be Newsletter Volume 4, Issue 3 - Overview of the new kit
|
||||
- <A HREF="http://open-beos.sourceforge.net/nsl.php?mode=display&id=33">OpenBeOS
|
||||
|
||||
@@ -54,3 +54,238 @@ Unfortunately, the Midi Kit provides no easy mechanism for doing any of this,
|
||||
so you are on your own here.
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\class BMidiLocalConsumer MidiConsumer.h
|
||||
\ingroup midi2
|
||||
\ingroup libmidi2
|
||||
\brief A consumer endpoint that is created by your own application
|
||||
|
||||
If you want to create a consumer that reacts to MIDI events, you should
|
||||
subclass BMidiLocalConsumer.
|
||||
|
||||
Each local consumer has its own thread that receives and dispatches the MIDI
|
||||
events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to
|
||||
a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so
|
||||
on. Calls to these hook functions are serialized -- they will never have to be
|
||||
re-entrant. They also should not be called from outside the thread that is
|
||||
invoking them.
|
||||
|
||||
Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer
|
||||
doesn't provide default implementations for them, so you don't have to call a
|
||||
hook's default implementation if you override it. For complete control, you can
|
||||
also override Data().
|
||||
|
||||
Most hook functions take a channel argument. Even though MIDI channels are
|
||||
really numbered 1 through 16, the hook functions work with channels 0 through
|
||||
15. The performance time for the event is specified in microseconds relative to
|
||||
the system time base. A performance time that is 0 (or really any time in the
|
||||
past) means "play as soon as possible". See the \ref midi2time "introduction"
|
||||
for more information about timing and consumers.
|
||||
|
||||
The thread driving the consumer's events is a very high priority real time
|
||||
thread. Events should be handled as quickly as possible (not counting
|
||||
snoozing). If non-time-critical computation is needed it may be wise to queue
|
||||
events up for a lower priority thread to handle them external to the main event
|
||||
thread.
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BMidiLocalConsumer::BMidiLocalConsumer(const char *name = NULL)
|
||||
\brief Creates a new local consumer endpoint
|
||||
|
||||
The new endpoint is not visible to other applications until you Register() it.
|
||||
|
||||
You can tell the constructor what the name of the new consumer will be. If you
|
||||
pass NULL (or use the default argument), then the consumer's name will be an
|
||||
empty string. It won't be NULL, since endpoint names cannot be NULL.
|
||||
|
||||
There is no guarantee that the endpoint will be successfully created. For
|
||||
example, the Midi Server may not be running. Therefore, you should always call
|
||||
IsValid() after creating a new endpoint to make sure that everything went okay.
|
||||
If not, Release() the object to reclaim memory and abort gracefully.
|
||||
|
||||
\code
|
||||
MyConsumer* cons = new MyConsumer(...);
|
||||
if (!cons->IsValid())
|
||||
{
|
||||
cons->Release();
|
||||
...exit gracefully...
|
||||
}
|
||||
\endcode
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SetLatency(bigtime_t latency)
|
||||
\brief Changes the published latency of the consumer
|
||||
\sa Latency()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int32 BMidiLocalConsumer::GetProducerID()
|
||||
\brief Returns the ID of the producer that most recently sent a MIDI event to
|
||||
this consumer
|
||||
|
||||
You can call this from one of the hooks to determine which producer the event
|
||||
came from.
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SetTimeout(bigtime_t when, void* data)
|
||||
\brief Requests that the Timeout() hook will be called at some point
|
||||
|
||||
This method asks the consumer thread to call the Timeout() hook as soon as
|
||||
possible after the timeout expires. For every call to SetTimeout(), the
|
||||
Timeout() hook is only called once. Note: the term "timeout" may be a little
|
||||
misleading; the hook will <I>always</I> be called, even if events are received
|
||||
in the mean time. Apparently, this facility is handy for dealing with early
|
||||
events.
|
||||
|
||||
Note that the event thread blocks on the consumer's port as long as no events
|
||||
arrive. By default no timeout is set, and as a result the thread blocks
|
||||
forever. Your call to SetTimeout() doesn't change this. The new timeout value
|
||||
will go into effect the next time the thread tries to read from the port, i.e.
|
||||
after the first event has been received. If no event ever comes in, the
|
||||
Timeout() hook will never be called. This also means that you cannot cancel a
|
||||
timeout once you have set it. To repeat, calling SetTimeout() only takes effect
|
||||
after at least one new event has been received.
|
||||
|
||||
\param when An absolute time that's measured against the system clock.
|
||||
|
||||
\param data A pointer to a "cookie" that you can pass along to Timeout(). The
|
||||
data is not copied, so you must ensure that the pointer remains valid until
|
||||
Timeout() is called. You typically delete the data inside Timeout().
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::Timeout(void* data)
|
||||
\brief Hook function that is called per your own request
|
||||
\sa SetTimeout()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::Data(
|
||||
uchar* data, size_t length, bool atomic, bigtime_t time)
|
||||
\brief Invoked when raw MIDI is received
|
||||
|
||||
What the default implementation of Data() does depends on the value of atomic.
|
||||
If atomic is true, the data received comprises a single MIDI event; i.e. one
|
||||
status byte followed by the appropriate number of data bytes and nothing else.
|
||||
In this case, Data() calls the event-specific hook function that corresponds to
|
||||
that status byte. This optimization is used by the Midi Kit to allow faster
|
||||
dispatch of events generated by the specific Spray functions from
|
||||
BMidiLocalProducer.
|
||||
|
||||
If atomic is false, Data() ignores the MIDI event. If you want a consumer to
|
||||
handle non-atomic events, you have to override Data() and program this
|
||||
yourself. In that case, you probably also want to call the default
|
||||
implementation to handle the "normal" MIDI events.
|
||||
|
||||
Data() is rarely overridden, but you can override it if you want to. If you do,
|
||||
remember that the data buffer is owned by the Midi Kit. Do not attempt to
|
||||
modify or free it, lest you wish to be laughed at by other developers.
|
||||
|
||||
\param data the MIDI event data
|
||||
\param length byte size of the data buffer
|
||||
\param atomic whether the data buffer contains a single complete MIDI event
|
||||
\param time the requested performance time of the event
|
||||
|
||||
\sa BMidiLocalProducer::SprayData()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::NoteOff(
|
||||
uchar channel, uchar note, uchar velocity, bigtime_t time)
|
||||
\brief Invoked when a Note Off event is received
|
||||
\sa BMidiLocalProducer::SprayNoteOff()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::NoteOn(
|
||||
uchar channel, uchar note, uchar velocity, bigtime_t time)
|
||||
\brief Invoked when a Note On event is received
|
||||
\sa BMidiLocalProducer::SprayNoteOn()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::KeyPressure(
|
||||
uchar channel, uchar note, uchar pressure, bigtime_t time)
|
||||
\brief Invoked when a Polyphonic Pressure (Aftertouch) event is received
|
||||
\sa BMidiLocalProducer::SprayKeyPressure()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::ControlChange(
|
||||
uchar channel, uchar controlNumber, uchar controlValue, bigtime_t time)
|
||||
\brief Invoked when a Controller Change event is received
|
||||
\sa BMidiLocalProducer::SprayControlChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::ProgramChange(
|
||||
uchar channel, uchar programNumber, bigtime_t time)
|
||||
\brief Invoked when a Program Change event is received
|
||||
\sa BMidiLocalProducer::SprayProgramChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::ChannelPressure(
|
||||
uchar channel, uchar pressure, bigtime_t time)
|
||||
\brief Invoked when a Channel Pressure event is received
|
||||
\sa BMidiLocalProducer::SprayChannelPressure()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::PitchBend(
|
||||
uchar channel, uchar lsb, uchar msb, bigtime_t time)
|
||||
\brief Invoked when a Pitch Bend event is received
|
||||
\sa BMidiLocalProducer::SprayPitchBend()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SystemExclusive(
|
||||
void* data, size_t length, bigtime_t time)
|
||||
\brief Invoked when a System Exclusive event is received
|
||||
|
||||
The data does not include the sysex start and end control bytes (0xF0 and 0xF7),
|
||||
only the payload of the sysex message.
|
||||
|
||||
The data belongs to the Midi Kit and is only valid for the duration of this
|
||||
event. You may not modify or free it.
|
||||
|
||||
\sa BMidiLocalProducer::SpraySystemExclusive()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SystemCommon(
|
||||
uchar status, uchar data1, uchar data2, bigtime_t time)
|
||||
\brief Invoked when a System Common event is received
|
||||
|
||||
Not all data bytes are used for all common events. Unused bytes are set to 0.
|
||||
|
||||
\sa BMidiLocalProducer::SpraySystemCommon()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SystemRealTime(
|
||||
uchar status, bigtime_t time)
|
||||
\brief Invoked when a Real Time event is received
|
||||
\sa BMidiLocalProducer::SpraySystemRealTime()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::TempoChange(int32 beatsPerMinute, bigtime_t time)
|
||||
\brief Invoked when a Tempo Change event is received
|
||||
\sa BMidiLocalProducer::SprayTempoChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::AllNotesOff(bool justChannel, bigtime_t time)
|
||||
\brief Not used
|
||||
*/
|
||||
|
||||
|
||||
|
||||
@@ -1,89 +0,0 @@
|
||||
/*!
|
||||
\page midi2defs Midi Kit definitions (Midi2Defs.h)
|
||||
|
||||
\section channelmasks Channel message masks
|
||||
|
||||
<TABLE BORDER="1">
|
||||
<TR><TD>B_NOTE_OFF</TD><TD>0x80</TD></TR>
|
||||
<TR><TD>B_NOTE_ON</TD><TD>0x90</TD></TR>
|
||||
<TR><TD>B_KEY_PRESSURE</TD><TD>0xa0</TD></TR>
|
||||
<TR><TD>B_CONTROL_CHANGE</TD><TD>0xb0</TD></TR>
|
||||
<TR><TD>B_PROGRAM_CHANGE</TD><TD>0xc0</TD></TR>
|
||||
<TR><TD>B_CHANNEL_PRESSURE</TD><TD>0xd0</TD></TR>
|
||||
<TR><TD>B_PITCH_BEND</TD><TD>0xe0</TD></TR>
|
||||
</TABLE>
|
||||
|
||||
\section systemmessages System messages
|
||||
|
||||
<TABLE BORDER="1">
|
||||
<TR><TD>B_SYS_EX_START</TD><TD>0xf0</TD></TR>
|
||||
<TR><TD>B_MIDI_TIME_CODE</TD><TD>0xf1</TD></TR>
|
||||
<TR><TD>B_SONG_POSITION</TD><TD>0xf2</TD></TR>
|
||||
<TR><TD>B_SONG_SELECT</TD><TD>0xf3</TD></TR>
|
||||
<TR><TD>B_CABLE_MESSAGE</TD><TD>0xf5</TD></TR>
|
||||
<TR><TD>B_TUNE_REQUEST</TD><TD>0xf6</TD></TR>
|
||||
<TR><TD>B_SYS_EX_END</TD><TD>0xf7</TD></TR>
|
||||
<TR><TD>B_TIMING_CLOCK</TD><TD>0xf8</TD></TR>
|
||||
<TR><TD>B_START</TD><TD>0xfa</TD></TR>
|
||||
<TR><TD>B_CONTINUE</TD><TD>0xfb</TD></TR>
|
||||
<TR><TD>B_STOP</TD><TD>0xfc</TD></TR>
|
||||
<TR><TD>B_ACTIVE_SENSING</TD><TD>0xfe</TD></TR>
|
||||
<TR><TD>B_SYSTEM_RESET</TD><TD>0xff</TD></TR>
|
||||
</TABLE>
|
||||
|
||||
\section controllernumbers Controller numbers
|
||||
|
||||
<TABLE BORDER="1">
|
||||
<TR><TD>B_MODULATION</TD><TD>0x01</TD></TR>
|
||||
<TR><TD>B_BREATH_CONTROLLER</TD><TD>0x02</TD></TR>
|
||||
<TR><TD>B_FOOT_CONTROLLER</TD><TD>0x04</TD></TR>
|
||||
<TR><TD>B_PORTAMENTO_TIME</TD><TD>0x05</TD></TR>
|
||||
<TR><TD>B_DATA_ENTRY</TD><TD>0x06</TD></TR>
|
||||
<TR><TD>B_MAIN_VOLUME</TD><TD>0x07</TD></TR>
|
||||
<TR><TD>B_MIDI_BALANCE</TD><TD>0x08</TD></TR>
|
||||
<TR><TD>B_PAN</TD><TD>0x0a</TD></TR>
|
||||
<TR><TD>B_EXPRESSION_CTRL</TD><TD>0x0b</TD></TR>
|
||||
<TR><TD>B_GENERAL_CTRL_1</TD><TD>0x10</TD></TR>
|
||||
<TR><TD>B_GENERAL_CTRL_2</TD><TD>0x11</TD></TR>
|
||||
<TR><TD>B_GENERAL_CTRL_3</TD><TD>0x12</TD></TR>
|
||||
<TR><TD>B_GENERAL_CTRL_4</TD><TD>0x13</TD></TR>
|
||||
<TR><TD>B_SUSTAIN_PEDAL</TD><TD>0x40</TD></TR>
|
||||
<TR><TD>B_PORTAMENTO</TD><TD>0x41</TD></TR>
|
||||
<TR><TD>B_SOSTENUTO</TD><TD>0x42</TD></TR>
|
||||
<TR><TD>B_SOFT_PEDAL</TD><TD>0x43</TD></TR>
|
||||
<TR><TD>B_HOLD_2</TD><TD>0x45</TD></TR>
|
||||
<TR><TD>B_GENERAL_CTRL_5</TD><TD>0x50</TD></TR>
|
||||
<TR><TD>B_GENERAL_CTRL_6</TD><TD>0x51</TD></TR>
|
||||
<TR><TD>B_TEMPO_CHANGE</TD><TD>0x51</TD></TR>
|
||||
<TR><TD>B_GENERAL_CTRL_7</TD><TD>0x52</TD></TR>
|
||||
<TR><TD>B_GENERAL_CTRL_8</TD><TD>0x53</TD></TR>
|
||||
<TR><TD>B_EFFECTS_DEPTH</TD><TD>0x5b</TD></TR>
|
||||
<TR><TD>B_TREMOLO_DEPTH</TD><TD>0x5c</TD></TR>
|
||||
<TR><TD>B_CHORUS_DEPTH</TD><TD>0x5d</TD></TR>
|
||||
<TR><TD>B_CELESTE_DEPTH</TD><TD>0x5e</TD></TR>
|
||||
<TR><TD>B_PHASER_DEPTH</TD><TD>0x5f</TD></TR>
|
||||
<TR><TD>B_DATA_INCREMENT</TD><TD>0x60</TD></TR>
|
||||
<TR><TD>B_DATA_DECREMENT</TD><TD>0x61</TD></TR>
|
||||
<TR><TD>B_RESET_ALL_CONTROLLERS</TD><TD>0x79</TD></TR>
|
||||
<TR><TD>B_LOCAL_CONTROL</TD><TD>0x7a</TD></TR>
|
||||
<TR><TD>B_ALL_NOTES_OFF</TD><TD>0x7b</TD></TR>
|
||||
<TR><TD>B_OMNI_MODE_OFF</TD><TD>0x7c</TD></TR>
|
||||
<TR><TD>B_OMNI_MODE_ON</TD><TD>0x7d</TD></TR>
|
||||
<TR><TD>B_MONO_MODE_ON</TD><TD>0x7e</TD></TR>
|
||||
<TR><TD>B_POLY_MODE_ON</TD><TD>0x7f</TD></TR>
|
||||
</TABLE>
|
||||
|
||||
\section bmidiop BMidiOp
|
||||
|
||||
<TABLE BORDER="1">
|
||||
<TR><TD>B_MIDI_NO_OP</TD></TR>
|
||||
<TR><TD>B_MIDI_REGISTERED</TD></TR>
|
||||
<TR><TD>B_MIDI_UNREGISTERED</TD></TR>
|
||||
<TR><TD>B_MIDI_CONNECTED</TD></TR>
|
||||
<TR><TD>B_MIDI_DISCONNECTED</TD></TR>
|
||||
<TR><TD>B_MIDI_CHANGED_NAME</TD></TR>
|
||||
<TR><TD>B_MIDI_CHANGED_LATENCY</TD></TR>
|
||||
<TR><TD>B_MIDI_CHANGED_PROPERTIES</TD></TR>
|
||||
</TABLE>
|
||||
|
||||
*/
|
||||
@@ -1,232 +0,0 @@
|
||||
/*!
|
||||
\class BMidiLocalConsumer MidiConsumer.h
|
||||
\ingroup midi2
|
||||
\ingroup libmidi2
|
||||
\brief A consumer endpoint that is created by your own application
|
||||
|
||||
If you want to create a consumer that reacts to MIDI events, you should
|
||||
subclass BMidiLocalConsumer.
|
||||
|
||||
Each local consumer has its own thread that receives and dispatches the MIDI
|
||||
events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to
|
||||
a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so
|
||||
on. Calls to these hook functions are serialized -- they will never have to be
|
||||
re-entrant. They also should not be called from outside the thread that is
|
||||
invoking them.
|
||||
|
||||
Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer
|
||||
doesn't provide default implementations for them, so you don't have to call a
|
||||
hook's default implementation if you override it. For complete control, you can
|
||||
also override Data().
|
||||
|
||||
Most hook functions take a channel argument. Even though MIDI channels are
|
||||
really numbered 1 through 16, the hook functions work with channels 0 through
|
||||
15. The performance time for the event is specified in microseconds relative to
|
||||
the system time base. A performance time that is 0 (or really any time in the
|
||||
past) means "play as soon as possible". See the \ref midi2time "introduction"
|
||||
for more information about timing and consumers.
|
||||
|
||||
The thread driving the consumer's events is a very high priority real time
|
||||
thread. Events should be handled as quickly as possible (not counting
|
||||
snoozing). If non-time-critical computation is needed it may be wise to queue
|
||||
events up for a lower priority thread to handle them external to the main event
|
||||
thread.
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BMidiLocalConsumer::BMidiLocalConsumer(const char *name = NULL)
|
||||
\brief Creates a new local consumer endpoint
|
||||
|
||||
The new endpoint is not visible to other applications until you Register() it.
|
||||
|
||||
You can tell the constructor what the name of the new consumer will be. If you
|
||||
pass NULL (or use the default argument), then the consumer's name will be an
|
||||
empty string. It won't be NULL, since endpoint names cannot be NULL.
|
||||
|
||||
There is no guarantee that the endpoint will be successfully created. For
|
||||
example, the Midi Server may not be running. Therefore, you should always call
|
||||
IsValid() after creating a new endpoint to make sure that everything went okay.
|
||||
If not, Release() the object to reclaim memory and abort gracefully.
|
||||
|
||||
\code
|
||||
MyConsumer* cons = new MyConsumer(...);
|
||||
if (!cons->IsValid())
|
||||
{
|
||||
cons->Release();
|
||||
...exit gracefully...
|
||||
}
|
||||
\endcode
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SetLatency(bigtime_t latency)
|
||||
\brief Changes the published latency of the consumer
|
||||
\sa Latency()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int32 BMidiLocalConsumer::GetProducerID()
|
||||
\brief Returns the ID of the producer that most recently sent a MIDI event to
|
||||
this consumer
|
||||
|
||||
You can call this from one of the hooks to determine which producer the event
|
||||
came from.
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SetTimeout(bigtime_t when, void* data)
|
||||
\brief Requests that the Timeout() hook will be called at some point
|
||||
|
||||
This method asks the consumer thread to call the Timeout() hook as soon as
|
||||
possible after the timeout expires. For every call to SetTimeout(), the
|
||||
Timeout() hook is only called once. Note: the term "timeout" may be a little
|
||||
misleading; the hook will <I>always</I> be called, even if events are received
|
||||
in the mean time. Apparently, this facility is handy for dealing with early
|
||||
events.
|
||||
|
||||
Note that the event thread blocks on the consumer's port as long as no events
|
||||
arrive. By default no timeout is set, and as a result the thread blocks
|
||||
forever. Your call to SetTimeout() doesn't change this. The new timeout value
|
||||
will go into effect the next time the thread tries to read from the port, i.e.
|
||||
after the first event has been received. If no event ever comes in, the
|
||||
Timeout() hook will never be called. This also means that you cannot cancel a
|
||||
timeout once you have set it. To repeat, calling SetTimeout() only takes effect
|
||||
after at least one new event has been received.
|
||||
|
||||
\param when An absolute time that's measured against the system clock.
|
||||
|
||||
\param data A pointer to a "cookie" that you can pass along to Timeout(). The
|
||||
data is not copied, so you must ensure that the pointer remains valid until
|
||||
Timeout() is called. You typically delete the data inside Timeout().
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::Timeout(void* data)
|
||||
\brief Hook function that is called per your own request
|
||||
\sa SetTimeout()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::Data(
|
||||
uchar* data, size_t length, bool atomic, bigtime_t time)
|
||||
\brief Invoked when raw MIDI is received
|
||||
|
||||
What the default implementation of Data() does depends on the value of atomic.
|
||||
If atomic is true, the data received comprises a single MIDI event; i.e. one
|
||||
status byte followed by the appropriate number of data bytes and nothing else.
|
||||
In this case, Data() calls the event-specific hook function that corresponds to
|
||||
that status byte. This optimization is used by the Midi Kit to allow faster
|
||||
dispatch of events generated by the specific Spray functions from
|
||||
BMidiLocalProducer.
|
||||
|
||||
If atomic is false, Data() ignores the MIDI event. If you want a consumer to
|
||||
handle non-atomic events, you have to override Data() and program this
|
||||
yourself. In that case, you probably also want to call the default
|
||||
implementation to handle the "normal" MIDI events.
|
||||
|
||||
Data() is rarely overridden, but you can override it if you want to. If you do,
|
||||
remember that the data buffer is owned by the Midi Kit. Do not attempt to
|
||||
modify or free it, lest you wish to be laughed at by other developers.
|
||||
|
||||
\param data the MIDI event data
|
||||
\param length byte size of the data buffer
|
||||
\param atomic whether the data buffer contains a single complete MIDI event
|
||||
\param time the requested performance time of the event
|
||||
|
||||
\sa BMidiLocalProducer::SprayData()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::NoteOff(
|
||||
uchar channel, uchar note, uchar velocity, bigtime_t time)
|
||||
\brief Invoked when a Note Off event is received
|
||||
\sa BMidiLocalProducer::SprayNoteOff()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::NoteOn(
|
||||
uchar channel, uchar note, uchar velocity, bigtime_t time)
|
||||
\brief Invoked when a Note On event is received
|
||||
\sa BMidiLocalProducer::SprayNoteOn()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::KeyPressure(
|
||||
uchar channel, uchar note, uchar pressure, bigtime_t time)
|
||||
\brief Invoked when a Polyphonic Pressure (Aftertouch) event is received
|
||||
\sa BMidiLocalProducer::SprayKeyPressure()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::ControlChange(
|
||||
uchar channel, uchar controlNumber, uchar controlValue, bigtime_t time)
|
||||
\brief Invoked when a Controller Change event is received
|
||||
\sa BMidiLocalProducer::SprayControlChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::ProgramChange(
|
||||
uchar channel, uchar programNumber, bigtime_t time)
|
||||
\brief Invoked when a Program Change event is received
|
||||
\sa BMidiLocalProducer::SprayProgramChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::ChannelPressure(
|
||||
uchar channel, uchar pressure, bigtime_t time)
|
||||
\brief Invoked when a Channel Pressure event is received
|
||||
\sa BMidiLocalProducer::SprayChannelPressure()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::PitchBend(
|
||||
uchar channel, uchar lsb, uchar msb, bigtime_t time)
|
||||
\brief Invoked when a Pitch Bend event is received
|
||||
\sa BMidiLocalProducer::SprayPitchBend()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SystemExclusive(
|
||||
void* data, size_t length, bigtime_t time)
|
||||
\brief Invoked when a System Exclusive event is received
|
||||
|
||||
The data does not include the sysex start and end control bytes (0xF0 and 0xF7),
|
||||
only the payload of the sysex message.
|
||||
|
||||
The data belongs to the Midi Kit and is only valid for the duration of this
|
||||
event. You may not modify or free it.
|
||||
|
||||
\sa BMidiLocalProducer::SpraySystemExclusive()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SystemCommon(
|
||||
uchar status, uchar data1, uchar data2, bigtime_t time)
|
||||
\brief Invoked when a System Common event is received
|
||||
|
||||
Not all data bytes are used for all common events. Unused bytes are set to 0.
|
||||
|
||||
\sa BMidiLocalProducer::SpraySystemCommon()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::SystemRealTime(
|
||||
uchar status, bigtime_t time)
|
||||
\brief Invoked when a Real Time event is received
|
||||
\sa BMidiLocalProducer::SpraySystemRealTime()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::TempoChange(int32 beatsPerMinute, bigtime_t time)
|
||||
\brief Invoked when a Tempo Change event is received
|
||||
\sa BMidiLocalProducer::SprayTempoChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalConsumer::AllNotesOff(bool justChannel, bigtime_t time)
|
||||
\brief Not used
|
||||
*/
|
||||
@@ -1,228 +0,0 @@
|
||||
/*!
|
||||
\class BMidiLocalProducer MidiProducer.h
|
||||
\ingroup midi2
|
||||
\ingroup libmidi2
|
||||
\brief A producer endpoint that is created by your own application
|
||||
|
||||
You create a BMidiLocalProducer if you want your application to send MIDI
|
||||
events. You use the various spray functions to send events to all connected
|
||||
consumers. If no consumers are connected to the producer, any calls to the
|
||||
spray functions are ignored.
|
||||
|
||||
Most spray functions accept a channel argument. Even though MIDI channels are
|
||||
really numbered 1 through 16, the spray functions work with channels 0 through
|
||||
15. You can also specify the performance time for the event using the time
|
||||
argument. Specify 0 (or any time in the past) to perform the event "now", i.e.
|
||||
as soon as possible. You can also schedule events to be performed in the
|
||||
future, by passing a time such as system_time() + 5000000, which means 5
|
||||
seconds from now.
|
||||
|
||||
Unlike BMidiLocalConsumer, which should be subclassed almost always, you hardly
|
||||
ever need to derive a class from BMidiLocalProducer. The only reason for
|
||||
subclassing is when you need to know when the producer gets connected or
|
||||
disconnected.
|
||||
|
||||
Also unlike consumers, local producers have no thread of control directly
|
||||
associated with them. If you want to send out the MIDI events from a different
|
||||
thread, you will have to create one yourself.
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BMidiLocalProducer::BMidiLocalProducer(const char *name = NULL)
|
||||
\brief Creates a new local producer endpoint
|
||||
|
||||
The new endpoint is not visible to other applications until you Register() it.
|
||||
|
||||
You can tell the constructor what the name of the new producer will be. If you
|
||||
pass NULL (or use the default argument), then the producer's name will be an
|
||||
empty string. It won't be NULL, since endpoint names cannot be NULL.
|
||||
|
||||
There is no guarantee that the endpoint will be successfully created. For
|
||||
example, the Midi Server may not be running. Therefore, you should always call
|
||||
IsValid() after creating a new endpoint to make sure that everything went okay.
|
||||
If not, Release() the object to reclaim memory and abort gracefully.
|
||||
|
||||
\code
|
||||
BMidiLocalProducer* prod = new BMidiLocalProducer(...);
|
||||
if (!prod->IsValid())
|
||||
{
|
||||
prod->Release();
|
||||
...exit gracefully...
|
||||
}
|
||||
\endcode
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::Connected(BMidiConsumer* cons)
|
||||
\brief Invoked when a new consumer is connected to this producer
|
||||
|
||||
Although typical notifications (i.e. from BMidiRoster's "watching" facility)
|
||||
are only sent if it is some other app that is performing the operation,
|
||||
Connected() is also called if you are making the connection yourself.
|
||||
|
||||
If you override this hook, you don't have to call the default implementation,
|
||||
because that does nothing.
|
||||
|
||||
\param cons The newly connected consumer. The reference count of the consumer
|
||||
object is not increased, so you should not Release() it. However, if you want
|
||||
to keep track of the consumer beyond this function, you should first Acquire()
|
||||
it, and Release() it when you are done.
|
||||
|
||||
\sa Disconnected()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::Disconnected(BMidiConsumer* cons)
|
||||
\brief Invoked when a consumer is disconnected from this producer
|
||||
\sa Connected()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayData(
|
||||
void* data, size_t length, bool atomic = false, bigtime_t time = 0) const
|
||||
\brief Sends raw MIDI data downstream to all connected consumers
|
||||
|
||||
Typically you won't have to call SprayData(); the other spray functions will do
|
||||
just fine. If you do call it, remember that you retain ownership of the data
|
||||
and that you are responsible for freeing it at some point. (Even though data is
|
||||
not declared const, the function does not change it.)
|
||||
|
||||
With atomic set to false, you can send a MIDI message in segments (perhaps for
|
||||
a large sysex dump). However, when you do this, you are on your own. The Midi
|
||||
Kit only tags the data as being non-atomic, but offers no additional support.
|
||||
The default implementation of BMidiLocalConsumer completely ignores such
|
||||
events. To handle non-atomic MIDI data, you should override the
|
||||
BMidiLocalConsumer::Data() hook and process the MIDI event yourself. All of
|
||||
BMidiLocalProducer's other spray functions always send atomic data.
|
||||
|
||||
\param data the MIDI event data
|
||||
\param length byte size of the data buffer
|
||||
\param atomic whether the data buffer contains a single complete MIDI event
|
||||
\param time the required performance time of the event
|
||||
|
||||
\sa BMidiLocalConsumer::Data()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayNoteOff(
|
||||
uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
|
||||
\brief Sends a Note Off event to all connected consumers
|
||||
\sa BMidiLocalConsumer::NoteOff()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayNoteOn(
|
||||
uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
|
||||
\brief Sends a Note On event to all connected consumers
|
||||
\sa BMidiLocalConsumer::NoteOn()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayKeyPressure(
|
||||
uchar channel, uchar note, uchar pressure, bigtime_t time = 0) const
|
||||
\brief Sends a Polyphonic Pressure (Aftertouch) event to all connected
|
||||
consumers
|
||||
\sa BMidiLocalConsumer::KeyPressure()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayControlChange(
|
||||
uchar channel, uchar controlNumber, uchar controlValue,
|
||||
bigtime_t time = 0) const
|
||||
\brief Sends a Controller Change event to all connected consumers
|
||||
|
||||
\sa \ref controllernumbers
|
||||
\sa BMidiLocalConsumer::ControlChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayProgramChange(
|
||||
uchar channel, uchar programNumber, bigtime_t time = 0) const
|
||||
\brief Sends a Program Change event to all connected consumers
|
||||
\sa BMidiLocalConsumer::ProgramChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayChannelPressure(
|
||||
uchar channel, uchar pressure, bigtime_t time = 0) const
|
||||
\brief Sends a Channel Pressure event to all connected consumers
|
||||
\sa BMidiLocalConsumer::ChannelPressure()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayPitchBend(
|
||||
uchar channel, uchar lsb, uchar msb, bigtime_t time = 0) const
|
||||
\brief Sends a Pitch Bend event to all connected consumers
|
||||
\sa BMidiLocalConsumer::PitchBend()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SpraySystemExclusive(
|
||||
void* data, size_t length, bigtime_t time = 0) const
|
||||
\brief Sends a System Exclusive event to all connected consumers
|
||||
|
||||
You retain ownership of the data and are responsible for freeing it. Even
|
||||
though data is not declared const, the function does not change it. Even though
|
||||
the amount of data may be quite large, this function always sends sysex
|
||||
messages as an atomic block of data.
|
||||
|
||||
\sa BMidiLocalConsumer::SystemExclusive()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SpraySystemCommon(
|
||||
uchar status, uchar data1, uchar data2, bigtime_t time = 0) const
|
||||
\brief Sends a System Common event to the connected consumers
|
||||
|
||||
The status byte must be one of the following:
|
||||
|
||||
<TABLE BORDER="1">
|
||||
<TR><TD>0xF1</TD><TD>B_MIDI_TIME_CODE</TD><TD>data1 only</TD></TR>
|
||||
<TR><TD>0xF2</TD><TD>B_SONG_POSITION</TD><TD>data1 and data2</TD></TR>
|
||||
<TR><TD>0xF3</TD><TD>B_SONG_SELECT</TD><TD>data1 only</TD></TR>
|
||||
<TR><TD>0xF5</TD><TD>B_CABLE_MESSAGE</TD><TD>data1 only</TD></TR>
|
||||
<TR><TD>0xF6</TD><TD>B_TUNE_REQUEST</TD><TD>no data</TD></TR>
|
||||
<TR><TD>0xF7</TD><TD>B_SYS_EX_END</TD><TD>no data</TD></TR>
|
||||
</TABLE>
|
||||
|
||||
\sa BMidiLocalConsumer::SystemCommon()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SpraySystemRealTime(
|
||||
uchar status, bigtime_t time = 0) const
|
||||
\brief Sends a Real Time event to the connected consumers
|
||||
|
||||
The status byte must be one of the following:
|
||||
|
||||
<TABLE BORDER="1">
|
||||
<TR><TD>0xF8</TD><TD>B_TIMING_CLOCK</TD></TR>
|
||||
<TR><TD>0xFA</TD><TD>B_START</TD></TR>
|
||||
<TR><TD>0xFB</TD><TD>B_CONTINUE</TD></TR>
|
||||
<TR><TD>0xFC</TD><TD>B_STOP</TD></TR>
|
||||
<TR><TD>0xFE</TD><TD>B_ACTIVE_SENSING</TD></TR>
|
||||
<TR><TD>0xFF</TD><TD>B_SYSTEM_RESET</TD></TR>
|
||||
</TABLE>
|
||||
|
||||
Because of their high priority, the MIDI specification allows real time
|
||||
messages to "interleave" with other MIDI messages. A large sysex dump, for
|
||||
example, may be interrupted by a real time event. The Midi Kit, however,
|
||||
doesn't care. If you (or another producer) have just sent a big system
|
||||
exclusive to a consumer, any following real time message will simply have to
|
||||
wait until the consumer has dealt with the sysex.
|
||||
|
||||
\sa BMidiLocalConsumer::SystemRealTime()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayTempoChange(
|
||||
int32 bpm, bigtime_t time = 0) const
|
||||
\brief Sends a Tempo Change event to the connected consumers.
|
||||
|
||||
This kind of Tempo Change event is not really part of the MIDI spec, rather
|
||||
it is an extension from the SMF (Standard MIDI File) format.
|
||||
|
||||
\sa BMidiLocalConsumer::TempoChange()
|
||||
*/
|
||||
@@ -75,3 +75,234 @@ list have their reference counts bumped, so you need to Release() them before
|
||||
you delete the list or they will go all leaky on you.
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\class BMidiLocalProducer MidiProducer.h
|
||||
\ingroup midi2
|
||||
\ingroup libmidi2
|
||||
\brief A producer endpoint that is created by your own application
|
||||
|
||||
You create a BMidiLocalProducer if you want your application to send MIDI
|
||||
events. You use the various spray functions to send events to all connected
|
||||
consumers. If no consumers are connected to the producer, any calls to the
|
||||
spray functions are ignored.
|
||||
|
||||
Most spray functions accept a channel argument. Even though MIDI channels are
|
||||
really numbered 1 through 16, the spray functions work with channels 0 through
|
||||
15. You can also specify the performance time for the event using the time
|
||||
argument. Specify 0 (or any time in the past) to perform the event "now", i.e.
|
||||
as soon as possible. You can also schedule events to be performed in the
|
||||
future, by passing a time such as system_time() + 5000000, which means 5
|
||||
seconds from now.
|
||||
|
||||
Unlike BMidiLocalConsumer, which should be subclassed almost always, you hardly
|
||||
ever need to derive a class from BMidiLocalProducer. The only reason for
|
||||
subclassing is when you need to know when the producer gets connected or
|
||||
disconnected.
|
||||
|
||||
Also unlike consumers, local producers have no thread of control directly
|
||||
associated with them. If you want to send out the MIDI events from a different
|
||||
thread, you will have to create one yourself.
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BMidiLocalProducer::BMidiLocalProducer(const char *name = NULL)
|
||||
\brief Creates a new local producer endpoint
|
||||
|
||||
The new endpoint is not visible to other applications until you Register() it.
|
||||
|
||||
You can tell the constructor what the name of the new producer will be. If you
|
||||
pass NULL (or use the default argument), then the producer's name will be an
|
||||
empty string. It won't be NULL, since endpoint names cannot be NULL.
|
||||
|
||||
There is no guarantee that the endpoint will be successfully created. For
|
||||
example, the Midi Server may not be running. Therefore, you should always call
|
||||
IsValid() after creating a new endpoint to make sure that everything went okay.
|
||||
If not, Release() the object to reclaim memory and abort gracefully.
|
||||
|
||||
\code
|
||||
BMidiLocalProducer* prod = new BMidiLocalProducer(...);
|
||||
if (!prod->IsValid())
|
||||
{
|
||||
prod->Release();
|
||||
...exit gracefully...
|
||||
}
|
||||
\endcode
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::Connected(BMidiConsumer* cons)
|
||||
\brief Invoked when a new consumer is connected to this producer
|
||||
|
||||
Although typical notifications (i.e. from BMidiRoster's "watching" facility)
|
||||
are only sent if it is some other app that is performing the operation,
|
||||
Connected() is also called if you are making the connection yourself.
|
||||
|
||||
If you override this hook, you don't have to call the default implementation,
|
||||
because that does nothing.
|
||||
|
||||
\param cons The newly connected consumer. The reference count of the consumer
|
||||
object is not increased, so you should not Release() it. However, if you want
|
||||
to keep track of the consumer beyond this function, you should first Acquire()
|
||||
it, and Release() it when you are done.
|
||||
|
||||
\sa Disconnected()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::Disconnected(BMidiConsumer* cons)
|
||||
\brief Invoked when a consumer is disconnected from this producer
|
||||
\sa Connected()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayData(
|
||||
void* data, size_t length, bool atomic = false, bigtime_t time = 0) const
|
||||
\brief Sends raw MIDI data downstream to all connected consumers
|
||||
|
||||
Typically you won't have to call SprayData(); the other spray functions will do
|
||||
just fine. If you do call it, remember that you retain ownership of the data
|
||||
and that you are responsible for freeing it at some point. (Even though data is
|
||||
not declared const, the function does not change it.)
|
||||
|
||||
With atomic set to false, you can send a MIDI message in segments (perhaps for
|
||||
a large sysex dump). However, when you do this, you are on your own. The Midi
|
||||
Kit only tags the data as being non-atomic, but offers no additional support.
|
||||
The default implementation of BMidiLocalConsumer completely ignores such
|
||||
events. To handle non-atomic MIDI data, you should override the
|
||||
BMidiLocalConsumer::Data() hook and process the MIDI event yourself. All of
|
||||
BMidiLocalProducer's other spray functions always send atomic data.
|
||||
|
||||
\param data the MIDI event data
|
||||
\param length byte size of the data buffer
|
||||
\param atomic whether the data buffer contains a single complete MIDI event
|
||||
\param time the required performance time of the event
|
||||
|
||||
\sa BMidiLocalConsumer::Data()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayNoteOff(
|
||||
uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
|
||||
\brief Sends a Note Off event to all connected consumers
|
||||
\sa BMidiLocalConsumer::NoteOff()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayNoteOn(
|
||||
uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
|
||||
\brief Sends a Note On event to all connected consumers
|
||||
\sa BMidiLocalConsumer::NoteOn()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayKeyPressure(
|
||||
uchar channel, uchar note, uchar pressure, bigtime_t time = 0) const
|
||||
\brief Sends a Polyphonic Pressure (Aftertouch) event to all connected
|
||||
consumers
|
||||
\sa BMidiLocalConsumer::KeyPressure()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayControlChange(
|
||||
uchar channel, uchar controlNumber, uchar controlValue,
|
||||
bigtime_t time = 0) const
|
||||
\brief Sends a Controller Change event to all connected consumers
|
||||
|
||||
\sa Midi2Defs.h
|
||||
\sa BMidiLocalConsumer::ControlChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayProgramChange(
|
||||
uchar channel, uchar programNumber, bigtime_t time = 0) const
|
||||
\brief Sends a Program Change event to all connected consumers
|
||||
\sa BMidiLocalConsumer::ProgramChange()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayChannelPressure(
|
||||
uchar channel, uchar pressure, bigtime_t time = 0) const
|
||||
\brief Sends a Channel Pressure event to all connected consumers
|
||||
\sa BMidiLocalConsumer::ChannelPressure()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayPitchBend(
|
||||
uchar channel, uchar lsb, uchar msb, bigtime_t time = 0) const
|
||||
\brief Sends a Pitch Bend event to all connected consumers
|
||||
\sa BMidiLocalConsumer::PitchBend()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SpraySystemExclusive(
|
||||
void* data, size_t length, bigtime_t time = 0) const
|
||||
\brief Sends a System Exclusive event to all connected consumers
|
||||
|
||||
You retain ownership of the data and are responsible for freeing it. Even
|
||||
though data is not declared const, the function does not change it. Even though
|
||||
the amount of data may be quite large, this function always sends sysex
|
||||
messages as an atomic block of data.
|
||||
|
||||
\sa BMidiLocalConsumer::SystemExclusive()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SpraySystemCommon(
|
||||
uchar status, uchar data1, uchar data2, bigtime_t time = 0) const
|
||||
\brief Sends a System Common event to the connected consumers
|
||||
|
||||
The status byte must be one of the following:
|
||||
|
||||
<TABLE BORDER="1">
|
||||
<TR><TD>0xF1</TD><TD>B_MIDI_TIME_CODE</TD><TD>data1 only</TD></TR>
|
||||
<TR><TD>0xF2</TD><TD>B_SONG_POSITION</TD><TD>data1 and data2</TD></TR>
|
||||
<TR><TD>0xF3</TD><TD>B_SONG_SELECT</TD><TD>data1 only</TD></TR>
|
||||
<TR><TD>0xF5</TD><TD>B_CABLE_MESSAGE</TD><TD>data1 only</TD></TR>
|
||||
<TR><TD>0xF6</TD><TD>B_TUNE_REQUEST</TD><TD>no data</TD></TR>
|
||||
<TR><TD>0xF7</TD><TD>B_SYS_EX_END</TD><TD>no data</TD></TR>
|
||||
</TABLE>
|
||||
|
||||
\sa BMidiLocalConsumer::SystemCommon()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SpraySystemRealTime(
|
||||
uchar status, bigtime_t time = 0) const
|
||||
\brief Sends a Real Time event to the connected consumers
|
||||
|
||||
The status byte must be one of the following:
|
||||
|
||||
<TABLE BORDER="1">
|
||||
<TR><TD>0xF8</TD><TD>B_TIMING_CLOCK</TD></TR>
|
||||
<TR><TD>0xFA</TD><TD>B_START</TD></TR>
|
||||
<TR><TD>0xFB</TD><TD>B_CONTINUE</TD></TR>
|
||||
<TR><TD>0xFC</TD><TD>B_STOP</TD></TR>
|
||||
<TR><TD>0xFE</TD><TD>B_ACTIVE_SENSING</TD></TR>
|
||||
<TR><TD>0xFF</TD><TD>B_SYSTEM_RESET</TD></TR>
|
||||
</TABLE>
|
||||
|
||||
Because of their high priority, the MIDI specification allows real time
|
||||
messages to "interleave" with other MIDI messages. A large sysex dump, for
|
||||
example, may be interrupted by a real time event. The Midi Kit, however,
|
||||
doesn't care. If you (or another producer) have just sent a big system
|
||||
exclusive to a consumer, any following real time message will simply have to
|
||||
wait until the consumer has dealt with the sysex.
|
||||
|
||||
\sa BMidiLocalConsumer::SystemRealTime()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMidiLocalProducer::SprayTempoChange(
|
||||
int32 bpm, bigtime_t time = 0) const
|
||||
\brief Sends a Tempo Change event to the connected consumers.
|
||||
|
||||
This kind of Tempo Change event is not really part of the MIDI spec, rather
|
||||
it is an extension from the SMF (Standard MIDI File) format.
|
||||
|
||||
\sa BMidiLocalConsumer::TempoChange()
|
||||
*/
|
||||
|
||||
|
||||
|
||||
@@ -257,7 +257,7 @@ void MyView::MessageReceived(BMessage* msg)
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa \ref bmidiop "The possible be:op codes (BMidiOp)"
|
||||
For the possible midi options, see #BMidiOp
|
||||
*/
|
||||
|
||||
/*!
|
||||
@@ -292,3 +292,12 @@ There is no real reason use this function, since all BMidiRoster's public
|
||||
function are static.
|
||||
|
||||
*/
|
||||
|
||||
/*!
|
||||
\enum BMidiOp
|
||||
\brief Defines the status codes for MIDI Server notification messages.
|
||||
|
||||
These codes are used when you request notification as in BMidiRoster::StartWatching().
|
||||
Check against these codes to determine what is happening. See the StartWatching() method
|
||||
for a more complete description of the codes and their meaning.
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user