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