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