1 /* 2 Copyright (C) 2004 Ian Esten 3 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. 8 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. 13 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. 17 18 */ 19 20 module jack.c.midiport; 21 public import jack.c.systemdeps; 22 public import jack.c.types; 23 24 extern (C) 25 { 26 27 /** Type for raw event data contained in @ref jack_midi_event_t. */ 28 alias jack_midi_data_t = ubyte; 29 30 31 /** A Jack MIDI event. */ 32 struct jack_midi_event_t 33 { 34 jack_nframes_t time; /**< Sample index at which event is valid */ 35 size_t size; /**< Number of bytes of data in \a buffer */ 36 jack_midi_data_t *buffer; /**< Raw MIDI data */ 37 }; 38 39 40 /** 41 * @defgroup MIDIAPI Reading and writing MIDI data 42 * @{ 43 */ 44 45 /** Get number of events in a port buffer. 46 * 47 * @param port_buffer Port buffer from which to retrieve event. 48 * @return number of events inside @a port_buffer 49 */ 50 uint32_t 51 jack_midi_get_event_count(void* port_buffer) /* JACK_OPTIONAL_WEAK_EXPORT */; 52 53 54 /** Get a MIDI event from an event port buffer. 55 * 56 * Jack MIDI is normalised, the MIDI event returned by this function is 57 * guaranteed to be a complete MIDI event (the status byte will always be 58 * present, and no realtime events will interspered with the event). 59 * 60 * @param event Event structure to store retrieved event in. 61 * @param port_buffer Port buffer from which to retrieve event. 62 * @param event_index Index of event to retrieve. 63 * @return 0 on success, ENODATA if buffer is empty. 64 */ 65 int 66 jack_midi_event_get(jack_midi_event_t *event, 67 void *port_buffer, 68 uint32_t event_index) /* JACK_OPTIONAL_WEAK_EXPORT */; 69 70 71 /** Clear an event buffer. 72 * 73 * This should be called at the beginning of each process cycle before calling 74 * @ref jack_midi_event_reserve or @ref jack_midi_event_write. This 75 * function may not be called on an input port's buffer. 76 * 77 * @param port_buffer Port buffer to clear (must be an output port buffer). 78 */ 79 void 80 jack_midi_clear_buffer(void *port_buffer) /* JACK_OPTIONAL_WEAK_EXPORT */; 81 82 83 /** Get the size of the largest event that can be stored by the port. 84 * 85 * This function returns the current space available, taking into account 86 * events already stored in the port. 87 * 88 * @param port_buffer Port buffer to check size of. 89 */ 90 size_t 91 jack_midi_max_event_size(void* port_buffer) /* JACK_OPTIONAL_WEAK_EXPORT */; 92 93 94 /** Allocate space for an event to be written to an event port buffer. 95 * 96 * Clients are to write the actual event data to be written starting at the 97 * pointer returned by this function. Clients must not write more than 98 * @a data_size bytes into this buffer. Clients must write normalised 99 * MIDI data to the port - no running status and no (1-byte) realtime 100 * messages interspersed with other messages (realtime messages are fine 101 * when they occur on their own, like other messages). 102 * 103 * Events must be written in order, sorted by their sample offsets. 104 * JACK will not sort the events for you, and will refuse to store 105 * out-of-order events. 106 * 107 * @param port_buffer Buffer to write event to. 108 * @param time Sample offset of event. 109 * @param data_size Length of event's raw data in bytes. 110 * @return Pointer to the beginning of the reserved event's data buffer, or 111 * NULL on error (ie not enough space). 112 */ 113 jack_midi_data_t* 114 jack_midi_event_reserve(void *port_buffer, 115 jack_nframes_t time, 116 size_t data_size) /* JACK_OPTIONAL_WEAK_EXPORT */; 117 118 119 /** Write an event into an event port buffer. 120 * 121 * This function is simply a wrapper for @ref jack_midi_event_reserve 122 * which writes the event data into the space reserved in the buffer. 123 * 124 * Clients must not write more than 125 * @a data_size bytes into this buffer. Clients must write normalised 126 * MIDI data to the port - no running status and no (1-byte) realtime 127 * messages interspersed with other messages (realtime messages are fine 128 * when they occur on their own, like other messages). 129 * 130 * Events must be written in order, sorted by their sample offsets. 131 * JACK will not sort the events for you, and will refuse to store 132 * out-of-order events. 133 * 134 * @param port_buffer Buffer to write event to. 135 * @param time Sample offset of event. 136 * @param data Message data to be written. 137 * @param data_size Length of @a data in bytes. 138 * @return 0 on success, ENOBUFS if there's not enough space in buffer for event. 139 */ 140 int 141 jack_midi_event_write(void *port_buffer, 142 jack_nframes_t time, 143 const(jack_midi_data_t) *data, 144 size_t data_size) /* JACK_OPTIONAL_WEAK_EXPORT */; 145 146 147 /** Get the number of events that could not be written to @a port_buffer. 148 * 149 * This function returning a non-zero value implies @a port_buffer is full. 150 * Currently the only way this can happen is if events are lost on port mixdown. 151 * 152 * @param port_buffer Port to receive count for. 153 * @returns Number of events that could not be written to @a port_buffer. 154 */ 155 uint32_t 156 jack_midi_get_lost_event_count(void *port_buffer) /* JACK_OPTIONAL_WEAK_EXPORT */; 157 158 /*@}*/ 159 160 }