midiport.h 5.76 KB
Newer Older
sletz's avatar
sletz committed
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
/*
    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>
sletz's avatar
sletz committed
30
#include <jack/weakmacros.h>
sletz's avatar
sletz committed
31
32
33
34
35
36
37
38
39
40
41
42
43
44
	
/** 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;


45
46
47
48
49
/**
 * @defgroup MIDIAPI Reading and writing MIDI data 
 * @{
 */

50
/** Get number of events in a port buffer.
sletz's avatar
sletz committed
51
52
53
54
55
 *
 * @param port_buffer Port buffer from which to retrieve event.
 * @return number of events inside @a port_buffer
 */
jack_nframes_t
sletz's avatar
sletz committed
56
jack_midi_get_event_count(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
sletz's avatar
sletz committed
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72


/** 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.
 * @return 0 on success, ENODATA if buffer is empty.
 */
int
jack_midi_event_get(jack_midi_event_t *event,
                    void              *port_buffer,
sletz's avatar
sletz committed
73
                    jack_nframes_t     event_index) JACK_OPTIONAL_WEAK_EXPORT;
sletz's avatar
sletz committed
74
75
76
77
78
79
80
81
82
83
84


/** 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).
 */
void
sletz's avatar
sletz committed
85
jack_midi_clear_buffer(void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
sletz's avatar
sletz committed
86
87
88
89
90
91
92
93
94
95


/** 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.
 */
size_t
sletz's avatar
sletz committed
96
jack_midi_max_event_size(void* port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
sletz's avatar
sletz committed
97
98
99
100
101
102
103
104
105
106
107


/** 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).
 *
108
109
110
111
 * 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. 
 * 
sletz's avatar
sletz committed
112
113
114
115
116
117
118
 * @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.
 * @return Pointer to the beginning of the reserved event's data buffer, or
 * NULL on error (ie not enough space).
 */
jack_midi_data_t*
sletz's avatar
sletz committed
119
jack_midi_event_reserve(void *port_buffer,
sletz's avatar
sletz committed
120
                        jack_nframes_t  time, 
sletz's avatar
sletz committed
121
                        size_t data_size) JACK_OPTIONAL_WEAK_EXPORT;
sletz's avatar
sletz committed
122
123
124
125
126
127
128


/** 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.
129
130
131
132
133
134
135
136
137
138
 *
 * 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). 
 * 
 * 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.
sletz's avatar
sletz committed
139
140
141
142
143
144
145
146
 * 
 * @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.
 * @return 0 on success, ENOBUFS if there's not enough space in buffer for event.
 */
int
sletz's avatar
sletz committed
147
148
jack_midi_event_write(void *port_buffer,
                      jack_nframes_t time,
sletz's avatar
sletz committed
149
                      const jack_midi_data_t *data,
sletz's avatar
sletz committed
150
                      size_t data_size) JACK_OPTIONAL_WEAK_EXPORT;
sletz's avatar
sletz committed
151
152
153
154
155
156
157
158
159
160
161


/** 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.
 * @returns Number of events that could not be written to @a port_buffer.
 */
jack_nframes_t
sletz's avatar
sletz committed
162
jack_midi_get_lost_event_count(void *port_buffer) JACK_OPTIONAL_WEAK_EXPORT;
sletz's avatar
sletz committed
163

164
/*@}*/
sletz's avatar
sletz committed
165
166
167
168
169
170
171
172
173

#ifdef __cplusplus
}
#endif


#endif /* __JACK_MIDIPORT_H */