From e6ecb3fc07443f15c9901127f2ca2bd8b1149953 Mon Sep 17 00:00:00 2001 From: Augustin Cavalier Date: Wed, 25 Mar 2015 11:30:01 -0400 Subject: [PATCH] Haiku Book: Midi2 fixes. * Automatic whitespace cleanup. * Removed all of Midi2 from the "libbe" group, as they aren't part of it * Get rid of the redundant "libmidi2" group, as all of midi2 is already in the "MIDI 2 Kit" group, and the docs explicitly state that the MIDI 2 Kit has its own library. --- docs/user/book.dox | 3 - docs/user/midi2/Midi2Defs.dox | 15 ++-- docs/user/midi2/MidiConsumer.dox | 147 +++++++++++++++---------------- docs/user/midi2/MidiEndpoint.dox | 7 +- docs/user/midi2/MidiProducer.dox | 7 +- docs/user/midi2/MidiRoster.dox | 3 - 6 files changed, 81 insertions(+), 101 deletions(-) diff --git a/docs/user/book.dox b/docs/user/book.dox index db417c68dd..824d1a0bfc 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -469,9 +469,6 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); - Jim Menard's MIDI Reference - \defgroup libmidi2 (libmidi2.so) - - \defgroup network Network Kit \brief Classes that deal with all network connections and communications. diff --git a/docs/user/midi2/Midi2Defs.dox b/docs/user/midi2/Midi2Defs.dox index f846992c63..778210ff1e 100644 --- a/docs/user/midi2/Midi2Defs.dox +++ b/docs/user/midi2/Midi2Defs.dox @@ -1,7 +1,6 @@ /*! \file Midi2Defs.h \ingroup midi2 - \ingroup libbe \brief Some definitions to define raw MIDI events. */ @@ -57,7 +56,7 @@ //! @} -/*! +/*! \name System Messages \brief Some definitions to define the raw MIDI system messages. @@ -140,7 +139,7 @@ //! @} -/*! +/*! \name Controller Numbers \brief Constants that represent specific controller messages. @@ -231,13 +230,13 @@ */ -/*! +/*! \var B_SOSTENUTO */ /*! - \var B_SOFT_PEDAL + \var B_SOFT_PEDAL */ @@ -277,7 +276,7 @@ /*! - \var B_TREMOLO_DEPTH + \var B_TREMOLO_DEPTH */ @@ -312,7 +311,7 @@ /*! - \var B_LOCAL_CONTROL + \var B_LOCAL_CONTROL */ @@ -327,7 +326,7 @@ /*! - \var B_OMNI_MODE_ON + \var B_OMNI_MODE_ON */ diff --git a/docs/user/midi2/MidiConsumer.dox b/docs/user/midi2/MidiConsumer.dox index 03660a24f9..756f933a86 100644 --- a/docs/user/midi2/MidiConsumer.dox +++ b/docs/user/midi2/MidiConsumer.dox @@ -1,7 +1,6 @@ /*! \file MidiConsumer.h \ingroup midi2 - \ingroup libbe \brief Defines consumer classes for the MIDI Kit. */ @@ -9,17 +8,15 @@ /*! \class BMidiConsumer MidiConsumer.h \ingroup midi2 - \ingroup libmidi2 - \ingroup libbe \brief Receives MIDI events from a producer - A consumer is an object that knows how to deal with incoming MIDI events. A - consumer can be connected to multiple producers at the same time. There is no - way to find out which producers are connected to this consumer just by looking + A consumer is an object that knows how to deal with incoming MIDI events. A + consumer can be connected to multiple producers at the same time. There is no + way to find out which producers are connected to this consumer just by looking at the BMidiConsumer object; you will have to consult BMidiRoster for that. - A BMidiConsumer either represents a local consumer, i.e. a class extending from - BMidiLocalConsumer, or is a proxy for a remote object published by another app. + A BMidiConsumer either represents a local consumer, i.e. a class extending from + BMidiLocalConsumer, or is a proxy for a remote object published by another app. */ @@ -27,15 +24,15 @@ \fn bigtime_t BMidiConsumer::Latency() const \brief Returns the latency of this consumer - The latency is measured in microseconds. Producers should attempt to get MIDI - events to this consumer by (when - latency). You do this by subtracting - the latency from the performance time when you spray the events (provided that + The latency is measured in microseconds. Producers should attempt to get MIDI + events to this consumer by (when - latency). You do this by subtracting + the latency from the performance time when you spray the events (provided that you spray these events ahead of time, of course). - You cannot set the latency on a BMidiConsumer, only on a + You cannot set the latency on a BMidiConsumer, only on a BMidiLocalConsumer. - The latency issue gets slightly more complicated when multiple endpoints are + The latency issue gets slightly more complicated when multiple endpoints are chained together, as in the following picture: \verbatim @@ -47,55 +44,53 @@ appA appB (filter) appC \endverbatim - Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply - reports 100ms, then prodA will schedule its events for (t - 100), which is - really 200ms too late. (Of course, producers send out their events as soon as - possible, so depending on the load of the system, everything may work out just + Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply + reports 100ms, then prodA will schedule its events for (t - 100), which is + really 200ms too late. (Of course, producers send out their events as soon as + possible, so depending on the load of the system, everything may work out just fine.) - ConsB should report the latency of the consumer that is hooked up to its - output, consC, in addition to its own latency. In other words, the full - downstream latency. So, the reported latency in this case would be 300ms. This - also means that appB should change the latency of consB when prodB makes or - breaks a connection, and when consC reports a latency change. (If multiple - consumers are connected to prodB, you should take the slowest one.) - Unfortunately, the Midi Kit provides no easy mechanism for doing any of this, + ConsB should report the latency of the consumer that is hooked up to its + output, consC, in addition to its own latency. In other words, the full + downstream latency. So, the reported latency in this case would be 300ms. This + also means that appB should change the latency of consB when prodB makes or + breaks a connection, and when consC reports a latency change. (If multiple + consumers are connected to prodB, you should take the slowest one.) + 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 - \ingroup libbe \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 + 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 + 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 + 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" + 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 + 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. */ @@ -106,13 +101,13 @@ 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 + 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. + 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 @@ -137,10 +132,10 @@ if (!cons->IsValid()) /*! \fn int32 BMidiLocalConsumer::GetProducerID() - \brief Returns the ID of the producer that most recently sent a MIDI event to + \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 + You can call this from one of the hooks to determine which producer the event came from. */ @@ -149,26 +144,26 @@ if (!cons->IsValid()) \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 always be called, even if events are received - in the mean time. Apparently, this facility is handy for dealing with early + 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 always 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 + 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 + \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(). */ @@ -185,21 +180,21 @@ if (!cons->IsValid()) 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 + 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 + 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 + 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 diff --git a/docs/user/midi2/MidiEndpoint.dox b/docs/user/midi2/MidiEndpoint.dox index 7ad6768fd4..4dc9fb8d74 100644 --- a/docs/user/midi2/MidiEndpoint.dox +++ b/docs/user/midi2/MidiEndpoint.dox @@ -1,7 +1,6 @@ /*! \file MidiEndpoint.h \ingroup midi2 - \ingroup libbe \brief Defines the Baseclass of all MIDI consumers and producers. */ @@ -9,8 +8,6 @@ /*! \class BMidiEndpoint \ingroup midi2 - \ingroup libmidi2 - \ingroup libbe \brief Base class for all MIDI endpoints. BMidiEndpoint is the abstract base class that represents either a @@ -261,7 +258,7 @@ if (endpoint->GetProperties(&props) == B_OK) { ...add data to the message... endpoint->SetProperties(&props); -} +} \endcode You are only allowed to call SetProperties() on a local object. @@ -310,7 +307,7 @@ if (endpoint->GetProperties(&props) == B_OK) \code BMessage props; -if (endpoint->GetProperties(&props) == B_OK) +if (endpoint->GetProperties(&props) == B_OK) { ...examine the contents of the message... } diff --git a/docs/user/midi2/MidiProducer.dox b/docs/user/midi2/MidiProducer.dox index 36c1fa1360..758d7af87b 100644 --- a/docs/user/midi2/MidiProducer.dox +++ b/docs/user/midi2/MidiProducer.dox @@ -1,7 +1,6 @@ /*! \file MidiProducer.h \ingroup midi2 - \ingroup libbe \brief Defines producer classes for the MIDI Kit. */ @@ -9,8 +8,6 @@ /*! \class BMidiProducer MidiProducer.h \ingroup midi2 - \ingroup libmidi2 - \ingroup libbe \brief Streams MIDI events to connected consumers. A producer is an object that generate a stream of MIDI events. Each @@ -28,7 +25,7 @@ \brief Connects a consumer to this producer. Establishes a connection between this producer and the specified consumer - endpoint. From now on, any events that this producer sprays will be sent + endpoint. From now on, any events that this producer sprays will be sent to that consumer. You may connect multiple consumers to a producer. \return B_OK on success, or an error code when the connection could not be @@ -91,8 +88,6 @@ delete list; /*! \class BMidiLocalProducer MidiProducer.h \ingroup midi2 - \ingroup libmidi2 - \ingroup libbe \brief A producer endpoint that is created by your own application. You create a BMidiLocalProducer if you want your application to send MIDI diff --git a/docs/user/midi2/MidiRoster.dox b/docs/user/midi2/MidiRoster.dox index f462463d5f..6c7d182e57 100644 --- a/docs/user/midi2/MidiRoster.dox +++ b/docs/user/midi2/MidiRoster.dox @@ -1,7 +1,6 @@ /*! \file MidiRoster.h \ingroup midi2 - \ingroup libbe \brief Defines the heart of the MIDI Kit: the MIDI Roster. */ @@ -27,8 +26,6 @@ /*! \class BMidiRoster MidiRoster.h \ingroup midi2 - \ingroup libmidi2 - \ingroup libbe \brief Interface to the system-wide Midi Roster. BMidiRoster allows you to find available MIDI consumer and producer