hostplugins/lv2/lv2_event.h

/* lv2_event.h - C header file for the LV2 events extension.
 * 
 * Copyright (C) 2006-2007 Lars Luthman <lars.luthman@gmail.com>
 * Copyright (C) 2008 Dave Robillard <dave@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
 
#define LV2_EVENT_URI "http://lv2plug.in/ns/ext/event"
#define LV2_EVENT_AUDIO_STAMP 0

#include <stdint.h>

/** @file
 * This header defines the code portion of the LV2 events extension with
 * URI <http://lv2plug.in/ns/ext/event>.
 *
 * Below, the URI prefix 'lv2ev' is assumed to expand to 
 * <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.
 * This requirement is implicit - a plugin does not have to list the URI Map
 * feature as required or optional in its RDF data for the host to provide
 * the URI Map LV2_Feature in the instantiation function.
 *
 * 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, as specified
 * in this extension, is a single chunk of POD (plain old data), usually 
 * contained in a flat buffer (see LV2_EventBuffer below), that can be safely
 * copied using a simple:
 *
 * memcpy(ev_copy, ev, sizeof(LV2_Event) + ev->size);  (or equivalent)
 *
 * However, events with event type 0 need to be handled specially (see below).
 */
typedef struct {

        /** The frames portion of timestamp.  The units used here can optionally
         * be set for a port (with lv2ev:supportsTimeStamp and related 
         * properties), 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 lv2ev:supportsTimeStamp and 
         * related properties), 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 below).  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.
         *
         * Plugins should not interpret type 0 events in any way unless
         * specified by another extension.
         */
        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.
         */
        uint16_t size;

        /* size bytes of data follow here */

} LV2_Event;


/** A buffer of LV2 events (header only).
 *
 * This struct is used as the port buffer for LV2 plugin ports that have the
 * port class lv2ev:EventPort.
 * 
 * The data member points to a buffer that 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).
         */
        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).
         */
        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.
         */
        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.
         */
        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.
         */
        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.
         */
        uint32_t size;

} LV2_Event_Buffer;


/** Opaque pointer to host data. */
typedef void* LV2_Event_Callback_Data;


/** The data field of the LV2_Feature for this extension.
 *
 * To support this extension 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 plugin does not have
 * to list that URI as a required or optional feature in its RDF data - the 
 * host MUST pass this LV2_Feature if the plugin has an port of class 
 * lv2ev:EventPortthat the host connects to.
 */
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.
         */
        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, or passed to two outputs, 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).
         *
         * The host guarantees that this function is realtime safe if the 
         * plugin is.
         *
         * @param event An event received at an input that will be copied to
         *              more than one output or duplicated in some other way.
         * 
         * 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).
         *
         * The host guarantees that this function is realtime safe if the 
         * plugin is.
         *
         * @param event An event received at an input that will not be copied to
         *              an output or stored in any way.
         *
         * 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);

} LV2_Event_Feature;


#endif // 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
31	* URI <http://lv2plug.in/ns/ext/event>.
32	*
33	* Below, the URI prefix 'lv2ev' is assumed to expand to
34	* <http://lv2plug.in/ns/ext/event#>.
35	*
36	* This extension is a generic transport mechanism for time stamped events
37	* of any type (e.g. MIDI, OSC, ramps, etc). Each port can transport mixed
38	* events of any type; the type of events and timestamps are defined by a URI
39	* which is mapped to an integer by the host for performance reasons.
40	*
41	* This extension requires the host to support the LV2 URI Map extension.
42	* This requirement is implicit - a plugin does not have to list the URI Map
43	* feature as required or optional in its RDF data for the host to provide
44	* the URI Map LV2_Feature in the instantiation function.
45	*
46	* Any host which supports this extension MUST guarantee that any call to
47	* the LV2 URI Map uri_to_id function with the URI of this extension as the
48	* 'map' argument returns a value within the range of uint16_t.
49	*/
50
51
52	/** The best Pulses Per Quarter Note for tempo-based uint32_t timestmaps.
53	* Equal to 2^12 * 5 * 7 * 9 * 11 * 13 * 17, which is evenly divisble
54	* by all integers from 1 through 18 inclusive, and powers of 2 up to 2^12.
55	*/
56	static const uint32_t LV2_EVENT_PPQN = 3136573440U;
57
58
59	/** An LV2 event (header only).
60	*
61	* LV2 events are generic time-stamped containers for any type of event.
62	* The type field defines the format of a given event's contents.
63	*
64	* This struct defines the header of an LV2 event. An LV2 event, as specified
65	* in this extension, is a single chunk of POD (plain old data), usually
66	* contained in a flat buffer (see LV2_EventBuffer below), that can be safely
67	* copied using a simple:
68	*
69	* memcpy(ev_copy, ev, sizeof(LV2_Event) + ev->size); (or equivalent)
70	*
71	* However, events with event type 0 need to be handled specially (see below).
72	*/
73	typedef struct {
74
75	/** The frames portion of timestamp. The units used here can optionally
76	* be set for a port (with lv2ev:supportsTimeStamp and related
77	* properties), otherwise this is audio frames, corresponding to the
78	* sample_count parameter of the LV2 run method (e.g. frame 0 is the
79	* first frame for that call to run).
80	*/
81	uint32_t frames;
82
83	/** The sub-frames portion of timestamp. The units used here can
84	* optionally be set for a port (with lv2ev:supportsTimeStamp and
85	* related properties), otherwise this is 1/(2^32) of an audio frame.
86	*/
87	uint32_t subframes;
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	*
94	* There are special rules which must be followed depending on the type
95	* of an event. If the plugin recognizes an event type, the definition
96	* of that event type will describe how to interpret the event, and
97	* any required behaviour. Otherwise, if the type is 0, this event is a
98	* non-POD event and lv2_event_unref MUST be called if the event is
99	* 'dropped' (see below). Even if the plugin does not understand an
100	* event, it may pass the event through to an output by simply copying
101	* (and NOT calling lv2_event_unref). These rules are designed to
102	* allow for generic event handling plugins and large non-POD events,
103	* but with minimal hassle on simple plugins that "don't care" about
104	* these more advanced features.
105	*
106	* Plugins should not interpret type 0 events in any way unless
107	* specified by another extension.
108	*/
109	uint16_t type;
110
111	/** The size of the data portion of this event in bytes, which
112	* immediately follows. The header size (12 bytes) is not included in
113	* this value.
114	*/
115	uint16_t size;
116
117	/* size bytes of data follow here */
118
119	} LV2_Event;
120
121
122
123	/** A buffer of LV2 events (header only).
124	*
125	* This struct is used as the port buffer for LV2 plugin ports that have the
126	* port class lv2ev:EventPort.
127	*
128	* The data member points to a buffer that contains an event header (defined
129	* by struct* LV2_Event), followed by that event's contents (padded to 64 bits),
130	* followed by another header, etc:
131	*
132	* \| \| \| \| \| \| \|
133	* \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \|
134	* \|FRAMES \|SUBFRMS\|TYP\|LEN\|DATA..DATA..PAD\|FRAMES \| ...
135	*/
136	typedef struct {
137
138	/** The contents of the event buffer. This may or may not reside in the
139	* same block of memory as this header, plugins must not assume either.
140	* The host guarantees this points to at least capacity bytes of
141	* allocated memory (though only size bytes of that are valid events).
142	*/
143	uint8_t* data;
144
145	/** The size of this event header in bytes (including everything).
146	*
147	* This is to allow for extending this header in the future without
148	* breaking binary compatibility. Whenever this header is copied,
149	* it MUST be done using this field (and NOT the sizeof this struct).
150	*/
151	uint16_t header_size;
152
153	/** The type of the time stamps for events in this buffer.
154	* As a special exception, '0' always means audio frames and subframes
155	* (1/UINT32_MAX'th of a frame) in the sample rate passed to instantiate.
156	* INPUTS: The host must set this field to the numeric ID of some URI
157	* defining the meaning of the frames/subframes fields of contained
158	* events (obtained by the LV2 URI Map uri_to_id function with the URI
159	* of this extension as the 'map' argument, see lv2_uri_map.h).
160	* The host must never pass a plugin a buffer which uses a stamp type
161	* the plugin does not 'understand'. The value of this field must
162	* never change, except when connect_port is called on the input
163	* port, at which time the host MUST have set the stamp_type field to
164	* the value that will be used for all subsequent run calls.
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
168	* this field to the type of time stamp they will be writing. On any
169	* call to connect_port on an event input port, the plugin may change
170	* this field on any output port, it is the responsibility of the host
171	* to check if any of these values have changed and act accordingly.
172	*/
173	uint16_t stamp_type;
174
175	/** The number of events in this buffer.
176	* INPUTS: The host must set this field to the number of events
177	* contained in the data buffer before calling run().
178	* The plugin must not change this field.
179	* OUTPUTS: The plugin must set this field to the number of events it
180	* has written to the buffer before returning from run().
181	* Any initial value should be ignored by the plugin.
182	*/
183	uint32_t event_count;
184
185	/** The size of the data buffer in bytes.
186	* This is set by the host and must not be changed by the plugin.
187	* The host is allowed to change this between run() calls.
188	*/
189	uint32_t capacity;
190
191	/** The size of the initial portion of the data buffer containing data.
192	* INPUTS: The host must set this field to the number of bytes used
193	* by all events it has written to the buffer (including headers)
194	* before calling the plugin's run().
195	* The plugin must not change this field.
196	* OUTPUTS: The plugin must set this field to the number of bytes
197	* used by all events it has written to the buffer (including headers)
198	* before returning from run().
199	* Any initial value should be ignored by the plugin.
200	*/
201	uint32_t size;
202
203	} LV2_Event_Buffer;
204
205
206	/** Opaque pointer to host data. */
207	typedef void* LV2_Event_Callback_Data;
208
209
210	/** The data field of the LV2_Feature for this extension.
211	*
212	* To support this extension the host must pass an LV2_Feature struct to the
213	* plugin's instantiate method with URI "http://lv2plug.in/ns/ext/event"
214	* and data pointed to an instance of this struct. The plugin does not have
215	* to list that URI as a required or optional feature in its RDF data - the
216	* host MUST pass this LV2_Feature if the plugin has an port of class
217	* lv2ev:EventPortthat the host connects to.
218	*/
219	typedef struct {
220
221	/** Opaque pointer to host data.
222	*
223	* The plugin MUST pass this to any call to functions in this struct.
224	* Otherwise, it must not be interpreted in any way.
225	*/
226	LV2_Event_Callback_Data callback_data;
227
228	/** Take a reference to a non-POD event.
229	*
230	* If a plugin receives an event with type 0, it means the event is a
231	* pointer to some object in memory and not a flat sequence of bytes
232	* in the buffer. When receiving a non-POD event, the plugin already
233	* has an implicit reference to the event. If the event is stored AND
234	* passed to an output, or passed to two outputs, lv2_event_ref MUST
235	* be called on that event.
236	* If the event is only stored OR passed through, this is not necessary
237	* (as the plugin already has 1 implicit reference).
238	*
239	* The host guarantees that this function is realtime safe if the
240	* plugin is.
241	*
242	* @param event An event received at an input that will be copied to
243	* more than one output or duplicated in some other way.
244	*
245	* PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
246	*/
247	uint32_t (*lv2_event_ref)(LV2_Event_Callback_Data callback_data,
248	LV2_Event* event);
249
250	/** Drop a reference to a non-POD event.
251	*
252	* If a plugin receives an event with type 0, it means the event is a
253	* pointer to some object in memory and not a flat sequence of bytes
254	* in the buffer. If the plugin does not pass the event through to
255	* an output or store it internally somehow, it MUST call this function
256	* on the event (more information on using non-POD events below).
257	*
258	* The host guarantees that this function is realtime safe if the
259	* plugin is.
260	*
261	* @param event An event received at an input that will not be copied to
262	* an output or stored in any way.
263	*
264	* PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
265	*/
266	uint32_t (*lv2_event_unref)(LV2_Event_Callback_Data callback_data,
267	LV2_Event* event);
268
269	} LV2_Event_Feature;
270
271
272	#endif // LV2_EVENT_H
273