libs/ardour/lv2ext/lv2_event.h

   1 /* lv2_event.h - C header file for the LV2 events extension.
   2  *
   3  * Copyright (C) 2006-2007 Lars Luthman <lars.luthman@gmail.com>
   4  * Copyright (C) 2008 Dave Robillard <dave@drobilla.net>
   5  *
   6  * This header is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU Lesser General Public License as published
   8  * by the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This header is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  14  * License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this header; if not, write to the Free Software Foundation,
  18  * Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA
  19  */
  20
  21 #ifndef LV2_EVENT_H
  22 #define LV2_EVENT_H
  23
  24 #define LV2_EVENT_URI "http://lv2plug.in/ns/ext/event"
  25 #define LV2_EVENT_AUDIO_STAMP 0
  26
  27 #include <stdint.h>
  28
  29 /** @file
  30  * This header defines the code portion of the LV2 events extension with URI
  31  * <http://lv2plug.in/ns/ext/event> ('lv2ev').
  32  *
  33  * This extension is a generic transport mechanism for time stamped events
  34  * of any type (e.g. MIDI, OSC, ramps, etc).  Each port can transport mixed
  35  * events of any type; the type of events and timestamps are defined by a URI
  36  * which is mapped to an integer by the host for performance reasons.
  37  *
  38  * This extension requires the host to support the LV2 URI Map extension.
  39  * Any host which supports this extension MUST guarantee that any call to
  40  * the LV2 URI Map uri_to_id function with the URI of this extension as the
  41  * 'map' argument returns a value within the range of uint16_t.
  42  */
  43
  44
  45 /** The best Pulses Per Quarter Note for tempo-based uint32_t timestmaps.
  46  * Equal to 2^12 * 5 * 7 * 9 * 11 * 13 * 17, which is evenly divisble
  47  * by all integers from 1 through 18 inclusive, and powers of 2 up to 2^12.
  48  */
  49 static const uint32_t LV2_EVENT_PPQN = 3136573440U;
  50
  51
  52 /** An LV2 event (header only).
  53  *
  54  * LV2 events are generic time-stamped containers for any type of event.
  55  * The type field defines the format of a given event's contents.
  56  *
  57  * This struct defines the header of an LV2 event.  An LV2 event is a single
  58  * chunk of POD (plain old data), usually contained in a flat buffer
  59  * (see LV2_EventBuffer below).  Unless a required feature says otherwise,
  60  * hosts may assume a deep copy of an LV2 event can be created safely
  61  * using a simple:
  62  *
  63  * memcpy(ev_copy, ev, sizeof(LV2_Event) + ev->size);  (or equivalent)
  64  */
  65 typedef struct {
  66
  67         /** The frames portion of timestamp.  The units used here can optionally be
  68          * set for a port (with the lv2ev:timeUnits property), otherwise this
  69          * is audio frames, corresponding to the sample_count parameter of the
  70          * LV2 run method (e.g. frame 0 is the first frame for that call to run).
  71          */
  72         uint32_t frames;
  73
  74         /** The sub-frames portion of timestamp.  The units used here can
  75          * optionally be set for a port (with the lv2ev:timeUnits property),
  76          * otherwise this is 1/(2^32) of an audio frame.
  77          */
  78         uint32_t subframes;
  79
  80         /** The type of this event, as a number which represents some URI
  81          * defining an event type.  This value MUST be some value previously
  82          * returned from a call to the uri_to_id function defined in the LV2
  83          * URI map extension (see lv2_uri_map.h).
  84          * There are special rules which must be followed depending on the type
  85          * of an event.  If the plugin recognizes an event type, the definition
  86          * of that event type will describe how to interpret the event, and
  87          * any required behaviour.  Otherwise, if the type is 0, this event is a
  88          * non-POD event and lv2_event_unref MUST be called if the event is
  89          * 'dropped' (see above).  Even if the plugin does not understand an event,
  90          * it may pass the event through to an output by simply copying (and NOT
  91          * calling lv2_event_unref).  These rules are designed to allow for generic
  92          * event handling plugins and large non-POD events, but with minimal hassle
  93          * on simple plugins that "don't care" about these more advanced features.
  94          */
  95         uint16_t type;
  96
  97         /** The size of the data portion of this event in bytes, which immediately
  98          * follows.  The header size (12 bytes) is not included in this value.
  99          */
 100         uint16_t size;
 101
 102         /* size bytes of data follow here */
 103
 104 } LV2_Event;
 105
 106
 107
 108 /** A buffer of LV2 events (header only).
 109  *
 110  * Like events (which this contains) an event buffer is a single chunk of POD:
 111  * the entire buffer (including contents) can be copied with a single memcpy.
 112  * The first contained event begins sizeof(LV2_EventBuffer) bytes after
 113  * the start of this struct.
 114  *
 115  * After this header, the buffer contains an event header (defined by struct
 116  * LV2_Event), followed by that event's contents (padded to 64 bits), followed by
 117  * another header, etc:
 118  *
 119  * |       |       |       |       |       |       |
 120  * | | | | | | | | | | | | | | | | | | | | | | | | |
 121  * |FRAMES |SUBFRMS|TYP|LEN|DATA..DATA..PAD|FRAMES | ...
 122  */
 123 typedef struct {
 124
 125         /** The contents of the event buffer.  This may or may not reside in the
 126          * same block of memory as this header, plugins must not assume either.
 127          * The host guarantees this points to at least capacity bytes of allocated
 128          * memory (though only size bytes of that are valid events).
 129          */
 130         uint8_t* data;
 131
 132         /** The size of this event header in bytes (including everything).
 133          *
 134          * This is to allow for extending this header in the future without
 135          * breaking binary compatibility.  Whenever this header is copied,
 136          * it MUST be done using this field (and NOT the sizeof this struct).
 137          */
 138         uint16_t header_size;
 139
 140         /** The type of the time stamps for events in this buffer.
 141          * As a special exception, '0' always means audio frames and subframes
 142          * (1/UINT32_MAX'th of a frame) in the sample rate passed to instantiate.
 143          * INPUTS: The host must set this field to the numeric ID of some URI
 144          *     defining the meaning of the frames/subframes fields of contained
 145          *     events (obtained by the LV2 URI Map uri_to_id function with the URI
 146          *     of this extension as the 'map' argument, see lv2_uri_map.h).
 147          *     The host must never pass a plugin a buffer which uses a stamp type
 148          *     the plugin does not 'understand'.  The value of this field must
 149          *     never change, except when connect_port is called on the input
 150          *     port, at which time the host MUST have set the stamp_type field to
 151          *     the value that will be used for all subsequent run calls.
 152          * OUTPUTS: The plugin may set this to any value that has been returned
 153          *     from uri_to_id with the URI of this extension for a 'map' argument.
 154          *     When connected to a buffer with connect_port, output ports MUST set
 155          *     this field to the type of time stamp they will be writing.  On any
 156          *     call to connect_port on an event input port, the plugin may change
 157          *     this field on any output port, it is the responsibility of the host
 158          *     to check if any of these values have changed and act accordingly.
 159          */
 160         uint16_t stamp_type;
 161
 162         /** The number of events in this buffer.
 163          * INPUTS: The host must set this field to the number of events
 164          *     contained in the data buffer before calling run().
 165          *     The plugin must not change this field.
 166          * OUTPUTS: The plugin must set this field to the number of events it
 167          *     has written to the buffer before returning from run().
 168          *     Any initial value should be ignored by the plugin.
 169          */
 170         uint32_t event_count;
 171
 172         /** The size of the data buffer in bytes.
 173          * This is set by the host and must not be changed by the plugin.
 174          * The host is allowed to change this between run() calls.
 175          */
 176         uint32_t capacity;
 177
 178         /** The size of the initial portion of the data buffer containing data.
 179          * INPUTS: The host must set this field to the number of bytes used
 180          *     by all events it has written to the buffer (including headers)
 181          *     before calling the plugin's run().
 182          *     The plugin must not change this field.
 183          * OUTPUTS: The plugin must set this field to the number of bytes
 184          *     used by all events it has written to the buffer (including headers)
 185          *     before returning from run().
 186          *     Any initial value should be ignored by the plugin.
 187          */
 188         uint32_t size;
 189
 190 } LV2_Event_Buffer;
 191
 192
 193 /** Opaque pointer to host data. */
 194 typedef void* LV2_Event_Callback_Data;
 195
 196
 197 /** The data field of the LV2_Feature for this extension.
 198  *
 199  * To support this feature the host must pass an LV2_Feature struct to the
 200  * plugin's instantiate method with URI "http://lv2plug.in/ns/ext/event"
 201  * and data pointed to an instance of this struct.
 202  */
 203 typedef struct {
 204
 205         /** Opaque pointer to host data.
 206          *
 207          * The plugin MUST pass this to any call to functions in this struct.
 208          * Otherwise, it must not be interpreted in any way.
 209          */
 210         LV2_Event_Callback_Data callback_data;
 211
 212         /** Take a reference to a non-POD event.
 213          *
 214          * If a plugin receives an event with type 0, it means the event is a
 215          * pointer to some object in memory and not a flat sequence of bytes
 216          * in the buffer.  When receiving a non-POD event, the plugin already
 217          * has an implicit reference to the event.  If the event is stored AND
 218          * passed to an output, lv2_event_ref MUST be called on that event.
 219          * If the event is only stored OR passed through, this is not necessary
 220          * (as the plugin already has 1 implicit reference).
 221          *
 222          * @param event An event received at an input that will not be copied to
 223          *              an output or stored in any way.
 224          * @param context The calling context.  (Like event types) this is a mapped
 225          *                URI, see lv2_context.h. Simple plugin with just a run()
 226          *                method should pass 0 here (the ID of the 'standard' LV2
 227          *                run context).  The host guarantees that this function is
 228          *                realtime safe iff @a context is realtime safe.
 229          *
 230          * PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
 231          */
 232         uint32_t (*lv2_event_ref)(LV2_Event_Callback_Data callback_data,
 233                                   LV2_Event*              event);
 234
 235         /** Drop a reference to a non-POD event.
 236          *
 237          * If a plugin receives an event with type 0, it means the event is a
 238          * pointer to some object in memory and not a flat sequence of bytes
 239          * in the buffer.  If the plugin does not pass the event through to
 240          * an output or store it internally somehow, it MUST call this function
 241          * on the event (more information on using non-POD events below).
 242          *
 243          * @param event An event received at an input that will not be copied to
 244          *              an output or stored in any way.
 245          * @param context The calling context.  (Like event types) this is a mapped
 246          *                URI, see lv2_context.h. Simple plugin with just a run()
 247          *                method should pass 0 here (the ID of the 'standard' LV2
 248          *                run context).  The host guarantees that this function is
 249          *                realtime safe iff @a context is realtime safe.
 250          *
 251          * PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
 252          */
 253         uint32_t (*lv2_event_unref)(LV2_Event_Callback_Data callback_data,
 254                                     LV2_Event*              event);
 255
 256 } LV2_Event_Feature;
 257
 258
 259 #endif // LV2_EVENT_H
 260