src/calf/lv2-midiport.h

   1 /****************************************************************************
   2
   3     lv2-midiport.h - header file for using MIDI in LV2 plugins
   4
   5     Copyright (C) 2006  Lars Luthman <lars.luthman@gmail.com>
   6
   7     This program is free software; you can redistribute it and/or modify
   8     it under the terms of the GNU Lesser General Public License as published by
   9     the Free Software Foundation; either version 2 of the License, or
  10     (at your option) any later version.
  11
  12     This program is distributed in the hope that it will be useful,
  13     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15     GNU Lesser General Public License for more details.
  16
  17     You should have received a copy of the GNU Lesser General Public License
  18     along with this program; if not, write to the Free Software
  19     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307  USA
  20
  21 ****************************************************************************/
  22
  23 /** @file
  24     This file contains the specification for an LV2 MIDI port extension.
  25 */
  26
  27 #ifndef LV2_MIDIPORT_H
  28 #define LV2_MIDIPORT_H
  29
  30
  31 /** This data structure is used to contain the MIDI events for one run()
  32     cycle. The port buffer for an LV2 port of the type
  33     <http://ll-plugins.nongnu.org/lv2/ext/MidiPort> should be a pointer
  34     to an instance of this struct.
  35
  36     To store two Note On events on MIDI channel 0 in a buffer, with timestamps
  37     12 and 35.5, you could use something like this code (assuming that
  38     midi_data is a variable of type LV2_MIDI):
  39     @code
  40
  41       uint32_t buffer_offset = 0;
  42       *(double*)(midi_data->data + buffer_offset) = 12;
  43       buffer_offset += sizeof(double);
  44       *(uint32_t*)(midi_data->data + buffer_offset) = 3;
  45       buffer_offset += sizeof(uint32_t);
  46       midi_data->data[buffer_offset++] = 0x90;
  47       midi_data->data[buffer_offset++] = 0x48;
  48       midi_data->data[buffer_offset++] = 0x64;
  49       ++midi_data->event_count;
  50
  51       *(double*)(midi_data->data + buffer_offset) = 35.5;
  52       buffer_offset += sizeof(double);
  53       *(uint32_t*)(midi_data->data + buffer_offset) = 3;
  54       buffer_offset += sizeof(uint32_t);
  55       midi_data->data[buffer_offset++] = 0x90;
  56       midi_data->data[buffer_offset++] = 0x55;
  57       midi_data->data[buffer_offset++] = 0x64;
  58       ++midi_data->event_count;
  59
  60       midi_data->size = buffer_offset;
  61
  62     @endcode
  63
  64     This would be done by the host in the case of an input port, and by the
  65     plugin in the case of an output port. Whoever is writing events to the
  66     buffer must also take care not to exceed the capacity of the data buffer.
  67
  68     To read events from a buffer, you could do something like this:
  69     @code
  70
  71       uint32_t buffer_offset = 0;
  72       uint32_t i;
  73       for (i = 0; i < midi_data->event_count; ++i) {
  74         double timestamp = *(double*)(midi_data->data + buffer_offset);
  75         buffer_offset += sizeof(double);
  76         uint32_t size = *(uint32_t*)(midi_data->data + buffer_offset);
  77         buffer_offset += sizeof(uint32_t);
  78         do_something_with_event(timestamp, size,
  79                                 midi_data->data + buffer_offset);
  80         buffer_offset += size;
  81       }
  82
  83     @endcode
  84
  85     If you think this looks like too much code to simply read and write MIDI
  86     events, take a look at the helper functions in lv2-midifunctions.h. They
  87     are not an official part of this extension, but they can be convenient.
  88 */
  89 typedef struct {
  90
  91   /** The number of MIDI events in the data buffer.
  92       INPUT PORTS: It's the host's responsibility to set this field to the
  93       number of MIDI events contained in the data buffer before calling the
  94       plugin's run() function. The plugin may not change this field.
  95       OUTPUT PORTS: It's the plugin's responsibility to set this field to the
  96       number of MIDI events it has stored in the data buffer before returning
  97       from the run() function. Any initial value should be ignored by the
  98       plugin.
  99   */
 100   uint32_t  event_count;
 101
 102   /** The size of the data buffer in bytes. It is set by the host and may not
 103       be changed by the plugin. The host is allowed to change this between
 104       run() calls.
 105   */
 106   uint32_t  capacity;
 107
 108   /** The size of the initial part of the data buffer that actually contains
 109       data.
 110       INPUT PORTS: It's the host's responsibility to set this field to the
 111       number of bytes used by all MIDI events it has written to the buffer
 112       (including timestamps and size fields) before calling the plugin's
 113       run() function. The plugin may not change this field.
 114       OUTPUT PORTS: It's the plugin's responsibility to set this field to
 115       the number of bytes used by all MIDI events it has written to the
 116       buffer (including timestamps and size fields) before returning from
 117       the run() function. Any initial value should be ignored by the plugin.
 118   */
 119   uint32_t  size;
 120
 121   /** The data buffer that is used to store MIDI events. The events are packed
 122       after each other, and the format of each event is as follows:
 123
 124       First there is a timestamp, which should have the type "double",
 125       i.e. have the same bit size as a double and the same bit layout as a
 126       double (whatever that is on the current platform). This timestamp gives
 127       the offset from the beginning of the current cycle, in frames, that
 128       the MIDI event occurs on. It must be strictly smaller than the 'nframes'
 129       parameter to the current run() call. The MIDI events in the buffer must
 130       be ordered by their timestamp, e.g. an event with a timestamp of 123.23
 131       must be stored after an event with a timestamp of 65.0.
 132
 133       The second part of the event is a size field, which should have the type
 134       "uint32_t" (as defined in the standard C header stddef.h). It should
 135       contain the size of the MIDI data for this event, i.e. the number of
 136       bytes used to store the actual MIDI event. The bytes used by the
 137       timestamp and the size field should not be counted.
 138
 139       The third part of the event is the actual MIDI data. There are some
 140       requirements that must be followed:
 141
 142       * Running status is not allowed. Every event must have its own status
 143         byte.
 144       * Note On events with velocity 0 are not allowed. These events are
 145         equivalent to Note Off in standard MIDI streams, but in order to make
 146         plugins and hosts easier to write, as well as more efficient, only
 147         proper Note Off events are allowed as Note Off.
 148       * "Realtime events" (status bytes 0xF8 to 0xFF) are allowed, but may not
 149         occur inside other events like they are allowed to in hardware MIDI
 150         streams.
 151       * All events must be fully contained in a single data buffer, i.e. events
 152         may not "wrap around" by storing the first few bytes in one buffer and
 153         then wait for the next run() call to store the rest of the event. If
 154         there isn't enough space in the current data buffer to store an event,
 155         the event will either have to wait until next run() call, be ignored,
 156         or compensated for in some more clever way.
 157       * All events must be valid MIDI events. This means for example that
 158         only the first byte in each event (the status byte) may have the eighth
 159         bit set, that Note On and Note Off events are always 3 bytes long etc.
 160         The MIDI writer (host or plugin) is responsible for writing valid MIDI
 161         events to the buffer, and the MIDI reader (plugin or host) can assume
 162         that all events are valid.
 163
 164       On a platform where double is 8 bytes the data buffer layout for a
 165       3-byte event followed by a 4-byte event may look something like this:
 166       _______________________________________________________________
 167       | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ...
 168       |TIMESTAMP 1    |SIZE 1 |DATA |TIMESTAMP 2    |SIZE 2 |DATA   | ...
 169
 170   */
 171   unsigned char* data;
 172
 173 } LV2_MIDI;
 174
 175
 176
 177 #endif