diff options
| -rw-r--r-- | ext/event.lv2/event.h | 421 |
1 files changed, 222 insertions, 199 deletions
diff --git a/ext/event.lv2/event.h b/ext/event.lv2/event.h index 7fb189c..9117723 100644 --- a/ext/event.lv2/event.h +++ b/ext/event.lv2/event.h @@ -1,22 +1,22 @@ -/* lv2_event.h - C header file for the LV2 events extension. - * - * Copyright (C) 2006-2007 Lars Luthman <lars.luthman@gmail.com> - * Copyright (C) 2008-2009 David Robillard <http://drobilla.net> - * - * This header is free software; you can redistribute it and/or modify it - * under the terms of the GNU Lesser General Public License as published - * by the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This header is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public - * License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this header; if not, write to the Free Software Foundation, - * Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA - */ +/* + LV2 Event Extension + Copyright (C) 2006-2007 Lars Luthman <lars.luthman@gmail.com> + Copyright (C) 2008-2011 David Robillard <http://drobilla.net> + + This header is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published + by the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This header is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public + License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with this header; if not, write to the Free Software Foundation, + Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA +*/ #ifndef LV2_EVENT_H #define LV2_EVENT_H @@ -26,76 +26,80 @@ #include <stdint.h> -/** @file - * C header for the LV2 Event extension <http://lv2plug.in/ns/ext/event>. - * - * This extension is a generic transport mechanism for time stamped events - * of any type (e.g. MIDI, OSC, ramps, etc). Each port can transport mixed - * events of any type; the type of events and timestamps are defined by a URI - * which is mapped to an integer by the host for performance reasons. - * - * This extension requires the host to support the LV2 URI Map extension. - * Any host which supports this extension MUST guarantee that any call to - * the LV2 URI Map uri_to_id function with the URI of this extension as the - * 'map' argument returns a value within the range of uint16_t. - */ - - -/** The best Pulses Per Quarter Note for tempo-based uint32_t timestmaps. - * Equal to 2^12 * 5 * 7 * 9 * 11 * 13 * 17, which is evenly divisble - * by all integers from 1 through 18 inclusive, and powers of 2 up to 2^12. - */ +/** + @file event.h + C API for the LV2 Event extension <http://lv2plug.in/ns/ext/event>. + + This extension is a generic transport mechanism for time stamped events + of any type (e.g. MIDI, OSC, ramps, etc). Each port can transport mixed + events of any type; the type of events and timestamps are defined by a URI + which is mapped to an integer by the host for performance reasons. + + This extension requires the host to support the LV2 URI Map extension. + Any host which supports this extension MUST guarantee that any call to + the LV2 URI Map uri_to_id function with the URI of this extension as the + 'map' argument returns a value within the range of uint16_t. +*/ + +/** + The best Pulses Per Quarter Note for tempo-based uint32_t timestmaps. + Equal to 2^12 * 5 * 7 * 9 * 11 * 13 * 17, which is evenly divisble + by all integers from 1 through 18 inclusive, and powers of 2 up to 2^12. +*/ static const uint32_t LV2_EVENT_PPQN = 3136573440U; - -/** An LV2 event (header only). - * - * LV2 events are generic time-stamped containers for any type of event. - * The type field defines the format of a given event's contents. - * - * This struct defines the header of an LV2 event. An LV2 event is a single - * chunk of POD (plain old data), usually contained in a flat buffer - * (see LV2_EventBuffer below). Unless a required feature says otherwise, - * hosts may assume a deep copy of an LV2 event can be created safely - * using a simple: - * - * memcpy(ev_copy, ev, sizeof(LV2_Event) + ev->size); (or equivalent) - */ +/** + An LV2 event (header only). + + LV2 events are generic time-stamped containers for any type of event. + The type field defines the format of a given event's contents. + + This struct defines the header of an LV2 event. An LV2 event is a single + chunk of POD (plain old data), usually contained in a flat buffer (see + LV2_EventBuffer below). Unless a required feature says otherwise, hosts may + assume a deep copy of an LV2 event can be created safely using a simple: + + memcpy(ev_copy, ev, sizeof(LV2_Event) + ev->size); (or equivalent) +*/ typedef struct { - /** The frames portion of timestamp. The units used here can optionally be - * set for a port (with the lv2ev:timeUnits property), otherwise this - * is audio frames, corresponding to the sample_count parameter of the - * LV2 run method (e.g. frame 0 is the first frame for that call to run). - */ + /** + The frames portion of timestamp. The units used here can optionally be + set for a port (with the lv2ev:timeUnits property), otherwise this is + audio frames, corresponding to the sample_count parameter of the LV2 run + method (e.g. frame 0 is the first frame for that call to run). + */ uint32_t frames; - /** The sub-frames portion of timestamp. The units used here can - * optionally be set for a port (with the lv2ev:timeUnits property), - * otherwise this is 1/(2^32) of an audio frame. - */ + /** + The sub-frames portion of timestamp. The units used here can optionally + be set for a port (with the lv2ev:timeUnits property), otherwise this is + 1/(2^32) of an audio frame. + */ uint32_t subframes; - /** The type of this event, as a number which represents some URI - * defining an event type. This value MUST be some value previously - * returned from a call to the uri_to_id function defined in the LV2 - * URI map extension (see lv2_uri_map.h). - * There are special rules which must be followed depending on the type - * of an event. If the plugin recognizes an event type, the definition - * of that event type will describe how to interpret the event, and - * any required behaviour. Otherwise, if the type is 0, this event is a - * non-POD event and lv2_event_unref MUST be called if the event is - * 'dropped' (see above). Even if the plugin does not understand an event, - * it may pass the event through to an output by simply copying (and NOT - * calling lv2_event_unref). These rules are designed to allow for generic - * event handling plugins and large non-POD events, but with minimal hassle - * on simple plugins that "don't care" about these more advanced features. - */ + /** + The type of this event, as a number which represents some URI + defining an event type. This value MUST be some value previously + returned from a call to the uri_to_id function defined in the LV2 + URI map extension (see lv2_uri_map.h). + There are special rules which must be followed depending on the type + of an event. If the plugin recognizes an event type, the definition + of that event type will describe how to interpret the event, and + any required behaviour. Otherwise, if the type is 0, this event is a + non-POD event and lv2_event_unref MUST be called if the event is + 'dropped' (see above). Even if the plugin does not understand an event, + it may pass the event through to an output by simply copying (and NOT + calling lv2_event_unref). These rules are designed to allow for generic + event handling plugins and large non-POD events, but with minimal hassle + on simple plugins that "don't care" about these more advanced features. + */ uint16_t type; - /** The size of the data portion of this event in bytes, which immediately - * follows. The header size (12 bytes) is not included in this value. - */ + /** + The size of the data portion of this event in bytes, which immediately + follows. The header size (12 bytes) is not included in this value. + */ uint16_t size; /* size bytes of data follow here */ @@ -103,152 +107,172 @@ typedef struct { } LV2_Event; - -/** A buffer of LV2 events (header only). - * - * Like events (which this contains) an event buffer is a single chunk of POD: - * the entire buffer (including contents) can be copied with a single memcpy. - * The first contained event begins sizeof(LV2_EventBuffer) bytes after - * the start of this struct. - * - * After this header, the buffer contains an event header (defined by struct - * LV2_Event), followed by that event's contents (padded to 64 bits), followed by - * another header, etc: - * - * | | | | | | | - * | | | | | | | | | | | | | | | | | | | | | | | | | - * |FRAMES |SUBFRMS|TYP|LEN|DATA..DATA..PAD|FRAMES | ... - */ +/** + A buffer of LV2 events (header only). + + Like events (which this contains) an event buffer is a single chunk of POD: + the entire buffer (including contents) can be copied with a single memcpy. + The first contained event begins sizeof(LV2_EventBuffer) bytes after the + start of this struct. + + After this header, the buffer contains an event header (defined by struct + LV2_Event), followed by that event's contents (padded to 64 bits), followed + by another header, etc: + + | | | | | | | + | | | | | | | | | | | | | | | | | | | | | | | | | + |FRAMES |SUBFRMS|TYP|LEN|DATA..DATA..PAD|FRAMES | ... +*/ typedef struct { - /** The contents of the event buffer. This may or may not reside in the - * same block of memory as this header, plugins must not assume either. - * The host guarantees this points to at least capacity bytes of allocated - * memory (though only size bytes of that are valid events). - */ + /** + The contents of the event buffer. This may or may not reside in the + same block of memory as this header, plugins must not assume either. + The host guarantees this points to at least capacity bytes of allocated + memory (though only size bytes of that are valid events). + */ uint8_t* data; - /** The size of this event header in bytes (including everything). - * - * This is to allow for extending this header in the future without - * breaking binary compatibility. Whenever this header is copied, - * it MUST be done using this field (and NOT the sizeof this struct). - */ + /** + The size of this event header in bytes (including everything). + + This is to allow for extending this header in the future without + breaking binary compatibility. Whenever this header is copied, + it MUST be done using this field (and NOT the sizeof this struct). + */ uint16_t header_size; - /** The type of the time stamps for events in this buffer. - * As a special exception, '0' always means audio frames and subframes - * (1/UINT32_MAX'th of a frame) in the sample rate passed to instantiate. - * INPUTS: The host must set this field to the numeric ID of some URI - * defining the meaning of the frames/subframes fields of contained - * events (obtained by the LV2 URI Map uri_to_id function with the URI - * of this extension as the 'map' argument, see lv2_uri_map.h). - * The host must never pass a plugin a buffer which uses a stamp type - * the plugin does not 'understand'. The value of this field must - * never change, except when connect_port is called on the input - * port, at which time the host MUST have set the stamp_type field to - * the value that will be used for all subsequent run calls. - * OUTPUTS: The plugin may set this to any value that has been returned - * from uri_to_id with the URI of this extension for a 'map' argument. - * When connected to a buffer with connect_port, output ports MUST set - * this field to the type of time stamp they will be writing. On any - * call to connect_port on an event input port, the plugin may change - * this field on any output port, it is the responsibility of the host - * to check if any of these values have changed and act accordingly. - */ + /** + The type of the time stamps for events in this buffer. + As a special exception, '0' always means audio frames and subframes + (1/UINT32_MAX'th of a frame) in the sample rate passed to instantiate. + + INPUTS: The host must set this field to the numeric ID of some URI + defining the meaning of the frames/subframes fields of contained events + (obtained by the LV2 URI Map uri_to_id function with the URI of this + extension as the 'map' argument, see lv2_uri_map.h). The host must + never pass a plugin a buffer which uses a stamp type the plugin does not + 'understand'. The value of this field must never change, except when + connect_port is called on the input port, at which time the host MUST + have set the stamp_type field to the value that will be used for all + subsequent run calls. + + OUTPUTS: The plugin may set this to any value that has been returned + from uri_to_id with the URI of this extension for a 'map' argument. + When connected to a buffer with connect_port, output ports MUST set this + field to the type of time stamp they will be writing. On any call to + connect_port on an event input port, the plugin may change this field on + any output port, it is the responsibility of the host to check if any of + these values have changed and act accordingly. + */ uint16_t stamp_type; - /** The number of events in this buffer. - * INPUTS: The host must set this field to the number of events - * contained in the data buffer before calling run(). - * The plugin must not change this field. - * OUTPUTS: The plugin must set this field to the number of events it - * has written to the buffer before returning from run(). - * Any initial value should be ignored by the plugin. - */ + /** + The number of events in this buffer. + + INPUTS: The host must set this field to the number of events contained + in the data buffer before calling run(). The plugin must not change + this field. + + OUTPUTS: The plugin must set this field to the number of events it has + written to the buffer before returning from run(). Any initial value + should be ignored by the plugin. + */ uint32_t event_count; - /** The size of the data buffer in bytes. - * This is set by the host and must not be changed by the plugin. - * The host is allowed to change this between run() calls. - */ + /** + The size of the data buffer in bytes. + This is set by the host and must not be changed by the plugin. + The host is allowed to change this between run() calls. + */ uint32_t capacity; - /** The size of the initial portion of the data buffer containing data. - * INPUTS: The host must set this field to the number of bytes used - * by all events it has written to the buffer (including headers) - * before calling the plugin's run(). - * The plugin must not change this field. - * OUTPUTS: The plugin must set this field to the number of bytes - * used by all events it has written to the buffer (including headers) - * before returning from run(). - * Any initial value should be ignored by the plugin. - */ + /** + The size of the initial portion of the data buffer containing data. + + INPUTS: The host must set this field to the number of bytes used + by all events it has written to the buffer (including headers) + before calling the plugin's run(). + The plugin must not change this field. + + OUTPUTS: The plugin must set this field to the number of bytes + used by all events it has written to the buffer (including headers) + before returning from run(). + Any initial value should be ignored by the plugin. + */ uint32_t size; } LV2_Event_Buffer; -/** Opaque pointer to host data. */ +/** + Opaque pointer to host data. +*/ typedef void* LV2_Event_Callback_Data; -/** The data field of the LV2_Feature for this extension. - * - * To support this feature the host must pass an LV2_Feature struct to the - * plugin's instantiate method with URI "http://lv2plug.in/ns/ext/event" - * and data pointed to an instance of this struct. - */ +/** + The data field of the LV2_Feature for this extension. + + To support this feature the host must pass an LV2_Feature struct to the + plugin's instantiate method with URI "http://lv2plug.in/ns/ext/event" + and data pointed to an instance of this struct. +*/ typedef struct { - /** Opaque pointer to host data. - * - * The plugin MUST pass this to any call to functions in this struct. - * Otherwise, it must not be interpreted in any way. - */ + /** + Opaque pointer to host data. + + The plugin MUST pass this to any call to functions in this struct. + Otherwise, it must not be interpreted in any way. + */ LV2_Event_Callback_Data callback_data; - /** Take a reference to a non-POD event. - * - * If a plugin receives an event with type 0, it means the event is a - * pointer to some object in memory and not a flat sequence of bytes - * in the buffer. When receiving a non-POD event, the plugin already - * has an implicit reference to the event. If the event is stored AND - * passed to an output, lv2_event_ref MUST be called on that event. - * If the event is only stored OR passed through, this is not necessary - * (as the plugin already has 1 implicit reference). - * - * @param event An event received at an input that will not be copied to - * an output or stored in any way. - * @param context The calling context. (Like event types) this is a mapped - * URI, see lv2_context.h. Simple plugin with just a run() - * method should pass 0 here (the ID of the 'standard' LV2 - * run context). The host guarantees that this function is - * realtime safe iff @a context is realtime safe. - * - * PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS. - */ + /** + Take a reference to a non-POD event. + + If a plugin receives an event with type 0, it means the event is a + pointer to some object in memory and not a flat sequence of bytes + in the buffer. When receiving a non-POD event, the plugin already + has an implicit reference to the event. If the event is stored AND + passed to an output, lv2_event_ref MUST be called on that event. + If the event is only stored OR passed through, this is not necessary + (as the plugin already has 1 implicit reference). + + @param event An event received at an input that will not be copied to + an output or stored in any way. + + @param context The calling context. Like event types, this is a mapped + URI, see lv2_context.h. Simple plugin with just a run() method should + pass 0 here (the ID of the 'standard' LV2 run context). The host + guarantees that this function is realtime safe iff @a context is + realtime safe. + + PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS. + */ uint32_t (*lv2_event_ref)(LV2_Event_Callback_Data callback_data, LV2_Event* event); - /** Drop a reference to a non-POD event. - * - * If a plugin receives an event with type 0, it means the event is a - * pointer to some object in memory and not a flat sequence of bytes - * in the buffer. If the plugin does not pass the event through to - * an output or store it internally somehow, it MUST call this function - * on the event (more information on using non-POD events below). - * - * @param event An event received at an input that will not be copied to - * an output or stored in any way. - * @param context The calling context. (Like event types) this is a mapped - * URI, see lv2_context.h. Simple plugin with just a run() - * method should pass 0 here (the ID of the 'standard' LV2 - * run context). The host guarantees that this function is - * realtime safe iff @a context is realtime safe. - * - * PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS. - */ + /** + Drop a reference to a non-POD event. + + If a plugin receives an event with type 0, it means the event is a + pointer to some object in memory and not a flat sequence of bytes + in the buffer. If the plugin does not pass the event through to + an output or store it internally somehow, it MUST call this function + on the event (more information on using non-POD events below). + + @param event An event received at an input that will not be copied to an + output or stored in any way. + + @param context The calling context. Like event types, this is a mapped + URI, see lv2_context.h. Simple plugin with just a run() method should + pass 0 here (the ID of the 'standard' LV2 run context). The host + guarantees that this function is realtime safe iff @a context is + realtime safe. + + PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS. + */ uint32_t (*lv2_event_unref)(LV2_Event_Callback_Data callback_data, LV2_Event* event); @@ -256,4 +280,3 @@ typedef struct { #endif /* LV2_EVENT_H */ - |