Crudebyte Logo
JACKiOS  1.9.10.3
Reading and writing MIDI data

Detailed Description

MIDI support in JACK is implemented as extension on top of the multi-purpose port design of the JACK API. That means ports are created, searched and managed with the same set of core functions (covered by the main JACK API functions in jack.h) as audio ports are managed with JACK.

The few functions in this API part cover the MIDI data aware parts necessary to use JACK MIDI ports conveniently in applications.

Functions

uint32_t jack_midi_get_event_count (void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT
int jack_midi_event_get (jack_midi_event_t *event, void *port_buffer, uint32_t event_index) JACK_OPTIONAL_WEAK_EXPORT
void jack_midi_clear_buffer (void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT
size_t jack_midi_max_event_size (void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT
jack_midi_data_tjack_midi_event_reserve (void *port_buffer, jack_nframes_t time, size_t data_size) JACK_OPTIONAL_WEAK_EXPORT
int jack_midi_event_write (void *port_buffer, jack_nframes_t time, const jack_midi_data_t *data, size_t data_size) JACK_OPTIONAL_WEAK_EXPORT
uint32_t jack_midi_get_lost_event_count (void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT

Function Documentation

uint32_t jack_midi_get_event_count ( void *  port_buffer)

Get number of events in a port buffer.

Parameters
port_bufferPort buffer from which to retrieve event.
Returns
number of events inside port_buffer
int jack_midi_event_get ( jack_midi_event_t event,
void *  port_buffer,
uint32_t  event_index 
)

Get a MIDI event from an event port buffer.

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 present, and no realtime events will interspered with the event).

Parameters
eventEvent structure to store retrieved event in.
port_bufferPort buffer from which to retrieve event.
event_indexIndex of event to retrieve.
Returns
0 on success, ENODATA if buffer is empty.
void jack_midi_clear_buffer ( void *  port_buffer)

Clear an event buffer.

This should be called at the beginning of each process cycle before calling jack_midi_event_reserve or jack_midi_event_write. This function may not be called on an input port's buffer.

Parameters
port_bufferPort buffer to clear (must be an output port buffer).
size_t jack_midi_max_event_size ( void *  port_buffer)

Get the size of the largest event that can be stored by the port.

This function returns the current space available, taking into account events already stored in the port.

Parameters
port_bufferPort buffer to check size of.
jack_midi_data_t* jack_midi_event_reserve ( void *  port_buffer,
jack_nframes_t  time,
size_t  data_size 
)

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 data_size bytes into this buffer. 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).

Events must be written in order, sorted by their sample offsets. JACK will not sort the events for you, and will refuse to store out-of-order events.

Parameters
port_bufferBuffer to write event to.
timeSample offset of event.
data_sizeLength of event's raw data in bytes.
Returns
Pointer to the beginning of the reserved event's data buffer, or NULL on error (ie not enough space).
int jack_midi_event_write ( void *  port_buffer,
jack_nframes_t  time,
const jack_midi_data_t data,
size_t  data_size 
)

Write an event into an event port buffer.

This function is simply a wrapper for jack_midi_event_reserve which writes the event data into the space reserved in the buffer.

Clients must not write more than data_size bytes into this buffer. 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).

Events must be written in order, sorted by their sample offsets. JACK will not sort the events for you, and will refuse to store out-of-order events.

Parameters
port_bufferBuffer to write event to.
timeSample offset of event.
dataMessage data to be written.
data_sizeLength of data in bytes.
Returns
0 on success, ENOBUFS if there's not enough space in buffer for event.
uint32_t jack_midi_get_lost_event_count ( void *  port_buffer)

Get the number of events that could not be written to port_buffer.

This function returning a non-zero value implies port_buffer is full. Currently the only way this can happen is if events are lost on port mixdown.

Parameters
port_bufferPort to receive count for.
Returns
Number of events that could not be written to port_buffer.
DE • EN
Copyright © MMXIII Crudebyte. All rights reserved.

twitter