jack/midiport.h

   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
  21 #ifndef __JACK_MIDIPORT_H
  22 #define __JACK_MIDIPORT_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 #include <jack/types.h>
  29 #include <stdlib.h>
  30
  31
  32 /** Type for raw event data contained in @ref jack_midi_event_t. */
  33 typedef unsigned char jack_midi_data_t;
  34
  35
  36 /** A Jack MIDI event. */
  37 typedef struct _jack_midi_event
  38 {
  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 */
  42 } jack_midi_event_t;
  43
  44
  45 /** Information about a Jack MIDI port/buffer. */
  46 typedef struct _jack_midi_port_info
  47 {
  48         jack_nframes_t event_count; /**< Number of events stored in the port */
  49 } jack_midi_port_info_t;
  50
  51
  52 /** Initialise the port state.
  53  *
  54  * @param port_buffer Port buffer to initialise.
  55  * @param nframes Number of valid frames this cycle.
  56  *
  57  * This must be called after port_buffer is allocated.
  58  */
  59 void
  60 jack_midi_reset_new_port(void           *port_buffer,
  61                          jack_nframes_t  nframes);
  62
  63
  64 /* Get a struct of information about a MIDI port.
  65  *
  66  * @param port_buffer Port buffer from which to retrieve event.
  67  * @param nframes Number of valid frames this cycle.
  68  * @return pointer to the @ref jack_midi_port_info_t structure that is inside @a port_buffer
  69  */
  70 jack_midi_port_info_t*
  71 jack_midi_port_get_info(void*          port_buffer,
  72                         jack_nframes_t nframes);
  73
  74
  75 /** Get a MIDI event from an event port buffer.
  76  *
  77  * Jack MIDI is normalised, the MIDI event returned by this function is
  78  * guaranteed to be a complete MIDI event (the status byte will always be
  79  * present, and no realtime events will interspered with the event).
  80  *
  81  * @param event Event structure to store retrieved event in.
  82  * @param port_buffer Port buffer from which to retrieve event.
  83  * @param event_index Index of event to retrieve.
  84  * @param nframes Number of valid frames this cycle.
  85  * @return 0 on success, ENODATA if buffer is empty.
  86  */
  87 int
  88 jack_midi_event_get(jack_midi_event_t *event,
  89                     void              *port_buffer,
  90                     jack_nframes_t     event_index,
  91                     jack_nframes_t     nframes);
  92
  93
  94 /** Clear an event buffer.
  95  *
  96  * This should be called at the beginning of each process cycle before calling
  97  * @ref jack_midi_event_reserve or @ref jack_midi_event_write. This
  98  * function may not be called on an input port's buffer.
  99  *
 100  * @param port_buffer Port buffer to clear (must be an output port buffer).
 101  * @param nframes Number of valid frames this cycle.
 102  */
 103 void
 104 jack_midi_clear_buffer(void           *port_buffer,
 105                        jack_nframes_t  nframes);
 106
 107
 108 /** Get the size of the largest event that can be stored by the port.
 109  *
 110  * This function returns the current space available, taking into account
 111  * events already stored in the port.
 112  *
 113  * @param port_buffer Port buffer to check size of.
 114  * @param nframes Number of valid frames this cycle.
 115  */
 116 size_t
 117 jack_midi_max_event_size(void* port_buffer, jack_nframes_t nframes);
 118
 119
 120 /** Allocate space for an event to be written to an event port buffer.
 121  *
 122  * Clients are to write the actual event data to be written starting at the
 123  * pointer returned by this function. Clients must not write more than
 124  * @a data_size bytes into this buffer.  Clients must write normalised
 125  * MIDI data to the port - no running status and no (1-byte) realtime
 126  * messages interspersed with other messages (realtime messages are fine
 127  * when they occur on their own, like other messages).
 128  *
 129  * @param port_buffer Buffer to write event to.
 130  * @param time Sample offset of event.
 131  * @param data_size Length of event's raw data in bytes.
 132  * @param nframes Number of valid frames this event.
 133  * @return Pointer to the beginning of the reserved event's data buffer, or
 134  * NULL on error (ie not enough space).
 135  */
 136 jack_midi_data_t*
 137 jack_midi_event_reserve(void           *port_buffer,
 138                         jack_nframes_t  time,
 139                         size_t          data_size,
 140                         jack_nframes_t  nframes);
 141
 142
 143 /** Write an event into an event port buffer.
 144  *
 145  * This function is simply a wrapper for @ref jack_midi_event_reserve
 146  * which writes the event data into the space reserved in the buffer.
 147  * The same restrictions on the MIDI data apply.
 148  *
 149  * @param port_buffer Buffer to write event to.
 150  * @param time Sample offset of event.
 151  * @param data Message data to be written.
 152  * @param data_size Length of @a data in bytes.
 153  * @param nframes Number of valid frames this event.
 154  * @return 0 on success, ENOBUFS if there's not enough space in buffer for event.
 155  */
 156 int
 157 jack_midi_event_write(void                   *port_buffer,
 158                       jack_nframes_t          time,
 159                       const jack_midi_data_t *data,
 160                       size_t                  data_size,
 161                       jack_nframes_t          nframes);
 162
 163
 164 /** Get the number of events that could not be written to @a port_buffer.
 165  *
 166  * This function returning a non-zero value implies @a port_buffer is full.
 167  * Currently the only way this can happen is if events are lost on port mixdown.
 168  *
 169  * @param port_buffer Port to receive count for.
 170  * @param nframes Number of valid frames this cycle.
 171  * @returns Number of events that could not be written to @a port_buffer.
 172  */
 173 jack_nframes_t
 174 jack_midi_get_lost_event_count(void           *port_buffer,
 175                                jack_nframes_t  nframes);
 176
 177
 178 #ifdef __cplusplus
 179 }
 180 #endif
 181
 182
 183 #endif /* __JACK_MIDIPORT_H */
 184
 185