source/includes/lv2/event.h

   1 /*
   2   Copyright 2008-2016 David Robillard <http://drobilla.net>
   3   Copyright 2006-2007 Lars Luthman <lars.luthman@gmail.com>
   4
   5   Permission to use, copy, modify, and/or distribute this software for any
   6   purpose with or without fee is hereby granted, provided that the above
   7   copyright notice and this permission notice appear in all copies.
   8
   9   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 */
  17
  18 /**
  19    @defgroup event Event
  20
  21    Generic time-stamped events, see <http://lv2plug.in/ns/ext/event> for
  22    details.
  23
  24    @{
  25 */
  26
  27 #ifndef LV2_EVENT_H
  28 #define LV2_EVENT_H
  29
  30 #define LV2_EVENT_URI    "http://lv2plug.in/ns/ext/event"  ///< http://lv2plug.in/ns/ext/event
  31 #define LV2_EVENT_PREFIX LV2_EVENT_URI "#"                 ///< http://lv2plug.in/ns/ext/event#
  32
  33 #define LV2_EVENT__Event              LV2_EVENT_PREFIX "Event"               ///< http://lv2plug.in/ns/ext/event#Event
  34 #define LV2_EVENT__EventPort          LV2_EVENT_PREFIX "EventPort"           ///< http://lv2plug.in/ns/ext/event#EventPort
  35 #define LV2_EVENT__FrameStamp         LV2_EVENT_PREFIX "FrameStamp"          ///< http://lv2plug.in/ns/ext/event#FrameStamp
  36 #define LV2_EVENT__TimeStamp          LV2_EVENT_PREFIX "TimeStamp"           ///< http://lv2plug.in/ns/ext/event#TimeStamp
  37 #define LV2_EVENT__generatesTimeStamp LV2_EVENT_PREFIX "generatesTimeStamp"  ///< http://lv2plug.in/ns/ext/event#generatesTimeStamp
  38 #define LV2_EVENT__generic            LV2_EVENT_PREFIX "generic"             ///< http://lv2plug.in/ns/ext/event#generic
  39 #define LV2_EVENT__inheritsEvent      LV2_EVENT_PREFIX "inheritsEvent"       ///< http://lv2plug.in/ns/ext/event#inheritsEvent
  40 #define LV2_EVENT__inheritsTimeStamp  LV2_EVENT_PREFIX "inheritsTimeStamp"   ///< http://lv2plug.in/ns/ext/event#inheritsTimeStamp
  41 #define LV2_EVENT__supportsEvent      LV2_EVENT_PREFIX "supportsEvent"       ///< http://lv2plug.in/ns/ext/event#supportsEvent
  42 #define LV2_EVENT__supportsTimeStamp  LV2_EVENT_PREFIX "supportsTimeStamp"   ///< http://lv2plug.in/ns/ext/event#supportsTimeStamp
  43
  44 #define LV2_EVENT_AUDIO_STAMP 0  ///< Special timestamp type for audio frames
  45
  46 #include <stdint.h>
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /**
  53    The best Pulses Per Quarter Note for tempo-based uint32_t timestamps.
  54    Equal to 2^12 * 5 * 7 * 9 * 11 * 13 * 17, which is evenly divisble
  55    by all integers from 1 through 18 inclusive, and powers of 2 up to 2^12.
  56 */
  57 static const uint32_t LV2_EVENT_PPQN = 3136573440U;
  58
  59 /**
  60    An LV2 event (header only).
  61
  62    LV2 events are generic time-stamped containers for any type of event.
  63    The type field defines the format of a given event's contents.
  64
  65    This struct defines the header of an LV2 event. An LV2 event is a single
  66    chunk of POD (plain old data), usually contained in a flat buffer (see
  67    LV2_EventBuffer below). Unless a required feature says otherwise, hosts may
  68    assume a deep copy of an LV2 event can be created safely using a simple:
  69
  70    memcpy(ev_copy, ev, sizeof(LV2_Event) + ev->size);  (or equivalent)
  71 */
  72 typedef struct {
  73         /**
  74            The frames portion of timestamp. The units used here can optionally be
  75            set for a port (with the lv2ev:timeUnits property), otherwise this is
  76            audio frames, corresponding to the sample_count parameter of the LV2 run
  77            method (e.g. frame 0 is the first frame for that call to run).
  78         */
  79         uint32_t frames;
  80
  81         /**
  82            The sub-frames portion of timestamp. The units used here can optionally
  83            be set for a port (with the lv2ev:timeUnits property), otherwise this is
  84            1/(2^32) of an audio frame.
  85         */
  86         uint32_t subframes;
  87
  88         /**
  89            The type of this event, as a number which represents some URI
  90            defining an event type. This value MUST be some value previously
  91            returned from a call to the uri_to_id function defined in the LV2
  92            URI map extension (see lv2_uri_map.h).
  93            There are special rules which must be followed depending on the type
  94            of an event. If the plugin recognizes an event type, the definition
  95            of that event type will describe how to interpret the event, and
  96            any required behaviour. Otherwise, if the type is 0, this event is a
  97            non-POD event and lv2_event_unref MUST be called if the event is
  98            'dropped' (see above). Even if the plugin does not understand an event,
  99            it may pass the event through to an output by simply copying (and NOT
 100            calling lv2_event_unref). These rules are designed to allow for generic
 101            event handling plugins and large non-POD events, but with minimal hassle
 102            on simple plugins that "don't care" about these more advanced features.
 103         */
 104         uint16_t type;
 105
 106         /**
 107            The size of the data portion of this event in bytes, which immediately
 108            follows. The header size (12 bytes) is not included in this value.
 109         */
 110         uint16_t size;
 111
 112         /* size bytes of data follow here */
 113 } LV2_Event;
 114
 115
 116 /**
 117    A buffer of LV2 events (header only).
 118
 119    Like events (which this contains) an event buffer is a single chunk of POD:
 120    the entire buffer (including contents) can be copied with a single memcpy.
 121    The first contained event begins sizeof(LV2_EventBuffer) bytes after the
 122    start of this struct.
 123
 124    After this header, the buffer contains an event header (defined by struct
 125    LV2_Event), followed by that event's contents (padded to 64 bits), followed
 126    by another header, etc:
 127
 128    |       |       |       |       |       |       |
 129    | | | | | | | | | | | | | | | | | | | | | | | | |
 130    |FRAMES |SUBFRMS|TYP|LEN|DATA..DATA..PAD|FRAMES | ...
 131 */
 132 typedef struct {
 133         /**
 134            The contents of the event buffer. This may or may not reside in the
 135            same block of memory as this header, plugins must not assume either.
 136            The host guarantees this points to at least capacity bytes of allocated
 137            memory (though only size bytes of that are valid events).
 138         */
 139         uint8_t* data;
 140
 141         /**
 142            The size of this event header in bytes (including everything).
 143
 144            This is to allow for extending this header in the future without
 145            breaking binary compatibility. Whenever this header is copied,
 146            it MUST be done using this field (and NOT the sizeof this struct).
 147         */
 148         uint16_t header_size;
 149
 150         /**
 151            The type of the time stamps for events in this buffer.
 152            As a special exception, '0' always means audio frames and subframes
 153            (1/UINT32_MAX'th of a frame) in the sample rate passed to instantiate.
 154
 155            INPUTS: The host must set this field to the numeric ID of some URI
 156            defining the meaning of the frames/subframes fields of contained events
 157            (obtained by the LV2 URI Map uri_to_id function with the URI of this
 158            extension as the 'map' argument, see lv2_uri_map.h).  The host must
 159            never pass a plugin a buffer which uses a stamp type the plugin does not
 160            'understand'. The value of this field must never change, except when
 161            connect_port is called on the input port, at which time the host MUST
 162            have set the stamp_type field to the value that will be used for all
 163            subsequent run calls.
 164
 165            OUTPUTS: The plugin may set this to any value that has been returned
 166            from uri_to_id with the URI of this extension for a 'map' argument.
 167            When connected to a buffer with connect_port, output ports MUST set this
 168            field to the type of time stamp they will be writing. On any call to
 169            connect_port on an event input port, the plugin may change this field on
 170            any output port, it is the responsibility of the host to check if any of
 171            these values have changed and act accordingly.
 172         */
 173         uint16_t stamp_type;
 174
 175         /**
 176            The number of events in this buffer.
 177
 178            INPUTS: The host must set this field to the number of events contained
 179            in the data buffer before calling run(). The plugin must not change
 180            this field.
 181
 182            OUTPUTS: The plugin must set this field to the number of events it has
 183            written to the buffer before returning from run(). Any initial value
 184            should be ignored by the plugin.
 185         */
 186         uint32_t event_count;
 187
 188         /**
 189            The size of the data buffer in bytes.
 190            This is set by the host and must not be changed by the plugin.
 191            The host is allowed to change this between run() calls.
 192         */
 193         uint32_t capacity;
 194
 195         /**
 196            The size of the initial portion of the data buffer containing data.
 197
 198            INPUTS: The host must set this field to the number of bytes used
 199            by all events it has written to the buffer (including headers)
 200            before calling the plugin's run().
 201            The plugin must not change this field.
 202
 203            OUTPUTS: The plugin must set this field to the number of bytes
 204            used by all events it has written to the buffer (including headers)
 205            before returning from run().
 206            Any initial value should be ignored by the plugin.
 207         */
 208         uint32_t size;
 209 } LV2_Event_Buffer;
 210
 211
 212 /**
 213    Opaque pointer to host data.
 214 */
 215 typedef void* LV2_Event_Callback_Data;
 216
 217
 218 /**
 219    Non-POD events feature.
 220
 221    To support this feature the host must pass an LV2_Feature struct to the
 222    plugin's instantiate method with URI "http://lv2plug.in/ns/ext/event"
 223    and data pointed to an instance of this struct.  Note this feature
 224    is not mandatory to support the event extension.
 225 */
 226 typedef struct {
 227         /**
 228            Opaque pointer to host data.
 229
 230            The plugin MUST pass this to any call to functions in this struct.
 231            Otherwise, it must not be interpreted in any way.
 232         */
 233         LV2_Event_Callback_Data callback_data;
 234
 235         /**
 236            Take a reference to a non-POD event.
 237
 238            If a plugin receives an event with type 0, it means the event is a
 239            pointer to some object in memory and not a flat sequence of bytes
 240            in the buffer. When receiving a non-POD event, the plugin already
 241            has an implicit reference to the event. If the event is stored AND
 242            passed to an output, lv2_event_ref MUST be called on that event.
 243            If the event is only stored OR passed through, this is not necessary
 244            (as the plugin already has 1 implicit reference).
 245
 246            @param event An event received at an input that will not be copied to
 247            an output or stored in any way.
 248
 249            @param context The calling context. Like event types, this is a mapped
 250            URI, see lv2_context.h. Simple plugin with just a run() method should
 251            pass 0 here (the ID of the 'standard' LV2 run context). The host
 252            guarantees that this function is realtime safe iff the context is
 253            realtime safe.
 254
 255            PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
 256         */
 257         uint32_t (*lv2_event_ref)(LV2_Event_Callback_Data callback_data,
 258                                   LV2_Event*              event);
 259
 260         /**
 261            Drop a reference to a non-POD event.
 262
 263            If a plugin receives an event with type 0, it means the event is a
 264            pointer to some object in memory and not a flat sequence of bytes
 265            in the buffer. If the plugin does not pass the event through to
 266            an output or store it internally somehow, it MUST call this function
 267            on the event (more information on using non-POD events below).
 268
 269            @param event An event received at an input that will not be copied to an
 270            output or stored in any way.
 271
 272            @param context The calling context. Like event types, this is a mapped
 273            URI, see lv2_context.h. Simple plugin with just a run() method should
 274            pass 0 here (the ID of the 'standard' LV2 run context). The host
 275            guarantees that this function is realtime safe iff the context is
 276            realtime safe.
 277
 278            PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
 279         */
 280         uint32_t (*lv2_event_unref)(LV2_Event_Callback_Data callback_data,
 281                                     LV2_Event*              event);
 282 } LV2_Event_Feature;
 283
 284 #ifdef __cplusplus
 285 }  /* extern "C" */
 286 #endif
 287
 288 #endif /* LV2_EVENT_H */
 289
 290 /**
 291    @}
 292 */