DPF

DISTRHO Plugin Framework
Log | Files | Refs | Submodules | README | LICENSE

event.h (11949B)


      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 */