2
Copyright (C) 2004 Ian Esten
4
This program is free software; you can redistribute it and/or modify
5
it under the terms of the GNU Lesser General Public License as published by
6
the Free Software Foundation; either version 2.1 of the License, or
7
(at your option) any later version.
9
This program is distributed in the hope that it will be useful,
10
but WITHOUT ANY WARRANTY; without even the implied warranty of
11
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
GNU Lesser General Public License for more details.
14
You should have received a copy of the GNU Lesser General Public License
15
along with this program; if not, write to the Free Software
16
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
21
#ifndef __JACK_MIDIPORT_H
22
#define __JACK_MIDIPORT_H
28
#include <jack/types.h>
32
/** Type for raw event data contained in @ref jack_midi_event_t. */
33
typedef unsigned char jack_midi_data_t;
36
/** A Jack MIDI event. */
37
typedef struct _jack_midi_event
39
jack_nframes_t time; /**< Sample index at which event is valid */
40
size_t size; /**< Number of bytes of data in \a buffer */
41
jack_midi_data_t *buffer; /**< Raw MIDI data */
46
* @defgroup MIDIAPI Reading and writing MIDI data
50
/* Get number of events in a port buffer.
52
* @param port_buffer Port buffer from which to retrieve event.
53
* @return number of events inside @a port_buffer
56
jack_midi_get_event_count(void* port_buffer);
59
/** Get a MIDI event from an event port buffer.
61
* Jack MIDI is normalised, the MIDI event returned by this function is
62
* guaranteed to be a complete MIDI event (the status byte will always be
63
* present, and no realtime events will interspered with the event).
65
* @param event Event structure to store retrieved event in.
66
* @param port_buffer Port buffer from which to retrieve event.
67
* @param event_index Index of event to retrieve.
68
* @return 0 on success, ENODATA if buffer is empty.
71
jack_midi_event_get(jack_midi_event_t *event,
73
jack_nframes_t event_index);
76
/** Clear an event buffer.
78
* This should be called at the beginning of each process cycle before calling
79
* @ref jack_midi_event_reserve or @ref jack_midi_event_write. This
80
* function may not be called on an input port's buffer.
82
* @param port_buffer Port buffer to clear (must be an output port buffer).
85
jack_midi_clear_buffer(void *port_buffer);
88
/** Get the size of the largest event that can be stored by the port.
90
* This function returns the current space available, taking into account
91
* events already stored in the port.
93
* @param port_buffer Port buffer to check size of.
96
jack_midi_max_event_size(void* port_buffer);
99
/** Allocate space for an event to be written to an event port buffer.
101
* Clients are to write the actual event data to be written starting at the
102
* pointer returned by this function. Clients must not write more than
103
* @a data_size bytes into this buffer. Clients must write normalised
104
* MIDI data to the port - no running status and no (1-byte) realtime
105
* messages interspersed with other messages (realtime messages are fine
106
* when they occur on their own, like other messages).
108
* @param port_buffer Buffer to write event to.
109
* @param time Sample offset of event.
110
* @param data_size Length of event's raw data in bytes.
111
* @return Pointer to the beginning of the reserved event's data buffer, or
112
* NULL on error (ie not enough space).
115
jack_midi_event_reserve(void *port_buffer,
120
/** Write an event into an event port buffer.
122
* This function is simply a wrapper for @ref jack_midi_event_reserve
123
* which writes the event data into the space reserved in the buffer.
124
* The same restrictions on the MIDI data apply.
126
* @param port_buffer Buffer to write event to.
127
* @param time Sample offset of event.
128
* @param data Message data to be written.
129
* @param data_size Length of @a data in bytes.
130
* @return 0 on success, ENOBUFS if there's not enough space in buffer for event.
133
jack_midi_event_write(void *port_buffer,
135
const jack_midi_data_t *data,
139
/** Get the number of events that could not be written to @a port_buffer.
141
* This function returning a non-zero value implies @a port_buffer is full.
142
* Currently the only way this can happen is if events are lost on port mixdown.
144
* @param port_buffer Port to receive count for.
145
* @returns Number of events that could not be written to @a port_buffer.
148
jack_midi_get_lost_event_count(void *port_buffer);
158
#endif /* __JACK_MIDIPORT_H */
added
removed
jack/midiport.h
