1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
/*
Copyright (C) 2004 Ian Esten
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
#ifndef __JACK_MIDIPORT_H
#define __JACK_MIDIPORT_H
#ifdef __cplusplus
extern "C" {
#endif
#include <jack/types.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;
/** Information about a Jack MIDI port/buffer. */
typedef struct _jack_midi_port_info
{
jack_nframes_t event_count; /**< Number of events stored in the port */
} jack_midi_port_info_t;
/** Initialise the port state.
*
* @param port_buffer Port buffer to initialise.
* @param nframes Number of valid frames this cycle.
*
* This must be called after port_buffer is allocated.
*/
void
jack_midi_reset_new_port(void *port_buffer,
jack_nframes_t nframes);
/* Get a struct of information about a MIDI port.
*
* @param port_buffer Port buffer from which to retrieve event.
* @param nframes Number of valid frames this cycle.
* @return pointer to the @ref jack_midi_port_info_t structure that is inside @a port_buffer
*/
jack_midi_port_info_t*
jack_midi_port_get_info(void* port_buffer,
jack_nframes_t nframes);
/** 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).
*
* @param event Event structure to store retrieved event in.
* @param port_buffer Port buffer from which to retrieve event.
* @param event_index Index of event to retrieve.
* @param nframes Number of valid frames this cycle.
* @return 0 on success, ENODATA if buffer is empty.
*/
int
jack_midi_event_get(jack_midi_event_t *event,
void *port_buffer,
jack_nframes_t event_index,
jack_nframes_t nframes);
/** 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
* function may not be called on an input port's buffer.
*
* @param port_buffer Port buffer to clear (must be an output port buffer).
* @param nframes Number of valid frames this cycle.
*/
void
jack_midi_clear_buffer(void *port_buffer,
jack_nframes_t nframes);
/** 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.
*
* @param port_buffer Port buffer to check size of.
* @param nframes Number of valid frames this cycle.
*/
size_t
jack_midi_max_event_size(void* port_buffer, jack_nframes_t nframes);
/** 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
* 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).
*
* @param port_buffer Buffer to write event to.
* @param time Sample offset of event.
* @param data_size Length of event's raw data in bytes.
* @param nframes Number of valid frames this event.
* @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_nframes_t time,
size_t data_size,
jack_nframes_t nframes);
/** Write an event into an event port buffer.
*
* This function is simply a wrapper for @ref jack_midi_event_reserve
* which writes the event data into the space reserved in the buffer.
* The same restrictions on the MIDI data apply.
*
* @param port_buffer Buffer to write event to.
* @param time Sample offset of event.
* @param data Message data to be written.
* @param data_size Length of @a data in bytes.
* @param nframes Number of valid frames this event.
* @return 0 on success, ENOBUFS if there's not enough space in buffer for event.
*/
int
jack_midi_event_write(void *port_buffer,
jack_nframes_t time,
const jack_midi_data_t *data,
size_t data_size,
jack_nframes_t nframes);
/** 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.
*
* @param port_buffer Port to receive count for.
* @param nframes Number of valid frames this cycle.
* @returns Number of events that could not be written to @a port_buffer.
*/
jack_nframes_t
jack_midi_get_lost_event_count(void *port_buffer,
jack_nframes_t nframes);
#ifdef __cplusplus
}
#endif
#endif /* __JACK_MIDIPORT_H */
|
