Rename midi functions to message

- Renamed all the methods, sometimes altering their name to make them more consistent - Removed deprecated methods - Adapted documentation - The `JackMessageAPI.cpp` currently is just a copy of `JackMidiAPI.cpp`.
piegamesde · Oct 12, 2019 · 8614e5d · 8614e5d
1 parent 0340919
commit 8614e5d
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 66 deletions.
diff --git a/common/JackMessageAPI.cpp b/common/JackMessageAPI.cpp
@@ -28,24 +28,22 @@ extern "C"
 {
 #endif
 
-    LIB_EXPORT uint32_t jack_midi_get_event_count(void* port_buffer);
+    LIB_EXPORT uint32_t jack_message_get_event_count(void* port_buffer);
 
-    LIB_EXPORT int jack_midi_event_get(jack_midi_event_t* event,
+    LIB_EXPORT int jack_message_event_read(jack_midi_event_t* event,
                                    void* port_buffer, uint32_t event_index);
 
-    LIB_EXPORT void jack_midi_clear_buffer(void* port_buffer);
-
-    LIB_EXPORT void jack_midi_reset_buffer(void* port_buffer);
+    LIB_EXPORT void jack_message_clear_buffer(void* port_buffer);
 
-    LIB_EXPORT size_t jack_midi_max_event_size(void* port_buffer);
+    LIB_EXPORT size_t jack_message_get_max_event_size(void* port_buffer);
 
-    LIB_EXPORT jack_midi_data_t* jack_midi_event_reserve(void* port_buffer,
+    LIB_EXPORT jack_midi_data_t* jack_message_event_reserve(void* port_buffer,
             jack_nframes_t time, size_t data_size);
 
-    LIB_EXPORT int jack_midi_event_write(void* port_buffer,
+    LIB_EXPORT int jack_message_event_write(void* port_buffer,
                                      jack_nframes_t time, const jack_midi_data_t* data, size_t data_size);
 
-    LIB_EXPORT jack_nframes_t jack_midi_get_lost_event_count(void* port_buffer);
+    LIB_EXPORT jack_nframes_t jack_message_get_lost_event_count(void* port_buffer);
 
 #ifdef __cplusplus
 }
@@ -54,7 +52,7 @@ extern "C"
 using namespace Jack;
 
 LIB_EXPORT
-uint32_t jack_midi_get_event_count(void* port_buffer)
+uint32_t jack_message_get_event_count(void* port_buffer)
 {
     JackMidiBuffer *buf = (JackMidiBuffer*)port_buffer;
     if (!buf || !buf->IsValid()) {
@@ -64,7 +62,7 @@ uint32_t jack_midi_get_event_count(void* port_buffer)
 }
 
 LIB_EXPORT
-int jack_midi_event_get(jack_midi_event_t *event, void* port_buffer, uint32_t event_index)
+int jack_message_event_read(jack_midi_event_t *event, void* port_buffer, uint32_t event_index)
 {
     JackMidiBuffer *buf = (JackMidiBuffer*)port_buffer;
     if (!buf || !buf->IsValid()) {
@@ -81,7 +79,7 @@ int jack_midi_event_get(jack_midi_event_t *event, void* port_buffer, uint32_t ev
 }
 
 LIB_EXPORT
-void jack_midi_clear_buffer(void* port_buffer)
+void jack_message_clear_buffer(void* port_buffer)
 {
     JackMidiBuffer *buf = (JackMidiBuffer*)port_buffer;
     if (buf && buf->IsValid()) {
@@ -90,13 +88,7 @@ void jack_midi_clear_buffer(void* port_buffer)
 }
 
 LIB_EXPORT
-void jack_midi_reset_buffer(void* port_buffer)
-{
-    MidiBufferInit(port_buffer, BUFFER_SIZE_MAX, BUFFER_SIZE_MAX);
-}
-
-LIB_EXPORT
-size_t jack_midi_max_event_size(void* port_buffer)
+size_t jack_message_get_max_event_size(void* port_buffer)
 {
     JackMidiBuffer *buf = (JackMidiBuffer*)port_buffer;
     if (buf && buf->IsValid()) {
@@ -106,7 +98,7 @@ size_t jack_midi_max_event_size(void* port_buffer)
 }
 
 LIB_EXPORT
-jack_midi_data_t* jack_midi_event_reserve(void* port_buffer, jack_nframes_t time, size_t data_size)
+jack_midi_data_t* jack_message_event_reserve(void* port_buffer, jack_nframes_t time, size_t data_size)
 {
     JackMidiBuffer *buf = (JackMidiBuffer*)port_buffer;
     if (! buf) {
@@ -131,7 +123,7 @@ jack_midi_data_t* jack_midi_event_reserve(void* port_buffer, jack_nframes_t time
 }
 
 LIB_EXPORT
-int jack_midi_event_write(void* port_buffer,
+int jack_message_event_write(void* port_buffer,
                           jack_nframes_t time, const jack_midi_data_t* data, size_t data_size)
 {
     JackMidiBuffer *buf = (JackMidiBuffer*)port_buffer;
@@ -150,7 +142,7 @@ int jack_midi_event_write(void* port_buffer,
 }
 
 LIB_EXPORT
-uint32_t jack_midi_get_lost_event_count(void* port_buffer)
+uint32_t jack_message_get_lost_event_count(void* port_buffer)
 {
     JackMidiBuffer *buf = (JackMidiBuffer*)port_buffer;
     if (buf && buf->IsValid()) {

diff --git a/common/jack/messageport.h b/common/jack/messageport.h
@@ -18,8 +18,8 @@
 */
 
 
-#ifndef __JACK_MIDIPORT_H
-#define __JACK_MIDIPORT_H
+#ifndef __JACK_MESSAGEPORT_H
+#define __JACK_MESSAGEPORT_H
 
 #ifdef __cplusplus
 extern "C" {
@@ -42,6 +42,9 @@ typedef struct _jack_midi_event
 	jack_midi_data_t *buffer; /**< Raw MIDI data */
 } jack_midi_event_t;
 
+typedef jack_midi_data_t jack_message_data_t;
+typedef jack_midi_event_t jack_message_event_t;
+
 
 /**
  * @defgroup MIDIAPI Reading and writing MIDI data
@@ -54,10 +57,15 @@ typedef struct _jack_midi_event
  * @return number of events inside @a port_buffer
  */
 uint32_t
-jack_midi_get_event_count(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
+jack_message_get_event_count(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
 
 
-/** Get a MIDI event from an event port buffer.
+/**
+ * Read an event from a message port buffer. It is up to the caller to determine
+ * which protocol to interpret the data with. The port's type and the metadata
+ * API should suffice to do so.
+ * 
+ * If the event represents MIDI data:
  *
  * Jack MIDI is normalised, the MIDI event returned by this function is
  * guaranteed to be a complete MIDI event (the status byte will always be
@@ -80,34 +88,21 @@ jack_midi_get_event_count(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
  * @return 0 on success, ENODATA if buffer is empty.
  */
 int
-jack_midi_event_get(jack_midi_event_t *event,
+jack_message_event_read(jack_message_event_t *event,
                     void        *port_buffer,
                     uint32_t    event_index) JACK_OPTIONAL_WEAK_EXPORT;
 
 
 /** Clear an event buffer.
  *
  * This should be called at the beginning of each process cycle before calling
- * @ref jack_midi_event_reserve or @ref jack_midi_event_write. This
+ * @ref jack_message_event_reserve or @ref jack_message_event_write. This
  * function may not be called on an input port's buffer.
  *
  * @param port_buffer Port buffer to clear (must be an output port buffer).
  */
 void
-jack_midi_clear_buffer(void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
-
-/** Reset an event buffer (from data allocated outside of JACK).
- *
- * This should be called at the beginning of each process cycle before calling
- * @ref jack_midi_event_reserve or @ref jack_midi_event_write. This
- * function may not be called on an input port's buffer.
- *
- * @deprecated Please use jack_midi_clear_buffer().
- *
- * @param port_buffer Port buffer to reset.
- */
-void
-jack_midi_reset_buffer(void *port_buffer) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
+jack_message_clear_buffer(void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
 
 
 /** Get the size of the largest event that can be stored by the port.
@@ -118,14 +113,17 @@ jack_midi_reset_buffer(void *port_buffer) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
  * @param port_buffer Port buffer to check size of.
  */
 size_t
-jack_midi_max_event_size(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
+jack_message_get_max_event_size(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
 
 
 /** Allocate space for an event to be written to an event port buffer.
  *
  * Clients are to write the actual event data to be written starting at the
  * pointer returned by this function. Clients must not write more than
- * @a data_size bytes into this buffer.  Clients must write normalised
+ * @a data_size bytes into this buffer. Clients may write arbitrary binary data,
+ * but should only write events using the protocol associated with the port.
+ * 
+ * If this is a MIDI port, clients must write normalised
  * MIDI data to the port - no running status and no (1-byte) realtime
  * messages interspersed with other messages (realtime messages are fine
  * when they occur on their own, like other messages).
@@ -140,19 +138,21 @@ jack_midi_max_event_size(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
  * @return Pointer to the beginning of the reserved event's data buffer, or
  * NULL on error (ie not enough space).
  */
-jack_midi_data_t*
-jack_midi_event_reserve(void *port_buffer,
+jack_message_data_t*
+jack_message_event_reserve(void *port_buffer,
                         jack_nframes_t  time,
                         size_t data_size) JACK_OPTIONAL_WEAK_EXPORT;
 
 
 /** Write an event into an event port buffer.
  *
- * This function is simply a wrapper for @ref jack_midi_event_reserve
+ * This function is simply a wrapper for @ref jack_message_sevent_reserve
  * which writes the event data into the space reserved in the buffer.
  *
  * Clients must not write more than
- * @a data_size bytes into this buffer.  Clients must write normalised
+ * @a data_size bytes into this buffer. Clients may write arbitrary binary data,
+ * but should only write events using the protocol associated with the port. 
+ * If this is a MIDI port, clients must write normalised
  * MIDI data to the port - no running status and no (1-byte) realtime
  * messages interspersed with other messages (realtime messages are fine
  * when they occur on their own, like other messages).
@@ -168,22 +168,23 @@ jack_midi_event_reserve(void *port_buffer,
  * @return 0 on success, ENOBUFS if there's not enough space in buffer for event.
  */
 int
-jack_midi_event_write(void *port_buffer,
+jack_message_event_write(void *port_buffer,
                       jack_nframes_t time,
-                      const jack_midi_data_t *data,
+                      const jack_message_data_t *data,
                       size_t data_size) JACK_OPTIONAL_WEAK_EXPORT;
 
 
 /** Get the number of events that could not be written to @a port_buffer.
  *
  * This function returning a non-zero value implies @a port_buffer is full.
- * Currently the only way this can happen is if events are lost on port mixdown.
+ * Currently the only way this can happen is if events are lost on port mixdown
+ * (when multiple event output ports are connected to one input port).
  *
  * @param port_buffer Port to receive count for.
  * @returns Number of events that could not be written to @a port_buffer.
  */
 uint32_t
-jack_midi_get_lost_event_count(void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
+jack_message_get_lost_event_count(void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
 
 /*@}*/
 
@@ -192,6 +193,6 @@ jack_midi_get_lost_event_count(void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
 #endif
 
 
-#endif /* __JACK_MIDIPORT_H */
+#endif /* __JACK_MESSAGEPORT_H */
 
 
diff --git a/common/jack/midiport.h b/common/jack/midiport.h
@@ -27,22 +27,10 @@ extern "C" {
 
 #include <jack/weakmacros.h>
 #include <jack/types.h>
+#include <jack/messageport.h>
 #include <stdlib.h>
 
 
-/** Type for raw event data contained in @ref jack_midi_event_t. */
-typedef unsigned char jack_midi_data_t;
-
-
-/** A Jack MIDI event. */
-typedef struct _jack_midi_event
-{
-	jack_nframes_t    time;   /**< Sample index at which event is valid */
-	size_t            size;   /**< Number of bytes of data in \a buffer */
-	jack_midi_data_t *buffer; /**< Raw MIDI data */
-} jack_midi_event_t;
-
-
 /**
  * @defgroup MIDIAPI Reading and writing MIDI data
  * @{