diff options
Diffstat (limited to 'lv2/event')
| -rw-r--r-- | lv2/event/event-helpers.h | 189 | ||||
| -rw-r--r-- | lv2/event/event.h | 349 |
2 files changed, 261 insertions, 277 deletions
diff --git a/lv2/event/event-helpers.h b/lv2/event/event-helpers.h index 6b39235..7e3f19c 100644 --- a/lv2/event/event-helpers.h +++ b/lv2/event/event-helpers.h @@ -47,96 +47,87 @@ LV2_DISABLE_DEPRECATION_WARNINGS * Note that these functions are all static inline which basically means: * do not take the address of these functions. */ - /** Pad a size to 64 bits (for event sizes) */ static inline uint16_t lv2_event_pad_size(uint16_t size) { - return (uint16_t)(size + 7U) & (uint16_t)(~7U); + return (uint16_t)(size + 7U) & (uint16_t)(~7U); } - /** Initialize (empty, reset..) an existing event buffer. * The contents of buf are ignored entirely and overwritten, except capacity * which is unmodified. */ static inline void -lv2_event_buffer_reset(LV2_Event_Buffer* buf, - uint16_t stamp_type, - uint8_t* data) +lv2_event_buffer_reset(LV2_Event_Buffer* buf, + uint16_t stamp_type, + uint8_t* data) { - buf->data = data; - buf->header_size = sizeof(LV2_Event_Buffer); - buf->stamp_type = stamp_type; - buf->event_count = 0; - buf->size = 0; + buf->data = data; + buf->header_size = sizeof(LV2_Event_Buffer); + buf->stamp_type = stamp_type; + buf->event_count = 0; + buf->size = 0; } - /** Allocate a new, empty event buffer. */ static inline LV2_Event_Buffer* lv2_event_buffer_new(uint32_t capacity, uint16_t stamp_type) { - const size_t size = sizeof(LV2_Event_Buffer) + capacity; - LV2_Event_Buffer* buf = (LV2_Event_Buffer*)malloc(size); - if (buf != NULL) { - buf->capacity = capacity; - lv2_event_buffer_reset(buf, stamp_type, (uint8_t *)(buf + 1)); - return buf; - } - return NULL; + const size_t size = sizeof(LV2_Event_Buffer) + capacity; + LV2_Event_Buffer* buf = (LV2_Event_Buffer*)malloc(size); + if (buf != NULL) { + buf->capacity = capacity; + lv2_event_buffer_reset(buf, stamp_type, (uint8_t*)(buf + 1)); + return buf; + } + return NULL; } - /** An iterator over an LV2_Event_Buffer. * * Multiple simultaneous read iterators over a single buffer is fine, * but changing the buffer invalidates all iterators. */ typedef struct { - LV2_Event_Buffer* buf; - uint32_t offset; + LV2_Event_Buffer* buf; + uint32_t offset; } LV2_Event_Iterator; - /** Reset an iterator to point to the start of `buf`. * @return True if `iter` is valid, otherwise false (buffer is empty) */ static inline bool -lv2_event_begin(LV2_Event_Iterator* iter, - LV2_Event_Buffer* buf) +lv2_event_begin(LV2_Event_Iterator* iter, LV2_Event_Buffer* buf) { - iter->buf = buf; - iter->offset = 0; - return (buf->size > 0); + iter->buf = buf; + iter->offset = 0; + return (buf->size > 0); } - /** Check if `iter` is valid. * @return True if `iter` is valid, otherwise false (past end of buffer) */ static inline bool lv2_event_is_valid(LV2_Event_Iterator* iter) { - return (iter->buf && (iter->offset < iter->buf->size)); + return (iter->buf && (iter->offset < iter->buf->size)); } - /** Advance `iter` forward one event. * `iter` must be valid. * @return True if `iter` is valid, otherwise false (reached end of buffer) */ static inline bool lv2_event_increment(LV2_Event_Iterator* iter) { - if (!lv2_event_is_valid(iter)) { - return false; - } + if (!lv2_event_is_valid(iter)) { + return false; + } - LV2_Event* const ev = (LV2_Event*)(iter->buf->data + iter->offset); + LV2_Event* const ev = (LV2_Event*)(iter->buf->data + iter->offset); - iter->offset += lv2_event_pad_size( - (uint16_t)((uint16_t)sizeof(LV2_Event) + ev->size)); + iter->offset += + lv2_event_pad_size((uint16_t)((uint16_t)sizeof(LV2_Event) + ev->size)); - return true; + return true; } - /** Dereference an event iterator (get the event currently pointed at). * `iter` must be valid. * `data` if non-NULL, will be set to point to the contents of the event @@ -145,23 +136,21 @@ lv2_event_increment(LV2_Event_Iterator* iter) * if the end of the buffer is reached (in which case `data` is * also set to NULL). */ static inline LV2_Event* -lv2_event_get(LV2_Event_Iterator* iter, - uint8_t** data) +lv2_event_get(LV2_Event_Iterator* iter, uint8_t** data) { - if (!lv2_event_is_valid(iter)) { - return NULL; - } + if (!lv2_event_is_valid(iter)) { + return NULL; + } - LV2_Event* const ev = (LV2_Event*)(iter->buf->data + iter->offset); + LV2_Event* const ev = (LV2_Event*)(iter->buf->data + iter->offset); - if (data) { - *data = (uint8_t*)ev + sizeof(LV2_Event); - } + if (data) { + *data = (uint8_t*)ev + sizeof(LV2_Event); + } - return ev; + return ev; } - /** Write an event at `iter`. * The event (if any) pointed to by `iter` will be overwritten, and `iter` * incremented to point to the following event (i.e. several calls to this @@ -175,62 +164,60 @@ lv2_event_write(LV2_Event_Iterator* iter, uint16_t size, const uint8_t* data) { - if (!iter->buf) { - return false; - } + if (!iter->buf) { + return false; + } - if (iter->buf->capacity - iter->buf->size < sizeof(LV2_Event) + size) { - return false; - } + if (iter->buf->capacity - iter->buf->size < sizeof(LV2_Event) + size) { + return false; + } - LV2_Event* const ev = (LV2_Event*)(iter->buf->data + iter->offset); + LV2_Event* const ev = (LV2_Event*)(iter->buf->data + iter->offset); - ev->frames = frames; - ev->subframes = subframes; - ev->type = type; - ev->size = size; - memcpy((uint8_t*)ev + sizeof(LV2_Event), data, size); - ++iter->buf->event_count; + ev->frames = frames; + ev->subframes = subframes; + ev->type = type; + ev->size = size; + memcpy((uint8_t*)ev + sizeof(LV2_Event), data, size); + ++iter->buf->event_count; - size = lv2_event_pad_size((uint16_t)(sizeof(LV2_Event) + size)); - iter->buf->size += size; - iter->offset += size; + size = lv2_event_pad_size((uint16_t)(sizeof(LV2_Event) + size)); + iter->buf->size += size; + iter->offset += size; - return true; + return true; } - /** Reserve space for an event in the buffer and return a pointer to the memory where the caller can write the event data, or NULL if there is not enough room in the buffer. */ static inline uint8_t* lv2_event_reserve(LV2_Event_Iterator* iter, - uint32_t frames, - uint32_t subframes, - uint16_t type, - uint16_t size) + uint32_t frames, + uint32_t subframes, + uint16_t type, + uint16_t size) { - const uint16_t total_size = (uint16_t)(sizeof(LV2_Event) + size); - if (iter->buf->capacity - iter->buf->size < total_size) { - return NULL; - } + const uint16_t total_size = (uint16_t)(sizeof(LV2_Event) + size); + if (iter->buf->capacity - iter->buf->size < total_size) { + return NULL; + } - LV2_Event* const ev = (LV2_Event*)(iter->buf->data + iter->offset); + LV2_Event* const ev = (LV2_Event*)(iter->buf->data + iter->offset); - ev->frames = frames; - ev->subframes = subframes; - ev->type = type; - ev->size = size; - ++iter->buf->event_count; + ev->frames = frames; + ev->subframes = subframes; + ev->type = type; + ev->size = size; + ++iter->buf->event_count; - const uint16_t padded_size = lv2_event_pad_size(total_size); - iter->buf->size += padded_size; - iter->offset += padded_size; + const uint16_t padded_size = lv2_event_pad_size(total_size); + iter->buf->size += padded_size; + iter->offset += padded_size; - return (uint8_t*)ev + sizeof(LV2_Event); + return (uint8_t*)ev + sizeof(LV2_Event); } - /** Write an event at `iter`. * The event (if any) pointed to by `iter` will be overwritten, and `iter` * incremented to point to the following event (i.e. several calls to this @@ -241,28 +228,28 @@ lv2_event_write_event(LV2_Event_Iterator* iter, const LV2_Event* ev, const uint8_t* data) { - const uint16_t total_size = (uint16_t)(sizeof(LV2_Event) + ev->size); - if (iter->buf->capacity - iter->buf->size < total_size) { - return false; - } + const uint16_t total_size = (uint16_t)(sizeof(LV2_Event) + ev->size); + if (iter->buf->capacity - iter->buf->size < total_size) { + return false; + } - LV2_Event* const write_ev = (LV2_Event*)(iter->buf->data + iter->offset); + LV2_Event* const write_ev = (LV2_Event*)(iter->buf->data + iter->offset); - *write_ev = *ev; - memcpy((uint8_t*)write_ev + sizeof(LV2_Event), data, ev->size); - ++iter->buf->event_count; + *write_ev = *ev; + memcpy((uint8_t*)write_ev + sizeof(LV2_Event), data, ev->size); + ++iter->buf->event_count; - const uint16_t padded_size = lv2_event_pad_size(total_size); - iter->buf->size += padded_size; - iter->offset += padded_size; + const uint16_t padded_size = lv2_event_pad_size(total_size); + iter->buf->size += padded_size; + iter->offset += padded_size; - return true; + return true; } LV2_RESTORE_WARNINGS #ifdef __cplusplus -} /* extern "C" */ +} /* extern "C" */ #endif #endif /* LV2_EVENT_HELPERS_H */ diff --git a/lv2/event/event.h b/lv2/event/event.h index ff91e3b..a0afd6c 100644 --- a/lv2/event/event.h +++ b/lv2/event/event.h @@ -47,7 +47,7 @@ // clang-format on -#define LV2_EVENT_AUDIO_STAMP 0 ///< Special timestamp type for audio frames +#define LV2_EVENT_AUDIO_STAMP 0 ///< Special timestamp type for audio frames #include "lv2/core/attributes.h" @@ -82,49 +82,48 @@ static const uint32_t LV2_EVENT_PPQN = 3136573440U; */ LV2_DEPRECATED 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 (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. - */ - 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. - */ - 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 */ + /** + 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 (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. + */ + 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. + */ + 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). @@ -143,92 +142,90 @@ typedef struct { */ LV2_DEPRECATED 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; + /** + 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. */ LV2_DEPRECATED typedef void* LV2_Event_Callback_Data; - /** Non-POD events feature. @@ -239,67 +236,67 @@ typedef void* LV2_Event_Callback_Data; */ LV2_DEPRECATED 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, 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 the 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 the 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); + /** + 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 the 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 the 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); } LV2_Event_Feature; LV2_RESTORE_WARNINGS #ifdef __cplusplus -} /* extern "C" */ +} /* extern "C" */ #endif /** |