From 6d2dba2a11fada7939d6418e6e1e4515d5fe5871 Mon Sep 17 00:00:00 2001 From: piegames Date: Sat, 12 Oct 2019 16:15:54 +0200 Subject: [PATCH] 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`. --- common/JackMessageAPI.cpp | 36 ++++++++------------- common/jack/messageport.h | 68 +++++++++++++++++++++------------------ common/jack/midiport.h | 14 +------- 3 files changed, 51 insertions(+), 67 deletions(-) diff --git a/common/JackMessageAPI.cpp b/common/JackMessageAPI.cpp index 61d77e12..d3aebce9 100644 --- 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 index 3fbf2126..370c9f22 100644 --- 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,9 +42,15 @@ 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 + * @defgroup MESSAGEAPI Reading and writing event data. This supersedes the + * older Midi API by extending it to work with arbitrary messsage protocols. + * The usage is basically the same except for renaming some methods. Use the + * metadata API to specify which protocol a port implements. * @{ */ @@ -54,10 +60,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,7 +91,7 @@ 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; @@ -88,26 +99,13 @@ jack_midi_event_get(jack_midi_event_t *event, /** 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 +116,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 +141,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 +171,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 +196,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 index 3fbf2126..39a3f141 100644 --- a/common/jack/midiport.h +++ b/common/jack/midiport.h @@ -27,22 +27,10 @@ extern "C" { #include #include +#include #include -/** 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 * @{